matrx-mandate-scan 0.1.0__tar.gz

matrx_mandate_scan-0.1.0/.gitignore

@@ -0,0 +1,303 @@
+*.pyc
+secrets/
+ignore/
+temp/
+logs/
+# The broad `logs/` rule above is for RUNTIME log output, but it also matched
+# the dashboard's SOURCE directory and silently swallowed an entire feature's
+# files (only the pre-existing index.tsx stayed tracked), breaking the prod
+# Docker build with "Could not resolve ./structured-tab". Re-include the source.
+!apps/dashboard/src/features/logs/
+!apps/dashboard/src/features/logs/**
+todo
+text_notes/
+aidream/secrets/2.env
+automation_matrix/matrix_processing/temp/*
+cd
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+.venv/
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+# The blanket lib/ rule above is from the standard Python .gitignore template
+# and was silently swallowing TS source under the SPA `src/lib/` folders.
+# Re-allow them explicitly so frontend builds don't ship without their lib layer.
+!apps/dashboard/src/lib/
+!apps/dashboard/src/lib/**
+!apps/dashboard/src/features/crawler/lib/
+!apps/dashboard/src/features/crawler/lib/**
+!apps/workflow-studio/src/lib/
+!apps/workflow-studio/src/lib/**
+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
+ai/tests/clean_response.json
+ai/tests/cx_storage_response.json
+ai/tests/execution_test.py
+ai/tests/final_response.json
+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
+
+# 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
+
+# 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/#use-with-ide
+.pdm.toml
+
+# 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
+.env_remote
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+.env.armanonly
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# random armani files
+/armani_dev/secrets/
+/armani/
+/_armani/
+
+
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+.idea/
+.vscode/
+/node_modules/
+
+# Frontend pnpm workspace (apps/) — node_modules at the workspace root and any
+# member, plus Vite caches and build output. The unified lockfile (apps/pnpm-lock.yaml)
+# IS committed; everything below is regenerated.
+node_modules/
+apps/**/.vite/
+apps/**/dist/
+.vite/
+
+dump.rdb
+
+frontend/
+
+# AME Temp Files and directory structure
+# Ignore all files in the temp directory and its subdirectories
+/temp/**/*
+/tmp/**/*
+
+# Allow .gitkeep files to retain directory structure
+!/temp/**/.gitkeep
+!/tmp/**/.gitkeep
+
+# Armani
+.history*
+.history/
+/local_data/
+local_reports_data/
+webscraper/quick_scrapes/temp/
+automation_matrix/ai_apis/fireworks/_dev/*
+automation_matrix/ai_apis/fireworks/_dev/fireworks_sample.py
+*.pdf
+*.flac
+*.mp3
+*.wav
+miniconda.sh
+/database/python_sql/temp_data/
+ .history*
+ .history/
+.history/
+
+_dev/
+/_dev/
+requirements_filtered.txt
+
+# matrx-dev-tools backups
+.env-backups/
+# Matrx Ship config (contains API key)
+.matrx-ship.json
+
+# Matrx config (contains API keys)
+.matrx.json
+.matrx-tools.conf
+
+# Claude Code local worktrees and per-user settings
+.claude/worktrees/
+.worktrees/
+.claude/settings.local.json
+
+# Append-only snapshots from matrx_utils.update_history (unbounded; do not commit)
+common/utils/data_in_code/data_history.json
+packages/matrx-utils/matrx_utils/data_in_code/data_history.json
+
+# Tool-dispatch debug logs — one file per server start, never committed
+.matrx-debug/
+# Per-definition BEFORE snapshots written by a live migration script. They are
+# the recovery record for one machine's run, not repo content — the durable
+# audit trail is the `metadata.migrations` stamp on the row itself.
+.matrx-migrations/
+
+# macOS Finder metadata
+.DS_Store
+**/.DS_Store
+
+# Environment files
+.env
+.env.*
+*.env
+*.env.*
+
+# Keep safe templates trackable
+!.env.example
+!.env.sample
+!.env.template
+
+# Never commit local OAuth client/token artifacts
+credentials.json
+token*.pickle
+token*.json
+tests_trials/rag_tests/kg_export_output/
+
+# Pooler-contamination watch output (machine-local evidence, not source)
+db/evidence/
+
+# Pooler contamination evidence — machine-local forensic capture, not source
+db/evidence/
+db/mirror/.env.mirror
+supabase/.temp/
+**/supabase/.temp/
+# Packed npm artifacts. Kept locally for a one-time bootstrap publish; never
+# committed (they are large binaries regenerable with `pnpm pack`).
+apps/shared/*/*.tgz
+
+# Guard forcing-function scratch packages. These tests plant real files inside
+# the real tree the guard scans (a temp dir would prove nothing) and delete
+# them in teardown — ignoring them keeps the auto-commit tooling from
+# capturing one mid-run.
+_kind_boundary_scratch*/
+_kind_marker_law_scratch*/

