feat: implement institutional mandate resolver
This commit is contained in:
@@ -0,0 +1,35 @@
|
|||||||
|
---
|
||||||
|
name: "Bug"
|
||||||
|
about: "Report a reproducible defect, regression, or incorrect behavior"
|
||||||
|
title: "[Bug] "
|
||||||
|
labels:
|
||||||
|
- type/bug
|
||||||
|
- status/triage
|
||||||
|
- module/core
|
||||||
|
---
|
||||||
|
|
||||||
|
## Scope
|
||||||
|
|
||||||
|
- Repository:
|
||||||
|
- Area/module:
|
||||||
|
- Affected version or commit:
|
||||||
|
|
||||||
|
## Behavior
|
||||||
|
|
||||||
|
Expected:
|
||||||
|
|
||||||
|
Actual:
|
||||||
|
|
||||||
|
## Reproduction
|
||||||
|
|
||||||
|
1.
|
||||||
|
2.
|
||||||
|
3.
|
||||||
|
|
||||||
|
## Evidence
|
||||||
|
|
||||||
|
Logs, screenshots, traces, or failing test output:
|
||||||
|
|
||||||
|
## Verification Target
|
||||||
|
|
||||||
|
Command or workflow that should pass when fixed:
|
||||||
@@ -0,0 +1 @@
|
|||||||
|
blank_issues_enabled: false
|
||||||
@@ -0,0 +1,27 @@
|
|||||||
|
---
|
||||||
|
name: "Docs / workflow"
|
||||||
|
about: "Request documentation, process, or developer workflow changes"
|
||||||
|
title: "[Docs] "
|
||||||
|
labels:
|
||||||
|
- type/docs
|
||||||
|
- status/triage
|
||||||
|
- module/core
|
||||||
|
- area/docs
|
||||||
|
---
|
||||||
|
|
||||||
|
## Scope
|
||||||
|
|
||||||
|
- Repository:
|
||||||
|
- Document or workflow:
|
||||||
|
|
||||||
|
## Current State
|
||||||
|
|
||||||
|
What is missing, unclear, duplicated, or stale?
|
||||||
|
|
||||||
|
## Desired State
|
||||||
|
|
||||||
|
What should the docs or workflow make clear?
|
||||||
|
|
||||||
|
## Verification Target
|
||||||
|
|
||||||
|
How should this be checked?
|
||||||
@@ -0,0 +1,32 @@
|
|||||||
|
---
|
||||||
|
name: "Feature"
|
||||||
|
about: "Propose new user-visible behavior or platform capability"
|
||||||
|
title: "[Feature] "
|
||||||
|
labels:
|
||||||
|
- type/feature
|
||||||
|
- status/triage
|
||||||
|
- module/core
|
||||||
|
---
|
||||||
|
|
||||||
|
## Problem
|
||||||
|
|
||||||
|
What user, operator, or developer problem should this solve?
|
||||||
|
|
||||||
|
## Proposed Capability
|
||||||
|
|
||||||
|
What should exist when this is done?
|
||||||
|
|
||||||
|
## Ownership
|
||||||
|
|
||||||
|
- Owning repository:
|
||||||
|
- Related module repositories:
|
||||||
|
- Extension point or integration boundary:
|
||||||
|
|
||||||
|
## Acceptance Criteria
|
||||||
|
|
||||||
|
- [ ]
|
||||||
|
- [ ]
|
||||||
|
|
||||||
|
## Verification Target
|
||||||
|
|
||||||
|
Command, scenario, or UI flow that should prove completion:
|
||||||
@@ -0,0 +1,28 @@
|
|||||||
|
---
|
||||||
|
name: "Task"
|
||||||
|
about: "Track implementation, maintenance, or migration work"
|
||||||
|
title: "[Task] "
|
||||||
|
labels:
|
||||||
|
- type/task
|
||||||
|
- status/triage
|
||||||
|
- module/core
|
||||||
|
---
|
||||||
|
|
||||||
|
## Objective
|
||||||
|
|
||||||
|
What needs to be completed?
|
||||||
|
|
||||||
|
## Scope
|
||||||
|
|
||||||
|
- Owning repository:
|
||||||
|
- In-scope:
|
||||||
|
- Out-of-scope:
|
||||||
|
|
||||||
|
## Checklist
|
||||||
|
|
||||||
|
- [ ]
|
||||||
|
- [ ]
|
||||||
|
|
||||||
|
## Verification Target
|
||||||
|
|
||||||
|
Command or manual check:
|
||||||
@@ -0,0 +1,25 @@
|
|||||||
|
---
|
||||||
|
name: "Tech debt"
|
||||||
|
about: "Track cleanup, refactoring, risk reduction, or deferred engineering work"
|
||||||
|
title: "[Debt] "
|
||||||
|
labels:
|
||||||
|
- type/debt
|
||||||
|
- status/triage
|
||||||
|
- module/core
|
||||||
|
---
|
||||||
|
|
||||||
|
## Current Cost
|
||||||
|
|
||||||
|
What does this make harder, riskier, slower, or more fragile?
|
||||||
|
|
||||||
|
## Desired Shape
|
||||||
|
|
||||||
|
What should the code, tests, or architecture look like afterwards?
|
||||||
|
|
||||||
|
## Constraints
|
||||||
|
|
||||||
|
What behavior, compatibility, or module boundary must be preserved?
|
||||||
|
|
||||||
|
## Verification Target
|
||||||
|
|
||||||
|
Focused checks that should pass:
|
||||||
@@ -0,0 +1,15 @@
|
|||||||
|
## Issue
|
||||||
|
|
||||||
|
Closes #
|
||||||
|
|
||||||
|
## Summary
|
||||||
|
|
||||||
|
-
|
||||||
|
|
||||||
|
## Verification
|
||||||
|
|
||||||
|
-
|
||||||
|
|
||||||
|
## Notes
|
||||||
|
|
||||||
|
Follow-up issues:
|
||||||
+353
@@ -0,0 +1,353 @@
|
|||||||
|
# ---> Node
|
||||||
|
# Logs
|
||||||
|
logs
|
||||||
|
*.log
|
||||||
|
npm-debug.log*
|
||||||
|
yarn-debug.log*
|
||||||
|
yarn-error.log*
|
||||||
|
lerna-debug.log*
|
||||||
|
.pnpm-debug.log*
|
||||||
|
|
||||||
|
# Diagnostic reports (https://nodejs.org/api/report.html)
|
||||||
|
report.[0-9]*.[0-9]*.[0-9]*.[0-9]*.json
|
||||||
|
|
||||||
|
# Runtime data
|
||||||
|
pids
|
||||||
|
*.pid
|
||||||
|
*.seed
|
||||||
|
*.pid.lock
|
||||||
|
|
||||||
|
# Directory for instrumented libs generated by jscoverage/JSCover
|
||||||
|
lib-cov
|
||||||
|
|
||||||
|
# Coverage directory used by tools like istanbul
|
||||||
|
coverage
|
||||||
|
*.lcov
|
||||||
|
|
||||||
|
# nyc test coverage
|
||||||
|
.nyc_output
|
||||||
|
|
||||||
|
# Grunt intermediate storage (https://gruntjs.com/creating-plugins#storing-task-files)
|
||||||
|
.grunt
|
||||||
|
|
||||||
|
# Bower dependency directory (https://bower.io/)
|
||||||
|
bower_components
|
||||||
|
|
||||||
|
# node-waf configuration
|
||||||
|
.lock-wscript
|
||||||
|
|
||||||
|
# Compiled binary addons (https://nodejs.org/api/addons.html)
|
||||||
|
build/Release
|
||||||
|
|
||||||
|
# Dependency directories
|
||||||
|
node_modules/
|
||||||
|
jspm_packages/
|
||||||
|
|
||||||
|
# Snowpack dependency directory (https://snowpack.dev/)
|
||||||
|
web_modules/
|
||||||
|
|
||||||
|
# TypeScript cache
|
||||||
|
*.tsbuildinfo
|
||||||
|
|
||||||
|
# Optional npm cache directory
|
||||||
|
.npm
|
||||||
|
|
||||||
|
# Optional eslint cache
|
||||||
|
.eslintcache
|
||||||
|
|
||||||
|
# Optional stylelint cache
|
||||||
|
.stylelintcache
|
||||||
|
|
||||||
|
# Microbundle cache
|
||||||
|
.rpt2_cache/
|
||||||
|
.rts2_cache_cjs/
|
||||||
|
.rts2_cache_es/
|
||||||
|
.rts2_cache_umd/
|
||||||
|
|
||||||
|
# Optional REPL history
|
||||||
|
.node_repl_history
|
||||||
|
|
||||||
|
# Output of 'npm pack'
|
||||||
|
*.tgz
|
||||||
|
|
||||||
|
# Yarn Integrity file
|
||||||
|
.yarn-integrity
|
||||||
|
|
||||||
|
# dotenv environment variable files
|
||||||
|
.env
|
||||||
|
.env.development.local
|
||||||
|
.env.test.local
|
||||||
|
.env.production.local
|
||||||
|
.env.local
|
||||||
|
|
||||||
|
# parcel-bundler cache (https://parceljs.org/)
|
||||||
|
.cache
|
||||||
|
.parcel-cache
|
||||||
|
|
||||||
|
# Next.js build output
|
||||||
|
.next
|
||||||
|
out
|
||||||
|
|
||||||
|
# Nuxt.js build / generate output
|
||||||
|
.nuxt
|
||||||
|
dist
|
||||||
|
|
||||||
|
# Gatsby files
|
||||||
|
.cache/
|
||||||
|
# Comment in the public line in if your project uses Gatsby and not Next.js
|
||||||
|
# https://nextjs.org/blog/next-9-1#public-directory-support
|
||||||
|
# public
|
||||||
|
|
||||||
|
# vuepress build output
|
||||||
|
.vuepress/dist
|
||||||
|
|
||||||
|
# vuepress v2.x temp and cache directory
|
||||||
|
.temp
|
||||||
|
.cache
|
||||||
|
|
||||||
|
# vitepress build output
|
||||||
|
**/.vitepress/dist
|
||||||
|
|
||||||
|
# vitepress cache directory
|
||||||
|
**/.vitepress/cache
|
||||||
|
|
||||||
|
# Docusaurus cache and generated files
|
||||||
|
.docusaurus
|
||||||
|
|
||||||
|
# Serverless directories
|
||||||
|
.serverless/
|
||||||
|
|
||||||
|
# FuseBox cache
|
||||||
|
.fusebox/
|
||||||
|
|
||||||
|
# DynamoDB Local files
|
||||||
|
.dynamodb/
|
||||||
|
|
||||||
|
# TernJS port file
|
||||||
|
.tern-port
|
||||||
|
|
||||||
|
# Stores VSCode versions used for testing VSCode extensions
|
||||||
|
.vscode-test
|
||||||
|
|
||||||
|
# yarn v2
|
||||||
|
.yarn/cache
|
||||||
|
.yarn/unplugged
|
||||||
|
.yarn/build-state.yml
|
||||||
|
.yarn/install-state.gz
|
||||||
|
.pnp.*
|
||||||
|
|
||||||
|
# Local WebUI test/build scratch directories
|
||||||
|
.component-test-build/
|
||||||
|
.file-drop-test-build/
|
||||||
|
.module-test-build/
|
||||||
|
.policy-test-build/
|
||||||
|
.template-preview-test-build/
|
||||||
|
.import-test-build/
|
||||||
|
webui/.component-test-build/
|
||||||
|
webui/.file-drop-test-build/
|
||||||
|
webui/.module-test-build/
|
||||||
|
webui/.policy-test-build/
|
||||||
|
webui/.template-preview-test-build/
|
||||||
|
webui/.import-test-build/
|
||||||
|
|
||||||
|
# Security audit reports
|
||||||
|
audit-reports/
|
||||||
|
|
||||||
|
# ---> Python
|
||||||
|
# Byte-compiled / optimized / DLL files
|
||||||
|
__pycache__/
|
||||||
|
*.py[cod]
|
||||||
|
*$py.class
|
||||||
|
|
||||||
|
# C extensions
|
||||||
|
*.so
|
||||||
|
|
||||||
|
# Distribution / packaging
|
||||||
|
.Python
|
||||||
|
build/
|
||||||
|
develop-eggs/
|
||||||
|
dist/
|
||||||
|
downloads/
|
||||||
|
eggs/
|
||||||
|
.eggs/
|
||||||
|
lib/
|
||||||
|
lib64/
|
||||||
|
parts/
|
||||||
|
sdist/
|
||||||
|
var/
|
||||||
|
wheels/
|
||||||
|
share/python-wheels/
|
||||||
|
*.egg-info/
|
||||||
|
.installed.cfg
|
||||||
|
*.egg
|
||||||
|
MANIFEST
|
||||||
|
|
||||||
|
# PyInstaller
|
||||||
|
# Usually these files are written by a python script from a template
|
||||||
|
# before PyInstaller builds the exe, so as to inject date/other infos into it.
|
||||||
|
*.manifest
|
||||||
|
*.spec
|
||||||
|
|
||||||
|
# Installer logs
|
||||||
|
pip-log.txt
|
||||||
|
pip-delete-this-directory.txt
|
||||||
|
|
||||||
|
# Unit test / coverage reports
|
||||||
|
htmlcov/
|
||||||
|
.tox/
|
||||||
|
.nox/
|
||||||
|
.coverage
|
||||||
|
.coverage.*
|
||||||
|
.cache
|
||||||
|
nosetests.xml
|
||||||
|
coverage.xml
|
||||||
|
*.cover
|
||||||
|
*.py,cover
|
||||||
|
.hypothesis/
|
||||||
|
.pytest_cache/
|
||||||
|
cover/
|
||||||
|
|
||||||
|
# Translations
|
||||||
|
*.mo
|
||||||
|
*.pot
|
||||||
|
|
||||||
|
# Django stuff:
|
||||||
|
*.log
|
||||||
|
local_settings.py
|
||||||
|
db.sqlite3
|
||||||
|
db.sqlite3-journal
|
||||||
|
|
||||||
|
# Flask stuff:
|
||||||
|
instance/
|
||||||
|
.webassets-cache
|
||||||
|
|
||||||
|
# Scrapy stuff:
|
||||||
|
.scrapy
|
||||||
|
|
||||||
|
# Sphinx documentation
|
||||||
|
docs/_build/
|
||||||
|
|
||||||
|
# PyBuilder
|
||||||
|
.pybuilder/
|
||||||
|
target/
|
||||||
|
|
||||||
|
# Jupyter Notebook
|
||||||
|
.ipynb_checkpoints
|
||||||
|
|
||||||
|
# IPython
|
||||||
|
profile_default/
|
||||||
|
ipython_config.py
|
||||||
|
|
||||||
|
# pyenv
|
||||||
|
# For a library or package, you might want to ignore these files since the code is
|
||||||
|
# intended to run in multiple environments; otherwise, check them in:
|
||||||
|
# .python-version
|
||||||
|
|
||||||
|
# pipenv
|
||||||
|
# According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
|
||||||
|
# However, in case of collaboration, if having platform-specific dependencies or dependencies
|
||||||
|
# having no cross-platform support, pipenv may install dependencies that don't work, or not
|
||||||
|
# install all needed dependencies.
|
||||||
|
#Pipfile.lock
|
||||||
|
|
||||||
|
# UV
|
||||||
|
# Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
|
||||||
|
# This is especially recommended for binary packages to ensure reproducibility, and is more
|
||||||
|
# commonly ignored for libraries.
|
||||||
|
#uv.lock
|
||||||
|
|
||||||
|
# poetry
|
||||||
|
# Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
|
||||||
|
# This is especially recommended for binary packages to ensure reproducibility, and is more
|
||||||
|
# commonly ignored for libraries.
|
||||||
|
# https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
|
||||||
|
#poetry.lock
|
||||||
|
|
||||||
|
# pdm
|
||||||
|
# Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
|
||||||
|
#pdm.lock
|
||||||
|
# pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
|
||||||
|
# in version control.
|
||||||
|
# https://pdm.fming.dev/latest/usage/project/#working-with-version-control
|
||||||
|
.pdm.toml
|
||||||
|
.pdm-python
|
||||||
|
.pdm-build/
|
||||||
|
|
||||||
|
# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
|
||||||
|
__pypackages__/
|
||||||
|
|
||||||
|
# Celery stuff
|
||||||
|
celerybeat-schedule
|
||||||
|
celerybeat.pid
|
||||||
|
|
||||||
|
# SageMath parsed files
|
||||||
|
*.sage.py
|
||||||
|
|
||||||
|
# Environments
|
||||||
|
.env
|
||||||
|
.venv
|
||||||
|
env/
|
||||||
|
venv/
|
||||||
|
ENV/
|
||||||
|
env.bak/
|
||||||
|
venv.bak/
|
||||||
|
|
||||||
|
# Spyder project settings
|
||||||
|
.spyderproject
|
||||||
|
.spyproject
|
||||||
|
|
||||||
|
# Rope project settings
|
||||||
|
.ropeproject
|
||||||
|
|
||||||
|
# mkdocs documentation
|
||||||
|
/site
|
||||||
|
|
||||||
|
# mypy
|
||||||
|
.mypy_cache/
|
||||||
|
.dmypy.json
|
||||||
|
dmypy.json
|
||||||
|
|
||||||
|
# Pyre type checker
|
||||||
|
.pyre/
|
||||||
|
|
||||||
|
# pytype static type analyzer
|
||||||
|
.pytype/
|
||||||
|
|
||||||
|
# Cython debug symbols
|
||||||
|
cython_debug/
|
||||||
|
|
||||||
|
# PyCharm
|
||||||
|
# JetBrains specific template is maintained in a separate JetBrains.gitignore that can
|
||||||
|
# be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
|
||||||
|
# and can be added to the global gitignore or merged into this file. For a more nuclear
|
||||||
|
# option (not recommended) you can uncomment the following to ignore the entire idea folder.
|
||||||
|
#.idea/
|
||||||
|
|
||||||
|
# Ruff stuff:
|
||||||
|
.ruff_cache/
|
||||||
|
|
||||||
|
# PyPI configuration file
|
||||||
|
.pypirc
|
||||||
|
|
||||||
|
# ---> VisualStudioCode
|
||||||
|
.vscode/*
|
||||||
|
!.vscode/settings.json
|
||||||
|
!.vscode/tasks.json
|
||||||
|
!.vscode/launch.json
|
||||||
|
!.vscode/extensions.json
|
||||||
|
!.vscode/*.code-snippets
|
||||||
|
|
||||||
|
# Local History for Visual Studio Code
|
||||||
|
.history/
|
||||||
|
|
||||||
|
# Built Visual Studio Code Extensions
|
||||||
|
*.vsix
|
||||||
|
|
||||||
|
*.db
|
||||||
|
|
||||||
|
# GovOPlaN local runtime state
|
||||||
|
runtime/
|
||||||
|
|
||||||
|
# GovOPlaN WebUI test output
|
||||||
|
webui/.module-test-build/
|
||||||
|
webui/.component-test-build/
|
||||||
@@ -0,0 +1,20 @@
|
|||||||
|
# GovOPlaN Mandates
|
||||||
|
|
||||||
|
<!-- govoplan-repository-type:start -->
|
||||||
|
**Repository type:** module (domain).
|
||||||
|
<!-- govoplan-repository-type:end -->
|
||||||
|
|
||||||
|
`govoplan-mandates` owns effective-dated institutional competence: tasks,
|
||||||
|
jurisdiction, responsibility, decision or signature authority, legal basis,
|
||||||
|
evidence, conflicts, suspension, replacement, and retirement.
|
||||||
|
|
||||||
|
Organizations owns structures and functions, IDM owns incumbency, Access owns
|
||||||
|
application permissions, and Policy owns constraints. Mandates answers why an
|
||||||
|
institution, unit, or function was competent to perform a governed action at a
|
||||||
|
specific time.
|
||||||
|
|
||||||
|
The module stores immutable mandate revisions and exposes the provider-neutral
|
||||||
|
`mandates.resolver` capability. Consumers retain exact returned references and
|
||||||
|
evidence instead of reading Mandates tables.
|
||||||
|
|
||||||
|
See [docs/MANDATES_DOMAIN.md](docs/MANDATES_DOMAIN.md).
|
||||||
@@ -0,0 +1,34 @@
|
|||||||
|
# Mandates Domain
|
||||||
|
|
||||||
|
## Ownership
|
||||||
|
|
||||||
|
Mandates owns stable mandate identities and immutable revisions. A revision
|
||||||
|
states effective time, task and authority types, constrained organization
|
||||||
|
units/functions, jurisdiction, subject scope, authority ceiling, legal bases,
|
||||||
|
evidence, lifecycle state, and explicit conflicts.
|
||||||
|
|
||||||
|
It does not own organization structures, function incumbency, accounts,
|
||||||
|
application permissions, policy rules, cases, or formal decisions.
|
||||||
|
|
||||||
|
## Resolution
|
||||||
|
|
||||||
|
Resolution is tenant-bound and deterministic. It evaluates the requested time,
|
||||||
|
task, authority, unit, function, jurisdiction, and subject against the latest
|
||||||
|
effective revision of each mandate. Conflicting effective mandates fail closed
|
||||||
|
and return their conflict/evidence references.
|
||||||
|
|
||||||
|
Consumers must freeze the exact mandate reference and evidence used for a
|
||||||
|
consequential action. A later mandate correction does not rewrite historical
|
||||||
|
decisions or effects.
|
||||||
|
|
||||||
|
## Revision And Recovery
|
||||||
|
|
||||||
|
Creation and revision use optimistic concurrency. Every new revision has a new
|
||||||
|
revision identifier, `recorded_at`, and change reason. Lifecycle transitions
|
||||||
|
follow the shared Core contract. Rows are append-only apart from marking the
|
||||||
|
previous row superseded; destructive retirement requires the platform database
|
||||||
|
snapshot and module-retirement preflight.
|
||||||
|
|
||||||
|
Database restore is the recovery unit. Replaying a request with the same
|
||||||
|
tenant, mandate identity, and revision is idempotent; a different payload under
|
||||||
|
an existing revision is rejected.
|
||||||
@@ -0,0 +1,21 @@
|
|||||||
|
[build-system]
|
||||||
|
requires = ["setuptools>=69", "wheel"]
|
||||||
|
build-backend = "setuptools.build_meta"
|
||||||
|
|
||||||
|
[project]
|
||||||
|
name = "govoplan-mandates"
|
||||||
|
version = "0.1.14"
|
||||||
|
description = "Effective institutional mandate, jurisdiction, and authority lifecycle for GovOPlaN."
|
||||||
|
readme = "README.md"
|
||||||
|
requires-python = ">=3.12"
|
||||||
|
authors = [{ name = "GovOPlaN" }]
|
||||||
|
dependencies = ["govoplan-core>=0.1.14"]
|
||||||
|
|
||||||
|
[tool.setuptools.packages.find]
|
||||||
|
where = ["src"]
|
||||||
|
|
||||||
|
[tool.setuptools.package-data]
|
||||||
|
govoplan_mandates = ["py.typed"]
|
||||||
|
|
||||||
|
[project.entry-points."govoplan.modules"]
|
||||||
|
"mandates" = "govoplan_mandates.backend.manifest:get_manifest"
|
||||||
@@ -0,0 +1,3 @@
|
|||||||
|
"""GovOPlaN institutional mandates module."""
|
||||||
|
|
||||||
|
__version__ = "0.1.14"
|
||||||
@@ -0,0 +1 @@
|
|||||||
|
"""Backend package for GovOPlaN Mandates."""
|
||||||
@@ -0,0 +1 @@
|
|||||||
|
"""Database models owned by GovOPlaN Mandates."""
|
||||||
@@ -0,0 +1,59 @@
|
|||||||
|
from __future__ import annotations
|
||||||
|
|
||||||
|
from datetime import datetime
|
||||||
|
import uuid
|
||||||
|
from typing import Any
|
||||||
|
|
||||||
|
from sqlalchemy import DateTime, ForeignKey, Index, JSON, String, UniqueConstraint
|
||||||
|
from sqlalchemy.orm import Mapped, mapped_column
|
||||||
|
|
||||||
|
from govoplan_core.db.base import Base, TimestampMixin
|
||||||
|
|
||||||
|
|
||||||
|
def new_uuid() -> str:
|
||||||
|
return str(uuid.uuid4())
|
||||||
|
|
||||||
|
|
||||||
|
class MandateRevision(Base, TimestampMixin):
|
||||||
|
__tablename__ = "mandate_revisions"
|
||||||
|
__table_args__ = (
|
||||||
|
UniqueConstraint(
|
||||||
|
"tenant_id",
|
||||||
|
"mandate_id",
|
||||||
|
"revision",
|
||||||
|
name="uq_mandate_revision",
|
||||||
|
),
|
||||||
|
Index(
|
||||||
|
"ix_mandate_current",
|
||||||
|
"tenant_id",
|
||||||
|
"mandate_id",
|
||||||
|
"superseded_at",
|
||||||
|
),
|
||||||
|
Index(
|
||||||
|
"ix_mandate_resolution",
|
||||||
|
"tenant_id",
|
||||||
|
"status",
|
||||||
|
"valid_from",
|
||||||
|
"valid_to",
|
||||||
|
),
|
||||||
|
)
|
||||||
|
|
||||||
|
id: Mapped[str] = mapped_column(String(36), primary_key=True, default=new_uuid)
|
||||||
|
tenant_id: Mapped[str] = mapped_column(String(36), nullable=False, index=True)
|
||||||
|
mandate_id: Mapped[str] = mapped_column(String(255), nullable=False, index=True)
|
||||||
|
revision: Mapped[str] = mapped_column(String(120), nullable=False)
|
||||||
|
previous_revision_id: Mapped[str | None] = mapped_column(
|
||||||
|
ForeignKey("mandate_revisions.id", ondelete="RESTRICT"),
|
||||||
|
nullable=True,
|
||||||
|
index=True,
|
||||||
|
)
|
||||||
|
status: Mapped[str] = mapped_column(String(30), nullable=False, index=True)
|
||||||
|
valid_from: Mapped[datetime | None] = mapped_column(DateTime(timezone=True), nullable=True)
|
||||||
|
valid_to: Mapped[datetime | None] = mapped_column(DateTime(timezone=True), nullable=True)
|
||||||
|
recorded_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), nullable=False, index=True)
|
||||||
|
superseded_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True), nullable=True, index=True)
|
||||||
|
payload: Mapped[dict[str, Any]] = mapped_column(JSON, nullable=False)
|
||||||
|
created_by: Mapped[str | None] = mapped_column(String(255), nullable=True, index=True)
|
||||||
|
|
||||||
|
|
||||||
|
__all__ = ["MandateRevision"]
|
||||||
@@ -0,0 +1,166 @@
|
|||||||
|
from __future__ import annotations
|
||||||
|
|
||||||
|
from pathlib import Path
|
||||||
|
|
||||||
|
from govoplan_core.core.institutional import CAPABILITY_MANDATE_RESOLVER
|
||||||
|
from govoplan_core.core.module_guards import (
|
||||||
|
drop_table_retirement_provider,
|
||||||
|
persistent_table_uninstall_guard,
|
||||||
|
)
|
||||||
|
from govoplan_core.core.modules import (
|
||||||
|
CapabilityDocumentation,
|
||||||
|
DocumentationLink,
|
||||||
|
DocumentationTopic,
|
||||||
|
MigrationSpec,
|
||||||
|
ModuleContext,
|
||||||
|
ModuleInterfaceProvider,
|
||||||
|
ModuleManifest,
|
||||||
|
PermissionDefinition,
|
||||||
|
RoleTemplate,
|
||||||
|
)
|
||||||
|
from govoplan_core.core.provider_governance import declared_module_architecture
|
||||||
|
from govoplan_core.db.base import Base
|
||||||
|
from govoplan_mandates.backend.db import models as mandate_models
|
||||||
|
from govoplan_mandates.backend.service import SqlMandateResolver
|
||||||
|
|
||||||
|
|
||||||
|
MODULE_ID = "mandates"
|
||||||
|
MODULE_NAME = "Mandates"
|
||||||
|
MODULE_VERSION = "0.1.14"
|
||||||
|
READ_SCOPE = "mandates:definition:read"
|
||||||
|
WRITE_SCOPE = "mandates:definition:write"
|
||||||
|
ADMIN_SCOPE = "mandates:definition:admin"
|
||||||
|
|
||||||
|
|
||||||
|
def _permission(scope: str, label: str, description: str) -> PermissionDefinition:
|
||||||
|
module_id, resource, action = scope.split(":", 2)
|
||||||
|
return PermissionDefinition(
|
||||||
|
scope=scope,
|
||||||
|
label=label,
|
||||||
|
description=description,
|
||||||
|
category="Mandates",
|
||||||
|
level="tenant",
|
||||||
|
module_id=module_id,
|
||||||
|
resource=resource,
|
||||||
|
action=action,
|
||||||
|
)
|
||||||
|
|
||||||
|
|
||||||
|
def _router(_context: ModuleContext):
|
||||||
|
from govoplan_mandates.backend.router import router
|
||||||
|
|
||||||
|
return router
|
||||||
|
|
||||||
|
|
||||||
|
def _resolver(_context: ModuleContext) -> SqlMandateResolver:
|
||||||
|
return SqlMandateResolver()
|
||||||
|
|
||||||
|
|
||||||
|
manifest = ModuleManifest(
|
||||||
|
id=MODULE_ID,
|
||||||
|
name=MODULE_NAME,
|
||||||
|
version=MODULE_VERSION,
|
||||||
|
optional_dependencies=("organizations", "idm", "access", "policy", "audit"),
|
||||||
|
provides_interfaces=(
|
||||||
|
ModuleInterfaceProvider(name="mandates.definition", version="0.1.0"),
|
||||||
|
ModuleInterfaceProvider(name="mandates.resolution", version="0.1.0"),
|
||||||
|
),
|
||||||
|
permissions=(
|
||||||
|
_permission(READ_SCOPE, "View mandates", "View mandate definitions, history, and resolution evidence."),
|
||||||
|
_permission(WRITE_SCOPE, "Manage mandates", "Create and revise mandate definitions."),
|
||||||
|
_permission(ADMIN_SCOPE, "Administer mandates", "Administer mandate lifecycle and recovery."),
|
||||||
|
),
|
||||||
|
role_templates=(
|
||||||
|
RoleTemplate(
|
||||||
|
slug="mandate_manager",
|
||||||
|
name="Mandate manager",
|
||||||
|
description="Manage institutional mandate and jurisdiction definitions.",
|
||||||
|
permissions=(READ_SCOPE, WRITE_SCOPE),
|
||||||
|
),
|
||||||
|
RoleTemplate(
|
||||||
|
slug="mandate_reader",
|
||||||
|
name="Mandate reader",
|
||||||
|
description="Inspect mandate definitions and resolution evidence.",
|
||||||
|
permissions=(READ_SCOPE,),
|
||||||
|
),
|
||||||
|
),
|
||||||
|
route_factory=_router,
|
||||||
|
capability_factories={CAPABILITY_MANDATE_RESOLVER: _resolver},
|
||||||
|
capability_documentation={
|
||||||
|
CAPABILITY_MANDATE_RESOLVER: CapabilityDocumentation(
|
||||||
|
label="Mandate resolver",
|
||||||
|
summary="Resolves effective institutional competence deterministically and fail-closed.",
|
||||||
|
contract_version="0.1.0",
|
||||||
|
)
|
||||||
|
},
|
||||||
|
migration_spec=MigrationSpec(
|
||||||
|
module_id=MODULE_ID,
|
||||||
|
metadata=Base.metadata,
|
||||||
|
script_location=str(Path(__file__).with_name("migrations") / "versions"),
|
||||||
|
retirement_supported=True,
|
||||||
|
retirement_provider=drop_table_retirement_provider(
|
||||||
|
mandate_models.MandateRevision,
|
||||||
|
label="Mandates",
|
||||||
|
),
|
||||||
|
retirement_notes="Destructive retirement requires a database snapshot and removes immutable Mandate history.",
|
||||||
|
),
|
||||||
|
uninstall_guard_providers=(
|
||||||
|
persistent_table_uninstall_guard(
|
||||||
|
mandate_models.MandateRevision,
|
||||||
|
label="Mandates",
|
||||||
|
),
|
||||||
|
),
|
||||||
|
documentation=(
|
||||||
|
DocumentationTopic(
|
||||||
|
id="mandates.definition-and-resolution",
|
||||||
|
title="Institutional mandates",
|
||||||
|
summary="Define and resolve effective authority, jurisdiction, legal basis, and evidence.",
|
||||||
|
body=(
|
||||||
|
"Mandates stores immutable revisions and resolves the one effective authority for a task. "
|
||||||
|
"Conflicting or missing authority fails closed. Consequential consumers retain the exact revision and evidence."
|
||||||
|
),
|
||||||
|
layer="configured",
|
||||||
|
documentation_types=("admin", "user"),
|
||||||
|
audience=("user", "operator", "module_admin", "auditor"),
|
||||||
|
links=(
|
||||||
|
DocumentationLink(
|
||||||
|
label="Mandates domain and recovery",
|
||||||
|
href="govoplan-mandates/docs/MANDATES_DOMAIN.md",
|
||||||
|
kind="repository",
|
||||||
|
),
|
||||||
|
),
|
||||||
|
),
|
||||||
|
),
|
||||||
|
architecture=declared_module_architecture(
|
||||||
|
layer="institutional_foundation",
|
||||||
|
kind="domain",
|
||||||
|
maturity="vertical_slice",
|
||||||
|
documentation_ref="docs/MANDATES_DOMAIN.md",
|
||||||
|
test_ref="tests/test_mandates.py",
|
||||||
|
known_limits=("No dedicated WebUI is included; administration is API-first.",),
|
||||||
|
supported_authority_modes=("native_authoritative",),
|
||||||
|
owned_concepts=("mandate", "jurisdiction authority", "competence history"),
|
||||||
|
non_owned_concepts=("organization structure", "function incumbency", "application permission", "formal decision"),
|
||||||
|
reference_packages=("product.service-to-decision",),
|
||||||
|
migration_docs=("docs/MANDATES_DOMAIN.md",),
|
||||||
|
recovery_docs=("docs/MANDATES_DOMAIN.md",),
|
||||||
|
security_docs=("docs/MANDATES_DOMAIN.md",),
|
||||||
|
operations_docs=("docs/MANDATES_DOMAIN.md",),
|
||||||
|
),
|
||||||
|
)
|
||||||
|
|
||||||
|
|
||||||
|
def get_manifest() -> ModuleManifest:
|
||||||
|
return manifest
|
||||||
|
|
||||||
|
|
||||||
|
__all__ = [
|
||||||
|
"ADMIN_SCOPE",
|
||||||
|
"MODULE_ID",
|
||||||
|
"MODULE_NAME",
|
||||||
|
"MODULE_VERSION",
|
||||||
|
"READ_SCOPE",
|
||||||
|
"WRITE_SCOPE",
|
||||||
|
"get_manifest",
|
||||||
|
"manifest",
|
||||||
|
]
|
||||||
@@ -0,0 +1 @@
|
|||||||
|
"""Mandates database migrations."""
|
||||||
@@ -0,0 +1 @@
|
|||||||
|
"""Mandates migration revisions."""
|
||||||
+51
@@ -0,0 +1,51 @@
|
|||||||
|
"""v0.1.14 Mandates baseline.
|
||||||
|
|
||||||
|
Revision ID: a8b1c2d3e4f5
|
||||||
|
Revises: None
|
||||||
|
"""
|
||||||
|
from __future__ import annotations
|
||||||
|
|
||||||
|
from alembic import op
|
||||||
|
import sqlalchemy as sa
|
||||||
|
|
||||||
|
|
||||||
|
revision = "a8b1c2d3e4f5"
|
||||||
|
down_revision = None
|
||||||
|
branch_labels = None
|
||||||
|
depends_on = "4f2a9c8e7b6d"
|
||||||
|
|
||||||
|
|
||||||
|
def upgrade() -> None:
|
||||||
|
op.create_table(
|
||||||
|
"mandate_revisions",
|
||||||
|
sa.Column("id", sa.String(length=36), nullable=False),
|
||||||
|
sa.Column("tenant_id", sa.String(length=36), nullable=False),
|
||||||
|
sa.Column("mandate_id", sa.String(length=255), nullable=False),
|
||||||
|
sa.Column("revision", sa.String(length=120), nullable=False),
|
||||||
|
sa.Column("previous_revision_id", sa.String(length=36), nullable=True),
|
||||||
|
sa.Column("status", sa.String(length=30), nullable=False),
|
||||||
|
sa.Column("valid_from", sa.DateTime(timezone=True), nullable=True),
|
||||||
|
sa.Column("valid_to", sa.DateTime(timezone=True), nullable=True),
|
||||||
|
sa.Column("recorded_at", sa.DateTime(timezone=True), nullable=False),
|
||||||
|
sa.Column("superseded_at", sa.DateTime(timezone=True), nullable=True),
|
||||||
|
sa.Column("payload", sa.JSON(), nullable=False),
|
||||||
|
sa.Column("created_by", sa.String(length=255), nullable=True),
|
||||||
|
sa.Column("created_at", sa.DateTime(timezone=True), nullable=False),
|
||||||
|
sa.Column("updated_at", sa.DateTime(timezone=True), nullable=False),
|
||||||
|
sa.ForeignKeyConstraint(
|
||||||
|
["previous_revision_id"],
|
||||||
|
["mandate_revisions.id"],
|
||||||
|
name=op.f("fk_mandate_revisions_previous_revision_id_mandate_revisions"),
|
||||||
|
ondelete="RESTRICT",
|
||||||
|
),
|
||||||
|
sa.PrimaryKeyConstraint("id", name=op.f("pk_mandate_revisions")),
|
||||||
|
sa.UniqueConstraint("tenant_id", "mandate_id", "revision", name="uq_mandate_revision"),
|
||||||
|
)
|
||||||
|
for column in ("tenant_id", "mandate_id", "previous_revision_id", "status", "recorded_at", "superseded_at", "created_by"):
|
||||||
|
op.create_index(op.f(f"ix_mandate_revisions_{column}"), "mandate_revisions", [column], unique=False)
|
||||||
|
op.create_index("ix_mandate_current", "mandate_revisions", ["tenant_id", "mandate_id", "superseded_at"], unique=False)
|
||||||
|
op.create_index("ix_mandate_resolution", "mandate_revisions", ["tenant_id", "status", "valid_from", "valid_to"], unique=False)
|
||||||
|
|
||||||
|
|
||||||
|
def downgrade() -> None:
|
||||||
|
op.drop_table("mandate_revisions")
|
||||||
@@ -0,0 +1,129 @@
|
|||||||
|
from __future__ import annotations
|
||||||
|
|
||||||
|
from typing import Any
|
||||||
|
|
||||||
|
from fastapi import APIRouter, Depends, HTTPException, Query, status
|
||||||
|
from sqlalchemy.orm import Session
|
||||||
|
|
||||||
|
from govoplan_core.auth import ApiPrincipal, get_api_principal, has_scope
|
||||||
|
from govoplan_core.core.institutional import InstitutionalContextError
|
||||||
|
from govoplan_core.db.session import get_session
|
||||||
|
from govoplan_mandates.backend.manifest import READ_SCOPE, WRITE_SCOPE
|
||||||
|
from govoplan_mandates.backend.schemas import (
|
||||||
|
MandateListResponse,
|
||||||
|
MandateResolutionPayload,
|
||||||
|
MandateWriteRequest,
|
||||||
|
)
|
||||||
|
from govoplan_mandates.backend.service import (
|
||||||
|
MandateStoreError,
|
||||||
|
SqlMandateResolver,
|
||||||
|
definition_from_mapping,
|
||||||
|
get_mandate,
|
||||||
|
list_mandates,
|
||||||
|
record_mandate,
|
||||||
|
resolution_request_from_mapping,
|
||||||
|
)
|
||||||
|
|
||||||
|
|
||||||
|
router = APIRouter(prefix="/mandates", tags=["mandates"])
|
||||||
|
|
||||||
|
|
||||||
|
def _require_scope(principal: ApiPrincipal, scope: str) -> None:
|
||||||
|
if not has_scope(principal, scope):
|
||||||
|
raise HTTPException(
|
||||||
|
status_code=status.HTTP_403_FORBIDDEN,
|
||||||
|
detail=f"Missing scope: {scope}",
|
||||||
|
)
|
||||||
|
|
||||||
|
|
||||||
|
def _error(exc: Exception) -> HTTPException:
|
||||||
|
message = str(exc)
|
||||||
|
code = status.HTTP_409_CONFLICT if "conflict" in message.lower() else status.HTTP_400_BAD_REQUEST
|
||||||
|
return HTTPException(status_code=code, detail=message)
|
||||||
|
|
||||||
|
|
||||||
|
@router.get("/definitions", response_model=MandateListResponse)
|
||||||
|
def api_list_mandates(
|
||||||
|
mandate_status: str | None = Query(default=None, alias="status"),
|
||||||
|
limit: int = Query(default=100, ge=1, le=200),
|
||||||
|
session: Session = Depends(get_session),
|
||||||
|
principal: ApiPrincipal = Depends(get_api_principal),
|
||||||
|
) -> MandateListResponse:
|
||||||
|
_require_scope(principal, READ_SCOPE)
|
||||||
|
try:
|
||||||
|
items = list_mandates(
|
||||||
|
session,
|
||||||
|
principal,
|
||||||
|
status=mandate_status,
|
||||||
|
limit=limit,
|
||||||
|
)
|
||||||
|
except (MandateStoreError, InstitutionalContextError) as exc:
|
||||||
|
raise _error(exc) from exc
|
||||||
|
return MandateListResponse(
|
||||||
|
mandates=[item.to_dict(include_inspection=True) for item in items]
|
||||||
|
)
|
||||||
|
|
||||||
|
|
||||||
|
@router.get("/definitions/{mandate_id}", response_model=dict[str, Any])
|
||||||
|
def api_get_mandate(
|
||||||
|
mandate_id: str,
|
||||||
|
revision: str | None = None,
|
||||||
|
session: Session = Depends(get_session),
|
||||||
|
principal: ApiPrincipal = Depends(get_api_principal),
|
||||||
|
) -> dict[str, Any]:
|
||||||
|
_require_scope(principal, READ_SCOPE)
|
||||||
|
item = get_mandate(
|
||||||
|
session,
|
||||||
|
principal,
|
||||||
|
mandate_id=mandate_id,
|
||||||
|
revision=revision,
|
||||||
|
)
|
||||||
|
if item is None:
|
||||||
|
raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Mandate not found")
|
||||||
|
return item.to_dict(include_inspection=True)
|
||||||
|
|
||||||
|
|
||||||
|
@router.post(
|
||||||
|
"/definitions",
|
||||||
|
response_model=dict[str, Any],
|
||||||
|
status_code=status.HTTP_201_CREATED,
|
||||||
|
)
|
||||||
|
def api_record_mandate(
|
||||||
|
payload: MandateWriteRequest,
|
||||||
|
session: Session = Depends(get_session),
|
||||||
|
principal: ApiPrincipal = Depends(get_api_principal),
|
||||||
|
) -> dict[str, Any]:
|
||||||
|
_require_scope(principal, WRITE_SCOPE)
|
||||||
|
try:
|
||||||
|
item = record_mandate(
|
||||||
|
session,
|
||||||
|
principal,
|
||||||
|
definition=definition_from_mapping(payload.definition),
|
||||||
|
expected_revision=payload.expected_revision,
|
||||||
|
)
|
||||||
|
session.commit()
|
||||||
|
except (MandateStoreError, InstitutionalContextError) as exc:
|
||||||
|
session.rollback()
|
||||||
|
raise _error(exc) from exc
|
||||||
|
return item.to_dict(include_inspection=True)
|
||||||
|
|
||||||
|
|
||||||
|
@router.post("/resolve", response_model=dict[str, Any])
|
||||||
|
def api_resolve_mandate(
|
||||||
|
payload: MandateResolutionPayload,
|
||||||
|
session: Session = Depends(get_session),
|
||||||
|
principal: ApiPrincipal = Depends(get_api_principal),
|
||||||
|
) -> dict[str, Any]:
|
||||||
|
_require_scope(principal, READ_SCOPE)
|
||||||
|
try:
|
||||||
|
result = SqlMandateResolver().resolve_mandate(
|
||||||
|
session,
|
||||||
|
principal,
|
||||||
|
request=resolution_request_from_mapping(payload.request),
|
||||||
|
)
|
||||||
|
except (MandateStoreError, InstitutionalContextError) as exc:
|
||||||
|
raise _error(exc) from exc
|
||||||
|
return result.to_dict(include_inspection=True)
|
||||||
|
|
||||||
|
|
||||||
|
__all__ = ["router"]
|
||||||
@@ -0,0 +1,29 @@
|
|||||||
|
from __future__ import annotations
|
||||||
|
|
||||||
|
from typing import Any
|
||||||
|
|
||||||
|
from pydantic import BaseModel, ConfigDict, Field
|
||||||
|
|
||||||
|
|
||||||
|
class MandateWriteRequest(BaseModel):
|
||||||
|
model_config = ConfigDict(extra="forbid")
|
||||||
|
|
||||||
|
definition: dict[str, Any]
|
||||||
|
expected_revision: str | None = Field(default=None, max_length=120)
|
||||||
|
|
||||||
|
|
||||||
|
class MandateResolutionPayload(BaseModel):
|
||||||
|
model_config = ConfigDict(extra="forbid")
|
||||||
|
|
||||||
|
request: dict[str, Any]
|
||||||
|
|
||||||
|
|
||||||
|
class MandateListResponse(BaseModel):
|
||||||
|
mandates: list[dict[str, Any]]
|
||||||
|
|
||||||
|
|
||||||
|
__all__ = [
|
||||||
|
"MandateListResponse",
|
||||||
|
"MandateResolutionPayload",
|
||||||
|
"MandateWriteRequest",
|
||||||
|
]
|
||||||
@@ -0,0 +1,307 @@
|
|||||||
|
from __future__ import annotations
|
||||||
|
|
||||||
|
from datetime import UTC, datetime
|
||||||
|
from typing import Any, Mapping
|
||||||
|
|
||||||
|
from sqlalchemy import or_
|
||||||
|
from sqlalchemy.orm import Session
|
||||||
|
|
||||||
|
from govoplan_core.core.institutional import (
|
||||||
|
InstitutionalContextError,
|
||||||
|
MandateDefinition,
|
||||||
|
MandateResolution,
|
||||||
|
MandateResolutionRequest,
|
||||||
|
TemporalRevision,
|
||||||
|
resolve_mandate_candidates,
|
||||||
|
revise_mandate_definition,
|
||||||
|
)
|
||||||
|
from govoplan_mandates.backend.db.models import MandateRevision
|
||||||
|
|
||||||
|
|
||||||
|
MAX_RESOLUTION_CANDIDATES = 1_000
|
||||||
|
|
||||||
|
|
||||||
|
class MandateStoreError(ValueError):
|
||||||
|
pass
|
||||||
|
|
||||||
|
|
||||||
|
def record_mandate(
|
||||||
|
session: Session,
|
||||||
|
principal: object,
|
||||||
|
*,
|
||||||
|
definition: MandateDefinition,
|
||||||
|
expected_revision: str | None = None,
|
||||||
|
) -> MandateDefinition:
|
||||||
|
tenant_id = _principal_tenant(principal)
|
||||||
|
_validate_definition_owner(definition, tenant_id=tenant_id)
|
||||||
|
normalized_payload = definition.to_dict(include_inspection=True)
|
||||||
|
|
||||||
|
replay = (
|
||||||
|
session.query(MandateRevision)
|
||||||
|
.filter(
|
||||||
|
MandateRevision.tenant_id == tenant_id,
|
||||||
|
MandateRevision.mandate_id == definition.reference.object_id,
|
||||||
|
MandateRevision.revision == definition.temporal.revision,
|
||||||
|
)
|
||||||
|
.one_or_none()
|
||||||
|
)
|
||||||
|
if replay is not None:
|
||||||
|
if replay.payload != normalized_payload:
|
||||||
|
raise MandateStoreError(
|
||||||
|
"A different Mandate payload already uses this revision."
|
||||||
|
)
|
||||||
|
return _definition_from_row(replay)
|
||||||
|
|
||||||
|
current_row = _current_row(
|
||||||
|
session,
|
||||||
|
tenant_id=tenant_id,
|
||||||
|
mandate_id=definition.reference.object_id,
|
||||||
|
lock=True,
|
||||||
|
)
|
||||||
|
if current_row is None:
|
||||||
|
if expected_revision is not None:
|
||||||
|
raise MandateStoreError(
|
||||||
|
"Mandate revision conflict: no current revision exists."
|
||||||
|
)
|
||||||
|
_validate_new_temporal(definition.temporal)
|
||||||
|
else:
|
||||||
|
if expected_revision is None:
|
||||||
|
raise MandateStoreError(
|
||||||
|
"Mandate revision conflict: expected_revision is required."
|
||||||
|
)
|
||||||
|
current = _definition_from_row(current_row)
|
||||||
|
try:
|
||||||
|
lifecycle = revise_mandate_definition(
|
||||||
|
current,
|
||||||
|
expected_revision=expected_revision,
|
||||||
|
temporal=definition.temporal,
|
||||||
|
status=definition.status,
|
||||||
|
replacement_ref=definition.replacement_ref,
|
||||||
|
suspension_reason=definition.suspension_reason,
|
||||||
|
conflict_refs=definition.conflict_refs,
|
||||||
|
)
|
||||||
|
except InstitutionalContextError as exc:
|
||||||
|
raise MandateStoreError(str(exc)) from exc
|
||||||
|
if lifecycle.reference != definition.reference:
|
||||||
|
raise MandateStoreError(
|
||||||
|
"Mandate reference identity and version must follow its lifecycle revision."
|
||||||
|
)
|
||||||
|
current_row.superseded_at = definition.temporal.recorded_at
|
||||||
|
|
||||||
|
row = MandateRevision(
|
||||||
|
tenant_id=tenant_id,
|
||||||
|
mandate_id=definition.reference.object_id,
|
||||||
|
revision=definition.temporal.revision,
|
||||||
|
previous_revision_id=current_row.id if current_row is not None else None,
|
||||||
|
status=definition.status,
|
||||||
|
valid_from=definition.temporal.valid_from,
|
||||||
|
valid_to=definition.temporal.valid_to,
|
||||||
|
recorded_at=_required_recorded_at(definition.temporal),
|
||||||
|
payload=normalized_payload,
|
||||||
|
created_by=_principal_actor(principal),
|
||||||
|
)
|
||||||
|
session.add(row)
|
||||||
|
session.flush()
|
||||||
|
return _definition_from_row(row)
|
||||||
|
|
||||||
|
|
||||||
|
def get_mandate(
|
||||||
|
session: Session,
|
||||||
|
principal: object,
|
||||||
|
*,
|
||||||
|
mandate_id: str,
|
||||||
|
revision: str | None = None,
|
||||||
|
) -> MandateDefinition | None:
|
||||||
|
tenant_id = _principal_tenant(principal)
|
||||||
|
query = session.query(MandateRevision).filter(
|
||||||
|
MandateRevision.tenant_id == tenant_id,
|
||||||
|
MandateRevision.mandate_id == mandate_id,
|
||||||
|
)
|
||||||
|
if revision is not None:
|
||||||
|
query = query.filter(MandateRevision.revision == revision)
|
||||||
|
else:
|
||||||
|
query = query.filter(MandateRevision.superseded_at.is_(None))
|
||||||
|
row = query.order_by(MandateRevision.recorded_at.desc()).first()
|
||||||
|
return _definition_from_row(row) if row is not None else None
|
||||||
|
|
||||||
|
|
||||||
|
def list_mandates(
|
||||||
|
session: Session,
|
||||||
|
principal: object,
|
||||||
|
*,
|
||||||
|
status: str | None = None,
|
||||||
|
limit: int = 100,
|
||||||
|
) -> tuple[MandateDefinition, ...]:
|
||||||
|
tenant_id = _principal_tenant(principal)
|
||||||
|
if not 1 <= limit <= 200:
|
||||||
|
raise MandateStoreError("Mandate list limit must be between 1 and 200.")
|
||||||
|
query = session.query(MandateRevision).filter(
|
||||||
|
MandateRevision.tenant_id == tenant_id,
|
||||||
|
MandateRevision.superseded_at.is_(None),
|
||||||
|
)
|
||||||
|
if status:
|
||||||
|
query = query.filter(MandateRevision.status == status)
|
||||||
|
rows = query.order_by(
|
||||||
|
MandateRevision.mandate_id.asc(),
|
||||||
|
MandateRevision.recorded_at.desc(),
|
||||||
|
).limit(limit).all()
|
||||||
|
return tuple(_definition_from_row(row) for row in rows)
|
||||||
|
|
||||||
|
|
||||||
|
class SqlMandateResolver:
|
||||||
|
def resolve_mandate(
|
||||||
|
self,
|
||||||
|
session: object,
|
||||||
|
principal: object,
|
||||||
|
*,
|
||||||
|
request: MandateResolutionRequest,
|
||||||
|
) -> MandateResolution:
|
||||||
|
tenant_id = _principal_tenant(principal)
|
||||||
|
if request.tenant_id != tenant_id:
|
||||||
|
raise InstitutionalContextError(
|
||||||
|
"Mandate resolution cannot cross tenants."
|
||||||
|
)
|
||||||
|
typed_session = _session(session)
|
||||||
|
rows = (
|
||||||
|
typed_session.query(MandateRevision)
|
||||||
|
.filter(
|
||||||
|
MandateRevision.tenant_id == tenant_id,
|
||||||
|
or_(
|
||||||
|
MandateRevision.valid_from.is_(None),
|
||||||
|
MandateRevision.valid_from <= request.effective_at,
|
||||||
|
),
|
||||||
|
or_(
|
||||||
|
MandateRevision.valid_to.is_(None),
|
||||||
|
MandateRevision.valid_to > request.effective_at,
|
||||||
|
),
|
||||||
|
)
|
||||||
|
.order_by(
|
||||||
|
MandateRevision.mandate_id.asc(),
|
||||||
|
MandateRevision.recorded_at.desc(),
|
||||||
|
)
|
||||||
|
.limit(MAX_RESOLUTION_CANDIDATES + 1)
|
||||||
|
.all()
|
||||||
|
)
|
||||||
|
if len(rows) > MAX_RESOLUTION_CANDIDATES:
|
||||||
|
raise InstitutionalContextError(
|
||||||
|
"Mandate resolution candidate bound was exceeded."
|
||||||
|
)
|
||||||
|
latest: dict[str, MandateDefinition] = {}
|
||||||
|
for row in rows:
|
||||||
|
latest.setdefault(row.mandate_id, _definition_from_row(row))
|
||||||
|
return resolve_mandate_candidates(request, tuple(latest.values()))
|
||||||
|
|
||||||
|
|
||||||
|
def definition_from_mapping(value: Mapping[str, object]) -> MandateDefinition:
|
||||||
|
try:
|
||||||
|
return MandateDefinition.from_mapping(value)
|
||||||
|
except InstitutionalContextError as exc:
|
||||||
|
raise MandateStoreError(str(exc)) from exc
|
||||||
|
|
||||||
|
|
||||||
|
def resolution_request_from_mapping(
|
||||||
|
value: Mapping[str, object],
|
||||||
|
) -> MandateResolutionRequest:
|
||||||
|
try:
|
||||||
|
return MandateResolutionRequest.from_mapping(value)
|
||||||
|
except InstitutionalContextError as exc:
|
||||||
|
raise MandateStoreError(str(exc)) from exc
|
||||||
|
|
||||||
|
|
||||||
|
def _current_row(
|
||||||
|
session: Session,
|
||||||
|
*,
|
||||||
|
tenant_id: str,
|
||||||
|
mandate_id: str,
|
||||||
|
lock: bool,
|
||||||
|
) -> MandateRevision | None:
|
||||||
|
query = session.query(MandateRevision).filter(
|
||||||
|
MandateRevision.tenant_id == tenant_id,
|
||||||
|
MandateRevision.mandate_id == mandate_id,
|
||||||
|
MandateRevision.superseded_at.is_(None),
|
||||||
|
)
|
||||||
|
if lock:
|
||||||
|
query = query.with_for_update()
|
||||||
|
return query.one_or_none()
|
||||||
|
|
||||||
|
|
||||||
|
def _definition_from_row(row: MandateRevision) -> MandateDefinition:
|
||||||
|
payload: dict[str, Any] = dict(row.payload)
|
||||||
|
temporal = dict(payload.get("temporal") or {})
|
||||||
|
temporal["superseded_at"] = _datetime_text(row.superseded_at)
|
||||||
|
payload["temporal"] = temporal
|
||||||
|
return MandateDefinition.from_mapping(payload)
|
||||||
|
|
||||||
|
|
||||||
|
def _validate_definition_owner(
|
||||||
|
definition: MandateDefinition,
|
||||||
|
*,
|
||||||
|
tenant_id: str,
|
||||||
|
) -> None:
|
||||||
|
if definition.reference.owner_module != "mandates":
|
||||||
|
raise MandateStoreError("Mandate definitions must be owned by Mandates.")
|
||||||
|
if definition.reference.tenant_id != tenant_id:
|
||||||
|
raise MandateStoreError("Mandate definitions cannot cross tenants.")
|
||||||
|
if definition.reference.version != definition.temporal.revision:
|
||||||
|
raise MandateStoreError(
|
||||||
|
"Mandate reference version must match its temporal revision."
|
||||||
|
)
|
||||||
|
if definition.temporal.superseded_at is not None:
|
||||||
|
raise MandateStoreError("Clients cannot set Mandate superseded_at.")
|
||||||
|
|
||||||
|
|
||||||
|
def _validate_new_temporal(temporal: TemporalRevision) -> None:
|
||||||
|
_required_recorded_at(temporal)
|
||||||
|
if not str(temporal.change_reason or "").strip():
|
||||||
|
raise MandateStoreError(
|
||||||
|
"A Mandate revision requires recorded_at and change_reason."
|
||||||
|
)
|
||||||
|
|
||||||
|
|
||||||
|
def _required_recorded_at(temporal: TemporalRevision) -> datetime:
|
||||||
|
if temporal.recorded_at is None:
|
||||||
|
raise MandateStoreError("A Mandate revision requires recorded_at.")
|
||||||
|
return temporal.recorded_at
|
||||||
|
|
||||||
|
|
||||||
|
def _principal_tenant(principal: object) -> str:
|
||||||
|
tenant_id = str(getattr(principal, "tenant_id", "") or "").strip()
|
||||||
|
if not tenant_id:
|
||||||
|
raise InstitutionalContextError(
|
||||||
|
"Mandate operations require a tenant-bound principal."
|
||||||
|
)
|
||||||
|
return tenant_id
|
||||||
|
|
||||||
|
|
||||||
|
def _principal_actor(principal: object) -> str | None:
|
||||||
|
for name in ("account_id", "identity_id", "membership_id"):
|
||||||
|
value = str(getattr(principal, name, "") or "").strip()
|
||||||
|
if value:
|
||||||
|
return value
|
||||||
|
return None
|
||||||
|
|
||||||
|
|
||||||
|
def _session(value: object) -> Session:
|
||||||
|
if not hasattr(value, "query"):
|
||||||
|
raise InstitutionalContextError("Mandate resolver requires a database session.")
|
||||||
|
return value # type: ignore[return-value]
|
||||||
|
|
||||||
|
|
||||||
|
def _datetime_text(value: datetime | None) -> str | None:
|
||||||
|
if value is None:
|
||||||
|
return None
|
||||||
|
if value.tzinfo is None:
|
||||||
|
value = value.replace(tzinfo=UTC)
|
||||||
|
return value.isoformat()
|
||||||
|
|
||||||
|
|
||||||
|
__all__ = [
|
||||||
|
"MAX_RESOLUTION_CANDIDATES",
|
||||||
|
"MandateStoreError",
|
||||||
|
"SqlMandateResolver",
|
||||||
|
"definition_from_mapping",
|
||||||
|
"get_mandate",
|
||||||
|
"list_mandates",
|
||||||
|
"record_mandate",
|
||||||
|
"resolution_request_from_mapping",
|
||||||
|
]
|
||||||
@@ -0,0 +1 @@
|
|||||||
|
|
||||||
@@ -0,0 +1,129 @@
|
|||||||
|
from __future__ import annotations
|
||||||
|
|
||||||
|
from dataclasses import dataclass, replace
|
||||||
|
from datetime import UTC, datetime, timedelta
|
||||||
|
import unittest
|
||||||
|
|
||||||
|
from sqlalchemy import create_engine
|
||||||
|
from sqlalchemy.orm import Session
|
||||||
|
|
||||||
|
from govoplan_core.core.institutional import (
|
||||||
|
InstitutionalReference,
|
||||||
|
MandateDefinition,
|
||||||
|
MandateResolutionRequest,
|
||||||
|
TemporalRevision,
|
||||||
|
)
|
||||||
|
from govoplan_mandates.backend.db.models import MandateRevision
|
||||||
|
from govoplan_mandates.backend.service import (
|
||||||
|
MandateStoreError,
|
||||||
|
SqlMandateResolver,
|
||||||
|
get_mandate,
|
||||||
|
record_mandate,
|
||||||
|
)
|
||||||
|
|
||||||
|
|
||||||
|
NOW = datetime(2026, 8, 1, 9, 0, tzinfo=UTC)
|
||||||
|
|
||||||
|
|
||||||
|
@dataclass
|
||||||
|
class Principal:
|
||||||
|
tenant_id: str = "tenant-1"
|
||||||
|
account_id: str = "account-1"
|
||||||
|
|
||||||
|
|
||||||
|
def definition(*, revision: str = "1", status: str = "active") -> MandateDefinition:
|
||||||
|
temporal = TemporalRevision(
|
||||||
|
revision=revision,
|
||||||
|
valid_from=NOW,
|
||||||
|
recorded_at=NOW + timedelta(minutes=int(revision) - 1),
|
||||||
|
change_reason="Initial authority." if revision == "1" else "Authority changed.",
|
||||||
|
)
|
||||||
|
return MandateDefinition(
|
||||||
|
reference=InstitutionalReference(
|
||||||
|
kind="mandate",
|
||||||
|
owner_module="mandates",
|
||||||
|
object_id="committee-permit",
|
||||||
|
tenant_id="tenant-1",
|
||||||
|
version=revision,
|
||||||
|
valid_at=NOW,
|
||||||
|
),
|
||||||
|
temporal=temporal,
|
||||||
|
task_types=("committee.formal_decision",),
|
||||||
|
authority_types=("permit",),
|
||||||
|
status=status, # type: ignore[arg-type]
|
||||||
|
suspension_reason="Review pending." if status == "suspended" else None,
|
||||||
|
)
|
||||||
|
|
||||||
|
|
||||||
|
class MandateTests(unittest.TestCase):
|
||||||
|
def setUp(self) -> None:
|
||||||
|
self.engine = create_engine("sqlite+pysqlite:///:memory:")
|
||||||
|
MandateRevision.__table__.create(self.engine)
|
||||||
|
self.session = Session(self.engine)
|
||||||
|
self.principal = Principal()
|
||||||
|
|
||||||
|
def tearDown(self) -> None:
|
||||||
|
self.session.close()
|
||||||
|
self.engine.dispose()
|
||||||
|
|
||||||
|
def test_record_resolve_replay_and_occ(self) -> None:
|
||||||
|
first = definition()
|
||||||
|
recorded = record_mandate(self.session, self.principal, definition=first)
|
||||||
|
self.assertEqual("1", recorded.temporal.revision)
|
||||||
|
replay = record_mandate(self.session, self.principal, definition=first)
|
||||||
|
self.assertEqual("1", replay.temporal.revision)
|
||||||
|
|
||||||
|
request = MandateResolutionRequest(
|
||||||
|
tenant_id="tenant-1",
|
||||||
|
effective_at=NOW + timedelta(hours=1),
|
||||||
|
task_type="committee.formal_decision",
|
||||||
|
authority_type="permit",
|
||||||
|
)
|
||||||
|
resolved = SqlMandateResolver().resolve_mandate(
|
||||||
|
self.session,
|
||||||
|
self.principal,
|
||||||
|
request=request,
|
||||||
|
)
|
||||||
|
self.assertTrue(resolved.competent)
|
||||||
|
self.assertEqual("1", resolved.mandates[0].temporal.revision)
|
||||||
|
|
||||||
|
suspended = definition(revision="2", status="suspended")
|
||||||
|
record_mandate(
|
||||||
|
self.session,
|
||||||
|
self.principal,
|
||||||
|
definition=suspended,
|
||||||
|
expected_revision="1",
|
||||||
|
)
|
||||||
|
self.assertFalse(
|
||||||
|
SqlMandateResolver().resolve_mandate(
|
||||||
|
self.session,
|
||||||
|
self.principal,
|
||||||
|
request=request,
|
||||||
|
).competent
|
||||||
|
)
|
||||||
|
with self.assertRaisesRegex(MandateStoreError, "stale"):
|
||||||
|
stale = replace(
|
||||||
|
suspended,
|
||||||
|
reference=replace(suspended.reference, version="3"),
|
||||||
|
temporal=replace(suspended.temporal, revision="3"),
|
||||||
|
)
|
||||||
|
record_mandate(
|
||||||
|
self.session,
|
||||||
|
self.principal,
|
||||||
|
definition=stale,
|
||||||
|
expected_revision="1",
|
||||||
|
)
|
||||||
|
|
||||||
|
def test_tenant_isolation(self) -> None:
|
||||||
|
record_mandate(self.session, self.principal, definition=definition())
|
||||||
|
self.assertIsNone(
|
||||||
|
get_mandate(
|
||||||
|
self.session,
|
||||||
|
Principal(tenant_id="tenant-2"),
|
||||||
|
mandate_id="committee-permit",
|
||||||
|
)
|
||||||
|
)
|
||||||
|
|
||||||
|
|
||||||
|
if __name__ == "__main__":
|
||||||
|
unittest.main()
|
||||||
Reference in New Issue
Block a user