matrx_mandate_scan-0.1.0/CLAUDE.md

@@ -0,0 +1,91 @@
+# matrx-mandate-scan — agent notes
+
+**Archetype A (library).** Consumers: aidream (`scripts/audit_mandate_wiring.py`,
+`aidream/services/mandates/code_truth.py`, `release.sh`, CI), and — via `uvx` — every
+other Matrx repo's release path. It runs where aidream does not exist, which is the
+whole point.
+
+## Hard rules for this package
+
+- **Never import `aidream` or `matrx-orm`.** `scripts/check_package_boundaries.py`
+  fails the build on it. Submission uses raw asyncpg on purpose (`transport.py`), and
+  the SYSTEM-org constant there is a documented mirror of matrx-orm's, not an import.
+- **`contract.py` is FROZEN.** Adding a `reference_type`, a finding code, or a field
+  is an amendment recorded in
+  `common-docs/projects/mandate-declaration-reporting/REGISTER.md` — never a silent edit.
+  A **breaking** amendment bumps `CONTRACT_VERSION` and lane L1's
+  `mandate.submit_scan_report(jsonb)` moves in the same change. A purely **additive**
+  one (amendment 1, 2026-09-09: `coverage.dirty` / `coverage.head_moved`; amendment 2,
+  2026-09-10: the repo-level `coverage.top_level` inventory) does not —
+  the door accepts exactly version 1 and stores `coverage` as jsonb wholesale, so a
+  bump would make it refuse every report over keys it already accepts. Either way the
+  amendment is written down before the code lands.
+- **Never make a command exit non-zero without `--strict`** (D23).
+- **Never widen classification to shape.** A dotted string is a reference because a
+  carrier holds it, never because it looks like a key. The moment that slips,
+  `consumerId="extend.chat"` becomes a mandate and the inventory is worthless. The
+  self-test guards exactly this.
+- **THERE IS EXACTLY ONE KEY RESOLVER, AND IT LIVES HERE** (coordinator ruling,
+  2026-09-10): `adapters/python.py::_Resolver`. aidream's
+  `scripts/check_mandate_carrier_args.py` is a THIN CALLER of `carrier_sites()` — it
+  owns no resolution logic and must never grow any. Two resolvers means the number you
+  read depends on which tool printed it, and the two DID disagree: the census certified
+  as clean 16 sites the scanner was reporting as `UNRESOLVED_KEY`. A new resolution
+  shape goes in `_Resolver`, and both tools get it.
+- **A bypass is a request TARGET, never a mention.** The provider names and hosts live
+  in `provider_vocabulary.py`, which is listed in its OWN allowlist beside
+  `matrx_ai/providers/**`. A host string counts when it is URL-shaped or sits in a
+  request-target position; a host name in a tuple is data, and a URL quoted in a
+  docstring is prose. "Any string that names a provider" made this package's own
+  vocabulary 13 live `NEW_BYPASS` rows.
+- **Every importable top-level package is scanned or listed as skipped with a reason.**
+  `top_level_inventory()` names every top-level directory once. aidream had twelve
+  importable packages that were neither, and the report still said `complete`.
+- **The ratchet only goes down.** `baseline.write` refuses to grow; keep it that way.
+- **`repo.py` mirrors `platform.repo`.** An unknown remote is `UNMEASURED`. Never
+  infer a slug from a folder name — "ai-matrx" the repo is the `matrx-frontend`
+  directory, and guessing gets it backwards.
+- **Nothing about a checkout comes from its DIRECTORY NAME.** The repo root is
+  `git rev-parse --show-toplevel`; the slug is the git remote; the root package is what
+  the manifests declare, else the registered slug. A worktree, a CI checkout, a fork PR
+  and a container build stage all rename the directory, and V-L2 § 6 measured the cost:
+  the entire 4,000-file root package silently absent while the report still said
+  `complete`.
+- **The revision is read ONCE, at scan start, and the report says whether the tree was
+  clean.** A candidate report describes exactly ONE committed tree; `coverage.dirty` /
+  `coverage.head_moved` and an `UNMEASURED` finding say so when it does not (V-L2 § 7:
+  live rows attributed to a commit that predates the package they scanned). `--revision`
+  is a CI-only override and an override that disagrees with HEAD is reported, never
+  trusted.
+
+## Where the walkers came from
+
+`walkers.py` holds the AST walkers that used to be private copies in
+`scripts/audit_mandate_wiring.py` and `aidream/services/mandates/code_truth.py`. Both
+now import from here. Their behavior is byte-for-byte the same (proven by a parity run
+over 11,406 files at the move). Change one and you change both — that is the point.
+
+## Proving a change
+
+```bash
+uv run pytest packages/matrx-mandate-scan/tests -q     # 71 tests
+uv run matrx-mandate-scan --self-test                  # 44 checks; runs from a uvx install too
+uv run matrx-mandate-scan scan -o /tmp/scan.json       # the whole repo
+uv run pytest aidream/services/mandates/tests/test_code_truth.py -q
+uv run pytest aidream/services/mandates/tests/test_scanner_resolver_agreement.py -q
+python scripts/check_mandate_carrier_args.py --self-test --strict   # the thin caller
+```
+
+**Cost.** A cross-module key is only static if the scanner has seen the module that
+declares it, so `build_module_index` reads every python file once before the real pass
+(`module_index.py`). That pre-pass is CACHED per file on `(repo-relative path,
+st_mtime_ns, st_size)` under `<repo>/.cache/matrx-mandate-scan/`. Measured on aidream:
+**cold 62s, warm 34s**, byte-identical payloads. The cache answers only the pre-pass
+question; every reference and finding still comes from reading the file in the real
+pass, a changed file is always re-read, and a cache from another `scanner_version` is
+discarded rather than trusted.
+
+A new carrier or a new resolution shape gets a fixture in
+`matrx_mandate_scan/fixtures/sources.py` and a case in `selftest.py` — the pytest suite
+imports those cases, so the two can never disagree. Break the adapter deliberately and
+watch the case go red before you believe it.

matrx_mandate_scan-0.1.0/PKG-INFO

@@ -0,0 +1,129 @@
+Metadata-Version: 2.5
+Name: matrx-mandate-scan
+Version: 0.1.0
+Summary: The one Mandate reference scanner: finds every mandate carrier, every bypass, and reports contract-v1 JSON to the platform
+Project-URL: Homepage, https://github.com/AI-Matrix-Engine/aidream
+Project-URL: Repository, https://github.com/AI-Matrix-Engine/aidream
+Project-URL: Issues, https://github.com/AI-Matrix-Engine/aidream/issues
+Author-email: Matrx <admin@aimatrx.com>
+Maintainer-email: Matrx <admin@aimatrx.com>
+License: MIT
+Keywords: governance,mandates,matrx,static-analysis
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.13
+Requires-Dist: pyyaml>=6.0.3
+Provides-Extra: submit
+Requires-Dist: asyncpg>=0.31.0; extra == 'submit'
+Description-Content-Type: text/markdown
+
+# matrx-mandate-scan
+
+The ONE Mandate reference scanner. It finds every place code reaches for
+platform intelligence — through a Mandate carrier or around it — reports the
+result to the database in one frozen contract, and screams (never blocks) when
+something is unresolved, unmeasured, or bypassing the mandate system.
+
+Built for the **Mandate Declaration & Usage Reporting** program
+(`common-docs/projects/mandate-declaration-reporting/`), lane L2.
+
+## Install / run
+
+```bash
+# from any repo, no checkout needed
+uvx --from matrx-mandate-scan==0.1.0 matrx-mandate-scan check
+
+# inside the aidream workspace (vendored via [tool.uv.sources])
+uv run matrx-mandate-scan scan --root aidream --root packages/matrx-ai
+```
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `scan` | Contract-v1 JSON on **stdout**, the red human report on **stderr**. |
+| `report` | `scan`, then submit through `mandate.submit_scan_report(jsonb)` and file every red finding into `ops.system_error` (`source_app='mandate-scan'`). |
+| `check` | The release-path command: scan + report + reconcile. |
+| `explain <file:line>` | What the scanner sees at one location, and why. |
+| `--self-test` | The built-in RED→GREEN fixture suite. Runs from a `uvx` install. |
+
+**Every command exits 0** unless `--strict` is passed. That is ruling **D23**:
+a mandate check is loud and non-blocking; `--strict` exists for humans and for
+the scheduled remediation task, never for a release script.
+
+## What counts as a reference
+
+Classification is **by carrier, never by the word or the path**. A dotted
+string is a mandate key only where a carrier puts it — so `consumerId =
+"extend.chat"` is not a reference and never becomes one.
+
+Python carriers:
+
+- `declare_mandate` / `declare_generated_mandate` / `declare_mandated_agent` → `declaration`
+- `declare_mandate_family(prefix, members=...)` → `family_declaration`, one `constant` per resolvable member, `dynamic_family` when the iterable is computed
+- `resolve_mandate` → `resolution`; `run_mandate` → `execution`
+- `run_mandated(Cls)` / `Cls.run()` → `execution`
+- a `NamedAgent` subclass `mandate_key` (including `type(name, (NamedAgent,), {...})`) → `declaration`
+- `seed_agent_id=<uuid>` inside a `declare_*` → `seed_holder`
+- `@mandate_passthrough` / `MandateKeyParam` → `passthrough`, with the caller attributed when it lives in the same module
+
+Config carriers (JSON / YAML / TOML) — the **property name** is the carrier:
+`mandate_key`, `mandateKey`, `defaultMandateKey`, `fallback_mandate_key`.
+Anything else that merely looks key-shaped is `unclassified` and advisory.
+
+Keys resolve through literals, module and function constants (UPPER or not),
+attribute constants, f-strings, `+` concatenations, ternaries (both branches
+become real references), tuple/list loop members, aliases, literal-container
+subscripts, and one level of analyzable module-local wrapper function.
+
+An argument that resolves to none of those → finding **`UNRESOLVED_KEY`**, plus
+an `unresolved`-flagged reference: D21 says unreachable is a flag, never a
+filter, so nothing is ever dropped from the inventory.
+
+## Bypass detection and the ratchet
+
+Importing a provider SDK (`anthropic`, `openai`, `groq`, `google.genai`,
+`google.generativeai`, `litellm`, `xai`, `ollama`, `cohere`, `mistralai`) or
+naming a provider host, anywhere outside
+`packages/matrx-ai/matrx_ai/providers/**` and the one D10-approved module
+(`conversation_labeler.py`), is a `bypass` reference. The exact standalone
+RAG default embedding adapter (`packages/matrx-rag/matrx_rag/embeddings.py`) is
+also an approved provider adapter: it is injected through `EmbeddingProvider`,
+does not select a Mandate holder, and is independently ratcheted by
+`scripts/check_raw_llm_clients.py`. No broader `matrx-rag` exemption exists.
+
+- in the `--baseline` file → **`CONVERSION_PENDING`** (flag `conversion_pending`)
+- not in it → **`NEW_BYPASS`** (D20: no new ones)
+- a dynamic import that hides its target → **`UNRESOLVED_IMPORT`**
+
+`--write-baseline` regenerates the file and **refuses to write a larger one**.
+No entry in the baseline is an approved class; every one is a defect awaiting
+conversion.
+
+## Coverage is mandatory output
+
+Every file is scanned or listed with a reason (`generated`, `test_fixture`,
+`parse_error`, `unsupported_language`). Any `parse_error` makes the package
+`verification_status = incomplete` and files an `UNMEASURED` finding.
+
+## Reference identity
+
+`sha256(repo_slug · package_path · file_path · symbol · occurrence_n ·
+reference_type · mandate_key_or_prefix)`.
+
+`repo_slug` is always the repo the scan ran in, resolved from
+`git remote get-url origin` through the `platform.repo` mirror in
+`matrx_mandate_scan/repo.py`. **An unknown remote is `UNMEASURED`, never a
+guessed slug** — a folder name is not a repo identity.
+
+## Boundaries
+
+Per `docs/packages/PACKAGE_DOCTRINE.md`, this package imports **neither
+`aidream` nor `matrx-orm`**. It carries the AST walkers that used to live in
+`scripts/audit_mandate_wiring.py` and
+`aidream/services/mandates/code_truth.py`; those two modules now import them
+from here, so there is exactly one definition of "what a carrier looks like".

matrx_mandate_scan-0.1.0/README.md

@@ -0,0 +1,106 @@
+# matrx-mandate-scan
+
+The ONE Mandate reference scanner. It finds every place code reaches for
+platform intelligence — through a Mandate carrier or around it — reports the
+result to the database in one frozen contract, and screams (never blocks) when
+something is unresolved, unmeasured, or bypassing the mandate system.
+
+Built for the **Mandate Declaration & Usage Reporting** program
+(`common-docs/projects/mandate-declaration-reporting/`), lane L2.
+
+## Install / run
+
+```bash
+# from any repo, no checkout needed
+uvx --from matrx-mandate-scan==0.1.0 matrx-mandate-scan check
+
+# inside the aidream workspace (vendored via [tool.uv.sources])
+uv run matrx-mandate-scan scan --root aidream --root packages/matrx-ai
+```
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `scan` | Contract-v1 JSON on **stdout**, the red human report on **stderr**. |
+| `report` | `scan`, then submit through `mandate.submit_scan_report(jsonb)` and file every red finding into `ops.system_error` (`source_app='mandate-scan'`). |
+| `check` | The release-path command: scan + report + reconcile. |
+| `explain <file:line>` | What the scanner sees at one location, and why. |
+| `--self-test` | The built-in RED→GREEN fixture suite. Runs from a `uvx` install. |
+
+**Every command exits 0** unless `--strict` is passed. That is ruling **D23**:
+a mandate check is loud and non-blocking; `--strict` exists for humans and for
+the scheduled remediation task, never for a release script.
+
+## What counts as a reference
+
+Classification is **by carrier, never by the word or the path**. A dotted
+string is a mandate key only where a carrier puts it — so `consumerId =
+"extend.chat"` is not a reference and never becomes one.
+
+Python carriers:
+
+- `declare_mandate` / `declare_generated_mandate` / `declare_mandated_agent` → `declaration`
+- `declare_mandate_family(prefix, members=...)` → `family_declaration`, one `constant` per resolvable member, `dynamic_family` when the iterable is computed
+- `resolve_mandate` → `resolution`; `run_mandate` → `execution`
+- `run_mandated(Cls)` / `Cls.run()` → `execution`
+- a `NamedAgent` subclass `mandate_key` (including `type(name, (NamedAgent,), {...})`) → `declaration`
+- `seed_agent_id=<uuid>` inside a `declare_*` → `seed_holder`
+- `@mandate_passthrough` / `MandateKeyParam` → `passthrough`, with the caller attributed when it lives in the same module
+
+Config carriers (JSON / YAML / TOML) — the **property name** is the carrier:
+`mandate_key`, `mandateKey`, `defaultMandateKey`, `fallback_mandate_key`.
+Anything else that merely looks key-shaped is `unclassified` and advisory.
+
+Keys resolve through literals, module and function constants (UPPER or not),
+attribute constants, f-strings, `+` concatenations, ternaries (both branches
+become real references), tuple/list loop members, aliases, literal-container
+subscripts, and one level of analyzable module-local wrapper function.
+
+An argument that resolves to none of those → finding **`UNRESOLVED_KEY`**, plus
+an `unresolved`-flagged reference: D21 says unreachable is a flag, never a
+filter, so nothing is ever dropped from the inventory.
+
+## Bypass detection and the ratchet
+
+Importing a provider SDK (`anthropic`, `openai`, `groq`, `google.genai`,
+`google.generativeai`, `litellm`, `xai`, `ollama`, `cohere`, `mistralai`) or
+naming a provider host, anywhere outside
+`packages/matrx-ai/matrx_ai/providers/**` and the one D10-approved module
+(`conversation_labeler.py`), is a `bypass` reference. The exact standalone
+RAG default embedding adapter (`packages/matrx-rag/matrx_rag/embeddings.py`) is
+also an approved provider adapter: it is injected through `EmbeddingProvider`,
+does not select a Mandate holder, and is independently ratcheted by
+`scripts/check_raw_llm_clients.py`. No broader `matrx-rag` exemption exists.
+
+- in the `--baseline` file → **`CONVERSION_PENDING`** (flag `conversion_pending`)
+- not in it → **`NEW_BYPASS`** (D20: no new ones)
+- a dynamic import that hides its target → **`UNRESOLVED_IMPORT`**
+
+`--write-baseline` regenerates the file and **refuses to write a larger one**.
+No entry in the baseline is an approved class; every one is a defect awaiting
+conversion.
+
+## Coverage is mandatory output
+
+Every file is scanned or listed with a reason (`generated`, `test_fixture`,
+`parse_error`, `unsupported_language`). Any `parse_error` makes the package
+`verification_status = incomplete` and files an `UNMEASURED` finding.
+
+## Reference identity
+
+`sha256(repo_slug · package_path · file_path · symbol · occurrence_n ·
+reference_type · mandate_key_or_prefix)`.
+
+`repo_slug` is always the repo the scan ran in, resolved from
+`git remote get-url origin` through the `platform.repo` mirror in
+`matrx_mandate_scan/repo.py`. **An unknown remote is `UNMEASURED`, never a
+guessed slug** — a folder name is not a repo identity.
+
+## Boundaries
+
+Per `docs/packages/PACKAGE_DOCTRINE.md`, this package imports **neither
+`aidream` nor `matrx-orm`**. It carries the AST walkers that used to live in
+`scripts/audit_mandate_wiring.py` and
+`aidream/services/mandates/code_truth.py`; those two modules now import them
+from here, so there is exactly one definition of "what a carrier looks like".

matrx_mandate_scan-0.1.0/matrx_mandate_scan/__init__.py

@@ -0,0 +1,20 @@
+"""matrx-mandate-scan — the ONE Mandate reference scanner.
+
+Finds every mandate carrier, every dynamic family, every pass-through, and
+every path to intelligence that goes around the mandate system; emits the
+frozen contract-v1 report; submits it through the one DB door; files every red
+finding into the platform's one error system.
+
+Laws it is built to (campaign register, 2026-09-09):
+
+* **D23 — never block a release.** Every command exits 0 unless ``--strict``.
+* **D20 — no new bypasses; existing ones are a ratchet**, not an approved class.
+* **D21 — unreachable is a flag, never a filter.** Nothing is dropped for being
+  unresolved, orphaned or broken.
+* **PACKAGE_DOCTRINE** — this package never imports ``aidream`` or ``matrx-orm``.
+"""
+
+from .contract import CONTRACT_VERSION, SCANNER_VERSION, ScanReport, identity_hash
+
+__version__ = SCANNER_VERSION
+__all__ = ["CONTRACT_VERSION", "SCANNER_VERSION", "ScanReport", "identity_hash", "__version__"]

matrx_mandate_scan-0.1.0/matrx_mandate_scan/__main__.py

@@ -0,0 +1,4 @@
+from matrx_mandate_scan.cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

matrx_mandate_scan-0.1.0/matrx_mandate_scan/adapters/__init__.py

@@ -0,0 +1,5 @@
+"""Language adapters. One tool, many adapters, one writer (DESIGN § 3.3)."""
+
+from matrx_mandate_scan.adapters import config, python
+
+__all__ = ["config", "python"]