Release portable deterministic core 1.1.0: frozen formats, offline recovery and regression checks

.gitattributes

@@ -1,6 +1,8 @@
-* text=auto eol=lf
-*.safetensors filter=lfs diff=lfs merge=lfs -text
-*.gguf filter=lfs diff=lfs merge=lfs -text
-*.bin filter=lfs diff=lfs merge=lfs -text
-*.pt filter=lfs diff=lfs merge=lfs -text
-*.onnx filter=lfs diff=lfs merge=lfs -text
+* text=auto eol=lf
+*.zip -text -diff
+*.safetensors filter=lfs diff=lfs merge=lfs -text
+*.gguf filter=lfs diff=lfs merge=lfs -text
+*.bin filter=lfs diff=lfs merge=lfs -text
+*.pt filter=lfs diff=lfs merge=lfs -text
+*.onnx filter=lfs diff=lfs merge=lfs -text
+bodul-offline-1.1.0.zip filter=lfs diff=lfs merge=lfs -text

.gitignore

@@ -1,15 +1,20 @@
-__pycache__/
-*.py[cod]
-.env
-.env.*
-*.log
-*.tmp
-*.bak
-.venv/
-venv/
-.cache/
-tokens/
-credentials*
-secrets*
-*.pem
-*.key
+__pycache__/
+*.py[cod]
+.env
+.env.*
+.venv/
+venv/
+.cache/
+.pytest_cache/
+*.log
+*.tmp
+*.bak
+*.swp
+*.pem
+*.key
+credentials*
+secrets*
+tokens/
+build/
+dist/
+*.egg-info/

ARCHIVE_README.md

@@ -0,0 +1,38 @@
+# Bodulski HAL: portable execution archive 1.1.0
+
+Author: Damir Balenović (mirdax25-ux). License: Apache-2.0.
+
+This archive contains Matrix Core 3.6.0-OMEGA and the supplied-evidence verifier
+2.1.2. Both use Python's standard library. No Hugging Face account, inference
+endpoint, model weights, Docker, pip installation or network is needed to run
+the Python examples. An installed Python runtime is required.
+
+```bash
+python -B verify_release.py
+python -B -m unittest discover -s tests -q
+python -B offline_cli.py matrix examples/matrix.txt --at "2026-11-03T12:00:00Z"
+python -B offline_cli.py verify-matrix examples/matrix-result.json
+python -B offline_cli.py claims examples/supported.json
+```
+
+Open `offline.html` directly for the single-file Matrix browser tool. It has no
+external assets or network requests. The full evidence verifier is available
+through `offline_cli.py claims`; it evaluates supplied structured evidence,
+not current external reality. Its CLI returns 0 for APPROVE, 3 for BLOCK or
+ESCALATE, and 2 for file/JSON input errors. Matrix returns 0 for successful
+checksum/verification and 2 for rejected input.
+
+Use `-` instead of a file name to read UTF-8 standard input. For durable Windows
+archives, use the CLI's file inputs and avoid shell-dependent text encodings.
+`examples/matrix-result.json` is synthetic public data, suitable for replay.
+Do not put personal evidence or secrets in this public archive.
+
+See `MATRIX_FORMAT.md` for exact bytes and frozen Unicode rules,
+`JSON_CONTRACT.md` for the verifier interface, `MAINTENANCE.md` for backup,
+restoration and migration procedures, and `CHANGELOG.md` for compatibility notes.
+`RELEASE_MANIFEST.json` lists SHA-256/SHA-512 digests of the source contents.
+Digests establish byte consistency, not authorship or real-world truth.
+
+The year-2126 and leap-year fixtures test date arithmetic; they are not a
+century-long uptime or security test. Preserve this archive and its trusted
+digests in independent storage and periodically restore it on a clean machine.

ARCHIVE_SHA256.txt

@@ -0,0 +1 @@
+b1e2f3a1a8ce43278cb0382df1e493f1cbbe7db0554846647d41af6b4ecf6e1a  bodul-offline-1.1.0.zip

ARCHIVE_SHA512.txt

@@ -0,0 +1 @@
+090fac7bb696199896114695e8f684f6546791dfb1d5386a3c5b542b945ffa9d907f01051c93b58eb15fb3caa495cb6f9fb231daad3cc462905ae9b6d21e31dd  bodul-offline-1.1.0.zip

CHANGELOG.md

@@ -0,0 +1,37 @@
+# Release notes
+
+## Portable source release 1.1.0 — 2026-11-03
+
+- Matrix Core 3.6.0-OMEGA freezes the 29-character whitespace table and v1
+  checksum byte contract; existing valid 3.5.1 checksum values are preserved.
+- Results add `checksum_format`, `normalization_profile` and `hash_algorithm`.
+  Complete-object clients must account for these additional metadata fields.
+- Invalid Unicode and raw inputs exceeding 1 MiB receive explicit errors and
+  no checksum. Timestamp strings use the documented narrow ASCII grammar.
+- Saved-result verification supports explicit v1 records and original
+  unlabeled 3.5.1-OMEGA records, rejecting unknown/partial formats.
+- Public JSON entry points reject duplicate keys, non-finite numbers,
+  excessive nesting, oversized inputs and lone surrogates. Python callers use
+  the same bounded serialization boundary. Human-approval flags remain ignored
+  in the public demo. The supplied-evidence algorithm remains 2.1.2.
+- Offline CLI, independent vectors, single-file HTML checksum tool, source ZIP,
+  dual archive digests, source manifest and restoration instructions are added.
+- Regression fixtures include 2126, non-leap centuries and the leap year 2400.
+
+## Matrix 3.5.1-OMEGA — 2026-11-03
+
+UTC date selection, aware-time requirements, invalid-input behavior, JSON CLI,
+16 unit tests, model cards and a Gradio-Lite Matrix panel were published.
+
+## Failure records addressed by 1.1.0
+
+| Failure mode | Cause | Guardrail and regression |
+| --- | --- | --- |
+| Future normalization drift | Runtime Unicode properties could change | Frozen whitespace table; all 29 code points plus preserved non-whitespace fixtures. |
+| Lone surrogate raises an encoding exception | Invalid scalar input reached UTF-8 hashing | Explicit rejection without a seal; Python/JSON/browser fixtures. |
+| Ambiguous JSON input | Default parsers accept duplicate keys and non-finite numbers | Bounded strict JSON parser and malformed-input tests. |
+| Lost hosting/CDN | Presentation depended on external delivery | Self-contained HTML and standard-library archive; actual offline restoration checks. |
+| Unsupported future format interpreted silently | Records lacked explicit format metadata | Labeled formats, legacy-only reader, unknown-format rejection tests. |
+
+Passing these regressions covers their recorded fixtures. It does not certify
+the absence of every defect or future runtime incompatibility.

JSON_CONTRACT.md

@@ -1,149 +1,166 @@
-# BodulskiHal JSON Contract — schema v3
-
-Schema v3 keeps the deterministic JSON adapter boundary and adds epistemic metadata needed by the real conversation benchmark.
-
-## Single-claim request
-
-```json
-{
-  "claim": {
-    "id": "count-1",
-    "text": "Conversation has 30 questions",
-    "type": "observation",
-    "risk": "low",
-    "consequential": true,
-    "authority_scope": "external_fact",
-    "answerability": "answerable"
-  },
-  "evidence": [
-    {
-      "source_id": "count-tool",
-      "evidence_id": "count-tool-1",
-      "supports": true,
-      "observed_at": "2026-10-03T21:30:00+00:00",
-      "directness": "direct",
-      "post_action": false,
-      "eligible": true,
-      "source_role": "external",
-      "source_ref": "tool://conversation-counter",
-      "independence_group": "conversation-counter",
-      "origin": "tool_observation",
-      "authority_scope": "external_fact"
-    }
-  ],
-  "policy": {
-    "version": "3.0",
-    "max_age_seconds": 300,
-    "reject_future_evidence": true,
-    "require_independent_action_evidence": true,
-    "medium_risk_min_independent_sources": 2,
-    "require_runtime_provenance": false
-  },
-  "evaluation_time": "2026-10-03T21:30:00+00:00",
-  "human_approved": false
-}
-```
-
-New claim fields are optional in the Python adapter and default fail-safely to:
-- `authority_scope = external_fact`
-- `answerability = answerable`
-
-New evidence fields are optional and default to:
-- `origin = external_source`
-- `authority_scope = external_fact`
-- `independence_group = null`
-
-For source-independence quorum, eligible direct supporting evidence is grouped by
-shared `source_id`, `source_ref`, or `independence_group`, including transitive
-overlap. Values are trimmed and compared within their own field namespace.
-Optional metadata can merge identities; it cannot split a known source into
-independent votes. Different group labels on the same provenance reference still
-count as one group. No URL canonicalization or external source authentication is
-implied by this deterministic comparison.
-
-The ingestion evidence boundary accepts the same optional `independence_group`
-field. The Python ingestion API requires a real `TypeAuthority` enum member;
-strings and other runtime values are rejected before claim typing. Lifecycle
-checkpoint/approval flags likewise require actual booleans.
-
-## Classification
-
-Schema v3 supports:
-- FACT
-- INFERENCE
-- ESTIMATE
-- UNKNOWN
-- REFUTED
-- CONFLICT
-
-Pure eligible counterevidence is REFUTED. Mixed supporting and contradicting evidence is CONFLICT.
-
-## Evidence origin
-
-Allowed values:
-- external_source
-- tool_observation
-- computed_result
-- memory
-- user_assertion
-- user_self_report
-- user_preference
-- user_instruction
-
-## Authority scope
-
-Allowed values:
-- external_fact
-- system_state
-- user_self_report
-- user_preference
-- user_instruction
-
-A user assertion is not sufficient evidence for an external fact merely because it was supplied by the caller.
-
-## Answerability
-
-Allowed values:
-- answerable
-- partially_answerable
-- underspecified
-- false_premise
-- contradictory_input
-- needs_clarification
-- out_of_scope
-
-Non-answerable claims fail closed before ordinary fact approval. `needs_clarification` escalates.
-
-## Runtime provenance
-
-Every receipt contains runtime provenance fields. A policy may set:
-
-`require_runtime_provenance = true`
-
-Then the verifier requires:
-- `BODULSKIHAL_SOURCE_COMMIT`
-- `BODULSKIHAL_SOURCE_REF`
-- `BODULSKIHAL_BUILD_ID`
-
-to identify a verified build.
-
-## Compound request
-
-Use `claims`, `evidence_by_claim`, optional `human_approvals`, one shared policy and one evaluation time.
-
-Unknown claim ids in evidence or approval maps are rejected.
-
-## Fail-closed boundary rules
-
-- Required strings must be non-empty.
-- Boolean fields must be actual booleans.
-- Datetimes must be ISO 8601 and timezone-aware.
-- Evidence/claim identities must be unique.
-- Provenance enum values must be known.
-- Content SHA-256, when supplied, must be a valid 64-character hexadecimal digest.
-- Memory and user-origin evidence are subject to authority policy; origin does not imply truth.
-- The adapter does not fetch URLs, authenticate arbitrary external sources or perform external actions.
-
-## Conversation contract
-
-Conversation goal/referent/constraint verification is exposed through `conversation_gate.py` as a deterministic internal gate. Semantic extraction of those fields is upstream work for BodulLogic/PRECICA or another preparation layer.
+# BodulskiHal JSON Contract — schema v3
+
+Schema v3 keeps the deterministic JSON adapter boundary and adds epistemic metadata needed by the real conversation benchmark.
+
+## Single-claim request
+
+```json
+{
+  "claim": {
+    "id": "count-1",
+    "text": "Conversation has 30 questions",
+    "type": "observation",
+    "risk": "low",
+    "consequential": true,
+    "authority_scope": "external_fact",
+    "answerability": "answerable"
+  },
+  "evidence": [
+    {
+      "source_id": "count-tool",
+      "evidence_id": "count-tool-1",
+      "supports": true,
+      "observed_at": "2026-10-03T21:30:00+00:00",
+      "directness": "direct",
+      "post_action": false,
+      "eligible": true,
+      "source_role": "external",
+      "source_ref": "tool://conversation-counter",
+      "independence_group": "conversation-counter",
+      "origin": "tool_observation",
+      "authority_scope": "external_fact"
+    }
+  ],
+  "policy": {
+    "version": "3.0",
+    "max_age_seconds": 300,
+    "reject_future_evidence": true,
+    "require_independent_action_evidence": true,
+    "medium_risk_min_independent_sources": 2,
+    "require_runtime_provenance": false
+  },
+  "evaluation_time": "2026-10-03T21:30:00+00:00",
+  "human_approved": false
+}
+```
+
+New claim fields are optional in the Python adapter and default fail-safely to:
+- `authority_scope = external_fact`
+- `answerability = answerable`
+
+New evidence fields are optional and default to:
+- `origin = external_source`
+- `authority_scope = external_fact`
+- `independence_group = null`
+
+For source-independence quorum, eligible direct supporting evidence is grouped by
+shared `source_id`, `source_ref`, or `independence_group`, including transitive
+overlap. Values are trimmed and compared within their own field namespace.
+Optional metadata can merge identities; it cannot split a known source into
+independent votes. Different group labels on the same provenance reference still
+count as one group. No URL canonicalization or external source authentication is
+implied by this deterministic comparison.
+
+The ingestion evidence boundary accepts the same optional `independence_group`
+field. The Python ingestion API requires a real `TypeAuthority` enum member;
+strings and other runtime values are rejected before claim typing. Lifecycle
+checkpoint/approval flags likewise require actual booleans.
+
+## Classification
+
+Schema v3 supports:
+- FACT
+- INFERENCE
+- ESTIMATE
+- UNKNOWN
+- REFUTED
+- CONFLICT
+
+Pure eligible counterevidence is REFUTED. Mixed supporting and contradicting evidence is CONFLICT.
+
+## Evidence origin
+
+Allowed values:
+- external_source
+- tool_observation
+- computed_result
+- memory
+- user_assertion
+- user_self_report
+- user_preference
+- user_instruction
+
+## Authority scope
+
+Allowed values:
+- external_fact
+- system_state
+- user_self_report
+- user_preference
+- user_instruction
+
+A user assertion is not sufficient evidence for an external fact merely because it was supplied by the caller.
+
+## Answerability
+
+Allowed values:
+- answerable
+- partially_answerable
+- underspecified
+- false_premise
+- contradictory_input
+- needs_clarification
+- out_of_scope
+
+Non-answerable claims fail closed before ordinary fact approval. `needs_clarification` escalates.
+
+## Runtime provenance
+
+Every receipt contains runtime provenance fields. A policy may set:
+
+`require_runtime_provenance = true`
+
+Then the verifier requires:
+- `BODULSKIHAL_SOURCE_COMMIT`
+- `BODULSKIHAL_SOURCE_REF`
+- `BODULSKIHAL_BUILD_ID`
+
+to identify a verified build.
+
+## Compound request
+
+Use `claims`, `evidence_by_claim`, optional `human_approvals`, one shared policy and one evaluation time.
+
+Unknown claim ids in evidence or approval maps are rejected.
+
+## Fail-closed boundary rules
+
+- Required strings must be non-empty.
+- Boolean fields must be actual booleans.
+- Datetimes must be ISO 8601 and timezone-aware.
+- Evidence/claim identities must be unique.
+- Provenance enum values must be known.
+- Content SHA-256, when supplied, must be a valid 64-character hexadecimal digest.
+- Memory and user-origin evidence are subject to authority policy; origin does not imply truth.
+- The adapter does not fetch URLs, authenticate arbitrary external sources or perform external actions.
+
+## Conversation contract
+
+Conversation goal/referent/constraint verification is exposed through `conversation_gate.py` as a deterministic internal gate. Semantic extraction of those fields is upstream work for BodulLogic/PRECICA or another preparation layer.
+
+## Portable public boundary 1.1.0
+
+The public `demo.evaluate`, `demo.evaluate_json`, and offline CLI impose a
+1 MiB UTF-8 JSON limit, 32 nesting levels, 128 integer digits, 1000 evidence
+records and 100 batch claims. Duplicate keys, non-finite numbers and lone
+surrogates are rejected. Public approval flags remain ignored.
+
+Timestamp strings follow the narrow ASCII interchange grammar documented in
+MATRIX_FORMAT.md and are normalized to UTC before evaluation. The boundary
+rejects unknown -00:00 offsets, leap seconds and implicit/local time zones.
+Equivalent timestamp offsets therefore give the same public receipt. Lower-level
+Python adapter APIs retain their existing schema-3 behavior and are trusted
+integration interfaces. The underlying decision algorithm remains 2.1.2.
+
+Historical replay requires the original explicit evaluation time, policy and
+evidence timestamps. APPROVE in such a replay does not imply present-day truth.

MAINTENANCE.md

@@ -0,0 +1,86 @@
+# Preservation and maintenance
+
+This release aims to make future reconstruction practical. It does not promise
+100 years of service availability, browser compatibility, cryptographic
+security, or unattended maintenance. No background maintenance job is installed
+by this release. A designated human maintainer remains necessary.
+
+## What can be preserved independently
+
+- Python sources, tests, synthetic fixtures and format specifications.
+- A single-file offline Matrix page with its own SHA-256 implementation.
+- A deterministic ZIP source archive, two hash manifests, Apache-2.0 license,
+  and instructions that require no account, model weights, pip or network.
+- Original evidence, its acquisition timestamp, policy, evaluation time and
+  runtime context, retained separately under the data owner's control.
+
+The verification kernel and Matrix core use Python's standard library. The
+Gradio-Lite presentation is optional and has pinned external dependencies; its
+continued operation depends on browsers, package/CDN availability and the host.
+The offline archive is the recovery path if those dependencies disappear.
+
+## Review schedule
+
+| When | Maintainer action |
+| --- | --- |
+| After any source or dependency change | Run tests, compare vectors, review decision changes, regenerate manifests and archive, verify deployed bytes. |
+| Quarterly | Open the live demo, test an empty/invalid input and one known vector; check official runtime and dependency advisories. |
+| Annually | Restore an archive onto a clean machine with networking disabled; run integrity check and tests; check backup readability. |
+| Before an OS/Python/browser upgrade | Test the archived vectors and public-boundary regressions with the proposed runtime. Keep the previous working archive. |
+| When hash guidance changes | Introduce a new explicit format; preserve old readers and create linked migration records. |
+| Before moving hosts or retiring a service | Copy and verify original files; retain at least two independent storage locations and one offline copy. |
+
+Suggested backup practice: three copies across two storage types, with one
+offline or offsite copy. Check stored bytes periodically and replace aging
+media. A Git tag or a checksum beside an archive does not authenticate an
+attacker-controlled replacement; keep a trusted digest/revision separately.
+
+## Restore without Hugging Face
+
+1. Copy `bodul-offline-1.1.0.zip` and its trusted `ARCHIVE_SHA256.txt` and
+   `ARCHIVE_SHA512.txt` from your backup. Compare the ZIP bytes with a trusted
+   tool before executing its contents. Extract only into a new directory.
+2. Open `offline.html` for the local checksum tool. It loads no external scripts
+   and its content security policy blocks network connections.
+3. With Python available, run `python -B verify_release.py`, then
+   `python -B -m unittest discover -s tests -q`.
+4. Run `python -B offline_cli.py matrix examples/matrix.txt --at
+   "2026-11-03T12:00:00Z"` and compare with `test_vectors.json`.
+5. Run `python -B offline_cli.py claims examples/supported.json`. This checks
+   the archived synthetic fixture at its explicit historical evaluation time;
+   it does not establish present-day truth or current source freshness.
+
+The source ZIP uses sorted paths, fixed timestamps, fixed permissions and
+uncompressed entries so identical source bytes produce identical archive bytes.
+Text files are UTF-8/LF. There is no absolute install location in the package.
+To reproduce a verified extracted archive, run
+`python -B build_archive.py ../rebuilt.zip`; the destination must be outside the
+extracted directory and must not already exist. Compare its digest with your
+trusted archive record before replacing a backup.
+
+## Runtime policy
+
+Reference minimum: Python 3.10. The validation record identifies which versions
+were actually executed; a minimum version declaration is not evidence that
+every interpreter/OS combination was tested. Preserve the working interpreter
+installer or distribution under its applicable license for disaster recovery.
+Re-run tests rather than assuming a future interpreter is compatible.
+
+Keep platform-specific hosting, UI and authenticated MCP adapters separate from
+the pure execution modules. The public demo ignores caller-supplied approval
+flags. Direct Python integrations must provide their own authenticated human
+review and source-collection boundary before acting on a decision.
+
+## Version and trust boundaries
+
+- Matrix implementation: 3.6.0-OMEGA; frozen checksum format: bodul-matrix-v1.
+- Supplied-evidence algorithm: 2.1.2; existing JSON adapter schema: 3.
+- Public bounded JSON boundary: 1.1.0; archive release: 1.1.0.
+- No source acquisition, identity authentication, external action or truth
+  guarantee is supplied by a local checksum or a caller-provided evidence flag.
+- Archive integrity verification proves comparison with the selected manifest,
+  not trusted authorship. Keep the verifier and manifest in your trust review.
+
+Do not silently alter behavior under a frozen format ID. Preserve legacy
+vectors, publish migration notes, and test readers against modified and unknown
+formats. Never label unmeasured reliability as a 0% hallucination guarantee.

MATRIX_FORMAT.md

@@ -0,0 +1,114 @@
+# Matrix checksum format: bodul-matrix-v1
+
+Status: frozen compatibility specification, published 2026-11-03. Reference
+implementation: Matrix Core 3.6.0-OMEGA, Apache-2.0. Changes to this document may
+clarify examples but MUST NOT silently change the v1 byte sequence.
+
+## Inputs and normalization
+
+The payload is a non-empty sequence of Unicode scalar values. Encode with strict
+UTF-8, without adding a byte order mark. An existing U+FEFF in input is data.
+Lone UTF-16 surrogates are invalid. The reference entry points impose a limit of
+1,048,576 raw UTF-8 bytes BEFORE normalization; oversized input receives no seal.
+
+Normalization profile **bodul-whitespace-v1** uses exactly these 29 code points:
+
+```text
+0009 000A 000B 000C 000D 001C 001D 001E 001F 0020
+0085 00A0 1680 2000 2001 2002 2003 2004 2005 2006
+2007 2008 2009 200A 2028 2029 202F 205F 3000
+```
+
+Replace each maximal run with one U+0020, then remove leading and trailing
+U+0020. Reject an empty result. No NFC, NFKC, case folding, punctuation changes,
+locale rules, or future Unicode property lookup applies. U+180E, U+200B, U+2060,
+and U+FEFF remain data. Visually similar text may intentionally have different
+checksums. This table preserves the legacy Python 3.12 whitespace behavior
+without depending on future Unicode databases.
+
+## UTC date and exact message bytes
+
+Convert an explicitly supplied aware datetime to UTC FIRST. Select its date
+in the proleptic Gregorian calendar, years 0001 through 9999 inclusive. Format
+the date as ten ASCII characters `YYYY-MM-DD`, including leading zeroes.
+
+Concatenate exactly, without quotes, BOM, terminal newline, or NUL terminator:
+
+```text
+BODUL_MATRIX::<normalized text>::<YYYY-MM-DD>::OMEGA_FLOW
+```
+
+Encode as strict UTF-8 and apply SHA-256 as specified by
+[FIPS 180-4](https://csrc.nist.gov/pubs/fips/180-4/upd1/final).
+Return 64 lowercase hexadecimal characters, preserving leading zeroes.
+
+The suffix is not a parser for recovering text: verification uses the supplied
+payload and date. Literal `::` in the payload is ordinary data. There are no
+secret keys. The engine version, full timestamp, and response labels are NOT
+part of the hash input.
+
+## Timestamp interchange grammar
+
+The portable JSON/CLI boundary accepts only ASCII:
+
+```text
+YYYY-MM-DDTHH:MM:SS[.ffffff](Z|+HH:MM|-HH:MM)
+```
+
+Fractional seconds, when present, have 1 through 6 digits. Offset hours are
+00..23; offset minutes are 00..59. Calendar validity is checked. `-00:00` denotes
+an unknown offset and is rejected. Leap seconds, offsets containing seconds,
+week dates, compact dates, spaces instead of `T`, and missing offsets are
+rejected. Results use a UTC `+00:00` offset; nonzero microseconds use six digits.
+UTC conversion outside 0001..9999 is rejected. This deliberately narrow grammar
+prevents a future parser expansion from changing accepted input implicitly.
+
+The Python datetime API also accepts aware datetime objects; archive replay
+uses the stricter text interchange grammar. With no `now`, the Python core
+captures UTC once. Offline CLI replay requires `--at` explicitly.
+
+## Output and historical verification
+
+Success includes `valid: true`, normalized `input_payload`, `seal_date`,
+`matrix_verification_seal`, `timestamp`, `engine_version`, `checksum_format`,
+`normalization_profile`, and `hash_algorithm`. An invalid payload includes
+`valid: false`, an error code and metadata, with NO seal. Machine schema:
+`schemas/matrix-result-v1.json`; independent fixtures: `test_vectors.json`.
+
+`verify_result` verifies the consistency of a successful exported result. It
+requires the exact field set, supported format/profile/hash identifiers,
+canonical normalized input, a timestamp matching the UTC date, and the correct
+seal. Original unlabeled **3.5.1-OMEGA** records remain readable. Other unlabeled
+records and unknown future formats fail closed. Invalid-input records cannot
+be verified as successful checksums.
+
+Existing valid 3.5.1 checksums remain unchanged. Version 3.6 adds explicit
+format metadata and controlled Unicode/size errors; clients comparing complete
+objects must account for the additional fields and engine version.
+
+The full result repeats only when text, time and engine metadata also match.
+The seal repeats for matching normalized text and UTC date. Metadata may be
+edited without changing a same-day seal; verification does not authenticate
+that metadata, authorship, original acquisition time, or external truth.
+
+## Future migrations
+
+Never redefine v1 or infer the format from digest length alone. If a new hash,
+normalization profile or message layout is needed, publish a NEW format ID,
+domain-separated bytes, independent vectors, reader and migration notes. Keep
+the old reader for historical checks. Store original source text, old result,
+new result, migration date and source revision together; do not overwrite the
+only historical record. Rehashing does not prove when the original existed.
+
+SHA-256 security is not guaranteed for a century. Review cryptographic guidance
+periodically. Archive manifests include SHA-256 and SHA-512 for byte comparison;
+neither is a signature, and both belong to the SHA-2 family.
+
+## References
+
+- [Python whitespace behavior](https://docs.python.org/3/library/stdtypes.html#str.isspace)
+- [NIST Secure Hash Standard](https://csrc.nist.gov/pubs/fips/180-4/upd1/final)
+- [RFC 3339 timestamp conventions](https://www.rfc-editor.org/rfc/rfc3339)
+
+These links explain current conventions. The explicit rules and bundled
+fixtures above are the preservation contract if the websites disappear.

README.md

@@ -1,126 +1,137 @@
----
-license: apache-2.0
-tags: [deterministic-ai, hal, system-architecture, agentic, mcp]
----
-# Deterministic Engine
-
-## Executive Summary
-
-Deterministic Engine provides an explicit deterministic control boundary for agent claims. Structured evidence, policy and evaluation time are evaluated without probabilistic text generation. Unsupported claims are blocked; insufficient authority can require escalation. The calling application must enforce the decision.
-
-This is an executable Python system, **not a pretrained language model**. No model weights are required or included. Deterministic control eliminates stochastic generation inside the verifier; it does not establish the truth of untrusted input or eliminate every hallucination in an upstream LLM.
-
-## Architecture Overview
-
-```text
-Structured claim + supplied evidence + policy + evaluation time
-                           |
-                           v
-                 Schema and type validation
-                           |
-                           v
-           Freshness / authority / contradiction gates
-                           |
-                           v
-          Deterministic classification and policy decision
-                           |
-                           v
-              Result + reason + SHA-256 receipt
-                           |
-                           v
-                Calling application enforces verdict
-```
-
-## Deterministic Execution Proof
-
-For fixed inputs, policy, evaluation time and runtime provenance, the local benchmark produced **1,000 identical serialized results in 1,000 executions**. The reproducible check covers that synthetic fixture, not an unrestricted correctness guarantee. Algorithm version: **2.1.2**; JSON contract: **v3**.
-
-The zero-hallucination objective is implemented as a fail-closed claim boundary. **0% real-world hallucinations is not a measured or guaranteed metric.** Fabricated evidence, incorrect adapters and callers that ignore a verdict remain outside that guarantee.
-
-## Quickstart Code Snippets
-
-After cloning or downloading the repository, use Python 3.12 or later:
-
-```bash
-python run_example.py
-```
-
-```python
-import json
-from demo import evaluate, example
-
-payload = example("supported")  # Explicitly synthetic demo evidence
-result = evaluate(payload)
-print(json.dumps(result, indent=2))
-
-payload["evidence"] = []
-blocked = evaluate(payload)
-assert blocked["classification"] == "UNKNOWN"
-assert blocked["verdict"] == "BLOCK"
-```
-
-For production integration, replace the synthetic sample with actual structured evidence and its original timestamp. See [JSON_CONTRACT.md](JSON_CONTRACT.md). This public wrapper ignores caller-supplied human-approval flags; high-risk claims still require review.
-
-## Benchmark & Reliability Specifications
-
-| Property | Local observation / contract |
-| --- | --- |
-| Execution | CPU, standard-library verification kernel; no inference service |
-| Fixture | One synthetic claim with fixed input and evaluation time |
-| Repetitions | 1000 |
-| Identical serialized results | 1000 |
-| Kernel latency p50 | 0.1524 ms |
-| Kernel latency p95 | 0.2647 ms |
-| Runtime | Python 3.12.14, AMD64 |
-| Exclusions | HTTP, UI, cold starts, workload scaling and external truth accuracy |
-| Decisions | APPROVE, BLOCK, ESCALATE |
-| Integrity | SHA-256 receipt; does not authenticate external sources |
-
-These measurements characterize one local execution environment. They are not a hosted SLA or evidence of enterprise certification. Zero-trust handling means missing, stale, unauthorized and contradictory evidence must not be silently upgraded to fact. The verifier does not fetch URLs or authenticate evidence provenance by itself.
-
-## System Integration
-
-- [Free interactive Gradio-Lite Space](https://huggingface.co/spaces/mirdax25-ux/bodulski-hal-playground) — Python runs in the browser; no server-side MCP endpoint.
-- [Bodulski HAL repository](https://huggingface.co/mirdax25-ux/Bodul)
-- [Deterministic engine repository](https://huggingface.co/mirdax25-ux/deterministic-engine)
-- [Authenticated MCP Actor on Apify](https://apify.com/bodul/bodulskihal-claim-verifier)
-
-The free Static Space runs Gradio-Lite and Python in the browser. It does not expose a remote MCP server. Use the separately authenticated Apify Actor for server-side MCP integration. Do not submit secrets or personal data to the public demo. The application does not explicitly persist claim payloads; hosting retention and logs require separate review.
-
-## Author and License
-
-[GitHub](https://github.com/mirdax25-ux) · [X](https://x.com/ddddddd97424402) · [LinkedIn](https://www.linkedin.com/in/damir-balenovic-594015429/)
-
-Apache License 2.0. This release does not provide warranties, source-authentication services or a guarantee of real-world truth.
-
-<!-- MATRIX_CORE:START -->
-## Matrix Core: deterministic text checksums
-
-`matrix_core.py` is a separate, standard-library-only module by Damir Balenović (mirdax25-ux), version **3.5.1-OMEGA**. It normalizes whitespace, rejects empty/non-string input, and computes SHA-256 over the normalized text and **UTC date**. It does not replace the evidence verifier.
-
-```python
-from datetime import datetime, timezone
-from matrix_core import DeterministicMatrixCore
-
-core = DeterministicMatrixCore()
-result = core.enforce_zero_tolerance_matrix(
-    "  Evidence\tbefore\nconfidence.  ",
-    now=datetime(2026, 11, 3, 12, tzinfo=timezone.utc),
-)
-assert result["valid"] is True
-assert result["matrix_verification_seal"] == "36e7be60a50a6d846b8b162c199a5e534c612ba171163d9c3406e2f2b12c0651"
-```
-
-```bash
-python matrix_core.py "Evidence before confidence." --at "2026-11-03T12:00:00+00:00"
-python -m unittest discover -s tests -p test_matrix_core.py -q
-```
-
-The checksum is repeatable for identical normalized text and UTC date. The **entire response** is repeatable only with the same instant and engine version, because the response includes a full timestamp. Supplied aware timestamps are converted to UTC before selecting the date; naive datetimes are rejected. With no timestamp, one UTC instant is captured for the whole response.
-
-`valid: true` means non-empty text, **not verified truth or authorization**. The checksum is not a keyed signature: anyone who knows the text and date can recompute it. The engine version and full timestamp are metadata outside the checksum input. Text that resembles a shell command is treated as data and is never executed.
-
-Empty input returns `valid: false`, `EMPTY_OR_INVALID_PAYLOAD` and **no checksum**. The CLI returns exit code 2 for invalid input or a timestamp without a timezone; missing CLI input no longer substitutes a deployment-like example string. Importing the module does not configure the root logger.
-
-[Try the free Matrix Core browser panel](https://huggingface.co/spaces/mirdax25-ux/bodulski-hal-playground).
-<!-- MATRIX_CORE:END -->
+---
+license: apache-2.0
+language: [en, hr]
+tags: [deterministic-ai, hal, system-architecture, agentic, mcp, reproducibility, offline]
+---
+# Deterministic Engine
+
+## Executive Summary
+
+Portable deterministic execution for structured evidence and text integrity.
+Bodulski HAL evaluates supplied evidence against explicit policy; Matrix Core
+normalizes text with a frozen character table and computes a UTC-date checksum.
+Neither path performs probabilistic text generation or requires model weights.
+The calling application controls source collection, trust and enforcement.
+
+Release **1.1.0** separates the standard-library core from optional presentation
+and hosting. The source archive, exact format specification, independent vectors
+and restoration instructions make the core recoverable without this service.
+
+## Architecture Overview
+
+```text
+Structured evidence + policy + explicit evaluation time
+             |
+     Bounded strict JSON boundary
+             |
+     Freshness / authority / contradiction gates
+             |
+     Classification + APPROVE / BLOCK / ESCALATE + receipt
+             |
+     Calling application enforces the decision
+
+Text + explicit instant -> frozen whitespace profile -> UTC date
+             -> exact UTF-8 v1 message -> SHA-256 checksum
+             -> export -> offline consistency verification
+```
+
+## Quickstart Code Snippets
+
+Download [the complete offline source archive](bodul-offline-1.1.0.zip), extract
+it into a new directory, then use an installed Python runtime:
+
+```bash
+python -B verify_release.py
+python -B -m unittest discover -s tests -q
+python -B offline_cli.py matrix examples/matrix.txt --at "2026-11-03T12:00:00Z"
+python -B offline_cli.py verify-matrix examples/matrix-result.json
+python -B offline_cli.py claims examples/supported.json
+```
+
+```python
+from datetime import datetime, timezone
+from matrix_core import DeterministicMatrixCore, verify_result
+from demo import evaluate, example
+
+at = datetime(2026, 11, 3, 12, tzinfo=timezone.utc)
+result = DeterministicMatrixCore().enforce_zero_tolerance_matrix(
+    "  Evidence\tbefore\nconfidence.  ", now=at
+)
+assert result["matrix_verification_seal"] == "36e7be60a50a6d846b8b162c199a5e534c612ba171163d9c3406e2f2b12c0651"
+assert verify_result(result)["verified"] is True
+assert evaluate(example("unsupported", at=at))["verdict"] == "BLOCK"
+```
+
+The examples are synthetic public fixtures. Historical replay uses their
+original explicit evaluation time; it is not evidence of present-day freshness.
+
+## Deterministic Execution Proof
+
+For fixed text and UTC date, the v1 checksum byte sequence is specified in
+[MATRIX_FORMAT.md](MATRIX_FORMAT.md), independent of a future Unicode database.
+For the entire response to repeat, the full instant and engine metadata must
+also match. The evidence verifier likewise requires fixed input, policy,
+evaluation time and runtime provenance. [test_vectors.json](test_vectors.json)
+includes legacy compatibility, Unicode, 2126, Gregorian boundary and leap-year
+fixtures. These fixtures test arithmetic and reproducibility, not future uptime.
+
+The core performs no stochastic generation. **A 0% real-world hallucination
+rate is neither measured nor guaranteed.** Supplied evidence can be fabricated;
+callers must authenticate sources and enforce BLOCK/ESCALATE decisions.
+
+## Benchmark & Reliability Specifications
+
+| Property | Release contract |
+| --- | --- |
+| Matrix implementation | 3.6.0-OMEGA |
+| Frozen checksum / normalization | bodul-matrix-v1 / bodul-whitespace-v1 |
+| Supplied-evidence algorithm / JSON schema | 2.1.2 / 3 |
+| Public JSON boundary / archive | 1.1.0 / 1.1.0 |
+| Core dependencies | Python standard library; no inference service |
+| Raw Matrix / JSON input limits | 1 MiB each; JSON nesting 32 levels |
+| Public evidence limits | 1000 evidence records; 100 batch claims |
+| Validation | [Recorded tests and local timing](VALIDATION.json) |
+| Integrity | SHA-256/SHA-512 archive comparison; no source authentication |
+
+Local timing measures synthetic in-process execution on the recorded runtime;
+it excludes cold starts, UI, network and real-world truth accuracy. It is not
+a hosted SLA, enterprise certification or a century-long reliability result.
+Invalid Unicode, duplicate JSON keys, non-finite numbers and malformed records
+fail closed at the documented public boundary.
+
+## Preservation and System Integration
+
+- [Free interactive evidence playground](https://huggingface.co/spaces/mirdax25-ux/bodulski-hal-playground).
+- [Single-file offline Matrix tool](https://mirdax25-ux-bodulski-hal-playground.static.hf.space/offline.html): save and open locally, with no CDN or network.
+- [Portable source archive](bodul-offline-1.1.0.zip), [SHA-256](ARCHIVE_SHA256.txt), [SHA-512](ARCHIVE_SHA512.txt).
+- [Maintenance, backup and restoration](MAINTENANCE.md); [compatibility notes](CHANGELOG.md).
+- [Evidence JSON contract](JSON_CONTRACT.md); [Matrix result schema](schemas/matrix-result-v1.json).
+- [Bodulski HAL](https://huggingface.co/mirdax25-ux/Bodul) and [Deterministic Engine](https://huggingface.co/mirdax25-ux/deterministic-engine).
+- [Separately authenticated Apify MCP Actor](https://apify.com/bodul/bodulskihal-claim-verifier).
+
+The hosted Space is **Static/Gradio-Lite**, with pinned browser dependencies
+and no paid compute, persistent volume or inference endpoint. The first load
+downloads its Python runtime. It exposes no server-side MCP endpoint. Use the
+standalone offline page/archive if the host or CDNs are unavailable.
+
+## Trust and Compatibility
+
+`valid: true` establishes accepted text, not truth or permission. A Matrix
+checksum can be recomputed by anyone; full timestamps and engine versions are
+unsealed metadata. `verify_result` checks consistency, not authorship. Existing
+3.5.1 checksum values remain valid; 3.6 adds explicit format fields and controlled
+input errors. Unknown future formats are rejected until a reader is added.
+
+Public Python/JSON entry points ignore caller-provided human approval flags.
+The lower-level kernel is a trusted integration API and requires external
+authentication and source validation. The public demo does not fetch URLs,
+execute payload text, or establish source identity. Do not submit secrets.
+
+No service availability, runtime support or cryptographic strength can be
+promised for 100 years. The preservation strategy is explicit formats, readable
+source, tested recovery, multiple backups and maintained migration paths.
+
+## Author and License
+
+Damir Balenović — [GitHub](https://github.com/mirdax25-ux) · [X](https://x.com/ddddddd97424402) · [LinkedIn](https://www.linkedin.com/in/damir-balenovic-594015429/).
+Apache License 2.0; see [LICENSE](LICENSE).

VALIDATION.json

@@ -0,0 +1,38 @@
+{
+  "started_at": "2026-11-03T10:21:46.791090+00:00",
+  "status": "passed",
+  "interpreters": [
+    {
+      "runtime": "Python 3.12.14",
+      "passed": true,
+      "tests": 46
+    },
+    {
+      "runtime": "Python 3.15.2",
+      "passed": true,
+      "tests": 46
+    }
+  ],
+  "browser_logic": {
+    "passed": true,
+    "node": "v22.23.2",
+    "sha256_reference_cases": 18,
+    "vectors": 13,
+    "whitespace_cases": 29,
+    "selftest_checks": 9
+  },
+  "python_javascript_full_result_matches": 13,
+  "space_app_constructed_and_handlers_passed": true,
+  "space_embedded_source_matches": true,
+  "benchmark": {
+    "iterations": 1000,
+    "identical_results": 1000,
+    "p50_ms": 0.2542,
+    "p95_ms": 0.4011,
+    "runtime": "3.12.14",
+    "machine": "AMD64",
+    "scope": "one synthetic claim, in-process public boundary; excludes UI, network, cold start, external truth accuracy"
+  },
+  "documentation_examples_passed": 3,
+  "completed_at": "2026-11-03T10:22:03.684574+00:00"
+}

bodul-offline-1.1.0.zip

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:b1e2f3a1a8ce43278cb0382df1e493f1cbbe7db0554846647d41af6b4ecf6e1a
+size 213666

bodulskihal_core/__init__.py

@@ -1,120 +1,120 @@
-from .engine import (
-    ALGORITHM_VERSION,
-    AnswerabilityStatus,
-    AuthorityScope,
-    Claim,
-    ClaimType,
-    Classification,
-    CompoundResult,
-    Directness,
-    Evidence,
-    EvidenceOrigin,
-    SourceRole,
-    Policy,
-    RiskLevel,
-    VerificationResult,
-    Verdict,
-    verify_claim,
-    verify_compound,
-    canonical_receipt_sha256,
-    make_failure_evolution_record,
-)
-
-__all__ = [
-    "ALGORITHM_VERSION",
-    "AnswerabilityStatus",
-    "AuthorityScope",
-    "Claim",
-    "ClaimType",
-    "Classification",
-    "CompoundResult",
-    "Directness",
-    "Evidence",
-    "EvidenceOrigin",
-    "SourceRole",
-    "Policy",
-    "RiskLevel",
-    "VerificationResult",
-    "Verdict",
-    "verify_claim",
-    "verify_compound",
-    "canonical_receipt_sha256",
-    "make_failure_evolution_record",
-    "SCHEMA_VERSION",
-    "verify_payload",
-    "verify_compound_payload",
-    "run_research_demo",
-    "evaluate_benchmark",
-    "GUARD_VERSION",
-    "Realism",
-    "GuardStage",
-    "UnknownSeverity",
-    "UnknownRecord",
-    "SelfCheck",
-    "GuardResult",
-    "run_guard_loop",
-    "ProjectState",
-    "LifecycleResult",
-    "freeze_project",
-    "authorize_mutation",
-    "reopen_project",
-    "SpeakerRole",
-    "AtomStatus",
-    "RawResponseEnvelope",
-    "ClaimAtom",
-    "EvidenceContract",
-    "bind_atom",
-    "atomize_raw_response",
-    "build_evidence_contract",
-    "ConstraintRecord",
-    "ConversationContract",
-    "ConversationGateResult",
-    "canonical_conversation_contract_sha256",
-    "evaluate_conversation_contract",
-    "RuntimeProvenance",
-    "current_runtime_provenance",
-]
-
-from .adapter import SCHEMA_VERSION, verify_compound_payload, verify_payload
-from .evaluation import evaluate_benchmark
-from .research_demo import run_research_demo
-
-from .guard_loop import (
-    GUARD_VERSION,
-    GuardResult,
-    GuardStage,
-    Realism,
-    SelfCheck,
-    UnknownRecord,
-    UnknownSeverity,
-    run_guard_loop,
-)
-
-from .lifecycle import (
-    LifecycleResult,
-    ProjectState,
-    authorize_mutation,
-    freeze_project,
-    reopen_project,
-)
-
-from .raw_pipeline import (
-    AtomStatus,
-    ClaimAtom,
-    EvidenceContract,
-    RawResponseEnvelope,
-    SpeakerRole,
-    atomize_raw_response,
-    bind_atom,
-    build_evidence_contract,
-)
-
-from .conversation_gate import (
-    ConstraintRecord,
-    ConversationContract,
-    ConversationGateResult,
-    canonical_conversation_contract_sha256,
-    evaluate_conversation_contract,
-)
-
+from .engine import (
+    ALGORITHM_VERSION,
+    AnswerabilityStatus,
+    AuthorityScope,
+    Claim,
+    ClaimType,
+    Classification,
+    CompoundResult,
+    Directness,
+    Evidence,
+    EvidenceOrigin,
+    SourceRole,
+    Policy,
+    RiskLevel,
+    VerificationResult,
+    Verdict,
+    verify_claim,
+    verify_compound,
+    canonical_receipt_sha256,
+    make_failure_evolution_record,
+)
+
+__all__ = [
+    "ALGORITHM_VERSION",
+    "AnswerabilityStatus",
+    "AuthorityScope",
+    "Claim",
+    "ClaimType",
+    "Classification",
+    "CompoundResult",
+    "Directness",
+    "Evidence",
+    "EvidenceOrigin",
+    "SourceRole",
+    "Policy",
+    "RiskLevel",
+    "VerificationResult",
+    "Verdict",
+    "verify_claim",
+    "verify_compound",
+    "canonical_receipt_sha256",
+    "make_failure_evolution_record",
+    "SCHEMA_VERSION",
+    "verify_payload",
+    "verify_compound_payload",
+    "run_research_demo",
+    "evaluate_benchmark",
+    "GUARD_VERSION",
+    "Realism",
+    "GuardStage",
+    "UnknownSeverity",
+    "UnknownRecord",
+    "SelfCheck",
+    "GuardResult",
+    "run_guard_loop",
+    "ProjectState",
+    "LifecycleResult",
+    "freeze_project",
+    "authorize_mutation",
+    "reopen_project",
+    "SpeakerRole",
+    "AtomStatus",
+    "RawResponseEnvelope",
+    "ClaimAtom",
+    "EvidenceContract",
+    "bind_atom",
+    "atomize_raw_response",
+    "build_evidence_contract",
+    "ConstraintRecord",
+    "ConversationContract",
+    "ConversationGateResult",
+    "canonical_conversation_contract_sha256",
+    "evaluate_conversation_contract",
+    "RuntimeProvenance",
+    "current_runtime_provenance",
+]
+
+from .adapter import SCHEMA_VERSION, verify_compound_payload, verify_payload
+from .evaluation import evaluate_benchmark
+from .research_demo import run_research_demo
+
+from .guard_loop import (
+    GUARD_VERSION,
+    GuardResult,
+    GuardStage,
+    Realism,
+    SelfCheck,
+    UnknownRecord,
+    UnknownSeverity,
+    run_guard_loop,
+)
+
+from .lifecycle import (
+    LifecycleResult,
+    ProjectState,
+    authorize_mutation,
+    freeze_project,
+    reopen_project,
+)
+
+from .raw_pipeline import (
+    AtomStatus,
+    ClaimAtom,
+    EvidenceContract,
+    RawResponseEnvelope,
+    SpeakerRole,
+    atomize_raw_response,
+    bind_atom,
+    build_evidence_contract,
+)
+
+from .conversation_gate import (
+    ConstraintRecord,
+    ConversationContract,
+    ConversationGateResult,
+    canonical_conversation_contract_sha256,
+    evaluate_conversation_contract,
+)
+
 from .runtime_provenance import RuntimeProvenance, current_runtime_provenance

bodulskihal_core/adapter.py

@@ -1,264 +1,264 @@
-from __future__ import annotations
-
-from datetime import datetime
-from typing import Any, Mapping
-
-from .engine import (
-    ALGORITHM_VERSION,
-    AnswerabilityStatus,
-    AuthorityScope,
-    Claim,
-    ClaimType,
-    Directness,
-    Evidence,
-    EvidenceOrigin,
-    Policy,
-    RiskLevel,
-    SourceRole,
-    verify_claim,
-    verify_compound,
-)
-
-SCHEMA_VERSION = 3
-
-
-def _mapping(value: Any, path: str) -> Mapping[str, Any]:
-    if not isinstance(value, Mapping):
-        raise TypeError(f"{path} must be object")
-    return value
-
-
-def _list(value: Any, path: str) -> list[Any]:
-    if not isinstance(value, list):
-        raise TypeError(f"{path} must be list")
-    return value
-
-
-def _required(obj: Mapping[str, Any], key: str, path: str) -> Any:
-    if key not in obj:
-        raise ValueError(f"missing required field: {path}.{key}")
-    return obj[key]
-
-
-def _string(value: Any, path: str) -> str:
-    if not isinstance(value, str) or not value:
-        raise TypeError(f"{path} must be non-empty string")
-    return value
-
-
-def _optional_string(value: Any, path: str) -> str | None:
-    if value is None:
-        return None
-    return _string(value, path)
-
-
-def _bool(value: Any, path: str) -> bool:
-    if type(value) is not bool:
-        raise TypeError(f"{path} must be bool")
-    return value
-
-
-def _int(value: Any, path: str) -> int:
-    if isinstance(value, bool) or not isinstance(value, int):
-        raise TypeError(f"{path} must be int")
-    return value
-
-
-def _datetime(value: Any, path: str) -> datetime:
-    raw = _string(value, path)
-    if raw.endswith("Z"):
-        raw = raw[:-1] + "+00:00"
-    try:
-        parsed = datetime.fromisoformat(raw)
-    except ValueError as exc:
-        raise ValueError(f"{path} must be ISO 8601 datetime") from exc
-    if parsed.tzinfo is None or parsed.utcoffset() is None:
-        raise ValueError(f"{path} must be timezone-aware")
-    return parsed
-
-
-def _enum(enum_type, value: Any, path: str):
-    raw = _string(value, path)
-    try:
-        return enum_type(raw)
-    except ValueError as exc:
-        raise ValueError(f"invalid {path}: {raw}") from exc
-
-
-def _claim(raw: Any, path: str = "claim") -> Claim:
-    obj = _mapping(raw, path)
-    return Claim(
-        claim_id=_string(_required(obj, "id", path), f"{path}.id"),
-        text=_string(_required(obj, "text", path), f"{path}.text"),
-        claim_type=_enum(ClaimType, _required(obj, "type", path), f"{path}.type"),
-        risk=_enum(RiskLevel, obj.get("risk", RiskLevel.LOW.value), f"{path}.risk"),
-        consequential=_bool(obj.get("consequential", True), f"{path}.consequential"),
-        authority_scope=_enum(
-            AuthorityScope,
-            obj.get("authority_scope", AuthorityScope.EXTERNAL_FACT.value),
-            f"{path}.authority_scope",
-        ),
-        answerability=_enum(
-            AnswerabilityStatus,
-            obj.get("answerability", AnswerabilityStatus.ANSWERABLE.value),
-            f"{path}.answerability",
-        ),
-    )
-
-
-def _evidence(raw: Any, path: str) -> Evidence:
-    obj = _mapping(raw, path)
-    return Evidence(
-        source_id=_string(_required(obj, "source_id", path), f"{path}.source_id"),
-        supports=_bool(_required(obj, "supports", path), f"{path}.supports"),
-        observed_at=_datetime(_required(obj, "observed_at", path), f"{path}.observed_at"),
-        directness=_enum(Directness, _required(obj, "directness", path), f"{path}.directness"),
-        post_action=_bool(obj.get("post_action", False), f"{path}.post_action"),
-        eligible=_bool(obj.get("eligible", True), f"{path}.eligible"),
-        evidence_id=_optional_string(obj.get("evidence_id"), f"{path}.evidence_id"),
-        source_role=_enum(
-            SourceRole,
-            obj.get("source_role", SourceRole.EXTERNAL.value),
-            f"{path}.source_role",
-        ),
-        source_ref=_optional_string(obj.get("source_ref"), f"{path}.source_ref"),
-        independence_group=_optional_string(
-            obj.get("independence_group"),
-            f"{path}.independence_group",
-        ),
-        content_sha256=_optional_string(
-            obj.get("content_sha256"),
-            f"{path}.content_sha256",
-        ),
-        origin=_enum(
-            EvidenceOrigin,
-            obj.get("origin", EvidenceOrigin.EXTERNAL_SOURCE.value),
-            f"{path}.origin",
-        ),
-        authority_scope=_enum(
-            AuthorityScope,
-            obj.get("authority_scope", AuthorityScope.EXTERNAL_FACT.value),
-            f"{path}.authority_scope",
-        ),
-    )
-
-
-def _policy(raw: Any) -> Policy:
-    path = "policy"
-    obj = _mapping(raw, path)
-    return Policy(
-        version=_string(_required(obj, "version", path), "policy.version"),
-        max_age_seconds=_int(_required(obj, "max_age_seconds", path), "policy.max_age_seconds"),
-        reject_future_evidence=_bool(
-            obj.get("reject_future_evidence", True),
-            "policy.reject_future_evidence",
-        ),
-        require_independent_action_evidence=_bool(
-            obj.get("require_independent_action_evidence", True),
-            "policy.require_independent_action_evidence",
-        ),
-        medium_risk_min_independent_sources=_int(
-            obj.get("medium_risk_min_independent_sources", 2),
-            "policy.medium_risk_min_independent_sources",
-        ),
-        require_runtime_provenance=_bool(
-            obj.get("require_runtime_provenance", False),
-            "policy.require_runtime_provenance",
-        ),
-    )
-
-
-def _result_dict(result) -> dict[str, Any]:
-    return {
-        "schema_version": SCHEMA_VERSION,
-        "algorithm_version": ALGORITHM_VERSION,
-        "classification": result.classification.value,
-        "verdict": result.verdict.value,
-        "reason": result.reason,
-        "receipt": result.receipt,
-        "failure_record": result.failure_record,
-    }
-
-
-def verify_payload(payload: Mapping[str, Any]) -> dict[str, Any]:
-    obj = _mapping(payload, "payload")
-    claim = _claim(_required(obj, "claim", "payload"))
-    evidence_raw = _list(_required(obj, "evidence", "payload"), "payload.evidence")
-    evidence = tuple(
-        _evidence(item, f"evidence[{index}]")
-        for index, item in enumerate(evidence_raw)
-    )
-    policy = _policy(_required(obj, "policy", "payload"))
-    evaluation_time = _datetime(
-        _required(obj, "evaluation_time", "payload"),
-        "payload.evaluation_time",
-    )
-    human_approved = _bool(obj.get("human_approved", False), "payload.human_approved")
-    return _result_dict(
-        verify_claim(
-            claim,
-            evidence,
-            policy=policy,
-            evaluation_time=evaluation_time,
-            human_approved=human_approved,
-        )
-    )
-
-
-def verify_compound_payload(payload: Mapping[str, Any]) -> dict[str, Any]:
-    obj = _mapping(payload, "payload")
-    claims_raw = _list(_required(obj, "claims", "payload"), "payload.claims")
-    claims = tuple(_claim(item, f"claims[{index}]") for index, item in enumerate(claims_raw))
-    claim_ids = {claim.claim_id for claim in claims}
-
-    evidence_map_raw = _mapping(
-        _required(obj, "evidence_by_claim", "payload"),
-        "payload.evidence_by_claim",
-    )
-    unknown_evidence_ids = set(evidence_map_raw) - claim_ids
-    if unknown_evidence_ids:
-        raise ValueError(
-            "evidence_by_claim contains unknown claim id: "
-            + ", ".join(sorted(unknown_evidence_ids))
-        )
-
-    evidence_by_claim = {
-        claim_id: tuple(
-            _evidence(item, f"evidence_by_claim.{claim_id}[{index}]")
-            for index, item in enumerate(
-                _list(evidence_map_raw.get(claim_id, []), f"evidence_by_claim.{claim_id}")
-            )
-        )
-        for claim_id in claim_ids
-    }
-
-    approvals_raw = _mapping(obj.get("human_approvals", {}), "payload.human_approvals")
-    unknown_approval_ids = set(approvals_raw) - claim_ids
-    if unknown_approval_ids:
-        raise ValueError(
-            "human_approvals contains unknown claim id: "
-            + ", ".join(sorted(unknown_approval_ids))
-        )
-    approvals = {
-        claim_id: _bool(value, f"human_approvals.{claim_id}")
-        for claim_id, value in approvals_raw.items()
-    }
-
-    policy = _policy(_required(obj, "policy", "payload"))
-    evaluation_time = _datetime(
-        _required(obj, "evaluation_time", "payload"),
-        "payload.evaluation_time",
-    )
-    result = verify_compound(
-        claims,
-        evidence_by_claim,
-        policy=policy,
-        evaluation_time=evaluation_time,
-        human_approvals=approvals,
-    )
-    return {
-        "schema_version": SCHEMA_VERSION,
-        "algorithm_version": ALGORITHM_VERSION,
-        "verdict": result.verdict.value,
-        "results": [_result_dict(item) for item in result.results],
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any, Mapping
+
+from .engine import (
+    ALGORITHM_VERSION,
+    AnswerabilityStatus,
+    AuthorityScope,
+    Claim,
+    ClaimType,
+    Directness,
+    Evidence,
+    EvidenceOrigin,
+    Policy,
+    RiskLevel,
+    SourceRole,
+    verify_claim,
+    verify_compound,
+)
+
+SCHEMA_VERSION = 3
+
+
+def _mapping(value: Any, path: str) -> Mapping[str, Any]:
+    if not isinstance(value, Mapping):
+        raise TypeError(f"{path} must be object")
+    return value
+
+
+def _list(value: Any, path: str) -> list[Any]:
+    if not isinstance(value, list):
+        raise TypeError(f"{path} must be list")
+    return value
+
+
+def _required(obj: Mapping[str, Any], key: str, path: str) -> Any:
+    if key not in obj:
+        raise ValueError(f"missing required field: {path}.{key}")
+    return obj[key]
+
+
+def _string(value: Any, path: str) -> str:
+    if not isinstance(value, str) or not value:
+        raise TypeError(f"{path} must be non-empty string")
+    return value
+
+
+def _optional_string(value: Any, path: str) -> str | None:
+    if value is None:
+        return None
+    return _string(value, path)
+
+
+def _bool(value: Any, path: str) -> bool:
+    if type(value) is not bool:
+        raise TypeError(f"{path} must be bool")
+    return value
+
+
+def _int(value: Any, path: str) -> int:
+    if isinstance(value, bool) or not isinstance(value, int):
+        raise TypeError(f"{path} must be int")
+    return value
+
+
+def _datetime(value: Any, path: str) -> datetime:
+    raw = _string(value, path)
+    if raw.endswith("Z"):
+        raw = raw[:-1] + "+00:00"
+    try:
+        parsed = datetime.fromisoformat(raw)
+    except ValueError as exc:
+        raise ValueError(f"{path} must be ISO 8601 datetime") from exc
+    if parsed.tzinfo is None or parsed.utcoffset() is None:
+        raise ValueError(f"{path} must be timezone-aware")
+    return parsed
+
+
+def _enum(enum_type, value: Any, path: str):
+    raw = _string(value, path)
+    try:
+        return enum_type(raw)
+    except ValueError as exc:
+        raise ValueError(f"invalid {path}: {raw}") from exc
+
+
+def _claim(raw: Any, path: str = "claim") -> Claim:
+    obj = _mapping(raw, path)
+    return Claim(
+        claim_id=_string(_required(obj, "id", path), f"{path}.id"),
+        text=_string(_required(obj, "text", path), f"{path}.text"),
+        claim_type=_enum(ClaimType, _required(obj, "type", path), f"{path}.type"),
+        risk=_enum(RiskLevel, obj.get("risk", RiskLevel.LOW.value), f"{path}.risk"),
+        consequential=_bool(obj.get("consequential", True), f"{path}.consequential"),
+        authority_scope=_enum(
+            AuthorityScope,
+            obj.get("authority_scope", AuthorityScope.EXTERNAL_FACT.value),
+            f"{path}.authority_scope",
+        ),
+        answerability=_enum(
+            AnswerabilityStatus,
+            obj.get("answerability", AnswerabilityStatus.ANSWERABLE.value),
+            f"{path}.answerability",
+        ),
+    )
+
+
+def _evidence(raw: Any, path: str) -> Evidence:
+    obj = _mapping(raw, path)
+    return Evidence(
+        source_id=_string(_required(obj, "source_id", path), f"{path}.source_id"),
+        supports=_bool(_required(obj, "supports", path), f"{path}.supports"),
+        observed_at=_datetime(_required(obj, "observed_at", path), f"{path}.observed_at"),
+        directness=_enum(Directness, _required(obj, "directness", path), f"{path}.directness"),
+        post_action=_bool(obj.get("post_action", False), f"{path}.post_action"),
+        eligible=_bool(obj.get("eligible", True), f"{path}.eligible"),
+        evidence_id=_optional_string(obj.get("evidence_id"), f"{path}.evidence_id"),
+        source_role=_enum(
+            SourceRole,
+            obj.get("source_role", SourceRole.EXTERNAL.value),
+            f"{path}.source_role",
+        ),
+        source_ref=_optional_string(obj.get("source_ref"), f"{path}.source_ref"),
+        independence_group=_optional_string(
+            obj.get("independence_group"),
+            f"{path}.independence_group",
+        ),
+        content_sha256=_optional_string(
+            obj.get("content_sha256"),
+            f"{path}.content_sha256",
+        ),
+        origin=_enum(
+            EvidenceOrigin,
+            obj.get("origin", EvidenceOrigin.EXTERNAL_SOURCE.value),
+            f"{path}.origin",
+        ),
+        authority_scope=_enum(
+            AuthorityScope,
+            obj.get("authority_scope", AuthorityScope.EXTERNAL_FACT.value),
+            f"{path}.authority_scope",
+        ),
+    )
+
+
+def _policy(raw: Any) -> Policy:
+    path = "policy"
+    obj = _mapping(raw, path)
+    return Policy(
+        version=_string(_required(obj, "version", path), "policy.version"),
+        max_age_seconds=_int(_required(obj, "max_age_seconds", path), "policy.max_age_seconds"),
+        reject_future_evidence=_bool(
+            obj.get("reject_future_evidence", True),
+            "policy.reject_future_evidence",
+        ),
+        require_independent_action_evidence=_bool(
+            obj.get("require_independent_action_evidence", True),
+            "policy.require_independent_action_evidence",
+        ),
+        medium_risk_min_independent_sources=_int(
+            obj.get("medium_risk_min_independent_sources", 2),
+            "policy.medium_risk_min_independent_sources",
+        ),
+        require_runtime_provenance=_bool(
+            obj.get("require_runtime_provenance", False),
+            "policy.require_runtime_provenance",
+        ),
+    )
+
+
+def _result_dict(result) -> dict[str, Any]:
+    return {
+        "schema_version": SCHEMA_VERSION,
+        "algorithm_version": ALGORITHM_VERSION,
+        "classification": result.classification.value,
+        "verdict": result.verdict.value,
+        "reason": result.reason,
+        "receipt": result.receipt,
+        "failure_record": result.failure_record,
+    }
+
+
+def verify_payload(payload: Mapping[str, Any]) -> dict[str, Any]:
+    obj = _mapping(payload, "payload")
+    claim = _claim(_required(obj, "claim", "payload"))
+    evidence_raw = _list(_required(obj, "evidence", "payload"), "payload.evidence")
+    evidence = tuple(
+        _evidence(item, f"evidence[{index}]")
+        for index, item in enumerate(evidence_raw)
+    )
+    policy = _policy(_required(obj, "policy", "payload"))
+    evaluation_time = _datetime(
+        _required(obj, "evaluation_time", "payload"),
+        "payload.evaluation_time",
+    )
+    human_approved = _bool(obj.get("human_approved", False), "payload.human_approved")
+    return _result_dict(
+        verify_claim(
+            claim,
+            evidence,
+            policy=policy,
+            evaluation_time=evaluation_time,
+            human_approved=human_approved,
+        )
+    )
+
+
+def verify_compound_payload(payload: Mapping[str, Any]) -> dict[str, Any]:
+    obj = _mapping(payload, "payload")
+    claims_raw = _list(_required(obj, "claims", "payload"), "payload.claims")
+    claims = tuple(_claim(item, f"claims[{index}]") for index, item in enumerate(claims_raw))
+    claim_ids = {claim.claim_id for claim in claims}
+
+    evidence_map_raw = _mapping(
+        _required(obj, "evidence_by_claim", "payload"),
+        "payload.evidence_by_claim",
+    )
+    unknown_evidence_ids = set(evidence_map_raw) - claim_ids
+    if unknown_evidence_ids:
+        raise ValueError(
+            "evidence_by_claim contains unknown claim id: "
+            + ", ".join(sorted(unknown_evidence_ids))
+        )
+
+    evidence_by_claim = {
+        claim_id: tuple(
+            _evidence(item, f"evidence_by_claim.{claim_id}[{index}]")
+            for index, item in enumerate(
+                _list(evidence_map_raw.get(claim_id, []), f"evidence_by_claim.{claim_id}")
+            )
+        )
+        for claim_id in claim_ids
+    }
+
+    approvals_raw = _mapping(obj.get("human_approvals", {}), "payload.human_approvals")
+    unknown_approval_ids = set(approvals_raw) - claim_ids
+    if unknown_approval_ids:
+        raise ValueError(
+            "human_approvals contains unknown claim id: "
+            + ", ".join(sorted(unknown_approval_ids))
+        )
+    approvals = {
+        claim_id: _bool(value, f"human_approvals.{claim_id}")
+        for claim_id, value in approvals_raw.items()
+    }
+
+    policy = _policy(_required(obj, "policy", "payload"))
+    evaluation_time = _datetime(
+        _required(obj, "evaluation_time", "payload"),
+        "payload.evaluation_time",
+    )
+    result = verify_compound(
+        claims,
+        evidence_by_claim,
+        policy=policy,
+        evaluation_time=evaluation_time,
+        human_approvals=approvals,
+    )
+    return {
+        "schema_version": SCHEMA_VERSION,
+        "algorithm_version": ALGORITHM_VERSION,
+        "verdict": result.verdict.value,
+        "results": [_result_dict(item) for item in result.results],
     }

bodulskihal_core/conversation_gate.py

@@ -1,150 +1,150 @@
-from __future__ import annotations
-
-import hashlib
-import json
-from dataclasses import dataclass
-
-
-@dataclass(frozen=True)
-class ConstraintRecord:
-    constraint_id: str
-    kind: str
-    value: str
-    active: bool = True
-    satisfied: bool = False
-    source_turn_id: str | None = None
-    priority: int = 0
-    supersedes: str | None = None
-
-    def __post_init__(self) -> None:
-        for field_name in ("constraint_id", "kind", "value"):
-            value = getattr(self, field_name)
-            if not isinstance(value, str) or not value.strip():
-                raise ValueError(f"{field_name} must be non-empty string")
-        if type(self.active) is not bool:
-            raise TypeError("constraint.active must be bool")
-        if type(self.satisfied) is not bool:
-            raise TypeError("constraint.satisfied must be bool")
-        if isinstance(self.priority, bool) or not isinstance(self.priority, int):
-            raise TypeError("constraint.priority must be int")
-        for field_name in ("source_turn_id", "supersedes"):
-            value = getattr(self, field_name)
-            if value is not None and (
-                not isinstance(value, str) or not value.strip()
-            ):
-                raise ValueError(f"{field_name} must be non-empty when supplied")
-
-
-@dataclass(frozen=True)
-class ConversationContract:
-    goal_id: str
-    referent_id: str
-    candidate_goal_id: str
-    candidate_referent_id: str
-    constraints: tuple[ConstraintRecord, ...] = ()
-
-    def __post_init__(self) -> None:
-        for field_name in (
-            "goal_id",
-            "referent_id",
-            "candidate_goal_id",
-            "candidate_referent_id",
-        ):
-            value = getattr(self, field_name)
-            if not isinstance(value, str) or not value.strip():
-                raise ValueError(f"{field_name} must be non-empty string")
-        if not isinstance(self.constraints, tuple):
-            raise TypeError("constraints must be tuple")
-        if any(not isinstance(item, ConstraintRecord) for item in self.constraints):
-            raise TypeError("constraints must contain ConstraintRecord values")
-        ids = [item.constraint_id for item in self.constraints]
-        if len(ids) != len(set(ids)):
-            raise ValueError("duplicate constraint_id")
-
-
-@dataclass(frozen=True)
-class ConversationGateResult:
-    approved: bool
-    reason: str
-    failed_constraint_ids: tuple[str, ...]
-    contract_sha256: str
-
-
-def canonical_conversation_contract_sha256(contract: ConversationContract) -> str:
-    payload = {
-        "goal_id": contract.goal_id,
-        "referent_id": contract.referent_id,
-        "candidate_goal_id": contract.candidate_goal_id,
-        "candidate_referent_id": contract.candidate_referent_id,
-        "constraints": [
-            {
-                "constraint_id": item.constraint_id,
-                "kind": item.kind,
-                "value": item.value,
-                "active": item.active,
-                "satisfied": item.satisfied,
-                "source_turn_id": item.source_turn_id,
-                "priority": item.priority,
-                "supersedes": item.supersedes,
-            }
-            for item in sorted(
-                contract.constraints,
-                key=lambda value: (value.priority, value.constraint_id),
-            )
-        ],
-    }
-    canonical = json.dumps(
-        payload,
-        sort_keys=True,
-        ensure_ascii=False,
-        separators=(",", ":"),
-    ).encode("utf-8")
-    return hashlib.sha256(canonical).hexdigest()
-
-
-def evaluate_conversation_contract(
-    contract: ConversationContract,
-) -> ConversationGateResult:
-    if not isinstance(contract, ConversationContract):
-        raise TypeError("contract must be ConversationContract")
-
-    digest = canonical_conversation_contract_sha256(contract)
-
-    if contract.candidate_goal_id != contract.goal_id:
-        return ConversationGateResult(
-            approved=False,
-            reason="goal_mismatch",
-            failed_constraint_ids=(),
-            contract_sha256=digest,
-        )
-
-    if contract.candidate_referent_id != contract.referent_id:
-        return ConversationGateResult(
-            approved=False,
-            reason="referent_mismatch",
-            failed_constraint_ids=(),
-            contract_sha256=digest,
-        )
-
-    failed = tuple(
-        item.constraint_id
-        for item in sorted(
-            contract.constraints,
-            key=lambda value: (-value.priority, value.constraint_id),
-        )
-        if item.active and not item.satisfied
-    )
-    if failed:
-        return ConversationGateResult(
-            approved=False,
-            reason="active_constraint_failed",
-            failed_constraint_ids=failed,
-            contract_sha256=digest,
-        )
-
-    return ConversationGateResult(
-        approved=True,
-        reason="conversation_contract_satisfied",
-        failed_constraint_ids=(),
-        contract_sha256=digest,
+from __future__ import annotations
+
+import hashlib
+import json
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class ConstraintRecord:
+    constraint_id: str
+    kind: str
+    value: str
+    active: bool = True
+    satisfied: bool = False
+    source_turn_id: str | None = None
+    priority: int = 0
+    supersedes: str | None = None
+
+    def __post_init__(self) -> None:
+        for field_name in ("constraint_id", "kind", "value"):
+            value = getattr(self, field_name)
+            if not isinstance(value, str) or not value.strip():
+                raise ValueError(f"{field_name} must be non-empty string")
+        if type(self.active) is not bool:
+            raise TypeError("constraint.active must be bool")
+        if type(self.satisfied) is not bool:
+            raise TypeError("constraint.satisfied must be bool")
+        if isinstance(self.priority, bool) or not isinstance(self.priority, int):
+            raise TypeError("constraint.priority must be int")
+        for field_name in ("source_turn_id", "supersedes"):
+            value = getattr(self, field_name)
+            if value is not None and (
+                not isinstance(value, str) or not value.strip()
+            ):
+                raise ValueError(f"{field_name} must be non-empty when supplied")
+
+
+@dataclass(frozen=True)
+class ConversationContract:
+    goal_id: str
+    referent_id: str
+    candidate_goal_id: str
+    candidate_referent_id: str
+    constraints: tuple[ConstraintRecord, ...] = ()
+
+    def __post_init__(self) -> None:
+        for field_name in (
+            "goal_id",
+            "referent_id",
+            "candidate_goal_id",
+            "candidate_referent_id",
+        ):
+            value = getattr(self, field_name)
+            if not isinstance(value, str) or not value.strip():
+                raise ValueError(f"{field_name} must be non-empty string")
+        if not isinstance(self.constraints, tuple):
+            raise TypeError("constraints must be tuple")
+        if any(not isinstance(item, ConstraintRecord) for item in self.constraints):
+            raise TypeError("constraints must contain ConstraintRecord values")
+        ids = [item.constraint_id for item in self.constraints]
+        if len(ids) != len(set(ids)):
+            raise ValueError("duplicate constraint_id")
+
+
+@dataclass(frozen=True)
+class ConversationGateResult:
+    approved: bool
+    reason: str
+    failed_constraint_ids: tuple[str, ...]
+    contract_sha256: str
+
+
+def canonical_conversation_contract_sha256(contract: ConversationContract) -> str:
+    payload = {
+        "goal_id": contract.goal_id,
+        "referent_id": contract.referent_id,
+        "candidate_goal_id": contract.candidate_goal_id,
+        "candidate_referent_id": contract.candidate_referent_id,
+        "constraints": [
+            {
+                "constraint_id": item.constraint_id,
+                "kind": item.kind,
+                "value": item.value,
+                "active": item.active,
+                "satisfied": item.satisfied,
+                "source_turn_id": item.source_turn_id,
+                "priority": item.priority,
+                "supersedes": item.supersedes,
+            }
+            for item in sorted(
+                contract.constraints,
+                key=lambda value: (value.priority, value.constraint_id),
+            )
+        ],
+    }
+    canonical = json.dumps(
+        payload,
+        sort_keys=True,
+        ensure_ascii=False,
+        separators=(",", ":"),
+    ).encode("utf-8")
+    return hashlib.sha256(canonical).hexdigest()
+
+
+def evaluate_conversation_contract(
+    contract: ConversationContract,
+) -> ConversationGateResult:
+    if not isinstance(contract, ConversationContract):
+        raise TypeError("contract must be ConversationContract")
+
+    digest = canonical_conversation_contract_sha256(contract)
+
+    if contract.candidate_goal_id != contract.goal_id:
+        return ConversationGateResult(
+            approved=False,
+            reason="goal_mismatch",
+            failed_constraint_ids=(),
+            contract_sha256=digest,
+        )
+
+    if contract.candidate_referent_id != contract.referent_id:
+        return ConversationGateResult(
+            approved=False,
+            reason="referent_mismatch",
+            failed_constraint_ids=(),
+            contract_sha256=digest,
+        )
+
+    failed = tuple(
+        item.constraint_id
+        for item in sorted(
+            contract.constraints,
+            key=lambda value: (-value.priority, value.constraint_id),
+        )
+        if item.active and not item.satisfied
+    )
+    if failed:
+        return ConversationGateResult(
+            approved=False,
+            reason="active_constraint_failed",
+            failed_constraint_ids=failed,
+            contract_sha256=digest,
+        )
+
+    return ConversationGateResult(
+        approved=True,
+        reason="conversation_contract_satisfied",
+        failed_constraint_ids=(),
+        contract_sha256=digest,
     )

bodulskihal_core/engine.py

@@ -1,689 +1,689 @@
-from __future__ import annotations
-
-import hashlib
-import json
-from dataclasses import dataclass
-from datetime import datetime
-from enum import Enum
-from typing import Iterable, Mapping, Sequence
-
-from .runtime_provenance import RuntimeProvenance, current_runtime_provenance
-
-ALGORITHM_VERSION = "2.1.2"
-
-
-class ClaimType(str, Enum):
-    UNCLASSIFIED = "unclassified"
-    OBSERVATION = "observation"
-    INFERENCE = "inference"
-    ESTIMATE = "estimate"
-    ACTION_STATE = "action_state"
-    RISK_SENSITIVE = "risk_sensitive"
-
-
-class Classification(str, Enum):
-    FACT = "FACT"
-    INFERENCE = "INFERENCE"
-    ESTIMATE = "ESTIMATE"
-    UNKNOWN = "UNKNOWN"
-    REFUTED = "REFUTED"
-    CONFLICT = "CONFLICT"
-
-
-class Verdict(str, Enum):
-    APPROVE = "APPROVE"
-    BLOCK = "BLOCK"
-    ESCALATE = "ESCALATE"
-
-
-class RiskLevel(str, Enum):
-    LOW = "low"
-    MEDIUM = "medium"
-    HIGH = "high"
-
-
-class Directness(str, Enum):
-    DIRECT = "direct"
-    INDIRECT = "indirect"
-
-
-class SourceRole(str, Enum):
-    EXECUTOR = "executor"
-    VERIFIER = "verifier"
-    EXTERNAL = "external"
-
-
-class EvidenceOrigin(str, Enum):
-    EXTERNAL_SOURCE = "external_source"
-    TOOL_OBSERVATION = "tool_observation"
-    COMPUTED_RESULT = "computed_result"
-    MEMORY = "memory"
-    USER_ASSERTION = "user_assertion"
-    USER_SELF_REPORT = "user_self_report"
-    USER_PREFERENCE = "user_preference"
-    USER_INSTRUCTION = "user_instruction"
-
-
-class AuthorityScope(str, Enum):
-    EXTERNAL_FACT = "external_fact"
-    SYSTEM_STATE = "system_state"
-    USER_SELF_REPORT = "user_self_report"
-    USER_PREFERENCE = "user_preference"
-    USER_INSTRUCTION = "user_instruction"
-
-
-class AnswerabilityStatus(str, Enum):
-    ANSWERABLE = "answerable"
-    PARTIALLY_ANSWERABLE = "partially_answerable"
-    UNDERSPECIFIED = "underspecified"
-    FALSE_PREMISE = "false_premise"
-    CONTRADICTORY_INPUT = "contradictory_input"
-    NEEDS_CLARIFICATION = "needs_clarification"
-    OUT_OF_SCOPE = "out_of_scope"
-
-
-@dataclass(frozen=True)
-class Claim:
-    claim_id: str
-    text: str
-    claim_type: ClaimType
-    risk: RiskLevel = RiskLevel.LOW
-    consequential: bool = True
-    authority_scope: AuthorityScope = AuthorityScope.EXTERNAL_FACT
-    answerability: AnswerabilityStatus = AnswerabilityStatus.ANSWERABLE
-
-
-@dataclass(frozen=True)
-class Evidence:
-    source_id: str
-    supports: bool
-    observed_at: datetime
-    directness: Directness
-    post_action: bool = False
-    eligible: bool = True
-    evidence_id: str | None = None
-    source_role: SourceRole = SourceRole.EXTERNAL
-    source_ref: str | None = None
-    independence_group: str | None = None
-    content_sha256: str | None = None
-    origin: EvidenceOrigin = EvidenceOrigin.EXTERNAL_SOURCE
-    authority_scope: AuthorityScope = AuthorityScope.EXTERNAL_FACT
-
-
-@dataclass(frozen=True)
-class Policy:
-    version: str
-    max_age_seconds: int
-    reject_future_evidence: bool = True
-    require_independent_action_evidence: bool = True
-    medium_risk_min_independent_sources: int = 2
-    require_runtime_provenance: bool = False
-
-
-@dataclass(frozen=True)
-class VerificationResult:
-    claim: Claim
-    classification: Classification
-    verdict: Verdict
-    reason: str
-    receipt: dict
-    failure_record: dict | None
-
-
-@dataclass(frozen=True)
-class CompoundResult:
-    results: tuple[VerificationResult, ...]
-    verdict: Verdict
-
-
-def _is_aware(value: datetime) -> bool:
-    return value.tzinfo is not None and value.utcoffset() is not None
-
-
-def _effective_evidence_id(item: Evidence) -> str:
-    return item.evidence_id or item.source_id
-
-
-def _validate_human_approval(value: bool, *, field_name: str = "human_approved") -> None:
-    if type(value) is not bool:
-        raise TypeError(f"{field_name} must be bool")
-
-
-def _validate_non_empty_string(value: object, field_name: str) -> None:
-    if not isinstance(value, str) or not value.strip():
-        raise ValueError(f"{field_name} must be non-empty string")
-
-
-def _validate_provenance_inputs(
-    claim: Claim, evidence: Sequence[Evidence], policy: Policy
-) -> None:
-    _validate_non_empty_string(claim.claim_id, "claim_id")
-    _validate_non_empty_string(claim.text, "claim.text")
-    _validate_non_empty_string(policy.version, "policy.version")
-    if not isinstance(claim.authority_scope, AuthorityScope):
-        raise TypeError("claim.authority_scope must be AuthorityScope")
-    if not isinstance(claim.answerability, AnswerabilityStatus):
-        raise TypeError("claim.answerability must be AnswerabilityStatus")
-    for item in evidence:
-        _validate_non_empty_string(item.source_id, "evidence.source_id")
-        if not isinstance(item.origin, EvidenceOrigin):
-            raise TypeError("evidence.origin must be EvidenceOrigin")
-        if not isinstance(item.authority_scope, AuthorityScope):
-            raise TypeError("evidence.authority_scope must be AuthorityScope")
-
-
-
-def _validate_common_inputs(
-    evidence: Sequence[Evidence], *, policy: Policy, evaluation_time: datetime
-) -> None:
-    if not _is_aware(evaluation_time):
-        raise ValueError("evaluation_time must be timezone-aware")
-    if policy.max_age_seconds < 0:
-        raise ValueError("max_age_seconds must be non-negative")
-    if policy.medium_risk_min_independent_sources < 1:
-        raise ValueError("medium_risk_min_independent_sources must be at least 1")
-    if type(policy.require_runtime_provenance) is not bool:
-        raise TypeError("require_runtime_provenance must be bool")
-    for item in evidence:
-        if not _is_aware(item.observed_at):
-            raise ValueError("observed_at must be timezone-aware")
-        if item.evidence_id is not None and not item.evidence_id.strip():
-            raise ValueError("evidence_id must be non-empty when supplied")
-        if item.source_ref is not None and not item.source_ref.strip():
-            raise ValueError("source_ref must be non-empty when supplied")
-        if item.independence_group is not None and not item.independence_group.strip():
-            raise ValueError("independence_group must be non-empty when supplied")
-        if item.content_sha256 is not None:
-            digest = item.content_sha256.lower()
-            if len(digest) != 64 or any(ch not in "0123456789abcdef" for ch in digest):
-                raise ValueError("content_sha256 must be a 64-character hexadecimal SHA-256")
-
-
-def _validate_evidence_gate_types(evidence: Sequence[Evidence]) -> None:
-    for item in evidence:
-        if type(item.supports) is not bool:
-            raise TypeError("evidence.supports must be bool")
-        if type(item.post_action) is not bool:
-            raise TypeError("evidence.post_action must be bool")
-        if type(item.eligible) is not bool:
-            raise TypeError("evidence.eligible must be bool")
-
-
-def _validate_evidence_identity(evidence: Sequence[Evidence]) -> None:
-    ids = [_effective_evidence_id(item) for item in evidence]
-    if len(ids) != len(set(ids)):
-        raise ValueError(
-            "duplicate evidence_id; duplicate source_id fallback identity is not allowed"
-        )
-
-
-def _is_fresh(item: Evidence, *, policy: Policy, evaluation_time: datetime) -> bool:
-    age = (evaluation_time - item.observed_at).total_seconds()
-    if policy.reject_future_evidence and age < 0:
-        return False
-    return 0 <= age <= policy.max_age_seconds
-
-
-def _eligible_evidence(
-    evidence: Sequence[Evidence], *, policy: Policy, evaluation_time: datetime
-) -> tuple[Evidence, ...]:
-    return tuple(
-        item
-        for item in evidence
-        if item.eligible and _is_fresh(item, policy=policy, evaluation_time=evaluation_time)
-    )
-
-
-_USER_ORIGINS = {
-    EvidenceOrigin.USER_ASSERTION,
-    EvidenceOrigin.USER_SELF_REPORT,
-    EvidenceOrigin.USER_PREFERENCE,
-    EvidenceOrigin.USER_INSTRUCTION,
-}
-
-
-def _authority_allows(claim: Claim, item: Evidence) -> bool:
-    if item.authority_scope is not claim.authority_scope:
-        return False
-
-    if claim.authority_scope in {AuthorityScope.EXTERNAL_FACT, AuthorityScope.SYSTEM_STATE}:
-        return item.origin in {
-            EvidenceOrigin.EXTERNAL_SOURCE,
-            EvidenceOrigin.TOOL_OBSERVATION,
-            EvidenceOrigin.COMPUTED_RESULT,
-        }
-    if claim.authority_scope is AuthorityScope.USER_PREFERENCE:
-        return item.origin in {
-            EvidenceOrigin.USER_PREFERENCE,
-            EvidenceOrigin.USER_SELF_REPORT,
-            EvidenceOrigin.TOOL_OBSERVATION,
-        }
-    if claim.authority_scope is AuthorityScope.USER_INSTRUCTION:
-        return item.origin in {
-            EvidenceOrigin.USER_INSTRUCTION,
-            EvidenceOrigin.TOOL_OBSERVATION,
-        }
-    if claim.authority_scope is AuthorityScope.USER_SELF_REPORT:
-        return item.origin in {
-            EvidenceOrigin.USER_SELF_REPORT,
-            EvidenceOrigin.TOOL_OBSERVATION,
-        }
-    return False
-
-
-def _authorized_evidence(
-    claim: Claim, evidence: Sequence[Evidence]
-) -> tuple[Evidence, ...]:
-    return tuple(item for item in evidence if _authority_allows(claim, item))
-
-
-def _classify(claim: Claim, eligible: Sequence[Evidence]) -> Classification:
-    if claim.answerability is AnswerabilityStatus.CONTRADICTORY_INPUT:
-        return Classification.CONFLICT
-    if claim.answerability is not AnswerabilityStatus.ANSWERABLE:
-        return Classification.UNKNOWN
-    if claim.claim_type is ClaimType.UNCLASSIFIED:
-        return Classification.UNKNOWN
-
-    supporting = tuple(item for item in eligible if item.supports)
-    contradicting = tuple(item for item in eligible if not item.supports)
-    if supporting and contradicting:
-        return Classification.CONFLICT
-    if contradicting:
-        return Classification.REFUTED
-    if not supporting:
-        return Classification.UNKNOWN
-
-    if claim.claim_type is ClaimType.INFERENCE:
-        return Classification.INFERENCE
-    if claim.claim_type is ClaimType.ESTIMATE:
-        return Classification.ESTIMATE
-
-    if not any(item.directness is Directness.DIRECT for item in supporting):
-        return Classification.INFERENCE
-
-    return Classification.FACT
-
-
-def _has_direct_post_action_evidence(eligible: Sequence[Evidence]) -> bool:
-    return any(
-        item.supports
-        and item.post_action
-        and item.directness is Directness.DIRECT
-        for item in eligible
-    )
-
-
-def _has_independent_post_action_evidence(eligible: Sequence[Evidence]) -> bool:
-    return any(
-        item.supports
-        and item.post_action
-        and item.directness is Directness.DIRECT
-        and item.source_role in {SourceRole.VERIFIER, SourceRole.EXTERNAL}
-        for item in eligible
-    )
-
-
-def _independent_supporting_source_count(eligible: Sequence[Evidence]) -> int:
-    # Extra metadata may join known identities, never split the same provenance.
-    # Connected components preserve overlap transitively, regardless of input order.
-    parents: list[int] = []
-    seen: dict[tuple[str, str], int] = {}
-
-    def root(index: int) -> int:
-        while parents[index] != index:
-            parents[index] = parents[parents[index]]
-            index = parents[index]
-        return index
-
-    for item in eligible:
-        if not (
-            item.supports
-            and item.directness is Directness.DIRECT
-            and item.source_role in {SourceRole.VERIFIER, SourceRole.EXTERNAL}
-        ):
-            continue
-        index = len(parents)
-        parents.append(index)
-        identities = [("source", item.source_id.strip())]
-        if item.source_ref is not None:
-            identities.append(("ref", item.source_ref.strip()))
-        if item.independence_group is not None:
-            identities.append(("group", item.independence_group.strip()))
-        if item.content_sha256 is not None:
-            identities.append(("content", item.content_sha256.lower()))
-        for identity in identities:
-            previous = seen.setdefault(identity, index)
-            parents[root(index)] = root(previous)
-
-    return len({root(index) for index in range(len(parents))})
-
-
-def _decide_verdict(
-    claim: Claim,
-    classification: Classification,
-    eligible: Sequence[Evidence],
-    *,
-    policy: Policy,
-    human_approved: bool,
-    authority_rejected: bool = False,
-    runtime_provenance_verified: bool = False,
-) -> tuple[Verdict, str]:
-    if policy.require_runtime_provenance and not runtime_provenance_verified:
-        return Verdict.BLOCK, "runtime_provenance_unverified"
-
-    if claim.answerability is AnswerabilityStatus.NEEDS_CLARIFICATION:
-        return Verdict.ESCALATE, "answerability_needs_clarification"
-    if claim.answerability is not AnswerabilityStatus.ANSWERABLE:
-        return Verdict.BLOCK, f"answerability_{claim.answerability.value}"
-    if claim.claim_type is ClaimType.UNCLASSIFIED:
-        return Verdict.BLOCK, "unclassified_claim"
-
-    if classification is Classification.CONFLICT:
-        return Verdict.BLOCK, "eligible_contradiction"
-    if classification is Classification.REFUTED:
-        return Verdict.BLOCK, "claim_refuted_by_eligible_evidence"
-    if classification is Classification.UNKNOWN:
-        if authority_rejected:
-            return Verdict.BLOCK, "insufficient_authorized_evidence"
-        return Verdict.BLOCK, "insufficient_eligible_evidence"
-    if classification is Classification.INFERENCE:
-        return Verdict.BLOCK, "inference_not_fact"
-    if classification is Classification.ESTIMATE:
-        return Verdict.BLOCK, "estimate_not_fact"
-
-    if claim.claim_type is ClaimType.ACTION_STATE:
-        if not _has_direct_post_action_evidence(eligible):
-            return Verdict.BLOCK, "missing_post_action_final_state_evidence"
-        if (
-            policy.require_independent_action_evidence
-            and not _has_independent_post_action_evidence(eligible)
-        ):
-            return Verdict.BLOCK, "missing_independent_post_action_evidence"
-
-    if (
-        claim.risk is RiskLevel.MEDIUM
-        and _independent_supporting_source_count(eligible)
-        < policy.medium_risk_min_independent_sources
-    ):
-        return Verdict.ESCALATE, "additional_independent_evidence_required"
-
-    if claim.risk is RiskLevel.HIGH and not human_approved:
-        return Verdict.ESCALATE, "human_approval_required"
-
-    return Verdict.APPROVE, "fact_with_required_gates"
-
-
-def _iso(value: datetime) -> str:
-    return value.isoformat()
-
-
-def _make_failure_record(claim: Claim, verdict: Verdict, reason: str) -> dict | None:
-    if verdict is Verdict.APPROVE:
-        return None
-    return {
-        "record_type": "expected_gate",
-        "claim_id": claim.claim_id,
-        "failure_mode": reason,
-        "root_cause": "verification_gate_not_satisfied",
-        "guardrail": f"preserve_{verdict.value.lower()}_until_new_eligible_evidence_or_required_approval",
-        "regression_test_required": False,
-        "version_change_required": False,
-    }
-
-
-def make_failure_evolution_record(
-    *,
-    failure_mode: str,
-    root_cause: str,
-    guardrail: str,
-    regression_test: str,
-) -> dict:
-    fields = {
-        "failure_mode": failure_mode,
-        "root_cause": root_cause,
-        "guardrail": guardrail,
-        "regression_test": regression_test,
-    }
-    for name, value in fields.items():
-        if not isinstance(value, str) or not value.strip():
-            raise ValueError(f"{name} must be non-empty")
-    return {
-        "record_type": "failure_evolution",
-        "failure_mode": failure_mode.strip(),
-        "root_cause": root_cause.strip(),
-        "guardrail": guardrail.strip(),
-        "regression_test": regression_test.strip(),
-        "regression_test_required": True,
-        "version_change_required": True,
-    }
-
-
-def canonical_receipt_sha256(receipt: Mapping) -> str:
-    payload = {
-        key: value
-        for key, value in receipt.items()
-        if key != "receipt_sha256"
-    }
-    canonical = json.dumps(
-        payload,
-        sort_keys=True,
-        separators=(",", ":"),
-        ensure_ascii=False,
-    ).encode("utf-8")
-    return hashlib.sha256(canonical).hexdigest()
-
-
-def _make_receipt(
-    *,
-    claim: Claim,
-    policy: Policy,
-    evaluation_time: datetime,
-    all_evidence: Sequence[Evidence],
-    eligible: Sequence[Evidence],
-    classification: Classification,
-    verdict: Verdict,
-    reason: str,
-    human_approved: bool,
-    authority_rejected: Sequence[Evidence] = (),
-    runtime_provenance: RuntimeProvenance | None = None,
-) -> dict:
-    eligible_ids = {_effective_evidence_id(item) for item in eligible}
-    sorted_all = sorted(
-        all_evidence,
-        key=lambda item: (_effective_evidence_id(item), item.source_id),
-    )
-
-    supporting_sources = sorted(item.source_id for item in eligible if item.supports)
-    contradicting_sources = sorted(item.source_id for item in eligible if not item.supports)
-    supporting_evidence_ids = sorted(
-        _effective_evidence_id(item) for item in eligible if item.supports
-    )
-    contradicting_evidence_ids = sorted(
-        _effective_evidence_id(item) for item in eligible if not item.supports
-    )
-    if claim.risk is RiskLevel.HIGH:
-        human_gate = "approved" if human_approved else "required"
-    else:
-        human_gate = "not_required"
-
-    receipt = {
-        "algorithm_version": ALGORITHM_VERSION,
-        "policy_version": policy.version,
-        "evaluation_time": _iso(evaluation_time),
-        "claim": {
-            "id": claim.claim_id,
-            "text": claim.text,
-            "type": claim.claim_type.value,
-            "risk": claim.risk.value,
-            "consequential": claim.consequential,
-            "authority_scope": claim.authority_scope.value,
-            "answerability": claim.answerability.value,
-        },
-        "classification": classification.value,
-        "verdict": verdict.value,
-        "reason": reason,
-        "human_approved": human_approved,
-        "runtime_provenance": (
-            runtime_provenance.as_dict()
-            if runtime_provenance is not None
-            else current_runtime_provenance().as_dict()
-        ),
-        "gates": {
-            "eligible_source_count": len(eligible),
-            "supporting_sources": supporting_sources,
-            "contradicting_sources": contradicting_sources,
-            "supporting_evidence_ids": supporting_evidence_ids,
-            "contradicting_evidence_ids": contradicting_evidence_ids,
-            "contradiction_count": len(contradicting_evidence_ids),
-            "authority_rejected_evidence_ids": sorted(
-                _effective_evidence_id(item) for item in authority_rejected
-            ),
-            "post_action_verified": (
-                _has_direct_post_action_evidence(eligible)
-                if claim.claim_type is ClaimType.ACTION_STATE
-                else None
-            ),
-            "independent_post_action_verified": (
-                _has_independent_post_action_evidence(eligible)
-                if claim.claim_type is ClaimType.ACTION_STATE
-                else None
-            ),
-            "independent_supporting_source_count": _independent_supporting_source_count(eligible),
-            "independent_supporting_group_count": _independent_supporting_source_count(eligible),
-            "medium_risk_required_sources": (
-                policy.medium_risk_min_independent_sources
-                if claim.risk is RiskLevel.MEDIUM
-                else None
-            ),
-            "human_gate": human_gate,
-            "runtime_provenance_required": policy.require_runtime_provenance,
-        },
-        "evidence": [
-            {
-                "evidence_id": _effective_evidence_id(item),
-                "source_id": item.source_id,
-                "source_role": item.source_role.value,
-                "source_ref": item.source_ref,
-                "independence_group": item.independence_group,
-                "content_sha256": (
-                    item.content_sha256.lower()
-                    if item.content_sha256 is not None
-                    else None
-                ),
-                "origin": item.origin.value,
-                "authority_scope": item.authority_scope.value,
-                "supports": item.supports,
-                "observed_at": _iso(item.observed_at),
-                "directness": item.directness.value,
-                "post_action": item.post_action,
-                "caller_eligible": item.eligible,
-                "eligible_at_evaluation": _effective_evidence_id(item) in eligible_ids,
-            }
-            for item in sorted_all
-        ],
-    }
-    receipt["receipt_sha256"] = canonical_receipt_sha256(receipt)
-    return receipt
-
-
-def verify_claim(
-    claim: Claim,
-    evidence: Iterable[Evidence],
-    *,
-    policy: Policy,
-    evaluation_time: datetime,
-    human_approved: bool = False,
-) -> VerificationResult:
-    _validate_human_approval(human_approved)
-    evidence_seq = tuple(evidence)
-    _validate_provenance_inputs(claim, evidence_seq, policy)
-    _validate_evidence_gate_types(evidence_seq)
-    _validate_evidence_identity(evidence_seq)
-    _validate_common_inputs(evidence_seq, policy=policy, evaluation_time=evaluation_time)
-
-    fresh_eligible = _eligible_evidence(
-        evidence_seq,
-        policy=policy,
-        evaluation_time=evaluation_time,
-    )
-    eligible = _authorized_evidence(claim, fresh_eligible)
-    authority_rejected = tuple(
-        item for item in fresh_eligible if item not in eligible
-    )
-    runtime_provenance = current_runtime_provenance()
-    classification = _classify(claim, eligible)
-    verdict, reason = _decide_verdict(
-        claim,
-        classification,
-        eligible,
-        policy=policy,
-        human_approved=human_approved,
-        authority_rejected=bool(authority_rejected),
-        runtime_provenance_verified=runtime_provenance.verified,
-    )
-    receipt = _make_receipt(
-        claim=claim,
-        policy=policy,
-        evaluation_time=evaluation_time,
-        all_evidence=evidence_seq,
-        eligible=eligible,
-        classification=classification,
-        verdict=verdict,
-        reason=reason,
-        human_approved=human_approved,
-        authority_rejected=authority_rejected,
-        runtime_provenance=runtime_provenance,
-    )
-    failure_record = _make_failure_record(claim, verdict, reason)
-    return VerificationResult(
-        claim=claim,
-        classification=classification,
-        verdict=verdict,
-        reason=reason,
-        receipt=receipt,
-        failure_record=failure_record,
-    )
-
-
-def verify_compound(
-    claims: Sequence[Claim],
-    evidence_by_claim: Mapping[str, Iterable[Evidence]],
-    *,
-    policy: Policy,
-    evaluation_time: datetime,
-    human_approvals: Mapping[str, bool] | None = None,
-) -> CompoundResult:
-    if not claims:
-        raise ValueError("at least one claim is required")
-    claim_ids = [claim.claim_id for claim in claims]
-    if len(claim_ids) != len(set(claim_ids)):
-        raise ValueError("duplicate claim_id")
-
-    approvals = human_approvals or {}
-    for approval_claim_id, approval in approvals.items():
-        _validate_human_approval(
-            approval,
-            field_name=f"human approval for {approval_claim_id}",
-        )
-
-    results = tuple(
-        verify_claim(
-            claim,
-            evidence_by_claim.get(claim.claim_id, ()),
-            policy=policy,
-            evaluation_time=evaluation_time,
-            human_approved=approvals.get(claim.claim_id, False),
-        )
-        for claim in claims
-    )
-
-    consequential = [result for result in results if result.claim.consequential]
-    if any(result.verdict is Verdict.ESCALATE for result in consequential):
-        overall = Verdict.ESCALATE
-    elif any(result.verdict is not Verdict.APPROVE for result in consequential):
-        overall = Verdict.BLOCK
-    else:
-        overall = Verdict.APPROVE
-
+from __future__ import annotations
+
+import hashlib
+import json
+from dataclasses import dataclass
+from datetime import datetime
+from enum import Enum
+from typing import Iterable, Mapping, Sequence
+
+from .runtime_provenance import RuntimeProvenance, current_runtime_provenance
+
+ALGORITHM_VERSION = "2.1.2"
+
+
+class ClaimType(str, Enum):
+    UNCLASSIFIED = "unclassified"
+    OBSERVATION = "observation"
+    INFERENCE = "inference"
+    ESTIMATE = "estimate"
+    ACTION_STATE = "action_state"
+    RISK_SENSITIVE = "risk_sensitive"
+
+
+class Classification(str, Enum):
+    FACT = "FACT"
+    INFERENCE = "INFERENCE"
+    ESTIMATE = "ESTIMATE"
+    UNKNOWN = "UNKNOWN"
+    REFUTED = "REFUTED"
+    CONFLICT = "CONFLICT"
+
+
+class Verdict(str, Enum):
+    APPROVE = "APPROVE"
+    BLOCK = "BLOCK"
+    ESCALATE = "ESCALATE"
+
+
+class RiskLevel(str, Enum):
+    LOW = "low"
+    MEDIUM = "medium"
+    HIGH = "high"
+
+
+class Directness(str, Enum):
+    DIRECT = "direct"
+    INDIRECT = "indirect"
+
+
+class SourceRole(str, Enum):
+    EXECUTOR = "executor"
+    VERIFIER = "verifier"
+    EXTERNAL = "external"
+
+
+class EvidenceOrigin(str, Enum):
+    EXTERNAL_SOURCE = "external_source"
+    TOOL_OBSERVATION = "tool_observation"
+    COMPUTED_RESULT = "computed_result"
+    MEMORY = "memory"
+    USER_ASSERTION = "user_assertion"
+    USER_SELF_REPORT = "user_self_report"
+    USER_PREFERENCE = "user_preference"
+    USER_INSTRUCTION = "user_instruction"
+
+
+class AuthorityScope(str, Enum):
+    EXTERNAL_FACT = "external_fact"
+    SYSTEM_STATE = "system_state"
+    USER_SELF_REPORT = "user_self_report"
+    USER_PREFERENCE = "user_preference"
+    USER_INSTRUCTION = "user_instruction"
+
+
+class AnswerabilityStatus(str, Enum):
+    ANSWERABLE = "answerable"
+    PARTIALLY_ANSWERABLE = "partially_answerable"
+    UNDERSPECIFIED = "underspecified"
+    FALSE_PREMISE = "false_premise"
+    CONTRADICTORY_INPUT = "contradictory_input"
+    NEEDS_CLARIFICATION = "needs_clarification"
+    OUT_OF_SCOPE = "out_of_scope"
+
+
+@dataclass(frozen=True)
+class Claim:
+    claim_id: str
+    text: str
+    claim_type: ClaimType
+    risk: RiskLevel = RiskLevel.LOW
+    consequential: bool = True
+    authority_scope: AuthorityScope = AuthorityScope.EXTERNAL_FACT
+    answerability: AnswerabilityStatus = AnswerabilityStatus.ANSWERABLE
+
+
+@dataclass(frozen=True)
+class Evidence:
+    source_id: str
+    supports: bool
+    observed_at: datetime
+    directness: Directness
+    post_action: bool = False
+    eligible: bool = True
+    evidence_id: str | None = None
+    source_role: SourceRole = SourceRole.EXTERNAL
+    source_ref: str | None = None
+    independence_group: str | None = None
+    content_sha256: str | None = None
+    origin: EvidenceOrigin = EvidenceOrigin.EXTERNAL_SOURCE
+    authority_scope: AuthorityScope = AuthorityScope.EXTERNAL_FACT
+
+
+@dataclass(frozen=True)
+class Policy:
+    version: str
+    max_age_seconds: int
+    reject_future_evidence: bool = True
+    require_independent_action_evidence: bool = True
+    medium_risk_min_independent_sources: int = 2
+    require_runtime_provenance: bool = False
+
+
+@dataclass(frozen=True)
+class VerificationResult:
+    claim: Claim
+    classification: Classification
+    verdict: Verdict
+    reason: str
+    receipt: dict
+    failure_record: dict | None
+
+
+@dataclass(frozen=True)
+class CompoundResult:
+    results: tuple[VerificationResult, ...]
+    verdict: Verdict
+
+
+def _is_aware(value: datetime) -> bool:
+    return value.tzinfo is not None and value.utcoffset() is not None
+
+
+def _effective_evidence_id(item: Evidence) -> str:
+    return item.evidence_id or item.source_id
+
+
+def _validate_human_approval(value: bool, *, field_name: str = "human_approved") -> None:
+    if type(value) is not bool:
+        raise TypeError(f"{field_name} must be bool")
+
+
+def _validate_non_empty_string(value: object, field_name: str) -> None:
+    if not isinstance(value, str) or not value.strip():
+        raise ValueError(f"{field_name} must be non-empty string")
+
+
+def _validate_provenance_inputs(
+    claim: Claim, evidence: Sequence[Evidence], policy: Policy
+) -> None:
+    _validate_non_empty_string(claim.claim_id, "claim_id")
+    _validate_non_empty_string(claim.text, "claim.text")
+    _validate_non_empty_string(policy.version, "policy.version")
+    if not isinstance(claim.authority_scope, AuthorityScope):
+        raise TypeError("claim.authority_scope must be AuthorityScope")
+    if not isinstance(claim.answerability, AnswerabilityStatus):
+        raise TypeError("claim.answerability must be AnswerabilityStatus")
+    for item in evidence:
+        _validate_non_empty_string(item.source_id, "evidence.source_id")
+        if not isinstance(item.origin, EvidenceOrigin):
+            raise TypeError("evidence.origin must be EvidenceOrigin")
+        if not isinstance(item.authority_scope, AuthorityScope):
+            raise TypeError("evidence.authority_scope must be AuthorityScope")
+
+
+
+def _validate_common_inputs(
+    evidence: Sequence[Evidence], *, policy: Policy, evaluation_time: datetime
+) -> None:
+    if not _is_aware(evaluation_time):
+        raise ValueError("evaluation_time must be timezone-aware")
+    if policy.max_age_seconds < 0:
+        raise ValueError("max_age_seconds must be non-negative")
+    if policy.medium_risk_min_independent_sources < 1:
+        raise ValueError("medium_risk_min_independent_sources must be at least 1")
+    if type(policy.require_runtime_provenance) is not bool:
+        raise TypeError("require_runtime_provenance must be bool")
+    for item in evidence:
+        if not _is_aware(item.observed_at):
+            raise ValueError("observed_at must be timezone-aware")
+        if item.evidence_id is not None and not item.evidence_id.strip():
+            raise ValueError("evidence_id must be non-empty when supplied")
+        if item.source_ref is not None and not item.source_ref.strip():
+            raise ValueError("source_ref must be non-empty when supplied")
+        if item.independence_group is not None and not item.independence_group.strip():
+            raise ValueError("independence_group must be non-empty when supplied")
+        if item.content_sha256 is not None:
+            digest = item.content_sha256.lower()
+            if len(digest) != 64 or any(ch not in "0123456789abcdef" for ch in digest):
+                raise ValueError("content_sha256 must be a 64-character hexadecimal SHA-256")
+
+
+def _validate_evidence_gate_types(evidence: Sequence[Evidence]) -> None:
+    for item in evidence:
+        if type(item.supports) is not bool:
+            raise TypeError("evidence.supports must be bool")
+        if type(item.post_action) is not bool:
+            raise TypeError("evidence.post_action must be bool")
+        if type(item.eligible) is not bool:
+            raise TypeError("evidence.eligible must be bool")
+
+
+def _validate_evidence_identity(evidence: Sequence[Evidence]) -> None:
+    ids = [_effective_evidence_id(item) for item in evidence]
+    if len(ids) != len(set(ids)):
+        raise ValueError(
+            "duplicate evidence_id; duplicate source_id fallback identity is not allowed"
+        )
+
+
+def _is_fresh(item: Evidence, *, policy: Policy, evaluation_time: datetime) -> bool:
+    age = (evaluation_time - item.observed_at).total_seconds()
+    if policy.reject_future_evidence and age < 0:
+        return False
+    return 0 <= age <= policy.max_age_seconds
+
+
+def _eligible_evidence(
+    evidence: Sequence[Evidence], *, policy: Policy, evaluation_time: datetime
+) -> tuple[Evidence, ...]:
+    return tuple(
+        item
+        for item in evidence
+        if item.eligible and _is_fresh(item, policy=policy, evaluation_time=evaluation_time)
+    )
+
+
+_USER_ORIGINS = {
+    EvidenceOrigin.USER_ASSERTION,
+    EvidenceOrigin.USER_SELF_REPORT,
+    EvidenceOrigin.USER_PREFERENCE,
+    EvidenceOrigin.USER_INSTRUCTION,
+}
+
+
+def _authority_allows(claim: Claim, item: Evidence) -> bool:
+    if item.authority_scope is not claim.authority_scope:
+        return False
+
+    if claim.authority_scope in {AuthorityScope.EXTERNAL_FACT, AuthorityScope.SYSTEM_STATE}:
+        return item.origin in {
+            EvidenceOrigin.EXTERNAL_SOURCE,
+            EvidenceOrigin.TOOL_OBSERVATION,
+            EvidenceOrigin.COMPUTED_RESULT,
+        }
+    if claim.authority_scope is AuthorityScope.USER_PREFERENCE:
+        return item.origin in {
+            EvidenceOrigin.USER_PREFERENCE,
+            EvidenceOrigin.USER_SELF_REPORT,
+            EvidenceOrigin.TOOL_OBSERVATION,
+        }
+    if claim.authority_scope is AuthorityScope.USER_INSTRUCTION:
+        return item.origin in {
+            EvidenceOrigin.USER_INSTRUCTION,
+            EvidenceOrigin.TOOL_OBSERVATION,
+        }
+    if claim.authority_scope is AuthorityScope.USER_SELF_REPORT:
+        return item.origin in {
+            EvidenceOrigin.USER_SELF_REPORT,
+            EvidenceOrigin.TOOL_OBSERVATION,
+        }
+    return False
+
+
+def _authorized_evidence(
+    claim: Claim, evidence: Sequence[Evidence]
+) -> tuple[Evidence, ...]:
+    return tuple(item for item in evidence if _authority_allows(claim, item))
+
+
+def _classify(claim: Claim, eligible: Sequence[Evidence]) -> Classification:
+    if claim.answerability is AnswerabilityStatus.CONTRADICTORY_INPUT:
+        return Classification.CONFLICT
+    if claim.answerability is not AnswerabilityStatus.ANSWERABLE:
+        return Classification.UNKNOWN
+    if claim.claim_type is ClaimType.UNCLASSIFIED:
+        return Classification.UNKNOWN
+
+    supporting = tuple(item for item in eligible if item.supports)
+    contradicting = tuple(item for item in eligible if not item.supports)
+    if supporting and contradicting:
+        return Classification.CONFLICT
+    if contradicting:
+        return Classification.REFUTED
+    if not supporting:
+        return Classification.UNKNOWN
+
+    if claim.claim_type is ClaimType.INFERENCE:
+        return Classification.INFERENCE
+    if claim.claim_type is ClaimType.ESTIMATE:
+        return Classification.ESTIMATE
+
+    if not any(item.directness is Directness.DIRECT for item in supporting):
+        return Classification.INFERENCE
+
+    return Classification.FACT
+
+
+def _has_direct_post_action_evidence(eligible: Sequence[Evidence]) -> bool:
+    return any(
+        item.supports
+        and item.post_action
+        and item.directness is Directness.DIRECT
+        for item in eligible
+    )
+
+
+def _has_independent_post_action_evidence(eligible: Sequence[Evidence]) -> bool:
+    return any(
+        item.supports
+        and item.post_action
+        and item.directness is Directness.DIRECT
+        and item.source_role in {SourceRole.VERIFIER, SourceRole.EXTERNAL}
+        for item in eligible
+    )
+
+
+def _independent_supporting_source_count(eligible: Sequence[Evidence]) -> int:
+    # Extra metadata may join known identities, never split the same provenance.
+    # Connected components preserve overlap transitively, regardless of input order.
+    parents: list[int] = []
+    seen: dict[tuple[str, str], int] = {}
+
+    def root(index: int) -> int:
+        while parents[index] != index:
+            parents[index] = parents[parents[index]]
+            index = parents[index]
+        return index
+
+    for item in eligible:
+        if not (
+            item.supports
+            and item.directness is Directness.DIRECT
+            and item.source_role in {SourceRole.VERIFIER, SourceRole.EXTERNAL}
+        ):
+            continue
+        index = len(parents)
+        parents.append(index)
+        identities = [("source", item.source_id.strip())]
+        if item.source_ref is not None:
+            identities.append(("ref", item.source_ref.strip()))
+        if item.independence_group is not None:
+            identities.append(("group", item.independence_group.strip()))
+        if item.content_sha256 is not None:
+            identities.append(("content", item.content_sha256.lower()))
+        for identity in identities:
+            previous = seen.setdefault(identity, index)
+            parents[root(index)] = root(previous)
+
+    return len({root(index) for index in range(len(parents))})
+
+
+def _decide_verdict(
+    claim: Claim,
+    classification: Classification,
+    eligible: Sequence[Evidence],
+    *,
+    policy: Policy,
+    human_approved: bool,
+    authority_rejected: bool = False,
+    runtime_provenance_verified: bool = False,
+) -> tuple[Verdict, str]:
+    if policy.require_runtime_provenance and not runtime_provenance_verified:
+        return Verdict.BLOCK, "runtime_provenance_unverified"
+
+    if claim.answerability is AnswerabilityStatus.NEEDS_CLARIFICATION:
+        return Verdict.ESCALATE, "answerability_needs_clarification"
+    if claim.answerability is not AnswerabilityStatus.ANSWERABLE:
+        return Verdict.BLOCK, f"answerability_{claim.answerability.value}"
+    if claim.claim_type is ClaimType.UNCLASSIFIED:
+        return Verdict.BLOCK, "unclassified_claim"
+
+    if classification is Classification.CONFLICT:
+        return Verdict.BLOCK, "eligible_contradiction"
+    if classification is Classification.REFUTED:
+        return Verdict.BLOCK, "claim_refuted_by_eligible_evidence"
+    if classification is Classification.UNKNOWN:
+        if authority_rejected:
+            return Verdict.BLOCK, "insufficient_authorized_evidence"
+        return Verdict.BLOCK, "insufficient_eligible_evidence"
+    if classification is Classification.INFERENCE:
+        return Verdict.BLOCK, "inference_not_fact"
+    if classification is Classification.ESTIMATE:
+        return Verdict.BLOCK, "estimate_not_fact"
+
+    if claim.claim_type is ClaimType.ACTION_STATE:
+        if not _has_direct_post_action_evidence(eligible):
+            return Verdict.BLOCK, "missing_post_action_final_state_evidence"
+        if (
+            policy.require_independent_action_evidence
+            and not _has_independent_post_action_evidence(eligible)
+        ):
+            return Verdict.BLOCK, "missing_independent_post_action_evidence"
+
+    if (
+        claim.risk is RiskLevel.MEDIUM
+        and _independent_supporting_source_count(eligible)
+        < policy.medium_risk_min_independent_sources
+    ):
+        return Verdict.ESCALATE, "additional_independent_evidence_required"
+
+    if claim.risk is RiskLevel.HIGH and not human_approved:
+        return Verdict.ESCALATE, "human_approval_required"
+
+    return Verdict.APPROVE, "fact_with_required_gates"
+
+
+def _iso(value: datetime) -> str:
+    return value.isoformat()
+
+
+def _make_failure_record(claim: Claim, verdict: Verdict, reason: str) -> dict | None:
+    if verdict is Verdict.APPROVE:
+        return None
+    return {
+        "record_type": "expected_gate",
+        "claim_id": claim.claim_id,
+        "failure_mode": reason,
+        "root_cause": "verification_gate_not_satisfied",
+        "guardrail": f"preserve_{verdict.value.lower()}_until_new_eligible_evidence_or_required_approval",
+        "regression_test_required": False,
+        "version_change_required": False,
+    }
+
+
+def make_failure_evolution_record(
+    *,
+    failure_mode: str,
+    root_cause: str,
+    guardrail: str,
+    regression_test: str,
+) -> dict:
+    fields = {
+        "failure_mode": failure_mode,
+        "root_cause": root_cause,
+        "guardrail": guardrail,
+        "regression_test": regression_test,
+    }
+    for name, value in fields.items():
+        if not isinstance(value, str) or not value.strip():
+            raise ValueError(f"{name} must be non-empty")
+    return {
+        "record_type": "failure_evolution",
+        "failure_mode": failure_mode.strip(),
+        "root_cause": root_cause.strip(),
+        "guardrail": guardrail.strip(),
+        "regression_test": regression_test.strip(),
+        "regression_test_required": True,
+        "version_change_required": True,
+    }
+
+
+def canonical_receipt_sha256(receipt: Mapping) -> str:
+    payload = {
+        key: value
+        for key, value in receipt.items()
+        if key != "receipt_sha256"
+    }
+    canonical = json.dumps(
+        payload,
+        sort_keys=True,
+        separators=(",", ":"),
+        ensure_ascii=False,
+    ).encode("utf-8")
+    return hashlib.sha256(canonical).hexdigest()
+
+
+def _make_receipt(
+    *,
+    claim: Claim,
+    policy: Policy,
+    evaluation_time: datetime,
+    all_evidence: Sequence[Evidence],
+    eligible: Sequence[Evidence],
+    classification: Classification,
+    verdict: Verdict,
+    reason: str,
+    human_approved: bool,
+    authority_rejected: Sequence[Evidence] = (),
+    runtime_provenance: RuntimeProvenance | None = None,
+) -> dict:
+    eligible_ids = {_effective_evidence_id(item) for item in eligible}
+    sorted_all = sorted(
+        all_evidence,
+        key=lambda item: (_effective_evidence_id(item), item.source_id),
+    )
+
+    supporting_sources = sorted(item.source_id for item in eligible if item.supports)
+    contradicting_sources = sorted(item.source_id for item in eligible if not item.supports)
+    supporting_evidence_ids = sorted(
+        _effective_evidence_id(item) for item in eligible if item.supports
+    )
+    contradicting_evidence_ids = sorted(
+        _effective_evidence_id(item) for item in eligible if not item.supports
+    )
+    if claim.risk is RiskLevel.HIGH:
+        human_gate = "approved" if human_approved else "required"
+    else:
+        human_gate = "not_required"
+
+    receipt = {
+        "algorithm_version": ALGORITHM_VERSION,
+        "policy_version": policy.version,
+        "evaluation_time": _iso(evaluation_time),
+        "claim": {
+            "id": claim.claim_id,
+            "text": claim.text,
+            "type": claim.claim_type.value,
+            "risk": claim.risk.value,
+            "consequential": claim.consequential,
+            "authority_scope": claim.authority_scope.value,
+            "answerability": claim.answerability.value,
+        },
+        "classification": classification.value,
+        "verdict": verdict.value,
+        "reason": reason,
+        "human_approved": human_approved,
+        "runtime_provenance": (
+            runtime_provenance.as_dict()
+            if runtime_provenance is not None
+            else current_runtime_provenance().as_dict()
+        ),
+        "gates": {
+            "eligible_source_count": len(eligible),
+            "supporting_sources": supporting_sources,
+            "contradicting_sources": contradicting_sources,
+            "supporting_evidence_ids": supporting_evidence_ids,
+            "contradicting_evidence_ids": contradicting_evidence_ids,
+            "contradiction_count": len(contradicting_evidence_ids),
+            "authority_rejected_evidence_ids": sorted(
+                _effective_evidence_id(item) for item in authority_rejected
+            ),
+            "post_action_verified": (
+                _has_direct_post_action_evidence(eligible)
+                if claim.claim_type is ClaimType.ACTION_STATE
+                else None
+            ),
+            "independent_post_action_verified": (
+                _has_independent_post_action_evidence(eligible)
+                if claim.claim_type is ClaimType.ACTION_STATE
+                else None
+            ),
+            "independent_supporting_source_count": _independent_supporting_source_count(eligible),
+            "independent_supporting_group_count": _independent_supporting_source_count(eligible),
+            "medium_risk_required_sources": (
+                policy.medium_risk_min_independent_sources
+                if claim.risk is RiskLevel.MEDIUM
+                else None
+            ),
+            "human_gate": human_gate,
+            "runtime_provenance_required": policy.require_runtime_provenance,
+        },
+        "evidence": [
+            {
+                "evidence_id": _effective_evidence_id(item),
+                "source_id": item.source_id,
+                "source_role": item.source_role.value,
+                "source_ref": item.source_ref,
+                "independence_group": item.independence_group,
+                "content_sha256": (
+                    item.content_sha256.lower()
+                    if item.content_sha256 is not None
+                    else None
+                ),
+                "origin": item.origin.value,
+                "authority_scope": item.authority_scope.value,
+                "supports": item.supports,
+                "observed_at": _iso(item.observed_at),
+                "directness": item.directness.value,
+                "post_action": item.post_action,
+                "caller_eligible": item.eligible,
+                "eligible_at_evaluation": _effective_evidence_id(item) in eligible_ids,
+            }
+            for item in sorted_all
+        ],
+    }
+    receipt["receipt_sha256"] = canonical_receipt_sha256(receipt)
+    return receipt
+
+
+def verify_claim(
+    claim: Claim,
+    evidence: Iterable[Evidence],
+    *,
+    policy: Policy,
+    evaluation_time: datetime,
+    human_approved: bool = False,
+) -> VerificationResult:
+    _validate_human_approval(human_approved)
+    evidence_seq = tuple(evidence)
+    _validate_provenance_inputs(claim, evidence_seq, policy)
+    _validate_evidence_gate_types(evidence_seq)
+    _validate_evidence_identity(evidence_seq)
+    _validate_common_inputs(evidence_seq, policy=policy, evaluation_time=evaluation_time)
+
+    fresh_eligible = _eligible_evidence(
+        evidence_seq,
+        policy=policy,
+        evaluation_time=evaluation_time,
+    )
+    eligible = _authorized_evidence(claim, fresh_eligible)
+    authority_rejected = tuple(
+        item for item in fresh_eligible if item not in eligible
+    )
+    runtime_provenance = current_runtime_provenance()
+    classification = _classify(claim, eligible)
+    verdict, reason = _decide_verdict(
+        claim,
+        classification,
+        eligible,
+        policy=policy,
+        human_approved=human_approved,
+        authority_rejected=bool(authority_rejected),
+        runtime_provenance_verified=runtime_provenance.verified,
+    )
+    receipt = _make_receipt(
+        claim=claim,
+        policy=policy,
+        evaluation_time=evaluation_time,
+        all_evidence=evidence_seq,
+        eligible=eligible,
+        classification=classification,
+        verdict=verdict,
+        reason=reason,
+        human_approved=human_approved,
+        authority_rejected=authority_rejected,
+        runtime_provenance=runtime_provenance,
+    )
+    failure_record = _make_failure_record(claim, verdict, reason)
+    return VerificationResult(
+        claim=claim,
+        classification=classification,
+        verdict=verdict,
+        reason=reason,
+        receipt=receipt,
+        failure_record=failure_record,
+    )
+
+
+def verify_compound(
+    claims: Sequence[Claim],
+    evidence_by_claim: Mapping[str, Iterable[Evidence]],
+    *,
+    policy: Policy,
+    evaluation_time: datetime,
+    human_approvals: Mapping[str, bool] | None = None,
+) -> CompoundResult:
+    if not claims:
+        raise ValueError("at least one claim is required")
+    claim_ids = [claim.claim_id for claim in claims]
+    if len(claim_ids) != len(set(claim_ids)):
+        raise ValueError("duplicate claim_id")
+
+    approvals = human_approvals or {}
+    for approval_claim_id, approval in approvals.items():
+        _validate_human_approval(
+            approval,
+            field_name=f"human approval for {approval_claim_id}",
+        )
+
+    results = tuple(
+        verify_claim(
+            claim,
+            evidence_by_claim.get(claim.claim_id, ()),
+            policy=policy,
+            evaluation_time=evaluation_time,
+            human_approved=approvals.get(claim.claim_id, False),
+        )
+        for claim in claims
+    )
+
+    consequential = [result for result in results if result.claim.consequential]
+    if any(result.verdict is Verdict.ESCALATE for result in consequential):
+        overall = Verdict.ESCALATE
+    elif any(result.verdict is not Verdict.APPROVE for result in consequential):
+        overall = Verdict.BLOCK
+    else:
+        overall = Verdict.APPROVE
+
     return CompoundResult(results=results, verdict=overall)

bodulskihal_core/evaluation.py

@@ -1,192 +1,192 @@
-from __future__ import annotations
-
-from typing import Any, Mapping
-
-from .research_demo import run_research_demo
-
-
-_ALLOWED_LABELS = {
-    "supported",
-    "unsupported",
-    "contradiction",
-    "action_without_post_state",
-    "high_risk_without_human_approval",
-}
-
-
-def _mapping(value: Any, path: str) -> Mapping[str, Any]:
-    if not isinstance(value, Mapping):
-        raise TypeError(f"{path} must be object")
-    return value
-
-
-def _rate(numerator: int, denominator: int) -> float:
-    return (numerator / denominator) if denominator else 0.0
-
-
-def _validate_labels(
-    fixture: Mapping[str, Any],
-    benchmark: Mapping[str, Any],
-) -> dict[str, str]:
-    claims = fixture.get("claims")
-    if not isinstance(claims, list):
-        raise TypeError("fixture.claims must be list")
-
-    claim_ids: list[str] = []
-    for index, raw in enumerate(claims):
-        claim = _mapping(raw, f"fixture.claims[{index}]")
-        claim_id = claim.get("id")
-        if not isinstance(claim_id, str) or not claim_id:
-            raise TypeError(f"fixture.claims[{index}].id must be non-empty string")
-        claim_ids.append(claim_id)
-
-    if len(claim_ids) != len(set(claim_ids)):
-        raise ValueError("fixture contains duplicate claim id")
-
-    labels_raw = _mapping(benchmark.get("labels"), "benchmark.labels")
-    unknown_ids = sorted(set(labels_raw) - set(claim_ids))
-    if unknown_ids:
-        raise ValueError("benchmark label references unknown claim: " + ", ".join(unknown_ids))
-
-    missing_ids = [claim_id for claim_id in claim_ids if claim_id not in labels_raw]
-    if missing_ids:
-        raise ValueError("missing benchmark label for claim: " + ", ".join(missing_ids))
-
-    labels: dict[str, str] = {}
-    for claim_id in claim_ids:
-        label = labels_raw[claim_id]
-        if not isinstance(label, str) or label not in _ALLOWED_LABELS:
-            raise ValueError(f"invalid benchmark label kind for {claim_id}: {label}")
-        labels[claim_id] = label
-
-    missing_kinds = sorted(_ALLOWED_LABELS - set(labels.values()))
-    if missing_kinds:
-        raise ValueError(
-            "benchmark must contain every benchmark label kind: "
-            + ", ".join(missing_kinds)
-        )
-
-    return labels
-
-
-def _claim_ids_with_label(labels: Mapping[str, str], kind: str) -> list[str]:
-    return [claim_id for claim_id, label in labels.items() if label == kind]
-
-
-def _summary(metrics: Mapping[str, Any]) -> str:
-    return (
-        "BENCHMARK SUMMARY\n"
-        f"- total claims: {metrics['total_claims']}\n"
-        f"- automatic disposition rate: {metrics['automatic_disposition_rate']:.2f}\n"
-        f"- human attention queue: {metrics['human_attention_queue_count']} "
-        f"({metrics['human_attention_rate']:.2f})\n"
-        f"- evidence coverage: {metrics['evidence_coverage']:.2f}\n"
-        f"- unsupported-claim block rate: {metrics['unsupported_claim_block_rate']:.2f}\n"
-        f"- contradiction detection rate: {metrics['contradiction_detection_rate']:.2f}\n"
-        f"- action-completion false-positive rate: "
-        f"{metrics['action_completion_false_positive_rate']:.2f}\n"
-        f"- high-risk unauthorized approve rate: "
-        f"{metrics['high_risk_without_human_approval_approve_rate']:.2f}\n"
-        "Human attention is reported only as a routing count/rate; no timed human-effort result has been measured."
-    )
-
-
-def evaluate_benchmark(
-    fixture: Mapping[str, Any],
-    benchmark: Mapping[str, Any],
-) -> dict[str, Any]:
-    fixture_obj = _mapping(fixture, "fixture")
-    benchmark_obj = _mapping(benchmark, "benchmark")
-    labels = _validate_labels(fixture_obj, benchmark_obj)
-
-    demo = run_research_demo(fixture_obj)
-    results = demo["results"]
-    by_id = {
-        item["receipt"]["claim"]["id"]: item
-        for item in results
-    }
-
-    total = len(results)
-    auto_approved_count = sum(
-        1 for item in results if item["verdict"] == "APPROVE"
-    )
-    auto_blocked_count = sum(
-        1 for item in results if item["verdict"] == "BLOCK"
-    )
-    escalated_count = sum(
-        1 for item in results if item["verdict"] == "ESCALATE"
-    )
-
-    human_attention_claim_ids = [
-        item["receipt"]["claim"]["id"]
-        for item in results
-        if item["classification"] == "CONFLICT"
-        or item["verdict"] == "ESCALATE"
-    ]
-    human_attention_queue_count = len(human_attention_claim_ids)
-    automatic_disposition_count = total - human_attention_queue_count
-
-    unsupported_ids = _claim_ids_with_label(labels, "unsupported")
-    contradiction_ids = _claim_ids_with_label(labels, "contradiction")
-    action_ids = _claim_ids_with_label(labels, "action_without_post_state")
-    high_risk_ids = _claim_ids_with_label(
-        labels,
-        "high_risk_without_human_approval",
-    )
-
-    unsupported_blocked = sum(
-        1 for claim_id in unsupported_ids if by_id[claim_id]["verdict"] == "BLOCK"
-    )
-    contradiction_detected = sum(
-        1
-        for claim_id in contradiction_ids
-        if by_id[claim_id]["classification"] == "CONFLICT"
-    )
-    action_false_positive_approves = sum(
-        1 for claim_id in action_ids if by_id[claim_id]["verdict"] == "APPROVE"
-    )
-    high_risk_unauthorized_approves = sum(
-        1
-        for claim_id in high_risk_ids
-        if by_id[claim_id]["verdict"] == "APPROVE"
-    )
-
-    metrics = {
-        "total_claims": total,
-        "auto_approved_count": auto_approved_count,
-        "auto_blocked_count": auto_blocked_count,
-        "escalated_count": escalated_count,
-        "human_attention_queue_count": human_attention_queue_count,
-        "human_attention_rate": _rate(human_attention_queue_count, total),
-        "automatic_disposition_count": automatic_disposition_count,
-        "automatic_disposition_rate": _rate(automatic_disposition_count, total),
-        "evidence_coverage": demo["metrics"]["evidence_coverage"],
-        "unsupported_claim_block_rate": _rate(
-            unsupported_blocked,
-            len(unsupported_ids),
-        ),
-        "contradiction_detection_rate": _rate(
-            contradiction_detected,
-            len(contradiction_ids),
-        ),
-        "action_completion_false_positive_rate": _rate(
-            action_false_positive_approves,
-            len(action_ids),
-        ),
-        "high_risk_without_human_approval_approve_rate": _rate(
-            high_risk_unauthorized_approves,
-            len(high_risk_ids),
-        ),
-    }
-
-    return {
-        "benchmark_version": benchmark_obj.get("version"),
-        "research_request": demo["research_request"],
-        "algorithm_version": demo["algorithm_version"],
-        "schema_version": demo["schema_version"],
-        "policy_version": demo["policy_version"],
-        "labels": labels,
-        "metrics": metrics,
-        "human_attention_claim_ids": human_attention_claim_ids,
-        "human_summary": _summary(metrics),
+from __future__ import annotations
+
+from typing import Any, Mapping
+
+from .research_demo import run_research_demo
+
+
+_ALLOWED_LABELS = {
+    "supported",
+    "unsupported",
+    "contradiction",
+    "action_without_post_state",
+    "high_risk_without_human_approval",
+}
+
+
+def _mapping(value: Any, path: str) -> Mapping[str, Any]:
+    if not isinstance(value, Mapping):
+        raise TypeError(f"{path} must be object")
+    return value
+
+
+def _rate(numerator: int, denominator: int) -> float:
+    return (numerator / denominator) if denominator else 0.0
+
+
+def _validate_labels(
+    fixture: Mapping[str, Any],
+    benchmark: Mapping[str, Any],
+) -> dict[str, str]:
+    claims = fixture.get("claims")
+    if not isinstance(claims, list):
+        raise TypeError("fixture.claims must be list")
+
+    claim_ids: list[str] = []
+    for index, raw in enumerate(claims):
+        claim = _mapping(raw, f"fixture.claims[{index}]")
+        claim_id = claim.get("id")
+        if not isinstance(claim_id, str) or not claim_id:
+            raise TypeError(f"fixture.claims[{index}].id must be non-empty string")
+        claim_ids.append(claim_id)
+
+    if len(claim_ids) != len(set(claim_ids)):
+        raise ValueError("fixture contains duplicate claim id")
+
+    labels_raw = _mapping(benchmark.get("labels"), "benchmark.labels")
+    unknown_ids = sorted(set(labels_raw) - set(claim_ids))
+    if unknown_ids:
+        raise ValueError("benchmark label references unknown claim: " + ", ".join(unknown_ids))
+
+    missing_ids = [claim_id for claim_id in claim_ids if claim_id not in labels_raw]
+    if missing_ids:
+        raise ValueError("missing benchmark label for claim: " + ", ".join(missing_ids))
+
+    labels: dict[str, str] = {}
+    for claim_id in claim_ids:
+        label = labels_raw[claim_id]
+        if not isinstance(label, str) or label not in _ALLOWED_LABELS:
+            raise ValueError(f"invalid benchmark label kind for {claim_id}: {label}")
+        labels[claim_id] = label
+
+    missing_kinds = sorted(_ALLOWED_LABELS - set(labels.values()))
+    if missing_kinds:
+        raise ValueError(
+            "benchmark must contain every benchmark label kind: "
+            + ", ".join(missing_kinds)
+        )
+
+    return labels
+
+
+def _claim_ids_with_label(labels: Mapping[str, str], kind: str) -> list[str]:
+    return [claim_id for claim_id, label in labels.items() if label == kind]
+
+
+def _summary(metrics: Mapping[str, Any]) -> str:
+    return (
+        "BENCHMARK SUMMARY\n"
+        f"- total claims: {metrics['total_claims']}\n"
+        f"- automatic disposition rate: {metrics['automatic_disposition_rate']:.2f}\n"
+        f"- human attention queue: {metrics['human_attention_queue_count']} "
+        f"({metrics['human_attention_rate']:.2f})\n"
+        f"- evidence coverage: {metrics['evidence_coverage']:.2f}\n"
+        f"- unsupported-claim block rate: {metrics['unsupported_claim_block_rate']:.2f}\n"
+        f"- contradiction detection rate: {metrics['contradiction_detection_rate']:.2f}\n"
+        f"- action-completion false-positive rate: "
+        f"{metrics['action_completion_false_positive_rate']:.2f}\n"
+        f"- high-risk unauthorized approve rate: "
+        f"{metrics['high_risk_without_human_approval_approve_rate']:.2f}\n"
+        "Human attention is reported only as a routing count/rate; no timed human-effort result has been measured."
+    )
+
+
+def evaluate_benchmark(
+    fixture: Mapping[str, Any],
+    benchmark: Mapping[str, Any],
+) -> dict[str, Any]:
+    fixture_obj = _mapping(fixture, "fixture")
+    benchmark_obj = _mapping(benchmark, "benchmark")
+    labels = _validate_labels(fixture_obj, benchmark_obj)
+
+    demo = run_research_demo(fixture_obj)
+    results = demo["results"]
+    by_id = {
+        item["receipt"]["claim"]["id"]: item
+        for item in results
+    }
+
+    total = len(results)
+    auto_approved_count = sum(
+        1 for item in results if item["verdict"] == "APPROVE"
+    )
+    auto_blocked_count = sum(
+        1 for item in results if item["verdict"] == "BLOCK"
+    )
+    escalated_count = sum(
+        1 for item in results if item["verdict"] == "ESCALATE"
+    )
+
+    human_attention_claim_ids = [
+        item["receipt"]["claim"]["id"]
+        for item in results
+        if item["classification"] == "CONFLICT"
+        or item["verdict"] == "ESCALATE"
+    ]
+    human_attention_queue_count = len(human_attention_claim_ids)
+    automatic_disposition_count = total - human_attention_queue_count
+
+    unsupported_ids = _claim_ids_with_label(labels, "unsupported")
+    contradiction_ids = _claim_ids_with_label(labels, "contradiction")
+    action_ids = _claim_ids_with_label(labels, "action_without_post_state")
+    high_risk_ids = _claim_ids_with_label(
+        labels,
+        "high_risk_without_human_approval",
+    )
+
+    unsupported_blocked = sum(
+        1 for claim_id in unsupported_ids if by_id[claim_id]["verdict"] == "BLOCK"
+    )
+    contradiction_detected = sum(
+        1
+        for claim_id in contradiction_ids
+        if by_id[claim_id]["classification"] == "CONFLICT"
+    )
+    action_false_positive_approves = sum(
+        1 for claim_id in action_ids if by_id[claim_id]["verdict"] == "APPROVE"
+    )
+    high_risk_unauthorized_approves = sum(
+        1
+        for claim_id in high_risk_ids
+        if by_id[claim_id]["verdict"] == "APPROVE"
+    )
+
+    metrics = {
+        "total_claims": total,
+        "auto_approved_count": auto_approved_count,
+        "auto_blocked_count": auto_blocked_count,
+        "escalated_count": escalated_count,
+        "human_attention_queue_count": human_attention_queue_count,
+        "human_attention_rate": _rate(human_attention_queue_count, total),
+        "automatic_disposition_count": automatic_disposition_count,
+        "automatic_disposition_rate": _rate(automatic_disposition_count, total),
+        "evidence_coverage": demo["metrics"]["evidence_coverage"],
+        "unsupported_claim_block_rate": _rate(
+            unsupported_blocked,
+            len(unsupported_ids),
+        ),
+        "contradiction_detection_rate": _rate(
+            contradiction_detected,
+            len(contradiction_ids),
+        ),
+        "action_completion_false_positive_rate": _rate(
+            action_false_positive_approves,
+            len(action_ids),
+        ),
+        "high_risk_without_human_approval_approve_rate": _rate(
+            high_risk_unauthorized_approves,
+            len(high_risk_ids),
+        ),
+    }
+
+    return {
+        "benchmark_version": benchmark_obj.get("version"),
+        "research_request": demo["research_request"],
+        "algorithm_version": demo["algorithm_version"],
+        "schema_version": demo["schema_version"],
+        "policy_version": demo["policy_version"],
+        "labels": labels,
+        "metrics": metrics,
+        "human_attention_claim_ids": human_attention_claim_ids,
+        "human_summary": _summary(metrics),
     }

bodulskihal_core/guard_loop.py

@@ -1,255 +1,255 @@
-from __future__ import annotations
-
-from dataclasses import dataclass
-from datetime import datetime
-from enum import Enum
-from typing import Iterable
-
-from .engine import (
-    Claim,
-    Classification,
-    Evidence,
-    Policy,
-    VerificationResult,
-    Verdict,
-    verify_claim,
-)
-
-
-GUARD_VERSION = "2.0.0"
-
-
-class Realism(str, Enum):
-    POSSIBLE = "possible"
-    UNCERTAIN = "uncertain"
-    IMPOSSIBLE = "impossible"
-
-
-class GuardStage(str, Enum):
-    SELF_CHECK = "self_check"
-    VERIFICATION = "verification"
-
-
-class UnknownSeverity(str, Enum):
-    LOW = "low"
-    MEDIUM = "medium"
-    HIGH = "high"
-    CRITICAL = "critical"
-
-
-@dataclass(frozen=True)
-class UnknownRecord:
-    description: str
-    severity: UnknownSeverity = UnknownSeverity.MEDIUM
-    reviewed: bool = False
-    resolved: bool = False
-    blocking: bool = False
-    resolution_reference: str | None = None
-
-
-@dataclass(frozen=True)
-class SelfCheck:
-    realism: Realism
-    known: tuple[str, ...]
-    assumptions: tuple[str, ...]
-    unknowns: tuple[str, ...]
-    assumptions_reviewed: bool
-    unknowns_reviewed: bool
-    unknown_records: tuple[UnknownRecord, ...] = ()
-
-
-@dataclass(frozen=True)
-class GuardResult:
-    stage: GuardStage
-    classification: Classification
-    verdict: Verdict
-    reason: str
-    verification: VerificationResult | None
-    receipt: dict
-
-
-def _validate_self_check(check: SelfCheck) -> None:
-    if not isinstance(check, SelfCheck):
-        raise TypeError("self_check must be SelfCheck")
-    if not isinstance(check.realism, Realism):
-        raise TypeError("self_check.realism must be Realism")
-    if type(check.assumptions_reviewed) is not bool:
-        raise TypeError("assumptions_reviewed must be bool")
-    if type(check.unknowns_reviewed) is not bool:
-        raise TypeError("unknowns_reviewed must be bool")
-
-    for field_name, values in (
-        ("known", check.known),
-        ("assumptions", check.assumptions),
-        ("unknowns", check.unknowns),
-    ):
-        if not isinstance(values, tuple):
-            raise TypeError(f"{field_name} must be tuple")
-        if any(not isinstance(item, str) or not item.strip() for item in values):
-            raise ValueError(f"{field_name} items must be non-empty strings")
-
-    if not isinstance(check.unknown_records, tuple):
-        raise TypeError("unknown_records must be tuple")
-    for item in check.unknown_records:
-        if not isinstance(item, UnknownRecord):
-            raise TypeError("unknown_records must contain UnknownRecord values")
-        if not isinstance(item.description, str) or not item.description.strip():
-            raise ValueError("unknown record description must be non-empty")
-        if not isinstance(item.severity, UnknownSeverity):
-            raise TypeError("unknown record severity must be UnknownSeverity")
-        if type(item.reviewed) is not bool:
-            raise TypeError("unknown record reviewed must be bool")
-        if type(item.resolved) is not bool:
-            raise TypeError("unknown record resolved must be bool")
-        if type(item.blocking) is not bool:
-            raise TypeError("unknown record blocking must be bool")
-        if item.resolution_reference is not None and (
-            not isinstance(item.resolution_reference, str)
-            or not item.resolution_reference.strip()
-        ):
-            raise ValueError("resolution_reference must be non-empty when supplied")
-        if item.resolved and (item.blocking or item.severity is UnknownSeverity.CRITICAL):
-            if item.resolution_reference is None:
-                raise ValueError(
-                    "resolved blocking or critical unknown requires resolution_reference"
-                )
-
-
-def _self_check_payload(check: SelfCheck) -> dict:
-    return {
-        "realism": check.realism.value,
-        "known": list(check.known),
-        "assumptions": list(check.assumptions),
-        "unknowns": list(check.unknowns),
-        "assumptions_reviewed": check.assumptions_reviewed,
-        "unknowns_reviewed": check.unknowns_reviewed,
-        "unknown_records": [
-            {
-                "description": item.description,
-                "severity": item.severity.value,
-                "reviewed": item.reviewed,
-                "resolved": item.resolved,
-                "blocking": item.blocking,
-                "resolution_reference": item.resolution_reference,
-            }
-            for item in check.unknown_records
-        ],
-    }
-
-
-def _self_check_result(
-    *,
-    claim: Claim,
-    check: SelfCheck,
-    verdict: Verdict,
-    reason: str,
-) -> GuardResult:
-    receipt = {
-        "guard_version": GUARD_VERSION,
-        "claim_id": claim.claim_id,
-        "stage": GuardStage.SELF_CHECK.value,
-        "self_check": _self_check_payload(check),
-        "verification": None,
-        "classification": Classification.UNKNOWN.value,
-        "verdict": verdict.value,
-        "reason": reason,
-    }
-    return GuardResult(
-        stage=GuardStage.SELF_CHECK,
-        classification=Classification.UNKNOWN,
-        verdict=verdict,
-        reason=reason,
-        verification=None,
-        receipt=receipt,
-    )
-
-
-def run_guard_loop(
-    *,
-    claim: Claim,
-    evidence: Iterable[Evidence],
-    self_check: SelfCheck,
-    policy: Policy,
-    evaluation_time: datetime,
-    human_approved: bool = False,
-) -> GuardResult:
-    _validate_self_check(self_check)
-
-    if self_check.realism is Realism.IMPOSSIBLE:
-        return _self_check_result(
-            claim=claim,
-            check=self_check,
-            verdict=Verdict.BLOCK,
-            reason="self_check_impossible",
-        )
-
-    if self_check.realism is Realism.UNCERTAIN:
-        return _self_check_result(
-            claim=claim,
-            check=self_check,
-            verdict=Verdict.ESCALATE,
-            reason="self_check_uncertain",
-        )
-
-    unresolved_blocking = tuple(
-        item
-        for item in self_check.unknown_records
-        if not item.resolved
-        and (item.blocking or item.severity is UnknownSeverity.CRITICAL)
-    )
-    if unresolved_blocking:
-        return _self_check_result(
-            claim=claim,
-            check=self_check,
-            verdict=Verdict.ESCALATE,
-            reason="blocking_unknown_unresolved",
-        )
-
-    if not self_check.assumptions_reviewed:
-        return _self_check_result(
-            claim=claim,
-            check=self_check,
-            verdict=Verdict.ESCALATE,
-            reason="assumptions_not_reviewed",
-        )
-
-    if not self_check.unknowns_reviewed:
-        return _self_check_result(
-            claim=claim,
-            check=self_check,
-            verdict=Verdict.ESCALATE,
-            reason="unknowns_not_reviewed",
-        )
-
-    verification = verify_claim(
-        claim,
-        evidence,
-        policy=policy,
-        evaluation_time=evaluation_time,
-        human_approved=human_approved,
-    )
-
-    receipt = {
-        "guard_version": GUARD_VERSION,
-        "claim_id": claim.claim_id,
-        "stage": GuardStage.VERIFICATION.value,
-        "self_check": _self_check_payload(self_check),
-        "verification": {
-            "classification": verification.classification.value,
-            "verdict": verification.verdict.value,
-            "reason": verification.reason,
-            "receipt": verification.receipt,
-        },
-        "classification": verification.classification.value,
-        "verdict": verification.verdict.value,
-        "reason": verification.reason,
-    }
-
-    return GuardResult(
-        stage=GuardStage.VERIFICATION,
-        classification=verification.classification,
-        verdict=verification.verdict,
-        reason=verification.reason,
-        verification=verification,
-        receipt=receipt,
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime
+from enum import Enum
+from typing import Iterable
+
+from .engine import (
+    Claim,
+    Classification,
+    Evidence,
+    Policy,
+    VerificationResult,
+    Verdict,
+    verify_claim,
+)
+
+
+GUARD_VERSION = "2.0.0"
+
+
+class Realism(str, Enum):
+    POSSIBLE = "possible"
+    UNCERTAIN = "uncertain"
+    IMPOSSIBLE = "impossible"
+
+
+class GuardStage(str, Enum):
+    SELF_CHECK = "self_check"
+    VERIFICATION = "verification"
+
+
+class UnknownSeverity(str, Enum):
+    LOW = "low"
+    MEDIUM = "medium"
+    HIGH = "high"
+    CRITICAL = "critical"
+
+
+@dataclass(frozen=True)
+class UnknownRecord:
+    description: str
+    severity: UnknownSeverity = UnknownSeverity.MEDIUM
+    reviewed: bool = False
+    resolved: bool = False
+    blocking: bool = False
+    resolution_reference: str | None = None
+
+
+@dataclass(frozen=True)
+class SelfCheck:
+    realism: Realism
+    known: tuple[str, ...]
+    assumptions: tuple[str, ...]
+    unknowns: tuple[str, ...]
+    assumptions_reviewed: bool
+    unknowns_reviewed: bool
+    unknown_records: tuple[UnknownRecord, ...] = ()
+
+
+@dataclass(frozen=True)
+class GuardResult:
+    stage: GuardStage
+    classification: Classification
+    verdict: Verdict
+    reason: str
+    verification: VerificationResult | None
+    receipt: dict
+
+
+def _validate_self_check(check: SelfCheck) -> None:
+    if not isinstance(check, SelfCheck):
+        raise TypeError("self_check must be SelfCheck")
+    if not isinstance(check.realism, Realism):
+        raise TypeError("self_check.realism must be Realism")
+    if type(check.assumptions_reviewed) is not bool:
+        raise TypeError("assumptions_reviewed must be bool")
+    if type(check.unknowns_reviewed) is not bool:
+        raise TypeError("unknowns_reviewed must be bool")
+
+    for field_name, values in (
+        ("known", check.known),
+        ("assumptions", check.assumptions),
+        ("unknowns", check.unknowns),
+    ):
+        if not isinstance(values, tuple):
+            raise TypeError(f"{field_name} must be tuple")
+        if any(not isinstance(item, str) or not item.strip() for item in values):
+            raise ValueError(f"{field_name} items must be non-empty strings")
+
+    if not isinstance(check.unknown_records, tuple):
+        raise TypeError("unknown_records must be tuple")
+    for item in check.unknown_records:
+        if not isinstance(item, UnknownRecord):
+            raise TypeError("unknown_records must contain UnknownRecord values")
+        if not isinstance(item.description, str) or not item.description.strip():
+            raise ValueError("unknown record description must be non-empty")
+        if not isinstance(item.severity, UnknownSeverity):
+            raise TypeError("unknown record severity must be UnknownSeverity")
+        if type(item.reviewed) is not bool:
+            raise TypeError("unknown record reviewed must be bool")
+        if type(item.resolved) is not bool:
+            raise TypeError("unknown record resolved must be bool")
+        if type(item.blocking) is not bool:
+            raise TypeError("unknown record blocking must be bool")
+        if item.resolution_reference is not None and (
+            not isinstance(item.resolution_reference, str)
+            or not item.resolution_reference.strip()
+        ):
+            raise ValueError("resolution_reference must be non-empty when supplied")
+        if item.resolved and (item.blocking or item.severity is UnknownSeverity.CRITICAL):
+            if item.resolution_reference is None:
+                raise ValueError(
+                    "resolved blocking or critical unknown requires resolution_reference"
+                )
+
+
+def _self_check_payload(check: SelfCheck) -> dict:
+    return {
+        "realism": check.realism.value,
+        "known": list(check.known),
+        "assumptions": list(check.assumptions),
+        "unknowns": list(check.unknowns),
+        "assumptions_reviewed": check.assumptions_reviewed,
+        "unknowns_reviewed": check.unknowns_reviewed,
+        "unknown_records": [
+            {
+                "description": item.description,
+                "severity": item.severity.value,
+                "reviewed": item.reviewed,
+                "resolved": item.resolved,
+                "blocking": item.blocking,
+                "resolution_reference": item.resolution_reference,
+            }
+            for item in check.unknown_records
+        ],
+    }
+
+
+def _self_check_result(
+    *,
+    claim: Claim,
+    check: SelfCheck,
+    verdict: Verdict,
+    reason: str,
+) -> GuardResult:
+    receipt = {
+        "guard_version": GUARD_VERSION,
+        "claim_id": claim.claim_id,
+        "stage": GuardStage.SELF_CHECK.value,
+        "self_check": _self_check_payload(check),
+        "verification": None,
+        "classification": Classification.UNKNOWN.value,
+        "verdict": verdict.value,
+        "reason": reason,
+    }
+    return GuardResult(
+        stage=GuardStage.SELF_CHECK,
+        classification=Classification.UNKNOWN,
+        verdict=verdict,
+        reason=reason,
+        verification=None,
+        receipt=receipt,
+    )
+
+
+def run_guard_loop(
+    *,
+    claim: Claim,
+    evidence: Iterable[Evidence],
+    self_check: SelfCheck,
+    policy: Policy,
+    evaluation_time: datetime,
+    human_approved: bool = False,
+) -> GuardResult:
+    _validate_self_check(self_check)
+
+    if self_check.realism is Realism.IMPOSSIBLE:
+        return _self_check_result(
+            claim=claim,
+            check=self_check,
+            verdict=Verdict.BLOCK,
+            reason="self_check_impossible",
+        )
+
+    if self_check.realism is Realism.UNCERTAIN:
+        return _self_check_result(
+            claim=claim,
+            check=self_check,
+            verdict=Verdict.ESCALATE,
+            reason="self_check_uncertain",
+        )
+
+    unresolved_blocking = tuple(
+        item
+        for item in self_check.unknown_records
+        if not item.resolved
+        and (item.blocking or item.severity is UnknownSeverity.CRITICAL)
+    )
+    if unresolved_blocking:
+        return _self_check_result(
+            claim=claim,
+            check=self_check,
+            verdict=Verdict.ESCALATE,
+            reason="blocking_unknown_unresolved",
+        )
+
+    if not self_check.assumptions_reviewed:
+        return _self_check_result(
+            claim=claim,
+            check=self_check,
+            verdict=Verdict.ESCALATE,
+            reason="assumptions_not_reviewed",
+        )
+
+    if not self_check.unknowns_reviewed:
+        return _self_check_result(
+            claim=claim,
+            check=self_check,
+            verdict=Verdict.ESCALATE,
+            reason="unknowns_not_reviewed",
+        )
+
+    verification = verify_claim(
+        claim,
+        evidence,
+        policy=policy,
+        evaluation_time=evaluation_time,
+        human_approved=human_approved,
+    )
+
+    receipt = {
+        "guard_version": GUARD_VERSION,
+        "claim_id": claim.claim_id,
+        "stage": GuardStage.VERIFICATION.value,
+        "self_check": _self_check_payload(self_check),
+        "verification": {
+            "classification": verification.classification.value,
+            "verdict": verification.verdict.value,
+            "reason": verification.reason,
+            "receipt": verification.receipt,
+        },
+        "classification": verification.classification.value,
+        "verdict": verification.verdict.value,
+        "reason": verification.reason,
+    }
+
+    return GuardResult(
+        stage=GuardStage.VERIFICATION,
+        classification=verification.classification,
+        verdict=verification.verdict,
+        reason=verification.reason,
+        verification=verification,
+        receipt=receipt,
     )

bodulskihal_core/ingestion.py

@@ -1,557 +1,557 @@
-from __future__ import annotations
-
-import hashlib
-import re
-import unicodedata
-from dataclasses import dataclass
-from datetime import datetime
-from enum import Enum
-from typing import Any, Mapping
-
-from .engine import (
-    AuthorityScope,
-    Claim,
-    ClaimType,
-    Directness,
-    Evidence,
-    EvidenceOrigin,
-    Policy,
-    RiskLevel,
-    SourceRole,
-    VerificationResult,
-    Verdict,
-    verify_compound,
-)
-
-
-class TypeAuthority(str, Enum):
-    EXECUTOR = "executor"
-    TRUSTED_POLICY = "trusted_policy"
-    HUMAN = "human"
-
-
-@dataclass(frozen=True)
-class NormalizedResponse:
-    text: str
-    sha256: str
-
-
-@dataclass(frozen=True)
-class ClaimAtom:
-    atom_id: str
-    text: str
-    start: int
-    end: int
-    source_response_sha256: str
-    claim_type: ClaimType
-
-
-@dataclass(frozen=True)
-class EvidenceContract:
-    atom_id: str
-    claim_type: ClaimType
-    verification_ready: bool
-    required_directness: Directness | None
-    post_action_required: bool
-    independent_post_action_required: bool
-    minimum_independent_sources: int
-    human_approval_required: bool
-    reason: str
-
-
-@dataclass(frozen=True)
-class IngestionResult:
-    normalized: NormalizedResponse
-    atoms: tuple[ClaimAtom, ...]
-    contracts: tuple[EvidenceContract, ...]
-
-
-@dataclass(frozen=True)
-class IngestedVerificationResult:
-    ingestion: IngestionResult
-    results: tuple[VerificationResult, ...]
-    verdict: Verdict
-
-
-_TYPE_LABEL = re.compile(r"^\[(?P<label>[A-Za-z_]+)\](?:\s+|$)")
-
-_LABEL_TYPES = {
-    "INFERENCE": ClaimType.INFERENCE,
-    "ESTIMATE": ClaimType.ESTIMATE,
-    "ACTION_STATE": ClaimType.ACTION_STATE,
-    "RISK_SENSITIVE": ClaimType.RISK_SENSITIVE,
-    "OBSERVATION": ClaimType.OBSERVATION,
-}
-
-
-def normalize_model_response(raw: str) -> NormalizedResponse:
-    if not isinstance(raw, str):
-        raise TypeError("model response must be string")
-
-    normalized = raw.replace("\r\n", "\n").replace("\r", "\n")
-    normalized = unicodedata.normalize("NFC", normalized).strip()
-    if not normalized:
-        raise ValueError("model response must be non-empty")
-
-    return NormalizedResponse(
-        text=normalized,
-        sha256=hashlib.sha256(normalized.encode("utf-8")).hexdigest(),
-    )
-
-
-def type_clause(
-    text: str,
-    *,
-    authority: TypeAuthority = TypeAuthority.EXECUTOR,
-) -> ClaimType:
-    if not isinstance(authority, TypeAuthority):
-        raise TypeError("authority must be TypeAuthority")
-    if not isinstance(text, str) or not text.strip():
-        raise ValueError("clause text must be non-empty")
-
-    match = _TYPE_LABEL.match(text)
-    if match is None:
-        return ClaimType.UNCLASSIFIED
-
-    declared = _LABEL_TYPES.get(match.group("label").upper())
-    if declared is None:
-        return ClaimType.UNCLASSIFIED
-
-    if (
-        declared is ClaimType.OBSERVATION
-        and authority is TypeAuthority.EXECUTOR
-    ):
-        return ClaimType.UNCLASSIFIED
-
-    return declared
-
-
-def _span_segments(text: str) -> list[tuple[int, int]]:
-    spans: list[tuple[int, int]] = []
-    length = len(text)
-    start = 0
-
-    while start < length:
-        while start < length and text[start].isspace():
-            start += 1
-        if start >= length:
-            break
-
-        index = start
-        emitted = False
-        while index < length:
-            char = text[index]
-
-            if char == "\n":
-                end = index
-                while end > start and text[end - 1].isspace():
-                    end -= 1
-                if end > start:
-                    spans.append((start, end))
-                start = index + 1
-                emitted = True
-                break
-
-            if char in ".?!":
-                next_index = index + 1
-                if next_index == length or text[next_index].isspace():
-                    spans.append((start, next_index))
-                    start = next_index
-                    emitted = True
-                    break
-
-            index += 1
-
-        if not emitted:
-            end = length
-            while end > start and text[end - 1].isspace():
-                end -= 1
-            if end > start:
-                spans.append((start, end))
-            break
-
-    return spans
-
-
-def atomize_model_response(
-    normalized: NormalizedResponse,
-    *,
-    authority: TypeAuthority = TypeAuthority.EXECUTOR,
-) -> tuple[ClaimAtom, ...]:
-    if not isinstance(normalized, NormalizedResponse):
-        raise TypeError("normalized must be NormalizedResponse")
-
-    atoms = []
-    for index, (start, end) in enumerate(_span_segments(normalized.text), start=1):
-        text = normalized.text[start:end]
-        atoms.append(
-            ClaimAtom(
-                atom_id=f"atom-{index:04d}",
-                text=text,
-                start=start,
-                end=end,
-                source_response_sha256=normalized.sha256,
-                claim_type=type_clause(text, authority=authority),
-            )
-        )
-
-    if not atoms:
-        raise ValueError("model response produced no claim atoms")
-
-    return tuple(atoms)
-
-
-def build_evidence_contract(
-    *,
-    atom_id: str,
-    claim_type: ClaimType,
-) -> EvidenceContract:
-    if not isinstance(atom_id, str) or not atom_id.strip():
-        raise ValueError("atom_id must be non-empty")
-
-    if claim_type is ClaimType.UNCLASSIFIED:
-        return EvidenceContract(
-            atom_id=atom_id,
-            claim_type=claim_type,
-            verification_ready=False,
-            required_directness=None,
-            post_action_required=False,
-            independent_post_action_required=False,
-            minimum_independent_sources=0,
-            human_approval_required=False,
-            reason="trusted_typing_required",
-        )
-
-    if claim_type is ClaimType.ACTION_STATE:
-        return EvidenceContract(
-            atom_id=atom_id,
-            claim_type=claim_type,
-            verification_ready=True,
-            required_directness=Directness.DIRECT,
-            post_action_required=True,
-            independent_post_action_required=True,
-            minimum_independent_sources=1,
-            human_approval_required=False,
-            reason="post_action_final_state_required",
-        )
-
-    if claim_type is ClaimType.RISK_SENSITIVE:
-        return EvidenceContract(
-            atom_id=atom_id,
-            claim_type=claim_type,
-            verification_ready=True,
-            required_directness=Directness.DIRECT,
-            post_action_required=False,
-            independent_post_action_required=False,
-            minimum_independent_sources=1,
-            human_approval_required=True,
-            reason="human_approval_required",
-        )
-
-    if claim_type is ClaimType.OBSERVATION:
-        return EvidenceContract(
-            atom_id=atom_id,
-            claim_type=claim_type,
-            verification_ready=True,
-            required_directness=Directness.DIRECT,
-            post_action_required=False,
-            independent_post_action_required=False,
-            minimum_independent_sources=1,
-            human_approval_required=False,
-            reason="direct_evidence_required",
-        )
-
-    return EvidenceContract(
-        atom_id=atom_id,
-        claim_type=claim_type,
-        verification_ready=True,
-        required_directness=None,
-        post_action_required=False,
-        independent_post_action_required=False,
-        minimum_independent_sources=1,
-        human_approval_required=False,
-        reason="typed_nonfact_claim",
-    )
-
-
-def ingest_model_response(
-    raw: str,
-    *,
-    authority: TypeAuthority = TypeAuthority.EXECUTOR,
-) -> IngestionResult:
-    normalized = normalize_model_response(raw)
-    atoms = atomize_model_response(normalized, authority=authority)
-    contracts = tuple(
-        build_evidence_contract(
-            atom_id=atom.atom_id,
-            claim_type=atom.claim_type,
-        )
-        for atom in atoms
-    )
-    return IngestionResult(
-        normalized=normalized,
-        atoms=atoms,
-        contracts=contracts,
-    )
-
-
-
-_ALLOWED_EVIDENCE_KEYS = {
-    "source_id",
-    "supports",
-    "observed_at",
-    "directness",
-    "post_action",
-    "eligible",
-    "evidence_id",
-    "source_role",
-    "source_ref",
-    "independence_group",
-    "content_sha256",
-    "origin",
-    "authority_scope",
-}
-
-
-def _record_mapping(value: Any, path: str) -> Mapping[str, Any]:
-    if not isinstance(value, Mapping):
-        raise TypeError(f"{path} must be object")
-    return value
-
-
-def _record_string(value: Any, path: str) -> str:
-    if not isinstance(value, str) or not value.strip():
-        raise TypeError(f"{path} must be non-empty string")
-    return value.strip()
-
-
-def _record_optional_string(value: Any, path: str) -> str | None:
-    if value is None:
-        return None
-    return _record_string(value, path)
-
-
-def _record_bool(value: Any, path: str) -> bool:
-    if type(value) is not bool:
-        raise TypeError(f"{path} must be bool")
-    return value
-
-
-def _record_datetime(value: Any, path: str) -> datetime:
-    raw = _record_string(value, path)
-    if raw.endswith("Z"):
-        raw = raw[:-1] + "+00:00"
-    try:
-        parsed = datetime.fromisoformat(raw)
-    except ValueError as exc:
-        raise ValueError(f"{path} must be ISO 8601 datetime") from exc
-    if parsed.tzinfo is None or parsed.utcoffset() is None:
-        raise ValueError(f"{path} must be timezone-aware")
-    return parsed
-
-
-def _record_directness(value: Any, path: str) -> Directness:
-    raw = _record_string(value, path)
-    try:
-        return Directness(raw)
-    except ValueError as exc:
-        raise ValueError(f"invalid {path}: {raw}") from exc
-
-
-def _record_source_role(value: Any, path: str) -> SourceRole:
-    raw = _record_string(value, path)
-    try:
-        return SourceRole(raw)
-    except ValueError as exc:
-        raise ValueError(f"invalid {path}: {raw}") from exc
-
-
-def _record_evidence_origin(value: Any, path: str) -> EvidenceOrigin:
-    raw = _record_string(value, path)
-    try:
-        return EvidenceOrigin(raw)
-    except ValueError as exc:
-        raise ValueError(f"invalid {path}: {raw}") from exc
-
-
-def _record_authority_scope(value: Any, path: str) -> AuthorityScope:
-    raw = _record_string(value, path)
-    try:
-        return AuthorityScope(raw)
-    except ValueError as exc:
-        raise ValueError(f"invalid {path}: {raw}") from exc
-
-
-def collect_normalize_evidence(
-    records_by_atom: Mapping[str, list[Mapping[str, Any]]],
-    *,
-    known_atom_ids: set[str],
-) -> dict[str, tuple[Evidence, ...]]:
-    if not isinstance(records_by_atom, Mapping):
-        raise TypeError("records_by_atom must be object")
-    if not isinstance(known_atom_ids, set):
-        raise TypeError("known_atom_ids must be set")
-
-    unknown = sorted(set(records_by_atom) - known_atom_ids)
-    if unknown:
-        raise ValueError("unknown atom_id: " + ", ".join(unknown))
-
-    normalized: dict[str, tuple[Evidence, ...]] = {}
-    for atom_id in sorted(known_atom_ids):
-        raw_items = records_by_atom.get(atom_id, [])
-        if not isinstance(raw_items, list):
-            raise TypeError(f"evidence for {atom_id} must be list")
-
-        items: list[Evidence] = []
-        seen_evidence_ids: set[str] = set()
-
-        for index, raw in enumerate(raw_items):
-            path = f"evidence_by_atom.{atom_id}[{index}]"
-            obj = _record_mapping(raw, path)
-
-            extra = sorted(set(obj) - _ALLOWED_EVIDENCE_KEYS)
-            if extra:
-                raise ValueError(
-                    f"{path} contains unsupported fields: " + ", ".join(extra)
-                )
-
-            source_id = _record_string(obj.get("source_id"), f"{path}.source_id")
-            evidence_id = _record_optional_string(
-                obj.get("evidence_id"),
-                f"{path}.evidence_id",
-            )
-            effective_id = evidence_id or source_id
-            if effective_id in seen_evidence_ids:
-                if evidence_id is None:
-                    raise ValueError(
-                        f"duplicate source_id for {atom_id}: {source_id}"
-                    )
-                raise ValueError(
-                    f"duplicate evidence_id for {atom_id}: {effective_id}"
-                )
-            seen_evidence_ids.add(effective_id)
-
-            if "supports" not in obj:
-                raise ValueError(f"missing required field: {path}.supports")
-            if "observed_at" not in obj:
-                raise ValueError(f"missing required field: {path}.observed_at")
-            if "directness" not in obj:
-                raise ValueError(f"missing required field: {path}.directness")
-
-            items.append(
-                Evidence(
-                    source_id=source_id,
-                    supports=_record_bool(obj["supports"], f"{path}.supports"),
-                    observed_at=_record_datetime(
-                        obj["observed_at"],
-                        f"{path}.observed_at",
-                    ),
-                    directness=_record_directness(
-                        obj["directness"],
-                        f"{path}.directness",
-                    ),
-                    post_action=_record_bool(
-                        obj.get("post_action", False),
-                        f"{path}.post_action",
-                    ),
-                    eligible=_record_bool(
-                        obj.get("eligible", True),
-                        f"{path}.eligible",
-                    ),
-                    evidence_id=evidence_id,
-                    source_role=_record_source_role(
-                        obj.get("source_role", SourceRole.EXTERNAL.value),
-                        f"{path}.source_role",
-                    ),
-                    source_ref=_record_optional_string(
-                        obj.get("source_ref"),
-                        f"{path}.source_ref",
-                    ),
-                    independence_group=_record_optional_string(
-                        obj.get("independence_group"),
-                        f"{path}.independence_group",
-                    ),
-                    content_sha256=_record_optional_string(
-                        obj.get("content_sha256"),
-                        f"{path}.content_sha256",
-                    ),
-                    origin=_record_evidence_origin(
-                        obj.get("origin", EvidenceOrigin.EXTERNAL_SOURCE.value),
-                        f"{path}.origin",
-                    ),
-                    authority_scope=_record_authority_scope(
-                        obj.get("authority_scope", AuthorityScope.EXTERNAL_FACT.value),
-                        f"{path}.authority_scope",
-                    ),
-                )
-            )
-
-        normalized[atom_id] = tuple(
-            sorted(
-                items,
-                key=lambda item: (
-                    item.evidence_id or item.source_id,
-                    item.source_id,
-                ),
-            )
-        )
-
-    return normalized
-
-
-def _claim_from_atom(atom: ClaimAtom) -> Claim:
-    risk = (
-        RiskLevel.HIGH
-        if atom.claim_type is ClaimType.RISK_SENSITIVE
-        else RiskLevel.LOW
-    )
-    return Claim(
-        claim_id=atom.atom_id,
-        text=atom.text,
-        claim_type=atom.claim_type,
-        risk=risk,
-        consequential=True,
-    )
-
-
-def verify_model_response(
-    raw: str,
-    *,
-    evidence_by_atom: Mapping[str, list[Mapping[str, Any]]],
-    authority: TypeAuthority,
-    policy: Policy,
-    evaluation_time: datetime,
-    human_approvals: Mapping[str, bool] | None = None,
-) -> IngestedVerificationResult:
-    ingestion = ingest_model_response(raw, authority=authority)
-    atom_ids = {atom.atom_id for atom in ingestion.atoms}
-
-    evidence = collect_normalize_evidence(
-        evidence_by_atom,
-        known_atom_ids=atom_ids,
-    )
-
-    approvals = human_approvals or {}
-    unknown_approvals = sorted(set(approvals) - atom_ids)
-    if unknown_approvals:
-        raise ValueError(
-            "human_approvals contains unknown atom_id: "
-            + ", ".join(unknown_approvals)
-        )
-    for atom_id, value in approvals.items():
-        if type(value) is not bool:
-            raise TypeError(f"human_approvals.{atom_id} must be bool")
-
-    compound = verify_compound(
-        tuple(_claim_from_atom(atom) for atom in ingestion.atoms),
-        evidence,
-        policy=policy,
-        evaluation_time=evaluation_time,
-        human_approvals=approvals,
-    )
-
-    return IngestedVerificationResult(
-        ingestion=ingestion,
-        results=compound.results,
-        verdict=compound.verdict,
+from __future__ import annotations
+
+import hashlib
+import re
+import unicodedata
+from dataclasses import dataclass
+from datetime import datetime
+from enum import Enum
+from typing import Any, Mapping
+
+from .engine import (
+    AuthorityScope,
+    Claim,
+    ClaimType,
+    Directness,
+    Evidence,
+    EvidenceOrigin,
+    Policy,
+    RiskLevel,
+    SourceRole,
+    VerificationResult,
+    Verdict,
+    verify_compound,
+)
+
+
+class TypeAuthority(str, Enum):
+    EXECUTOR = "executor"
+    TRUSTED_POLICY = "trusted_policy"
+    HUMAN = "human"
+
+
+@dataclass(frozen=True)
+class NormalizedResponse:
+    text: str
+    sha256: str
+
+
+@dataclass(frozen=True)
+class ClaimAtom:
+    atom_id: str
+    text: str
+    start: int
+    end: int
+    source_response_sha256: str
+    claim_type: ClaimType
+
+
+@dataclass(frozen=True)
+class EvidenceContract:
+    atom_id: str
+    claim_type: ClaimType
+    verification_ready: bool
+    required_directness: Directness | None
+    post_action_required: bool
+    independent_post_action_required: bool
+    minimum_independent_sources: int
+    human_approval_required: bool
+    reason: str
+
+
+@dataclass(frozen=True)
+class IngestionResult:
+    normalized: NormalizedResponse
+    atoms: tuple[ClaimAtom, ...]
+    contracts: tuple[EvidenceContract, ...]
+
+
+@dataclass(frozen=True)
+class IngestedVerificationResult:
+    ingestion: IngestionResult
+    results: tuple[VerificationResult, ...]
+    verdict: Verdict
+
+
+_TYPE_LABEL = re.compile(r"^\[(?P<label>[A-Za-z_]+)\](?:\s+|$)")
+
+_LABEL_TYPES = {
+    "INFERENCE": ClaimType.INFERENCE,
+    "ESTIMATE": ClaimType.ESTIMATE,
+    "ACTION_STATE": ClaimType.ACTION_STATE,
+    "RISK_SENSITIVE": ClaimType.RISK_SENSITIVE,
+    "OBSERVATION": ClaimType.OBSERVATION,
+}
+
+
+def normalize_model_response(raw: str) -> NormalizedResponse:
+    if not isinstance(raw, str):
+        raise TypeError("model response must be string")
+
+    normalized = raw.replace("\r\n", "\n").replace("\r", "\n")
+    normalized = unicodedata.normalize("NFC", normalized).strip()
+    if not normalized:
+        raise ValueError("model response must be non-empty")
+
+    return NormalizedResponse(
+        text=normalized,
+        sha256=hashlib.sha256(normalized.encode("utf-8")).hexdigest(),
+    )
+
+
+def type_clause(
+    text: str,
+    *,
+    authority: TypeAuthority = TypeAuthority.EXECUTOR,
+) -> ClaimType:
+    if not isinstance(authority, TypeAuthority):
+        raise TypeError("authority must be TypeAuthority")
+    if not isinstance(text, str) or not text.strip():
+        raise ValueError("clause text must be non-empty")
+
+    match = _TYPE_LABEL.match(text)
+    if match is None:
+        return ClaimType.UNCLASSIFIED
+
+    declared = _LABEL_TYPES.get(match.group("label").upper())
+    if declared is None:
+        return ClaimType.UNCLASSIFIED
+
+    if (
+        declared is ClaimType.OBSERVATION
+        and authority is TypeAuthority.EXECUTOR
+    ):
+        return ClaimType.UNCLASSIFIED
+
+    return declared
+
+
+def _span_segments(text: str) -> list[tuple[int, int]]:
+    spans: list[tuple[int, int]] = []
+    length = len(text)
+    start = 0
+
+    while start < length:
+        while start < length and text[start].isspace():
+            start += 1
+        if start >= length:
+            break
+
+        index = start
+        emitted = False
+        while index < length:
+            char = text[index]
+
+            if char == "\n":
+                end = index
+                while end > start and text[end - 1].isspace():
+                    end -= 1
+                if end > start:
+                    spans.append((start, end))
+                start = index + 1
+                emitted = True
+                break
+
+            if char in ".?!":
+                next_index = index + 1
+                if next_index == length or text[next_index].isspace():
+                    spans.append((start, next_index))
+                    start = next_index
+                    emitted = True
+                    break
+
+            index += 1
+
+        if not emitted:
+            end = length
+            while end > start and text[end - 1].isspace():
+                end -= 1
+            if end > start:
+                spans.append((start, end))
+            break
+
+    return spans
+
+
+def atomize_model_response(
+    normalized: NormalizedResponse,
+    *,
+    authority: TypeAuthority = TypeAuthority.EXECUTOR,
+) -> tuple[ClaimAtom, ...]:
+    if not isinstance(normalized, NormalizedResponse):
+        raise TypeError("normalized must be NormalizedResponse")
+
+    atoms = []
+    for index, (start, end) in enumerate(_span_segments(normalized.text), start=1):
+        text = normalized.text[start:end]
+        atoms.append(
+            ClaimAtom(
+                atom_id=f"atom-{index:04d}",
+                text=text,
+                start=start,
+                end=end,
+                source_response_sha256=normalized.sha256,
+                claim_type=type_clause(text, authority=authority),
+            )
+        )
+
+    if not atoms:
+        raise ValueError("model response produced no claim atoms")
+
+    return tuple(atoms)
+
+
+def build_evidence_contract(
+    *,
+    atom_id: str,
+    claim_type: ClaimType,
+) -> EvidenceContract:
+    if not isinstance(atom_id, str) or not atom_id.strip():
+        raise ValueError("atom_id must be non-empty")
+
+    if claim_type is ClaimType.UNCLASSIFIED:
+        return EvidenceContract(
+            atom_id=atom_id,
+            claim_type=claim_type,
+            verification_ready=False,
+            required_directness=None,
+            post_action_required=False,
+            independent_post_action_required=False,
+            minimum_independent_sources=0,
+            human_approval_required=False,
+            reason="trusted_typing_required",
+        )
+
+    if claim_type is ClaimType.ACTION_STATE:
+        return EvidenceContract(
+            atom_id=atom_id,
+            claim_type=claim_type,
+            verification_ready=True,
+            required_directness=Directness.DIRECT,
+            post_action_required=True,
+            independent_post_action_required=True,
+            minimum_independent_sources=1,
+            human_approval_required=False,
+            reason="post_action_final_state_required",
+        )
+
+    if claim_type is ClaimType.RISK_SENSITIVE:
+        return EvidenceContract(
+            atom_id=atom_id,
+            claim_type=claim_type,
+            verification_ready=True,
+            required_directness=Directness.DIRECT,
+            post_action_required=False,
+            independent_post_action_required=False,
+            minimum_independent_sources=1,
+            human_approval_required=True,
+            reason="human_approval_required",
+        )
+
+    if claim_type is ClaimType.OBSERVATION:
+        return EvidenceContract(
+            atom_id=atom_id,
+            claim_type=claim_type,
+            verification_ready=True,
+            required_directness=Directness.DIRECT,
+            post_action_required=False,
+            independent_post_action_required=False,
+            minimum_independent_sources=1,
+            human_approval_required=False,
+            reason="direct_evidence_required",
+        )
+
+    return EvidenceContract(
+        atom_id=atom_id,
+        claim_type=claim_type,
+        verification_ready=True,
+        required_directness=None,
+        post_action_required=False,
+        independent_post_action_required=False,
+        minimum_independent_sources=1,
+        human_approval_required=False,
+        reason="typed_nonfact_claim",
+    )
+
+
+def ingest_model_response(
+    raw: str,
+    *,
+    authority: TypeAuthority = TypeAuthority.EXECUTOR,
+) -> IngestionResult:
+    normalized = normalize_model_response(raw)
+    atoms = atomize_model_response(normalized, authority=authority)
+    contracts = tuple(
+        build_evidence_contract(
+            atom_id=atom.atom_id,
+            claim_type=atom.claim_type,
+        )
+        for atom in atoms
+    )
+    return IngestionResult(
+        normalized=normalized,
+        atoms=atoms,
+        contracts=contracts,
+    )
+
+
+
+_ALLOWED_EVIDENCE_KEYS = {
+    "source_id",
+    "supports",
+    "observed_at",
+    "directness",
+    "post_action",
+    "eligible",
+    "evidence_id",
+    "source_role",
+    "source_ref",
+    "independence_group",
+    "content_sha256",
+    "origin",
+    "authority_scope",
+}
+
+
+def _record_mapping(value: Any, path: str) -> Mapping[str, Any]:
+    if not isinstance(value, Mapping):
+        raise TypeError(f"{path} must be object")
+    return value
+
+
+def _record_string(value: Any, path: str) -> str:
+    if not isinstance(value, str) or not value.strip():
+        raise TypeError(f"{path} must be non-empty string")
+    return value.strip()
+
+
+def _record_optional_string(value: Any, path: str) -> str | None:
+    if value is None:
+        return None
+    return _record_string(value, path)
+
+
+def _record_bool(value: Any, path: str) -> bool:
+    if type(value) is not bool:
+        raise TypeError(f"{path} must be bool")
+    return value
+
+
+def _record_datetime(value: Any, path: str) -> datetime:
+    raw = _record_string(value, path)
+    if raw.endswith("Z"):
+        raw = raw[:-1] + "+00:00"
+    try:
+        parsed = datetime.fromisoformat(raw)
+    except ValueError as exc:
+        raise ValueError(f"{path} must be ISO 8601 datetime") from exc
+    if parsed.tzinfo is None or parsed.utcoffset() is None:
+        raise ValueError(f"{path} must be timezone-aware")
+    return parsed
+
+
+def _record_directness(value: Any, path: str) -> Directness:
+    raw = _record_string(value, path)
+    try:
+        return Directness(raw)
+    except ValueError as exc:
+        raise ValueError(f"invalid {path}: {raw}") from exc
+
+
+def _record_source_role(value: Any, path: str) -> SourceRole:
+    raw = _record_string(value, path)
+    try:
+        return SourceRole(raw)
+    except ValueError as exc:
+        raise ValueError(f"invalid {path}: {raw}") from exc
+
+
+def _record_evidence_origin(value: Any, path: str) -> EvidenceOrigin:
+    raw = _record_string(value, path)
+    try:
+        return EvidenceOrigin(raw)
+    except ValueError as exc:
+        raise ValueError(f"invalid {path}: {raw}") from exc
+
+
+def _record_authority_scope(value: Any, path: str) -> AuthorityScope:
+    raw = _record_string(value, path)
+    try:
+        return AuthorityScope(raw)
+    except ValueError as exc:
+        raise ValueError(f"invalid {path}: {raw}") from exc
+
+
+def collect_normalize_evidence(
+    records_by_atom: Mapping[str, list[Mapping[str, Any]]],
+    *,
+    known_atom_ids: set[str],
+) -> dict[str, tuple[Evidence, ...]]:
+    if not isinstance(records_by_atom, Mapping):
+        raise TypeError("records_by_atom must be object")
+    if not isinstance(known_atom_ids, set):
+        raise TypeError("known_atom_ids must be set")
+
+    unknown = sorted(set(records_by_atom) - known_atom_ids)
+    if unknown:
+        raise ValueError("unknown atom_id: " + ", ".join(unknown))
+
+    normalized: dict[str, tuple[Evidence, ...]] = {}
+    for atom_id in sorted(known_atom_ids):
+        raw_items = records_by_atom.get(atom_id, [])
+        if not isinstance(raw_items, list):
+            raise TypeError(f"evidence for {atom_id} must be list")
+
+        items: list[Evidence] = []
+        seen_evidence_ids: set[str] = set()
+
+        for index, raw in enumerate(raw_items):
+            path = f"evidence_by_atom.{atom_id}[{index}]"
+            obj = _record_mapping(raw, path)
+
+            extra = sorted(set(obj) - _ALLOWED_EVIDENCE_KEYS)
+            if extra:
+                raise ValueError(
+                    f"{path} contains unsupported fields: " + ", ".join(extra)
+                )
+
+            source_id = _record_string(obj.get("source_id"), f"{path}.source_id")
+            evidence_id = _record_optional_string(
+                obj.get("evidence_id"),
+                f"{path}.evidence_id",
+            )
+            effective_id = evidence_id or source_id
+            if effective_id in seen_evidence_ids:
+                if evidence_id is None:
+                    raise ValueError(
+                        f"duplicate source_id for {atom_id}: {source_id}"
+                    )
+                raise ValueError(
+                    f"duplicate evidence_id for {atom_id}: {effective_id}"
+                )
+            seen_evidence_ids.add(effective_id)
+
+            if "supports" not in obj:
+                raise ValueError(f"missing required field: {path}.supports")
+            if "observed_at" not in obj:
+                raise ValueError(f"missing required field: {path}.observed_at")
+            if "directness" not in obj:
+                raise ValueError(f"missing required field: {path}.directness")
+
+            items.append(
+                Evidence(
+                    source_id=source_id,
+                    supports=_record_bool(obj["supports"], f"{path}.supports"),
+                    observed_at=_record_datetime(
+                        obj["observed_at"],
+                        f"{path}.observed_at",
+                    ),
+                    directness=_record_directness(
+                        obj["directness"],
+                        f"{path}.directness",
+                    ),
+                    post_action=_record_bool(
+                        obj.get("post_action", False),
+                        f"{path}.post_action",
+                    ),
+                    eligible=_record_bool(
+                        obj.get("eligible", True),
+                        f"{path}.eligible",
+                    ),
+                    evidence_id=evidence_id,
+                    source_role=_record_source_role(
+                        obj.get("source_role", SourceRole.EXTERNAL.value),
+                        f"{path}.source_role",
+                    ),
+                    source_ref=_record_optional_string(
+                        obj.get("source_ref"),
+                        f"{path}.source_ref",
+                    ),
+                    independence_group=_record_optional_string(
+                        obj.get("independence_group"),
+                        f"{path}.independence_group",
+                    ),
+                    content_sha256=_record_optional_string(
+                        obj.get("content_sha256"),
+                        f"{path}.content_sha256",
+                    ),
+                    origin=_record_evidence_origin(
+                        obj.get("origin", EvidenceOrigin.EXTERNAL_SOURCE.value),
+                        f"{path}.origin",
+                    ),
+                    authority_scope=_record_authority_scope(
+                        obj.get("authority_scope", AuthorityScope.EXTERNAL_FACT.value),
+                        f"{path}.authority_scope",
+                    ),
+                )
+            )
+
+        normalized[atom_id] = tuple(
+            sorted(
+                items,
+                key=lambda item: (
+                    item.evidence_id or item.source_id,
+                    item.source_id,
+                ),
+            )
+        )
+
+    return normalized
+
+
+def _claim_from_atom(atom: ClaimAtom) -> Claim:
+    risk = (
+        RiskLevel.HIGH
+        if atom.claim_type is ClaimType.RISK_SENSITIVE
+        else RiskLevel.LOW
+    )
+    return Claim(
+        claim_id=atom.atom_id,
+        text=atom.text,
+        claim_type=atom.claim_type,
+        risk=risk,
+        consequential=True,
+    )
+
+
+def verify_model_response(
+    raw: str,
+    *,
+    evidence_by_atom: Mapping[str, list[Mapping[str, Any]]],
+    authority: TypeAuthority,
+    policy: Policy,
+    evaluation_time: datetime,
+    human_approvals: Mapping[str, bool] | None = None,
+) -> IngestedVerificationResult:
+    ingestion = ingest_model_response(raw, authority=authority)
+    atom_ids = {atom.atom_id for atom in ingestion.atoms}
+
+    evidence = collect_normalize_evidence(
+        evidence_by_atom,
+        known_atom_ids=atom_ids,
+    )
+
+    approvals = human_approvals or {}
+    unknown_approvals = sorted(set(approvals) - atom_ids)
+    if unknown_approvals:
+        raise ValueError(
+            "human_approvals contains unknown atom_id: "
+            + ", ".join(unknown_approvals)
+        )
+    for atom_id, value in approvals.items():
+        if type(value) is not bool:
+            raise TypeError(f"human_approvals.{atom_id} must be bool")
+
+    compound = verify_compound(
+        tuple(_claim_from_atom(atom) for atom in ingestion.atoms),
+        evidence,
+        policy=policy,
+        evaluation_time=evaluation_time,
+        human_approvals=approvals,
+    )
+
+    return IngestedVerificationResult(
+        ingestion=ingestion,
+        results=compound.results,
+        verdict=compound.verdict,
     )

bodulskihal_core/lifecycle.py

@@ -1,280 +1,280 @@
-from __future__ import annotations
-
-from dataclasses import dataclass
-from enum import Enum
-
-from .engine import Verdict, canonical_receipt_sha256
-
-
-class ProjectState(str, Enum):
-    ACTIVE = "active"
-    FROZEN = "frozen"
-
-
-@dataclass(frozen=True)
-class LifecycleResult:
-    state: ProjectState
-    verdict: Verdict
-    reason: str
-    receipt: dict
-
-
-def _non_empty(value: str, name: str) -> str:
-    if not isinstance(value, str) or not value.strip():
-        raise ValueError(f"{name} must be non-empty")
-    return value.strip()
-
-
-def _validate_bool(value: bool, name: str) -> None:
-    if type(value) is not bool:
-        raise TypeError(f"{name} must be bool")
-
-
-def _receipt(
-    *,
-    project_id: str,
-    transition: str,
-    from_state: ProjectState,
-    to_state: ProjectState,
-    checkpoint_digest: str | None,
-    checkpoint_verified: bool | None,
-    human_approved: bool | None,
-    policy_version: str,
-    reason: str,
-    reopen_reason: str | None = None,
-) -> dict:
-    receipt = {
-        "subsystem": "project_lifecycle",
-        "policy_version": policy_version,
-        "project_id": project_id,
-        "transition": transition,
-        "from_state": from_state.value,
-        "to_state": to_state.value,
-        "checkpoint_digest": checkpoint_digest,
-        "checkpoint_verified": checkpoint_verified,
-        "human_approved": human_approved,
-        "reason": reason,
-        "reopen_reason": reopen_reason,
-    }
-    receipt["receipt_sha256"] = canonical_receipt_sha256(receipt)
-    return receipt
-
-
-def freeze_project(
-    *,
-    project_id: str,
-    current_state: ProjectState,
-    checkpoint_digest: str,
-    checkpoint_verified: bool,
-    human_approved: bool,
-    policy_version: str,
-    current_checkpoint_digest: str | None = None,
-) -> LifecycleResult:
-    project_id = _non_empty(project_id, "project_id")
-    checkpoint_digest = _non_empty(checkpoint_digest, "checkpoint_digest")
-    policy_version = _non_empty(policy_version, "policy_version")
-    _validate_bool(checkpoint_verified, "checkpoint_verified")
-    _validate_bool(human_approved, "human_approved")
-
-    if current_state is ProjectState.FROZEN:
-        if current_checkpoint_digest == checkpoint_digest:
-            reason = "already_frozen_same_checkpoint"
-            return LifecycleResult(
-                state=ProjectState.FROZEN,
-                verdict=Verdict.APPROVE,
-                reason=reason,
-                receipt=_receipt(
-                    project_id=project_id,
-                    transition="freeze",
-                    from_state=ProjectState.FROZEN,
-                    to_state=ProjectState.FROZEN,
-                    checkpoint_digest=checkpoint_digest,
-                    checkpoint_verified=checkpoint_verified,
-                    human_approved=human_approved,
-                    policy_version=policy_version,
-                    reason=reason,
-                ),
-            )
-
-        reason = "frozen_checkpoint_mismatch"
-        return LifecycleResult(
-            state=ProjectState.FROZEN,
-            verdict=Verdict.BLOCK,
-            reason=reason,
-            receipt=_receipt(
-                project_id=project_id,
-                transition="freeze",
-                from_state=ProjectState.FROZEN,
-                to_state=ProjectState.FROZEN,
-                checkpoint_digest=checkpoint_digest,
-                checkpoint_verified=checkpoint_verified,
-                human_approved=human_approved,
-                policy_version=policy_version,
-                reason=reason,
-            ),
-        )
-
-    if not checkpoint_verified:
-        reason = "checkpoint_not_verified"
-        return LifecycleResult(
-            state=ProjectState.ACTIVE,
-            verdict=Verdict.BLOCK,
-            reason=reason,
-            receipt=_receipt(
-                project_id=project_id,
-                transition="freeze",
-                from_state=ProjectState.ACTIVE,
-                to_state=ProjectState.ACTIVE,
-                checkpoint_digest=checkpoint_digest,
-                checkpoint_verified=False,
-                human_approved=human_approved,
-                policy_version=policy_version,
-                reason=reason,
-            ),
-        )
-
-    if not human_approved:
-        reason = "human_approval_required_for_freeze"
-        return LifecycleResult(
-            state=ProjectState.ACTIVE,
-            verdict=Verdict.ESCALATE,
-            reason=reason,
-            receipt=_receipt(
-                project_id=project_id,
-                transition="freeze",
-                from_state=ProjectState.ACTIVE,
-                to_state=ProjectState.ACTIVE,
-                checkpoint_digest=checkpoint_digest,
-                checkpoint_verified=True,
-                human_approved=False,
-                policy_version=policy_version,
-                reason=reason,
-            ),
-        )
-
-    reason = "verified_checkpoint_frozen"
-    return LifecycleResult(
-        state=ProjectState.FROZEN,
-        verdict=Verdict.APPROVE,
-        reason=reason,
-        receipt=_receipt(
-            project_id=project_id,
-            transition="freeze",
-            from_state=ProjectState.ACTIVE,
-            to_state=ProjectState.FROZEN,
-            checkpoint_digest=checkpoint_digest,
-            checkpoint_verified=True,
-            human_approved=True,
-            policy_version=policy_version,
-            reason=reason,
-        ),
-    )
-
-
-def authorize_mutation(
-    *,
-    project_id: str,
-    current_state: ProjectState,
-    policy_version: str,
-) -> LifecycleResult:
-    project_id = _non_empty(project_id, "project_id")
-    policy_version = _non_empty(policy_version, "policy_version")
-
-    if current_state is ProjectState.FROZEN:
-        reason = "project_frozen_controlled_reopen_required"
-        verdict = Verdict.BLOCK
-    else:
-        reason = "project_active"
-        verdict = Verdict.APPROVE
-
-    return LifecycleResult(
-        state=current_state,
-        verdict=verdict,
-        reason=reason,
-        receipt=_receipt(
-            project_id=project_id,
-            transition="mutation_gate",
-            from_state=current_state,
-            to_state=current_state,
-            checkpoint_digest=None,
-            checkpoint_verified=None,
-            human_approved=None,
-            policy_version=policy_version,
-            reason=reason,
-        ),
-    )
-
-
-def reopen_project(
-    *,
-    project_id: str,
-    current_state: ProjectState,
-    checkpoint_digest: str,
-    reopen_reason: str,
-    human_approved: bool,
-    policy_version: str,
-) -> LifecycleResult:
-    project_id = _non_empty(project_id, "project_id")
-    checkpoint_digest = _non_empty(checkpoint_digest, "checkpoint_digest")
-    reopen_reason = _non_empty(reopen_reason, "reopen_reason")
-    policy_version = _non_empty(policy_version, "policy_version")
-    _validate_bool(human_approved, "human_approved")
-
-    if current_state is not ProjectState.FROZEN:
-        reason = "invalid_reopen_transition"
-        return LifecycleResult(
-            state=current_state,
-            verdict=Verdict.BLOCK,
-            reason=reason,
-            receipt=_receipt(
-                project_id=project_id,
-                transition="reopen",
-                from_state=current_state,
-                to_state=current_state,
-                checkpoint_digest=checkpoint_digest,
-                checkpoint_verified=True,
-                human_approved=human_approved,
-                policy_version=policy_version,
-                reason=reason,
-                reopen_reason=reopen_reason,
-            ),
-        )
-
-    if not human_approved:
-        reason = "human_approval_required_for_reopen"
-        return LifecycleResult(
-            state=ProjectState.FROZEN,
-            verdict=Verdict.ESCALATE,
-            reason=reason,
-            receipt=_receipt(
-                project_id=project_id,
-                transition="reopen",
-                from_state=ProjectState.FROZEN,
-                to_state=ProjectState.FROZEN,
-                checkpoint_digest=checkpoint_digest,
-                checkpoint_verified=True,
-                human_approved=False,
-                policy_version=policy_version,
-                reason=reason,
-                reopen_reason=reopen_reason,
-            ),
-        )
-
-    reason = "controlled_reopen_approved"
-    return LifecycleResult(
-        state=ProjectState.ACTIVE,
-        verdict=Verdict.APPROVE,
-        reason=reason,
-        receipt=_receipt(
-            project_id=project_id,
-            transition="reopen",
-            from_state=ProjectState.FROZEN,
-            to_state=ProjectState.ACTIVE,
-            checkpoint_digest=checkpoint_digest,
-            checkpoint_verified=True,
-            human_approved=True,
-            policy_version=policy_version,
-            reason=reason,
-            reopen_reason=reopen_reason,
-        ),
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+
+from .engine import Verdict, canonical_receipt_sha256
+
+
+class ProjectState(str, Enum):
+    ACTIVE = "active"
+    FROZEN = "frozen"
+
+
+@dataclass(frozen=True)
+class LifecycleResult:
+    state: ProjectState
+    verdict: Verdict
+    reason: str
+    receipt: dict
+
+
+def _non_empty(value: str, name: str) -> str:
+    if not isinstance(value, str) or not value.strip():
+        raise ValueError(f"{name} must be non-empty")
+    return value.strip()
+
+
+def _validate_bool(value: bool, name: str) -> None:
+    if type(value) is not bool:
+        raise TypeError(f"{name} must be bool")
+
+
+def _receipt(
+    *,
+    project_id: str,
+    transition: str,
+    from_state: ProjectState,
+    to_state: ProjectState,
+    checkpoint_digest: str | None,
+    checkpoint_verified: bool | None,
+    human_approved: bool | None,
+    policy_version: str,
+    reason: str,
+    reopen_reason: str | None = None,
+) -> dict:
+    receipt = {
+        "subsystem": "project_lifecycle",
+        "policy_version": policy_version,
+        "project_id": project_id,
+        "transition": transition,
+        "from_state": from_state.value,
+        "to_state": to_state.value,
+        "checkpoint_digest": checkpoint_digest,
+        "checkpoint_verified": checkpoint_verified,
+        "human_approved": human_approved,
+        "reason": reason,
+        "reopen_reason": reopen_reason,
+    }
+    receipt["receipt_sha256"] = canonical_receipt_sha256(receipt)
+    return receipt
+
+
+def freeze_project(
+    *,
+    project_id: str,
+    current_state: ProjectState,
+    checkpoint_digest: str,
+    checkpoint_verified: bool,
+    human_approved: bool,
+    policy_version: str,
+    current_checkpoint_digest: str | None = None,
+) -> LifecycleResult:
+    project_id = _non_empty(project_id, "project_id")
+    checkpoint_digest = _non_empty(checkpoint_digest, "checkpoint_digest")
+    policy_version = _non_empty(policy_version, "policy_version")
+    _validate_bool(checkpoint_verified, "checkpoint_verified")
+    _validate_bool(human_approved, "human_approved")
+
+    if current_state is ProjectState.FROZEN:
+        if current_checkpoint_digest == checkpoint_digest:
+            reason = "already_frozen_same_checkpoint"
+            return LifecycleResult(
+                state=ProjectState.FROZEN,
+                verdict=Verdict.APPROVE,
+                reason=reason,
+                receipt=_receipt(
+                    project_id=project_id,
+                    transition="freeze",
+                    from_state=ProjectState.FROZEN,
+                    to_state=ProjectState.FROZEN,
+                    checkpoint_digest=checkpoint_digest,
+                    checkpoint_verified=checkpoint_verified,
+                    human_approved=human_approved,
+                    policy_version=policy_version,
+                    reason=reason,
+                ),
+            )
+
+        reason = "frozen_checkpoint_mismatch"
+        return LifecycleResult(
+            state=ProjectState.FROZEN,
+            verdict=Verdict.BLOCK,
+            reason=reason,
+            receipt=_receipt(
+                project_id=project_id,
+                transition="freeze",
+                from_state=ProjectState.FROZEN,
+                to_state=ProjectState.FROZEN,
+                checkpoint_digest=checkpoint_digest,
+                checkpoint_verified=checkpoint_verified,
+                human_approved=human_approved,
+                policy_version=policy_version,
+                reason=reason,
+            ),
+        )
+
+    if not checkpoint_verified:
+        reason = "checkpoint_not_verified"
+        return LifecycleResult(
+            state=ProjectState.ACTIVE,
+            verdict=Verdict.BLOCK,
+            reason=reason,
+            receipt=_receipt(
+                project_id=project_id,
+                transition="freeze",
+                from_state=ProjectState.ACTIVE,
+                to_state=ProjectState.ACTIVE,
+                checkpoint_digest=checkpoint_digest,
+                checkpoint_verified=False,
+                human_approved=human_approved,
+                policy_version=policy_version,
+                reason=reason,
+            ),
+        )
+
+    if not human_approved:
+        reason = "human_approval_required_for_freeze"
+        return LifecycleResult(
+            state=ProjectState.ACTIVE,
+            verdict=Verdict.ESCALATE,
+            reason=reason,
+            receipt=_receipt(
+                project_id=project_id,
+                transition="freeze",
+                from_state=ProjectState.ACTIVE,
+                to_state=ProjectState.ACTIVE,
+                checkpoint_digest=checkpoint_digest,
+                checkpoint_verified=True,
+                human_approved=False,
+                policy_version=policy_version,
+                reason=reason,
+            ),
+        )
+
+    reason = "verified_checkpoint_frozen"
+    return LifecycleResult(
+        state=ProjectState.FROZEN,
+        verdict=Verdict.APPROVE,
+        reason=reason,
+        receipt=_receipt(
+            project_id=project_id,
+            transition="freeze",
+            from_state=ProjectState.ACTIVE,
+            to_state=ProjectState.FROZEN,
+            checkpoint_digest=checkpoint_digest,
+            checkpoint_verified=True,
+            human_approved=True,
+            policy_version=policy_version,
+            reason=reason,
+        ),
+    )
+
+
+def authorize_mutation(
+    *,
+    project_id: str,
+    current_state: ProjectState,
+    policy_version: str,
+) -> LifecycleResult:
+    project_id = _non_empty(project_id, "project_id")
+    policy_version = _non_empty(policy_version, "policy_version")
+
+    if current_state is ProjectState.FROZEN:
+        reason = "project_frozen_controlled_reopen_required"
+        verdict = Verdict.BLOCK
+    else:
+        reason = "project_active"
+        verdict = Verdict.APPROVE
+
+    return LifecycleResult(
+        state=current_state,
+        verdict=verdict,
+        reason=reason,
+        receipt=_receipt(
+            project_id=project_id,
+            transition="mutation_gate",
+            from_state=current_state,
+            to_state=current_state,
+            checkpoint_digest=None,
+            checkpoint_verified=None,
+            human_approved=None,
+            policy_version=policy_version,
+            reason=reason,
+        ),
+    )
+
+
+def reopen_project(
+    *,
+    project_id: str,
+    current_state: ProjectState,
+    checkpoint_digest: str,
+    reopen_reason: str,
+    human_approved: bool,
+    policy_version: str,
+) -> LifecycleResult:
+    project_id = _non_empty(project_id, "project_id")
+    checkpoint_digest = _non_empty(checkpoint_digest, "checkpoint_digest")
+    reopen_reason = _non_empty(reopen_reason, "reopen_reason")
+    policy_version = _non_empty(policy_version, "policy_version")
+    _validate_bool(human_approved, "human_approved")
+
+    if current_state is not ProjectState.FROZEN:
+        reason = "invalid_reopen_transition"
+        return LifecycleResult(
+            state=current_state,
+            verdict=Verdict.BLOCK,
+            reason=reason,
+            receipt=_receipt(
+                project_id=project_id,
+                transition="reopen",
+                from_state=current_state,
+                to_state=current_state,
+                checkpoint_digest=checkpoint_digest,
+                checkpoint_verified=True,
+                human_approved=human_approved,
+                policy_version=policy_version,
+                reason=reason,
+                reopen_reason=reopen_reason,
+            ),
+        )
+
+    if not human_approved:
+        reason = "human_approval_required_for_reopen"
+        return LifecycleResult(
+            state=ProjectState.FROZEN,
+            verdict=Verdict.ESCALATE,
+            reason=reason,
+            receipt=_receipt(
+                project_id=project_id,
+                transition="reopen",
+                from_state=ProjectState.FROZEN,
+                to_state=ProjectState.FROZEN,
+                checkpoint_digest=checkpoint_digest,
+                checkpoint_verified=True,
+                human_approved=False,
+                policy_version=policy_version,
+                reason=reason,
+                reopen_reason=reopen_reason,
+            ),
+        )
+
+    reason = "controlled_reopen_approved"
+    return LifecycleResult(
+        state=ProjectState.ACTIVE,
+        verdict=Verdict.APPROVE,
+        reason=reason,
+        receipt=_receipt(
+            project_id=project_id,
+            transition="reopen",
+            from_state=ProjectState.FROZEN,
+            to_state=ProjectState.ACTIVE,
+            checkpoint_digest=checkpoint_digest,
+            checkpoint_verified=True,
+            human_approved=True,
+            policy_version=policy_version,
+            reason=reason,
+            reopen_reason=reopen_reason,
+        ),
     )

bodulskihal_core/raw_pipeline.py

@@ -1,464 +1,464 @@
-from __future__ import annotations
-
-import hashlib
-import re
-from dataclasses import dataclass
-from enum import Enum
-
-from .engine import ClaimType, Directness
-
-
-class SpeakerRole(str, Enum):
-    ASSISTANT = "assistant"
-    USER = "user"
-    TOOL = "tool"
-    UNKNOWN = "unknown"
-
-
-class AtomStatus(str, Enum):
-    READY = "ready"
-    REVIEW_REQUIRED = "review_required"
-
-
-class ClauseTypeStatus(str, Enum):
-    TYPED = "typed"
-    REVIEW_REQUIRED = "review_required"
-
-
-@dataclass(frozen=True)
-class RawResponseEnvelope:
-    response_id: str
-    text: str
-    speaker_role: SpeakerRole
-    raw_sha256: str
-
-    @classmethod
-    def create(
-        cls,
-        response_id: str,
-        text: str,
-        speaker_role: SpeakerRole,
-    ) -> "RawResponseEnvelope":
-        if not isinstance(response_id, str) or not response_id.strip():
-            raise ValueError("response_id must be non-empty")
-        if not isinstance(text, str) or not text.strip():
-            raise ValueError("text must be non-empty")
-        if not isinstance(speaker_role, SpeakerRole):
-            raise TypeError("speaker_role must be SpeakerRole")
-
-        return cls(
-            response_id=response_id.strip(),
-            text=text,
-            speaker_role=speaker_role,
-            raw_sha256=hashlib.sha256(text.encode("utf-8")).hexdigest(),
-        )
-
-
-@dataclass(frozen=True)
-class ClaimAtom:
-    atom_id: str
-    response_id: str
-    start: int
-    end: int
-    source_text: str
-    status: AtomStatus
-    review_reasons: tuple[str, ...]
-
-
-@dataclass(frozen=True)
-class EvidenceContract:
-    atom_id: str
-    claim_type: ClaimType
-    required_directness: Directness
-    requires_post_action: bool
-    requires_human_review: bool
-    fact_eligible: bool
-    review_reasons: tuple[str, ...]
-
-
-@dataclass(frozen=True)
-class ClauseTypeDecision:
-    atom_id: str
-    claim_type: ClaimType | None
-    status: ClauseTypeStatus
-    reasons: tuple[str, ...]
-    rule: str
-
-
-@dataclass(frozen=True)
-class SpanProposal:
-    atom_id: str
-    start: int
-    end: int
-    quoted_text: str
-
-
-_COMPOUND_CUES = re.compile(
-    r"\b(and|or|nor|but|while|although|however|whereas|because)\b",
-    re.IGNORECASE,
-)
-
-_EPISTEMIC_QUALIFIERS = re.compile(
-    r"\b(may|might|could|probably|likely|possibly|perhaps|appears?|seems?)\b",
-    re.IGNORECASE,
-)
-
-_CONDITIONAL_CUES = re.compile(
-    r"\b(if|unless|provided|assuming)\b",
-    re.IGNORECASE,
-)
-
-_ACTION_STATE_CUES = re.compile(
-    r"\b(completed|complete|finished|sent|submitted|deployed|merged|published|"
-    r"uploaded|downloaded|installed|deleted|created|updated|saved|executed|"
-    r"started|stopped|closed|opened|approved|rejected)\b",
-    re.IGNORECASE,
-)
-
-_ESTIMATE_CUES = re.compile(
-    r"\b(estimate|estimated|approximately|approximate|roughly)\b",
-    re.IGNORECASE,
-)
-
-_ABBREVIATIONS = {
-    "dr.",
-    "mr.",
-    "mrs.",
-    "ms.",
-    "prof.",
-    "sr.",
-    "jr.",
-    "st.",
-}
-
-_AMBIGUOUS_REFERENT = re.compile(
-    r"^(it|this|that|they|these|those|he|she)\b",
-    re.IGNORECASE,
-)
-
-
-def _review_reasons(source_text: str) -> tuple[str, ...]:
-    reasons: list[str] = []
-    stripped = source_text.strip()
-
-    if _COMPOUND_CUES.search(stripped) or ";" in stripped:
-        reasons.append("compound_clause")
-
-    if _EPISTEMIC_QUALIFIERS.search(stripped):
-        reasons.append("epistemic_qualifier")
-
-    if _CONDITIONAL_CUES.search(stripped):
-        reasons.append("conditional_clause")
-
-    if _AMBIGUOUS_REFERENT.search(stripped):
-        reasons.append("ambiguous_referent")
-
-    return tuple(reasons)
-
-
-def bind_atom(
-    envelope: RawResponseEnvelope,
-    *,
-    atom_id: str,
-    start: int,
-    end: int,
-    proposed_text: str | None = None,
-) -> ClaimAtom:
-    if not isinstance(atom_id, str) or not atom_id.strip():
-        raise ValueError("atom_id must be non-empty")
-    if not isinstance(start, int) or not isinstance(end, int):
-        raise TypeError("span offsets must be integers")
-    if start < 0 or end > len(envelope.text) or start >= end:
-        raise ValueError("invalid source span")
-
-    source_text = envelope.text[start:end]
-    if not source_text.strip():
-        raise ValueError("source span must contain non-whitespace text")
-
-    if proposed_text is not None and proposed_text != source_text:
-        raise ValueError("proposed text must exactly match source span")
-
-    reasons = _review_reasons(source_text)
-    status = AtomStatus.REVIEW_REQUIRED if reasons else AtomStatus.READY
-
-    return ClaimAtom(
-        atom_id=atom_id.strip(),
-        response_id=envelope.response_id,
-        start=start,
-        end=end,
-        source_text=source_text,
-        status=status,
-        review_reasons=reasons,
-    )
-
-
-def _is_abbreviation_period(text: str, index: int) -> bool:
-    if text[index] != "." or index + 1 >= len(text):
-        return False
-
-    word_start = index - 1
-    while word_start >= 0 and text[word_start].isalpha():
-        word_start -= 1
-    token = text[word_start + 1:index + 1].lower()
-
-    is_initial = len(token) == 2 and token[0].isalpha() and token[1] == "."
-    if token not in _ABBREVIATIONS and not is_initial:
-        return False
-
-    cursor = index + 1
-    while cursor < len(text) and text[cursor] in " \t":
-        cursor += 1
-
-    if cursor >= len(text) or "\n" in text[index + 1:cursor + 1]:
-        return False
-
-    return text[cursor].isupper()
-
-
-def _sentence_spans(text: str) -> tuple[tuple[int, int], ...]:
-    spans: list[tuple[int, int]] = []
-    length = len(text)
-    cursor = 0
-
-    while cursor < length:
-        while cursor < length and text[cursor].isspace():
-            cursor += 1
-        if cursor >= length:
-            break
-
-        start = cursor
-        end = length
-        i = cursor
-
-        while i < length:
-            ch = text[i]
-
-            if ch == "\n":
-                end = i
-                break
-
-            if ch in ".!?":
-                if ch == "." and _is_abbreviation_period(text, i):
-                    i += 1
-                    continue
-
-                next_index = i + 1
-                if next_index >= length or text[next_index].isspace():
-                    end = next_index
-                    break
-
-            i += 1
-
-        while end > start and text[end - 1].isspace():
-            end -= 1
-
-        if end > start:
-            spans.append((start, end))
-
-        cursor = max(i + 1, end)
-
-    return tuple(spans)
-
-
-def atomize_raw_response(
-    envelope: RawResponseEnvelope,
-) -> tuple[ClaimAtom, ...]:
-    if envelope.speaker_role is not SpeakerRole.ASSISTANT:
-        raise ValueError(
-            "only assistant responses may be atomized as assistant claims"
-        )
-
-    spans = _sentence_spans(envelope.text)
-    return tuple(
-        bind_atom(
-            envelope,
-            atom_id=f"{envelope.response_id}:atom:{index}",
-            start=start,
-            end=end,
-        )
-        for index, (start, end) in enumerate(spans, start=1)
-    )
-
-
-def validate_atom_proposals(
-    envelope: RawResponseEnvelope,
-    proposals: list[SpanProposal] | tuple[SpanProposal, ...],
-) -> tuple[ClaimAtom, ...]:
-    if envelope.speaker_role is not SpeakerRole.ASSISTANT:
-        raise ValueError(
-            "only assistant responses may be atomized as assistant claims"
-        )
-
-    proposal_seq = tuple(proposals)
-    atom_ids = [proposal.atom_id for proposal in proposal_seq]
-    if len(atom_ids) != len(set(atom_ids)):
-        raise ValueError("duplicate atom_id")
-
-    ordered = sorted(
-        proposal_seq,
-        key=lambda proposal: (proposal.start, proposal.end, proposal.atom_id),
-    )
-
-    previous_end: int | None = None
-    atoms: list[ClaimAtom] = []
-
-    for proposal in ordered:
-        if not isinstance(proposal.atom_id, str) or not proposal.atom_id.strip():
-            raise ValueError("atom_id must be non-empty")
-        if not isinstance(proposal.quoted_text, str):
-            raise TypeError("quoted_text must be string")
-
-        if (
-            proposal.start < 0
-            or proposal.end > len(envelope.text)
-            or proposal.start >= proposal.end
-        ):
-            raise ValueError("invalid source span")
-
-        exact_slice = envelope.text[proposal.start:proposal.end]
-        if proposal.quoted_text != exact_slice:
-            raise ValueError("quoted_text must exactly match source span")
-
-        atom = bind_atom(
-            envelope,
-            atom_id=proposal.atom_id,
-            start=proposal.start,
-            end=proposal.end,
-            proposed_text=proposal.quoted_text,
-        )
-
-        if previous_end is not None and atom.start < previous_end:
-            raise ValueError("span proposals must not overlap")
-
-        atoms.append(atom)
-        previous_end = atom.end
-
-    return tuple(atoms)
-
-
-def type_clause(atom: ClaimAtom) -> ClauseTypeDecision:
-    reasons = list(atom.review_reasons)
-    blocking_reasons = {
-        "compound_clause",
-        "conditional_clause",
-        "ambiguous_referent",
-    }
-
-    if blocking_reasons.intersection(reasons):
-        return ClauseTypeDecision(
-            atom_id=atom.atom_id,
-            claim_type=None,
-            status=ClauseTypeStatus.REVIEW_REQUIRED,
-            reasons=tuple(reasons),
-            rule="review_gate",
-        )
-
-    text = atom.source_text.strip()
-    action_signal = bool(_ACTION_STATE_CUES.search(text))
-    estimate_signal = bool(_ESTIMATE_CUES.search(text))
-    inference_signal = "epistemic_qualifier" in reasons
-
-    signals = [
-        claim_type
-        for claim_type, present in (
-            (ClaimType.ACTION_STATE, action_signal),
-            (ClaimType.ESTIMATE, estimate_signal),
-            (ClaimType.INFERENCE, inference_signal),
-        )
-        if present
-    ]
-
-    if len(signals) > 1:
-        if "multiple_type_signals" not in reasons:
-            reasons.append("multiple_type_signals")
-        return ClauseTypeDecision(
-            atom_id=atom.atom_id,
-            claim_type=None,
-            status=ClauseTypeStatus.REVIEW_REQUIRED,
-            reasons=tuple(reasons),
-            rule="conflicting_type_cues",
-        )
-
-    if inference_signal:
-        return ClauseTypeDecision(
-            atom_id=atom.atom_id,
-            claim_type=ClaimType.INFERENCE,
-            status=ClauseTypeStatus.REVIEW_REQUIRED,
-            reasons=tuple(reasons),
-            rule="epistemic_qualifier",
-        )
-
-    if estimate_signal:
-        return ClauseTypeDecision(
-            atom_id=atom.atom_id,
-            claim_type=ClaimType.ESTIMATE,
-            status=ClauseTypeStatus.TYPED,
-            reasons=tuple(reasons),
-            rule="estimate_cue",
-        )
-
-    if action_signal:
-        return ClauseTypeDecision(
-            atom_id=atom.atom_id,
-            claim_type=ClaimType.ACTION_STATE,
-            status=ClauseTypeStatus.TYPED,
-            reasons=tuple(reasons),
-            rule="action_state_cue",
-        )
-
-    return ClauseTypeDecision(
-        atom_id=atom.atom_id,
-        claim_type=ClaimType.OBSERVATION,
-        status=ClauseTypeStatus.TYPED,
-        reasons=tuple(reasons),
-        rule="default_observation",
-    )
-
-
-def build_evidence_contract(
-    atom: ClaimAtom,
-    claim_type: ClaimType,
-    *,
-    type_human_approved: bool = False,
-) -> EvidenceContract:
-    if not isinstance(claim_type, ClaimType):
-        raise TypeError("claim_type must be ClaimType")
-    if type(type_human_approved) is not bool:
-        raise TypeError("type_human_approved must be bool")
-
-    review_reasons = list(atom.review_reasons)
-    atom_requires_review = atom.status is AtomStatus.REVIEW_REQUIRED
-    requires_human_review = atom_requires_review
-    requires_post_action = claim_type is ClaimType.ACTION_STATE
-
-    if claim_type in {ClaimType.INFERENCE, ClaimType.ESTIMATE}:
-        fact_eligible = False
-    elif claim_type is ClaimType.ACTION_STATE:
-        fact_eligible = not atom_requires_review
-    elif claim_type is ClaimType.RISK_SENSITIVE:
-        fact_eligible = False
-        requires_human_review = True
-        if "risk_sensitive_requires_human_review" not in review_reasons:
-            review_reasons.append("risk_sensitive_requires_human_review")
-    else:
-        if atom_requires_review:
-            fact_eligible = False
-            requires_human_review = True
-        elif type_human_approved:
-            fact_eligible = True
-            requires_human_review = False
-        else:
-            fact_eligible = False
-            requires_human_review = True
-            if "observation_type_requires_approval" not in review_reasons:
-                review_reasons.append("observation_type_requires_approval")
-
-    return EvidenceContract(
-        atom_id=atom.atom_id,
-        claim_type=claim_type,
-        required_directness=Directness.DIRECT,
-        requires_post_action=requires_post_action,
-        requires_human_review=requires_human_review,
-        fact_eligible=fact_eligible,
-        review_reasons=tuple(review_reasons),
+from __future__ import annotations
+
+import hashlib
+import re
+from dataclasses import dataclass
+from enum import Enum
+
+from .engine import ClaimType, Directness
+
+
+class SpeakerRole(str, Enum):
+    ASSISTANT = "assistant"
+    USER = "user"
+    TOOL = "tool"
+    UNKNOWN = "unknown"
+
+
+class AtomStatus(str, Enum):
+    READY = "ready"
+    REVIEW_REQUIRED = "review_required"
+
+
+class ClauseTypeStatus(str, Enum):
+    TYPED = "typed"
+    REVIEW_REQUIRED = "review_required"
+
+
+@dataclass(frozen=True)
+class RawResponseEnvelope:
+    response_id: str
+    text: str
+    speaker_role: SpeakerRole
+    raw_sha256: str
+
+    @classmethod
+    def create(
+        cls,
+        response_id: str,
+        text: str,
+        speaker_role: SpeakerRole,
+    ) -> "RawResponseEnvelope":
+        if not isinstance(response_id, str) or not response_id.strip():
+            raise ValueError("response_id must be non-empty")
+        if not isinstance(text, str) or not text.strip():
+            raise ValueError("text must be non-empty")
+        if not isinstance(speaker_role, SpeakerRole):
+            raise TypeError("speaker_role must be SpeakerRole")
+
+        return cls(
+            response_id=response_id.strip(),
+            text=text,
+            speaker_role=speaker_role,
+            raw_sha256=hashlib.sha256(text.encode("utf-8")).hexdigest(),
+        )
+
+
+@dataclass(frozen=True)
+class ClaimAtom:
+    atom_id: str
+    response_id: str
+    start: int
+    end: int
+    source_text: str
+    status: AtomStatus
+    review_reasons: tuple[str, ...]
+
+
+@dataclass(frozen=True)
+class EvidenceContract:
+    atom_id: str
+    claim_type: ClaimType
+    required_directness: Directness
+    requires_post_action: bool
+    requires_human_review: bool
+    fact_eligible: bool
+    review_reasons: tuple[str, ...]
+
+
+@dataclass(frozen=True)
+class ClauseTypeDecision:
+    atom_id: str
+    claim_type: ClaimType | None
+    status: ClauseTypeStatus
+    reasons: tuple[str, ...]
+    rule: str
+
+
+@dataclass(frozen=True)
+class SpanProposal:
+    atom_id: str
+    start: int
+    end: int
+    quoted_text: str
+
+
+_COMPOUND_CUES = re.compile(
+    r"\b(and|or|nor|but|while|although|however|whereas|because)\b",
+    re.IGNORECASE,
+)
+
+_EPISTEMIC_QUALIFIERS = re.compile(
+    r"\b(may|might|could|probably|likely|possibly|perhaps|appears?|seems?)\b",
+    re.IGNORECASE,
+)
+
+_CONDITIONAL_CUES = re.compile(
+    r"\b(if|unless|provided|assuming)\b",
+    re.IGNORECASE,
+)
+
+_ACTION_STATE_CUES = re.compile(
+    r"\b(completed|complete|finished|sent|submitted|deployed|merged|published|"
+    r"uploaded|downloaded|installed|deleted|created|updated|saved|executed|"
+    r"started|stopped|closed|opened|approved|rejected)\b",
+    re.IGNORECASE,
+)
+
+_ESTIMATE_CUES = re.compile(
+    r"\b(estimate|estimated|approximately|approximate|roughly)\b",
+    re.IGNORECASE,
+)
+
+_ABBREVIATIONS = {
+    "dr.",
+    "mr.",
+    "mrs.",
+    "ms.",
+    "prof.",
+    "sr.",
+    "jr.",
+    "st.",
+}
+
+_AMBIGUOUS_REFERENT = re.compile(
+    r"^(it|this|that|they|these|those|he|she)\b",
+    re.IGNORECASE,
+)
+
+
+def _review_reasons(source_text: str) -> tuple[str, ...]:
+    reasons: list[str] = []
+    stripped = source_text.strip()
+
+    if _COMPOUND_CUES.search(stripped) or ";" in stripped:
+        reasons.append("compound_clause")
+
+    if _EPISTEMIC_QUALIFIERS.search(stripped):
+        reasons.append("epistemic_qualifier")
+
+    if _CONDITIONAL_CUES.search(stripped):
+        reasons.append("conditional_clause")
+
+    if _AMBIGUOUS_REFERENT.search(stripped):
+        reasons.append("ambiguous_referent")
+
+    return tuple(reasons)
+
+
+def bind_atom(
+    envelope: RawResponseEnvelope,
+    *,
+    atom_id: str,
+    start: int,
+    end: int,
+    proposed_text: str | None = None,
+) -> ClaimAtom:
+    if not isinstance(atom_id, str) or not atom_id.strip():
+        raise ValueError("atom_id must be non-empty")
+    if not isinstance(start, int) or not isinstance(end, int):
+        raise TypeError("span offsets must be integers")
+    if start < 0 or end > len(envelope.text) or start >= end:
+        raise ValueError("invalid source span")
+
+    source_text = envelope.text[start:end]
+    if not source_text.strip():
+        raise ValueError("source span must contain non-whitespace text")
+
+    if proposed_text is not None and proposed_text != source_text:
+        raise ValueError("proposed text must exactly match source span")
+
+    reasons = _review_reasons(source_text)
+    status = AtomStatus.REVIEW_REQUIRED if reasons else AtomStatus.READY
+
+    return ClaimAtom(
+        atom_id=atom_id.strip(),
+        response_id=envelope.response_id,
+        start=start,
+        end=end,
+        source_text=source_text,
+        status=status,
+        review_reasons=reasons,
+    )
+
+
+def _is_abbreviation_period(text: str, index: int) -> bool:
+    if text[index] != "." or index + 1 >= len(text):
+        return False
+
+    word_start = index - 1
+    while word_start >= 0 and text[word_start].isalpha():
+        word_start -= 1
+    token = text[word_start + 1:index + 1].lower()
+
+    is_initial = len(token) == 2 and token[0].isalpha() and token[1] == "."
+    if token not in _ABBREVIATIONS and not is_initial:
+        return False
+
+    cursor = index + 1
+    while cursor < len(text) and text[cursor] in " \t":
+        cursor += 1
+
+    if cursor >= len(text) or "\n" in text[index + 1:cursor + 1]:
+        return False
+
+    return text[cursor].isupper()
+
+
+def _sentence_spans(text: str) -> tuple[tuple[int, int], ...]:
+    spans: list[tuple[int, int]] = []
+    length = len(text)
+    cursor = 0
+
+    while cursor < length:
+        while cursor < length and text[cursor].isspace():
+            cursor += 1
+        if cursor >= length:
+            break
+
+        start = cursor
+        end = length
+        i = cursor
+
+        while i < length:
+            ch = text[i]
+
+            if ch == "\n":
+                end = i
+                break
+
+            if ch in ".!?":
+                if ch == "." and _is_abbreviation_period(text, i):
+                    i += 1
+                    continue
+
+                next_index = i + 1
+                if next_index >= length or text[next_index].isspace():
+                    end = next_index
+                    break
+
+            i += 1
+
+        while end > start and text[end - 1].isspace():
+            end -= 1
+
+        if end > start:
+            spans.append((start, end))
+
+        cursor = max(i + 1, end)
+
+    return tuple(spans)
+
+
+def atomize_raw_response(
+    envelope: RawResponseEnvelope,
+) -> tuple[ClaimAtom, ...]:
+    if envelope.speaker_role is not SpeakerRole.ASSISTANT:
+        raise ValueError(
+            "only assistant responses may be atomized as assistant claims"
+        )
+
+    spans = _sentence_spans(envelope.text)
+    return tuple(
+        bind_atom(
+            envelope,
+            atom_id=f"{envelope.response_id}:atom:{index}",
+            start=start,
+            end=end,
+        )
+        for index, (start, end) in enumerate(spans, start=1)
+    )
+
+
+def validate_atom_proposals(
+    envelope: RawResponseEnvelope,
+    proposals: list[SpanProposal] | tuple[SpanProposal, ...],
+) -> tuple[ClaimAtom, ...]:
+    if envelope.speaker_role is not SpeakerRole.ASSISTANT:
+        raise ValueError(
+            "only assistant responses may be atomized as assistant claims"
+        )
+
+    proposal_seq = tuple(proposals)
+    atom_ids = [proposal.atom_id for proposal in proposal_seq]
+    if len(atom_ids) != len(set(atom_ids)):
+        raise ValueError("duplicate atom_id")
+
+    ordered = sorted(
+        proposal_seq,
+        key=lambda proposal: (proposal.start, proposal.end, proposal.atom_id),
+    )
+
+    previous_end: int | None = None
+    atoms: list[ClaimAtom] = []
+
+    for proposal in ordered:
+        if not isinstance(proposal.atom_id, str) or not proposal.atom_id.strip():
+            raise ValueError("atom_id must be non-empty")
+        if not isinstance(proposal.quoted_text, str):
+            raise TypeError("quoted_text must be string")
+
+        if (
+            proposal.start < 0
+            or proposal.end > len(envelope.text)
+            or proposal.start >= proposal.end
+        ):
+            raise ValueError("invalid source span")
+
+        exact_slice = envelope.text[proposal.start:proposal.end]
+        if proposal.quoted_text != exact_slice:
+            raise ValueError("quoted_text must exactly match source span")
+
+        atom = bind_atom(
+            envelope,
+            atom_id=proposal.atom_id,
+            start=proposal.start,
+            end=proposal.end,
+            proposed_text=proposal.quoted_text,
+        )
+
+        if previous_end is not None and atom.start < previous_end:
+            raise ValueError("span proposals must not overlap")
+
+        atoms.append(atom)
+        previous_end = atom.end
+
+    return tuple(atoms)
+
+
+def type_clause(atom: ClaimAtom) -> ClauseTypeDecision:
+    reasons = list(atom.review_reasons)
+    blocking_reasons = {
+        "compound_clause",
+        "conditional_clause",
+        "ambiguous_referent",
+    }
+
+    if blocking_reasons.intersection(reasons):
+        return ClauseTypeDecision(
+            atom_id=atom.atom_id,
+            claim_type=None,
+            status=ClauseTypeStatus.REVIEW_REQUIRED,
+            reasons=tuple(reasons),
+            rule="review_gate",
+        )
+
+    text = atom.source_text.strip()
+    action_signal = bool(_ACTION_STATE_CUES.search(text))
+    estimate_signal = bool(_ESTIMATE_CUES.search(text))
+    inference_signal = "epistemic_qualifier" in reasons
+
+    signals = [
+        claim_type
+        for claim_type, present in (
+            (ClaimType.ACTION_STATE, action_signal),
+            (ClaimType.ESTIMATE, estimate_signal),
+            (ClaimType.INFERENCE, inference_signal),
+        )
+        if present
+    ]
+
+    if len(signals) > 1:
+        if "multiple_type_signals" not in reasons:
+            reasons.append("multiple_type_signals")
+        return ClauseTypeDecision(
+            atom_id=atom.atom_id,
+            claim_type=None,
+            status=ClauseTypeStatus.REVIEW_REQUIRED,
+            reasons=tuple(reasons),
+            rule="conflicting_type_cues",
+        )
+
+    if inference_signal:
+        return ClauseTypeDecision(
+            atom_id=atom.atom_id,
+            claim_type=ClaimType.INFERENCE,
+            status=ClauseTypeStatus.REVIEW_REQUIRED,
+            reasons=tuple(reasons),
+            rule="epistemic_qualifier",
+        )
+
+    if estimate_signal:
+        return ClauseTypeDecision(
+            atom_id=atom.atom_id,
+            claim_type=ClaimType.ESTIMATE,
+            status=ClauseTypeStatus.TYPED,
+            reasons=tuple(reasons),
+            rule="estimate_cue",
+        )
+
+    if action_signal:
+        return ClauseTypeDecision(
+            atom_id=atom.atom_id,
+            claim_type=ClaimType.ACTION_STATE,
+            status=ClauseTypeStatus.TYPED,
+            reasons=tuple(reasons),
+            rule="action_state_cue",
+        )
+
+    return ClauseTypeDecision(
+        atom_id=atom.atom_id,
+        claim_type=ClaimType.OBSERVATION,
+        status=ClauseTypeStatus.TYPED,
+        reasons=tuple(reasons),
+        rule="default_observation",
+    )
+
+
+def build_evidence_contract(
+    atom: ClaimAtom,
+    claim_type: ClaimType,
+    *,
+    type_human_approved: bool = False,
+) -> EvidenceContract:
+    if not isinstance(claim_type, ClaimType):
+        raise TypeError("claim_type must be ClaimType")
+    if type(type_human_approved) is not bool:
+        raise TypeError("type_human_approved must be bool")
+
+    review_reasons = list(atom.review_reasons)
+    atom_requires_review = atom.status is AtomStatus.REVIEW_REQUIRED
+    requires_human_review = atom_requires_review
+    requires_post_action = claim_type is ClaimType.ACTION_STATE
+
+    if claim_type in {ClaimType.INFERENCE, ClaimType.ESTIMATE}:
+        fact_eligible = False
+    elif claim_type is ClaimType.ACTION_STATE:
+        fact_eligible = not atom_requires_review
+    elif claim_type is ClaimType.RISK_SENSITIVE:
+        fact_eligible = False
+        requires_human_review = True
+        if "risk_sensitive_requires_human_review" not in review_reasons:
+            review_reasons.append("risk_sensitive_requires_human_review")
+    else:
+        if atom_requires_review:
+            fact_eligible = False
+            requires_human_review = True
+        elif type_human_approved:
+            fact_eligible = True
+            requires_human_review = False
+        else:
+            fact_eligible = False
+            requires_human_review = True
+            if "observation_type_requires_approval" not in review_reasons:
+                review_reasons.append("observation_type_requires_approval")
+
+    return EvidenceContract(
+        atom_id=atom.atom_id,
+        claim_type=claim_type,
+        required_directness=Directness.DIRECT,
+        requires_post_action=requires_post_action,
+        requires_human_review=requires_human_review,
+        fact_eligible=fact_eligible,
+        review_reasons=tuple(review_reasons),
     )

bodulskihal_core/research_demo.py

@@ -1,147 +1,147 @@
-from __future__ import annotations
-
-from typing import Any, Mapping
-
-from .adapter import SCHEMA_VERSION, verify_compound_payload
-from .engine import ALGORITHM_VERSION
-
-
-def _non_empty_string(value: Any, path: str) -> str:
-    if not isinstance(value, str) or not value.strip():
-        raise TypeError(f"{path} must be non-empty string")
-    return value.strip()
-
-
-def _metrics(results: list[dict[str, Any]]) -> dict[str, Any]:
-    total = len(results)
-    eligible_claims = sum(
-        1
-        for item in results
-        if item["receipt"]["gates"]["eligible_source_count"] > 0
-    )
-
-    return {
-        "total_claims": total,
-        "verified_fact_count": sum(
-            1
-            for item in results
-            if item["classification"] == "FACT" and item["verdict"] == "APPROVE"
-        ),
-        "unknown_blocked_count": sum(
-            1
-            for item in results
-            if item["classification"] == "UNKNOWN" and item["verdict"] == "BLOCK"
-        ),
-        "conflict_blocked_count": sum(
-            1
-            for item in results
-            if item["classification"] == "CONFLICT" and item["verdict"] == "BLOCK"
-        ),
-        "action_gate_blocked_count": sum(
-            1
-            for item in results
-            if item["reason"] == "missing_post_action_final_state_evidence"
-        ),
-        "escalated_count": sum(
-            1 for item in results if item["verdict"] == "ESCALATE"
-        ),
-        "blocked_unsupported_claim_count": sum(
-            1
-            for item in results
-            if item["classification"] == "UNKNOWN" and item["verdict"] == "BLOCK"
-        ),
-        "evidence_coverage": (eligible_claims / total) if total else 0.0,
-    }
-
-
-def _bullet(item: dict[str, Any]) -> str:
-    claim = item["receipt"]["claim"]
-    return f"- [{item['classification']}/{item['verdict']}] {claim['text']}"
-
-
-def _human_report(research_request: str, results: list[dict[str, Any]]) -> str:
-    sections = [
-        (
-            "VERIFIED FACTS",
-            [
-                item
-                for item in results
-                if item["classification"] == "FACT"
-                and item["verdict"] == "APPROVE"
-            ],
-        ),
-        (
-            "UNKNOWN / BLOCKED",
-            [
-                item
-                for item in results
-                if item["classification"] == "UNKNOWN"
-                and item["verdict"] == "BLOCK"
-            ],
-        ),
-        (
-            "CONFLICTS",
-            [item for item in results if item["classification"] == "CONFLICT"],
-        ),
-        (
-            "ACTION GATE BLOCKS",
-            [
-                item
-                for item in results
-                if item["reason"] == "missing_post_action_final_state_evidence"
-            ],
-        ),
-        (
-            "ESCALATIONS",
-            [item for item in results if item["verdict"] == "ESCALATE"],
-        ),
-    ]
-
-    lines = [f"RESEARCH REQUEST: {research_request}", ""]
-    for title, items in sections:
-        lines.append(title)
-        if items:
-            lines.extend(_bullet(item) for item in items)
-        else:
-            lines.append("- none")
-        lines.append("")
-
-    return "\n".join(lines).rstrip()
-
-
-def run_research_demo(payload: Mapping[str, Any]) -> dict[str, Any]:
-    if not isinstance(payload, Mapping):
-        raise TypeError("payload must be object")
-
-    research_request = _non_empty_string(
-        payload.get("research_request"),
-        "payload.research_request",
-    )
-
-    verification_payload = {
-        "claims": payload.get("claims"),
-        "evidence_by_claim": payload.get("evidence_by_claim"),
-        "human_approvals": payload.get("human_approvals", {}),
-        "policy": payload.get("policy"),
-        "evaluation_time": payload.get("evaluation_time"),
-    }
-
-    verified = verify_compound_payload(verification_payload)
-    results = verified["results"]
-    policy = payload.get("policy")
-    policy_version = (
-        policy.get("version")
-        if isinstance(policy, Mapping)
-        else None
-    )
-
-    return {
-        "research_request": research_request,
-        "schema_version": SCHEMA_VERSION,
-        "algorithm_version": ALGORITHM_VERSION,
-        "policy_version": policy_version,
-        "overall_verdict": verified["verdict"],
-        "results": results,
-        "metrics": _metrics(results),
-        "human_report": _human_report(research_request, results),
+from __future__ import annotations
+
+from typing import Any, Mapping
+
+from .adapter import SCHEMA_VERSION, verify_compound_payload
+from .engine import ALGORITHM_VERSION
+
+
+def _non_empty_string(value: Any, path: str) -> str:
+    if not isinstance(value, str) or not value.strip():
+        raise TypeError(f"{path} must be non-empty string")
+    return value.strip()
+
+
+def _metrics(results: list[dict[str, Any]]) -> dict[str, Any]:
+    total = len(results)
+    eligible_claims = sum(
+        1
+        for item in results
+        if item["receipt"]["gates"]["eligible_source_count"] > 0
+    )
+
+    return {
+        "total_claims": total,
+        "verified_fact_count": sum(
+            1
+            for item in results
+            if item["classification"] == "FACT" and item["verdict"] == "APPROVE"
+        ),
+        "unknown_blocked_count": sum(
+            1
+            for item in results
+            if item["classification"] == "UNKNOWN" and item["verdict"] == "BLOCK"
+        ),
+        "conflict_blocked_count": sum(
+            1
+            for item in results
+            if item["classification"] == "CONFLICT" and item["verdict"] == "BLOCK"
+        ),
+        "action_gate_blocked_count": sum(
+            1
+            for item in results
+            if item["reason"] == "missing_post_action_final_state_evidence"
+        ),
+        "escalated_count": sum(
+            1 for item in results if item["verdict"] == "ESCALATE"
+        ),
+        "blocked_unsupported_claim_count": sum(
+            1
+            for item in results
+            if item["classification"] == "UNKNOWN" and item["verdict"] == "BLOCK"
+        ),
+        "evidence_coverage": (eligible_claims / total) if total else 0.0,
+    }
+
+
+def _bullet(item: dict[str, Any]) -> str:
+    claim = item["receipt"]["claim"]
+    return f"- [{item['classification']}/{item['verdict']}] {claim['text']}"
+
+
+def _human_report(research_request: str, results: list[dict[str, Any]]) -> str:
+    sections = [
+        (
+            "VERIFIED FACTS",
+            [
+                item
+                for item in results
+                if item["classification"] == "FACT"
+                and item["verdict"] == "APPROVE"
+            ],
+        ),
+        (
+            "UNKNOWN / BLOCKED",
+            [
+                item
+                for item in results
+                if item["classification"] == "UNKNOWN"
+                and item["verdict"] == "BLOCK"
+            ],
+        ),
+        (
+            "CONFLICTS",
+            [item for item in results if item["classification"] == "CONFLICT"],
+        ),
+        (
+            "ACTION GATE BLOCKS",
+            [
+                item
+                for item in results
+                if item["reason"] == "missing_post_action_final_state_evidence"
+            ],
+        ),
+        (
+            "ESCALATIONS",
+            [item for item in results if item["verdict"] == "ESCALATE"],
+        ),
+    ]
+
+    lines = [f"RESEARCH REQUEST: {research_request}", ""]
+    for title, items in sections:
+        lines.append(title)
+        if items:
+            lines.extend(_bullet(item) for item in items)
+        else:
+            lines.append("- none")
+        lines.append("")
+
+    return "\n".join(lines).rstrip()
+
+
+def run_research_demo(payload: Mapping[str, Any]) -> dict[str, Any]:
+    if not isinstance(payload, Mapping):
+        raise TypeError("payload must be object")
+
+    research_request = _non_empty_string(
+        payload.get("research_request"),
+        "payload.research_request",
+    )
+
+    verification_payload = {
+        "claims": payload.get("claims"),
+        "evidence_by_claim": payload.get("evidence_by_claim"),
+        "human_approvals": payload.get("human_approvals", {}),
+        "policy": payload.get("policy"),
+        "evaluation_time": payload.get("evaluation_time"),
+    }
+
+    verified = verify_compound_payload(verification_payload)
+    results = verified["results"]
+    policy = payload.get("policy")
+    policy_version = (
+        policy.get("version")
+        if isinstance(policy, Mapping)
+        else None
+    )
+
+    return {
+        "research_request": research_request,
+        "schema_version": SCHEMA_VERSION,
+        "algorithm_version": ALGORITHM_VERSION,
+        "policy_version": policy_version,
+        "overall_verdict": verified["verdict"],
+        "results": results,
+        "metrics": _metrics(results),
+        "human_report": _human_report(research_request, results),
     }

bodulskihal_core/runtime_provenance.py

@@ -1,48 +1,48 @@
-from __future__ import annotations
-
-import os
-import re
-from dataclasses import asdict, dataclass
-
-
-UNVERIFIED = "UNVERIFIED"
-_GIT_DIGEST = re.compile(r"^(?:[0-9a-fA-F]{40}|[0-9a-fA-F]{64})$")
-
-
-@dataclass(frozen=True)
-class RuntimeProvenance:
-    source_commit: str
-    source_ref: str
-    build_id: str
-    verified: bool
-
-    def as_dict(self) -> dict[str, str | bool]:
-        return asdict(self)
-
-
-def _env_value(name: str) -> str:
-    raw = os.environ.get(name)
-    if raw is None:
-        return UNVERIFIED
-    value = raw.strip()
-    return value if value else UNVERIFIED
-
-
-def current_runtime_provenance() -> RuntimeProvenance:
-    source_commit = _env_value("BODULSKIHAL_SOURCE_COMMIT")
-    source_ref = _env_value("BODULSKIHAL_SOURCE_REF")
-    build_id = _env_value("BODULSKIHAL_BUILD_ID")
-
-    commit_verified = bool(_GIT_DIGEST.fullmatch(source_commit))
-    verified = (
-        commit_verified
-        and source_ref != UNVERIFIED
-        and build_id != UNVERIFIED
-    )
-
-    return RuntimeProvenance(
-        source_commit=source_commit.lower() if commit_verified else source_commit,
-        source_ref=source_ref,
-        build_id=build_id,
-        verified=verified,
+from __future__ import annotations
+
+import os
+import re
+from dataclasses import asdict, dataclass
+
+
+UNVERIFIED = "UNVERIFIED"
+_GIT_DIGEST = re.compile(r"^(?:[0-9a-fA-F]{40}|[0-9a-fA-F]{64})$")
+
+
+@dataclass(frozen=True)
+class RuntimeProvenance:
+    source_commit: str
+    source_ref: str
+    build_id: str
+    verified: bool
+
+    def as_dict(self) -> dict[str, str | bool]:
+        return asdict(self)
+
+
+def _env_value(name: str) -> str:
+    raw = os.environ.get(name)
+    if raw is None:
+        return UNVERIFIED
+    value = raw.strip()
+    return value if value else UNVERIFIED
+
+
+def current_runtime_provenance() -> RuntimeProvenance:
+    source_commit = _env_value("BODULSKIHAL_SOURCE_COMMIT")
+    source_ref = _env_value("BODULSKIHAL_SOURCE_REF")
+    build_id = _env_value("BODULSKIHAL_BUILD_ID")
+
+    commit_verified = bool(_GIT_DIGEST.fullmatch(source_commit))
+    verified = (
+        commit_verified
+        and source_ref != UNVERIFIED
+        and build_id != UNVERIFIED
+    )
+
+    return RuntimeProvenance(
+        source_commit=source_commit.lower() if commit_verified else source_commit,
+        source_ref=source_ref,
+        build_id=build_id,
+        verified=verified,
     )

build_archive.py

@@ -0,0 +1,41 @@
+#!/usr/bin/env python3
+"""Rebuild the exact source ZIP from a verified extracted release, offline."""
+import hashlib
+import json
+import sys
+import zipfile
+from pathlib import Path
+from safe_json import strict_loads
+from verify_release import verify_release
+
+
+def build_archive(root, target):
+    root, target = Path(root).resolve(), Path(target).resolve()
+    if target.is_relative_to(root):
+        raise ValueError("Write the ZIP outside the extracted release directory")
+    checked = verify_release(root)
+    if not checked["verified"]:
+        raise ValueError("Source integrity check failed")
+    manifest = strict_loads((root / "RELEASE_MANIFEST.json").read_text(encoding="utf-8"))
+    names = sorted([*manifest["files"], "RELEASE_MANIFEST.json"])
+    with target.open("xb") as handle:
+        with zipfile.ZipFile(handle, "w", compression=zipfile.ZIP_STORED) as archive:
+            for name in names:
+                entry = zipfile.ZipInfo(name, date_time=(1980, 1, 1, 0, 0, 0))
+                entry.create_system = 3
+                entry.external_attr = 0o100644 << 16
+                entry.compress_type = zipfile.ZIP_STORED
+                archive.writestr(entry, (root / name).read_bytes())
+    data = target.read_bytes()
+    return {"built": True, "bytes": len(data), "files": len(names), "sha256": hashlib.sha256(data).hexdigest(), "sha512": hashlib.sha512(data).hexdigest()}
+
+
+if __name__ == "__main__":
+    try:
+        if len(sys.argv) != 2:
+            raise ValueError("Usage: python -B build_archive.py ../rebuilt.zip")
+        result = build_archive(Path(__file__).resolve().parent, sys.argv[1])
+        print(json.dumps(result, sort_keys=True))
+    except (ValueError, OSError, zipfile.BadZipFile) as exc:
+        print(json.dumps({"built": False, "error": str(exc)}))
+        sys.exit(2)

demo.py

@@ -1,34 +1,74 @@
-"""Public demo boundary. Caller-supplied approvals are never authenticated."""
+"""Public supplied-evidence boundary v1.1.0; approvals are never authenticated."""
 from datetime import datetime, timezone
-from typing import Any
 from bodulskihal_core import verify_payload, verify_compound_payload
+from safe_json import strict_loads, strict_dumps
+from matrix_core import parse_instant
 
-def evaluate(payload: dict[str, Any], batch: bool = False) -> dict[str, Any]:
+BOUNDARY_VERSION = "1.1.0"
+MAX_EVIDENCE = 1000
+
+
+def _times(payload, evidence):
+    if "evaluation_time" in payload:
+        payload["evaluation_time"] = parse_instant(payload["evaluation_time"]).isoformat()
+    for item in evidence:
+        if isinstance(item, dict) and "observed_at" in item:
+            item["observed_at"] = parse_instant(item["observed_at"]).isoformat()
+
+
+def evaluate(payload, batch=False):
+    """Bounded local evaluation. Input evidence is supplied, not fetched/authenticated."""
     try:
-        if not isinstance(payload, dict):
-            raise TypeError('payload must be an object')
-        clean = dict(payload)
+        if not isinstance(payload, dict) or type(batch) is not bool:
+            raise TypeError("payload must be an object; batch must be bool")
+        # Apply the same finite-number, scalar-Unicode and resource limits to
+        # Python callers as the public JSON entry point.
+        clean = strict_loads(strict_dumps(payload))
         if batch:
-            claims = clean.get('claims')
+            claims = clean.get("claims")
             if not isinstance(claims, list) or not 1 <= len(claims) <= 100:
-                raise ValueError('Provide between 1 and 100 claims')
-            clean['human_approvals'] = {}
+                raise ValueError("Provide between 1 and 100 claims")
+            evidence_map = clean.get("evidence_by_claim", {})
+            if not isinstance(evidence_map, dict):
+                raise TypeError("evidence_by_claim must be an object")
+            if sum(len(v) if isinstance(v, list) else MAX_EVIDENCE + 1 for v in evidence_map.values()) > MAX_EVIDENCE:
+                raise ValueError("Too many evidence records")
+            _times(clean, [item for records in evidence_map.values() for item in records])
+            clean["human_approvals"] = {}
             return verify_compound_payload(clean)
-        clean['human_approved'] = False
+        evidence = clean.get("evidence", [])
+        if not isinstance(evidence, list) or len(evidence) > MAX_EVIDENCE:
+            raise ValueError("Evidence must be a list of at most 1000 records")
+        _times(clean, evidence)
+        clean["human_approved"] = False
         return verify_payload(clean)
-    except (ValueError, TypeError, KeyError) as exc:
-        return {'classification': 'UNKNOWN', 'verdict': 'BLOCK', 'reason': 'invalid_input', 'error': str(exc)}
+    except (ValueError, TypeError, KeyError, OverflowError, RecursionError, UnicodeError) as exc:
+        return {"classification": "UNKNOWN", "verdict": "BLOCK", "reason": "invalid_input", "error": str(exc)}
+
+
+def evaluate_json(text, batch=False):
+    try:
+        return evaluate(strict_loads(text), batch=batch)
+    except (ValueError, TypeError, OverflowError, RecursionError, UnicodeError) as exc:
+        return {"classification": "UNKNOWN", "verdict": "BLOCK", "reason": "invalid_json", "error": str(exc)}
+
 
-def example(scenario: str = 'supported') -> dict[str, Any]:
-    now = datetime.now(timezone.utc).isoformat()
+def example(scenario="supported", *, at=None):
+    """Synthetic fixture; an explicit aware datetime supports historical replay."""
+    instant = datetime.now(timezone.utc) if at is None else at
+    if not isinstance(instant, datetime) or instant.tzinfo is None or instant.utcoffset() is None:
+        raise ValueError("at must be timezone-aware")
+    now = instant.astimezone(timezone.utc).isoformat()
     payload = {
-        'claim': {'id': 'synthetic-count', 'text': 'This synthetic record contains 30 questions', 'type': 'observation', 'risk': 'low'},
-        'evidence': [{'source_id': 'synthetic-demo', 'supports': True, 'observed_at': now, 'directness': 'direct', 'origin': 'computed_result'}],
-        'policy': {'version': '3.0', 'max_age_seconds': 300},
-        'evaluation_time': now,
+        "claim": {"id": "synthetic-count", "text": "This synthetic record contains 30 questions", "type": "observation", "risk": "low"},
+        "evidence": [{"source_id": "synthetic-demo", "supports": True, "observed_at": now, "directness": "direct", "origin": "computed_result"}],
+        "policy": {"version": "3.0", "max_age_seconds": 300},
+        "evaluation_time": now,
     }
-    if scenario == 'unsupported':
-        payload['evidence'] = []
-    elif scenario == 'contradiction':
-        payload['evidence'][0]['supports'] = False
+    if scenario == "unsupported":
+        payload["evidence"] = []
+    elif scenario == "contradiction":
+        payload["evidence"][0]["supports"] = False
+    elif scenario != "supported":
+        raise ValueError("Unknown synthetic scenario")
     return payload

examples/contradiction.json

@@ -0,0 +1,22 @@
+{
+  "claim": {
+    "id": "synthetic-count",
+    "text": "This synthetic record contains 30 questions",
+    "type": "observation",
+    "risk": "low"
+  },
+  "evidence": [
+    {
+      "source_id": "synthetic-demo",
+      "supports": false,
+      "observed_at": "2026-11-03T12:00:00+00:00",
+      "directness": "direct",
+      "origin": "computed_result"
+    }
+  ],
+  "policy": {
+    "version": "3.0",
+    "max_age_seconds": 300
+  },
+  "evaluation_time": "2026-11-03T12:00:00+00:00"
+}

examples/matrix-result.json

@@ -0,0 +1,11 @@
+{
+  "valid": true,
+  "input_payload": "Evidence before confidence.",
+  "seal_date": "2026-11-03",
+  "matrix_verification_seal": "36e7be60a50a6d846b8b162c199a5e534c612ba171163d9c3406e2f2b12c0651",
+  "timestamp": "2026-11-03T12:00:00+00:00",
+  "engine_version": "3.6.0-OMEGA",
+  "checksum_format": "bodul-matrix-v1",
+  "normalization_profile": "bodul-whitespace-v1",
+  "hash_algorithm": "sha256"
+}

examples/matrix.txt

@@ -0,0 +1 @@
+Evidence before confidence.

examples/supported.json

@@ -0,0 +1,22 @@
+{
+  "claim": {
+    "id": "synthetic-count",
+    "text": "This synthetic record contains 30 questions",
+    "type": "observation",
+    "risk": "low"
+  },
+  "evidence": [
+    {
+      "source_id": "synthetic-demo",
+      "supports": true,
+      "observed_at": "2026-11-03T12:00:00+00:00",
+      "directness": "direct",
+      "origin": "computed_result"
+    }
+  ],
+  "policy": {
+    "version": "3.0",
+    "max_age_seconds": 300
+  },
+  "evaluation_time": "2026-11-03T12:00:00+00:00"
+}

examples/unsupported.json

@@ -0,0 +1,14 @@
+{
+  "claim": {
+    "id": "synthetic-count",
+    "text": "This synthetic record contains 30 questions",
+    "type": "observation",
+    "risk": "low"
+  },
+  "evidence": [],
+  "policy": {
+    "version": "3.0",
+    "max_age_seconds": 300
+  },
+  "evaluation_time": "2026-11-03T12:00:00+00:00"
+}

matrix_core.py

@@ -1,114 +1,199 @@
-#!/usr/bin/env python3
-# -*- coding: utf-8 -*-
-"""BODULAI MATRIX CORE — deterministic text checksums (v3.5.1).
-
-Author: Damir Balenović (mirdax25-ux).
-
-Normalizes whitespace, rejects empty/non-string input, and calculates SHA-256
-over the normalized payload and UTC date. This checksum is not a signature,
-proof of truth, authorization decision, or deployment action. Anyone who knows
-the payload and date can calculate it. The engine version and full timestamp
-are response metadata, not part of the checksum format.
-"""
-
-import hashlib
-import json
-import logging
-import sys
-from datetime import datetime, timezone
-from typing import Any, Dict, Optional
-
-ENGINE_VERSION = "3.5.1-OMEGA"
-logger = logging.getLogger("BodulMatrixCore")
-logger.addHandler(logging.NullHandler())
-
-
-class DeterministicMatrixCore:
-    def __init__(self, engine_version: str = ENGINE_VERSION):
-        self.engine_version = engine_version
-        logger.info("Initializing Matrix Core %s.", self.engine_version)
-
-    @staticmethod
-    def _sanitize_payload(payload: Any) -> Optional[str]:
-        if not isinstance(payload, str):
-            return None
-        clean = " ".join(payload.split())
-        return clean or None
-
-    @staticmethod
-    def _utc_now(now: Optional[datetime]) -> datetime:
-        if now is None:
-            return datetime.now(timezone.utc)
-        if not isinstance(now, datetime):
-            raise TypeError("now must be a timezone-aware datetime or None")
-        if now.tzinfo is None or now.utcoffset() is None:
-            raise ValueError("now must include a UTC offset or timezone")
-        return now.astimezone(timezone.utc)
-
-    def enforce_zero_tolerance_matrix(
-        self, payload: Any, now: Optional[datetime] = None
-    ) -> Dict[str, Any]:
-        """Return a normalized payload and UTC-date checksum, or reject input.
-
-        The checksum repeats for identical normalized text and UTC date.
-        The complete result repeats only if the time and engine version also
-        match. A supplied naive datetime is rejected rather than interpreted
-        using the machine's local timezone.
-        """
-        instant = self._utc_now(now)
-        clean = self._sanitize_payload(payload)
-        if clean is None:
-            logger.warning("Empty or invalid input; no checksum issued.")
-            return {
-                "valid": False,
-                "error": "EMPTY_OR_INVALID_PAYLOAD",
-                "timestamp": instant.isoformat(),
-                "engine_version": self.engine_version,
-            }
-
-        seal_date = instant.date().isoformat()
-        seal_raw = f"BODUL_MATRIX::{clean}::{seal_date}::OMEGA_FLOW"
-        seal = hashlib.sha256(seal_raw.encode("utf-8")).hexdigest()
-        logger.info("Checksum calculated: %s...", seal[:16])
-        return {
-            "valid": True,
-            "input_payload": clean,
-            "seal_date": seal_date,
-            "matrix_verification_seal": seal,
-            "timestamp": instant.isoformat(),
-            "engine_version": self.engine_version,
-        }
-
-
-def main(argv=None) -> int:
-    """JSON-only CLI; missing/invalid input returns exit code 2."""
-    import argparse
-
-    for stream in (sys.stdout, sys.stderr):
-        try:
-            stream.reconfigure(encoding="utf-8")
-        except (AttributeError, ValueError):
-            pass
-
-    parser = argparse.ArgumentParser(description=__doc__)
-    parser.add_argument("payload", nargs="*", help="Text to normalize and checksum")
-    parser.add_argument("--at", help="ISO 8601 timestamp with an explicit UTC offset")
-    parser.add_argument("--verbose", action="store_true")
-    args = parser.parse_args(argv)
-    if args.verbose:
-        logging.basicConfig(level=logging.INFO, stream=sys.stderr)
-
-    try:
-        instant = datetime.fromisoformat(args.at) if args.at else None
-        result = DeterministicMatrixCore().enforce_zero_tolerance_matrix(
-            " ".join(args.payload), now=instant
-        )
-    except (TypeError, ValueError) as exc:
-        print(json.dumps({"valid": False, "error": "INVALID_TIMESTAMP", "detail": str(exc)}, ensure_ascii=False))
-        return 2
-    print(json.dumps(result, indent=2, ensure_ascii=False))
-    return 0 if result["valid"] else 2
-
-
-if __name__ == "__main__":
-    sys.exit(main())
+#!/usr/bin/env python3
+"""BODULAI Matrix Core: portable v1 text checksums; Apache-2.0.
+
+Author: Damir Balenović (mirdax25-ux).
+The format and normalization table are frozen; see MATRIX_FORMAT.md.
+A checksum is not a signature, authorization, or evidence of truth.
+"""
+import hashlib
+import hmac
+import json
+import logging
+import re
+import sys
+from datetime import datetime, timezone
+from typing import Any, Dict, Optional
+
+ENGINE_VERSION = "3.6.0-OMEGA"
+CHECKSUM_FORMAT = "bodul-matrix-v1"
+NORMALIZATION_PROFILE = "bodul-whitespace-v1"
+HASH_ALGORITHM = "sha256"
+MAX_PAYLOAD_BYTES = 1_048_576
+# Frozen compatibility table: Python 3.12 split() whitespace, 29 code points.
+# Do not replace with str.split(), isspace(), or regex \s: Unicode evolves.
+WHITESPACE_CODEPOINTS = (
+    0x0009, 0x000A, 0x000B, 0x000C, 0x000D,
+    0x001C, 0x001D, 0x001E, 0x001F, 0x0020, 0x0085, 0x00A0, 0x1680,
+    0x2000, 0x2001, 0x2002, 0x2003, 0x2004, 0x2005, 0x2006, 0x2007,
+    0x2008, 0x2009, 0x200A, 0x2028, 0x2029, 0x202F, 0x205F, 0x3000,
+)
+_SEPARATORS = re.compile("[" + "".join(chr(n) for n in WHITESPACE_CODEPOINTS) + "]+")
+_DATE = re.compile(r"[0-9]{4}-[0-9]{2}-[0-9]{2}\Z")
+_HEX = re.compile(r"[0-9a-f]{64}\Z")
+_INSTANT = re.compile(r"[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}(?:\.[0-9]{1,6})?(?:Z|[+-][0-9]{2}:[0-9]{2})\Z")
+logger = logging.getLogger("BodulMatrixCore")
+logger.addHandler(logging.NullHandler())
+
+
+def parse_instant(value: str) -> datetime:
+    """Stable ASCII timestamp grammar with whole-minute offsets; return UTC."""
+    if not isinstance(value, str) or not _INSTANT.fullmatch(value):
+        raise ValueError("Use YYYY-MM-DDTHH:MM:SS[.ffffff]Z or an explicit +/-HH:MM offset")
+    # RFC 3339 -00:00 means unknown local offset, not confirmed UTC.
+    if value.endswith("-00:00"):
+        raise ValueError("Unknown UTC offset -00:00 is not accepted; use Z or +00:00")
+    if not value.endswith("Z") and (int(value[-5:-3]) > 23 or int(value[-2:]) > 59):
+        raise ValueError("UTC offset hours must be 00..23 and minutes 00..59")
+    try:
+        return datetime.fromisoformat(value[:-1] + "+00:00" if value.endswith("Z") else value).astimezone(timezone.utc)
+    except (ValueError, OverflowError) as exc:
+        raise ValueError("Timestamp is outside the supported Gregorian range 0001..9999") from exc
+
+
+def _date(value: Any) -> str:
+    if not isinstance(value, str) or not _DATE.fullmatch(value):
+        raise ValueError("Date must be YYYY-MM-DD")
+    datetime(int(value[:4]), int(value[5:7]), int(value[8:10]))
+    return value
+
+
+def _input_error(payload: Any) -> Optional[str]:
+    if not isinstance(payload, str):
+        return "EMPTY_OR_INVALID_PAYLOAD"
+    if len(payload) > MAX_PAYLOAD_BYTES:
+        return "PAYLOAD_TOO_LARGE"
+    try:
+        if len(payload.encode("utf-8", errors="strict")) > MAX_PAYLOAD_BYTES:
+            return "PAYLOAD_TOO_LARGE"
+    except UnicodeEncodeError:
+        return "INVALID_UNICODE"
+    return None
+
+
+def normalize_payload(payload: str) -> str:
+    """Collapse the frozen whitespace table; no Unicode normalization/casefold."""
+    error = _input_error(payload)
+    if error:
+        raise ValueError(error)
+    # trim only the explicit table; ordinary str.strip() is Unicode-dependent.
+    return _SEPARATORS.sub(" ", payload).strip(" ")
+
+
+def checksum_for_date(payload: str, seal_date: str) -> str:
+    """No clock or network: checksum of non-empty normalized text and UTC date."""
+    clean = normalize_payload(payload)
+    if not clean:
+        raise ValueError("EMPTY_OR_INVALID_PAYLOAD")
+    raw = "BODUL_MATRIX::" + clean + "::" + _date(seal_date) + "::OMEGA_FLOW"
+    return hashlib.sha256(raw.encode("utf-8", errors="strict")).hexdigest()
+
+
+class DeterministicMatrixCore:
+    def __init__(self, engine_version: str = ENGINE_VERSION):
+        if not isinstance(engine_version, str) or not engine_version.strip() or len(engine_version) > 128:
+            raise ValueError("engine_version must be a non-empty string of at most 128 characters")
+        self.engine_version = engine_version
+
+    @staticmethod
+    def _sanitize_payload(payload: Any) -> Optional[str]:
+        if _input_error(payload):
+            return None
+        return normalize_payload(payload) or None
+
+    @staticmethod
+    def _utc_now(now: Optional[datetime]) -> datetime:
+        if now is None:
+            return datetime.now(timezone.utc)
+        if not isinstance(now, datetime):
+            raise TypeError("now must be a timezone-aware datetime or None")
+        if now.tzinfo is None or now.utcoffset() is None:
+            raise ValueError("now must include a UTC offset or timezone")
+        try:
+            return now.astimezone(timezone.utc)
+        except (ValueError, OverflowError) as exc:
+            raise ValueError("UTC instant is outside supported years 0001..9999") from exc
+
+    def enforce_zero_tolerance_matrix(self, payload: Any, now: Optional[datetime] = None) -> Dict[str, Any]:
+        instant = self._utc_now(now)
+        metadata = {
+            "timestamp": instant.isoformat(), "engine_version": self.engine_version,
+            "checksum_format": CHECKSUM_FORMAT, "normalization_profile": NORMALIZATION_PROFILE,
+            "hash_algorithm": HASH_ALGORITHM,
+        }
+        error = _input_error(payload)
+        clean = None if error else normalize_payload(payload)
+        if not clean:
+            return {"valid": False, "error": error or "EMPTY_OR_INVALID_PAYLOAD", **metadata}
+        seal_date = instant.date().isoformat()
+        return {
+            "valid": True, "input_payload": clean, "seal_date": seal_date,
+            "matrix_verification_seal": checksum_for_date(clean, seal_date), **metadata,
+        }
+
+
+def verify_result(result: Any) -> Dict[str, Any]:
+    """Check checksum consistency of an exported result, never source identity.
+
+    Reads original 3.5.1 records and explicit v1 records. Unknown formats and
+    partially labeled records fail closed. Metadata is not authenticated.
+    """
+    def reject(reason):
+        return {"verified": False, "scope": "checksum_consistency", "error": reason}
+    if not isinstance(result, dict) or result.get("valid") is not True:
+        return reject("INVALID_RESULT")
+    base = {"valid", "input_payload", "seal_date", "matrix_verification_seal", "timestamp", "engine_version"}
+    identifiers = {"checksum_format", "normalization_profile", "hash_algorithm"}
+    if set(result) == base:
+        if result.get("engine_version") != "3.5.1-OMEGA":
+            return reject("UNLABELED_FORMAT")
+    elif set(result) == base | identifiers:
+        if result.get("checksum_format") != CHECKSUM_FORMAT or result.get("normalization_profile") != NORMALIZATION_PROFILE or result.get("hash_algorithm") != HASH_ALGORITHM:
+            return reject("UNSUPPORTED_FORMAT")
+    else:
+        return reject("UNEXPECTED_FIELDS")
+    try:
+        version = result["engine_version"]
+        if not isinstance(version, str) or not version.strip() or len(version) > 128:
+            return reject("INVALID_METADATA")
+        payload = result["input_payload"]
+        if not isinstance(payload, str) or not payload or normalize_payload(payload) != payload:
+            return reject("NON_CANONICAL_PAYLOAD")
+        instant = parse_instant(result["timestamp"])
+        if instant.date().isoformat() != _date(result["seal_date"]):
+            return reject("DATE_MISMATCH")
+        expected = checksum_for_date(payload, result["seal_date"])
+        provided = result["matrix_verification_seal"]
+        if not isinstance(provided, str) or not _HEX.fullmatch(provided) or not hmac.compare_digest(expected, provided):
+            return reject("CHECKSUM_MISMATCH")
+    except (ValueError, TypeError, OverflowError):
+        return reject("INVALID_RESULT")
+    return {"verified": True, "scope": "checksum_consistency", "checksum_format": CHECKSUM_FORMAT, "metadata_authenticated": False}
+
+
+def main(argv=None) -> int:
+    """JSON-only CLI. Exit 0 valid; 2 invalid input; 1 unexpected failure."""
+    import argparse
+    for stream in (sys.stdout, sys.stderr):
+        try:
+            stream.reconfigure(encoding="utf-8")
+        except (AttributeError, ValueError):
+            pass
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("payload", nargs="*")
+    parser.add_argument("--at", help="Explicit timezone required; see MATRIX_FORMAT.md")
+    parser.add_argument("--verbose", action="store_true")
+    args = parser.parse_args(argv)
+    if args.verbose:
+        logging.basicConfig(level=logging.INFO, stream=sys.stderr)
+    try:
+        instant = parse_instant(args.at) if args.at is not None else None
+        result = DeterministicMatrixCore().enforce_zero_tolerance_matrix(" ".join(args.payload), instant)
+    except (TypeError, ValueError) as exc:
+        print(json.dumps({"valid": False, "error": "INVALID_TIMESTAMP", "detail": str(exc)}, ensure_ascii=True))
+        return 2
+    print(json.dumps(result, ensure_ascii=True, sort_keys=True, indent=2, allow_nan=False))
+    return 0 if result["valid"] else 2
+
+
+if __name__ == "__main__":
+    sys.exit(main())

offline.html

@@ -0,0 +1,84 @@
+<!doctype html>
+<html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
+<meta http-equiv="Content-Security-Policy" content="default-src 'none'; script-src 'unsafe-inline'; style-src 'unsafe-inline'; connect-src 'none'; img-src 'none'; object-src 'none'; base-uri 'none'; form-action 'none'">
+<title>Bodulski HAL | Offline Matrix</title>
+<style>
+:root{color-scheme:dark;font-family:system-ui,sans-serif;background:#0b1118;color:#e6edf5}*{box-sizing:border-box}body{margin:0}main{max-width:1080px;margin:auto;padding:42px 24px}h1{font-size:clamp(2rem,5vw,3rem);margin:8px 0 12px}.eyebrow{color:#8de6c3;font-size:.8rem;letter-spacing:.14em;font-weight:700}.lead{color:#b6c6d7;max-width:760px;line-height:1.65}.grid{display:grid;grid-template-columns:1fr 1fr;gap:20px;margin-top:28px}.panel{background:#121d29;border:1px solid #2c3d50;border-radius:16px;padding:22px}label{display:block;margin-bottom:8px;font-weight:600}textarea,input{font:inherit;color:inherit;background:#09131e;border:1px solid #456075;border-radius:8px;padding:12px;width:100%;margin-bottom:20px}textarea{resize:vertical;min-height:160px}input{font-family:ui-monospace,monospace}button,a.button{font:inherit;font-weight:650;border-radius:8px;padding:11px 15px;border:1px solid #4c6d78;background:#172b36;color:#e6edf5;cursor:pointer;text-decoration:none;display:inline-block}button.primary{background:#8de6c3;border-color:#8de6c3;color:#09251b}button:focus-visible,a:focus-visible,input:focus-visible,textarea:focus-visible{outline:3px solid #b5c7ff;outline-offset:3px}.actions{display:flex;gap:9px;flex-wrap:wrap}button:disabled{opacity:.45;cursor:default}pre{white-space:pre-wrap;overflow-wrap:anywhere;font:13px/1.65 ui-monospace,monospace;margin:0}h2{font-size:1rem;margin-top:0}.note{font-size:.85rem;line-height:1.6;color:#b6c6d7}.status{color:#8de6c3;margin-top:16px;min-height:24px}footer{margin-top:26px;color:#b6c6d7;font-size:.85rem;line-height:1.7}a{color:#8de6c3}code{color:#c1d8ff}@media(max-width:760px){.grid{grid-template-columns:1fr}main{padding:28px 16px}}
+</style></head><body><main>
+<div class="eyebrow">BODULSKI HAL / PORTABLE EXECUTION</div>
+<h1>A checksum you can reproduce.</h1>
+<p class="lead">Normalize text and compute its UTC-date SHA-256 checksum. This page is a single file: no installation, external scripts, API keys or network requests. Save it and open it locally whenever you need it.</p>
+<div class="grid"><section class="panel" aria-label="Checksum inputs">
+<label for="payload">Input text</label><textarea id="payload" spellcheck="false">Evidence before confidence.</textarea>
+<label for="at">Explicit timestamp with timezone</label><input id="at" value="2026-11-03T12:00:00+00:00" autocomplete="off" spellcheck="false">
+<div class="actions"><button id="compute" class="primary" type="button">Compute checksum</button><button id="sample" type="button">Known vector</button><button id="boundary" type="button">UTC boundary</button><button id="empty" type="button">Empty input</button><button id="selftest" type="button">Run self-tests</button></div>
+<p class="note">The explicit time is intentional: the result can be reproduced without relying on a future system clock. Input limit: 1 MiB UTF-8. Format <code>bodul-matrix-v1</code>; normalization <code>bodul-whitespace-v1</code>.</p>
+</section><section class="panel" aria-label="Structured checksum result"><h2>Structured result</h2><pre id="output" aria-live="polite">Choose Compute checksum to begin.</pre><div class="actions" style="margin-top:20px"><button id="download" type="button" disabled>Save result.json</button></div><p id="status" class="status" role="status"></p></section></div>
+<footer><strong>Scope:</strong> <code>valid: true</code> means non-empty, valid text within the input limit. The checksum does not authenticate a source, establish truth or authorize an action. Anyone can recompute it. Full timestamps and engine versions are metadata outside the checksum.<br>
+Reference: Matrix Core 3.6.0-OMEGA · Apache-2.0 · Damir Balenović. The downloadable Python archive also contains the supplied-evidence verifier and tests. <a href="bodul-offline-1.1.0.zip" download>Download the complete offline source archive</a> · <a href="index.html">Open the evidence playground</a></footer>
+</main><script>
+"use strict";
+(function () {
+  const VERSION="3.6.0-OMEGA", FORMAT="bodul-matrix-v1", PROFILE="bodul-whitespace-v1", LIMIT=1048576;
+  const WHITE=[9,10,11,12,13,28,29,30,31,32,133,160,5760,8192,8193,8194,8195,8196,8197,8198,8199,8200,8201,8202,8232,8233,8239,8287,12288];
+  const separators=new RegExp("["+WHITE.map(n=>String.fromCharCode(n)).join("")+"]+","g");
+  const encoder=new TextEncoder();
+  function normalize(text){return text.replace(separators," ").replace(/^ +| +$/g,"");}
+  function scalarText(text){for(let i=0;i<text.length;i++){const c=text.charCodeAt(i);if(c>=0xd800&&c<=0xdbff){const d=text.charCodeAt(++i);if(!(d>=0xdc00&&d<=0xdfff))return false;}else if(c>=0xdc00&&c<=0xdfff)return false;}return true;}
+  function pad(n,len){return String(n).padStart(len||2,"0");}
+  function instant(raw){
+    const m=/^([0-9]{4})-([0-9]{2})-([0-9]{2})T([0-9]{2}):([0-9]{2}):([0-9]{2})(?:\.([0-9]{1,6}))?(Z|[+-][0-9]{2}:[0-9]{2})$/.exec(raw);
+    if(!m||m[8]==="-00:00")throw Error("Use a complete timestamp with a known UTC offset.");
+    const [y,mo,d,h,mi,s]=m.slice(1,7).map(Number), z=m[8];
+    if(y<1||mo<1||mo>12||d<1||d>31||h>23||mi>59||s>59)throw Error("Invalid Gregorian timestamp.");
+    const value=new Date(0);value.setUTCFullYear(y,mo-1,d);value.setUTCHours(h,mi,s,0);
+    if(value.getUTCFullYear()!==y||value.getUTCMonth()!==mo-1||value.getUTCDate()!==d)throw Error("Invalid Gregorian date.");
+    let offset=0;
+    if(z!=="Z"){const oh=Number(z.slice(1,3)),om=Number(z.slice(4));if(oh>23||om>59)throw Error("Invalid UTC offset.");offset=(oh*60+om)*(z[0]==="-"?-1:1);}
+    value.setTime(value.getTime()-offset*60000);
+    const year=value.getUTCFullYear();if(year<1||year>9999)throw Error("Supported UTC years are 0001 through 9999.");
+    const date=pad(year,4)+"-"+pad(value.getUTCMonth()+1)+"-"+pad(value.getUTCDate());
+    const micro=(m[7]||"").padEnd(6,"0");
+    return {date:date,timestamp:date+"T"+pad(value.getUTCHours())+":"+pad(value.getUTCMinutes())+":"+pad(value.getUTCSeconds())+(Number(micro)?"."+micro:"")+"+00:00"};
+  }
+  // SHA-256 compression from the published FIPS 180-4 algorithm. This is a
+  // checksum implementation, not a cryptographic certification or signature.
+  const K=[0x428a2f98,0x71374491,0xb5c0fbcf,0xe9b5dba5,0x3956c25b,0x59f111f1,0x923f82a4,0xab1c5ed5,0xd807aa98,0x12835b01,0x243185be,0x550c7dc3,0x72be5d74,0x80deb1fe,0x9bdc06a7,0xc19bf174,0xe49b69c1,0xefbe4786,0x0fc19dc6,0x240ca1cc,0x2de92c6f,0x4a7484aa,0x5cb0a9dc,0x76f988da,0x983e5152,0xa831c66d,0xb00327c8,0xbf597fc7,0xc6e00bf3,0xd5a79147,0x06ca6351,0x14292967,0x27b70a85,0x2e1b2138,0x4d2c6dfc,0x53380d13,0x650a7354,0x766a0abb,0x81c2c92e,0x92722c85,0xa2bfe8a1,0xa81a664b,0xc24b8b70,0xc76c51a3,0xd192e819,0xd6990624,0xf40e3585,0x106aa070,0x19a4c116,0x1e376c08,0x2748774c,0x34b0bcb5,0x391c0cb3,0x4ed8aa4a,0x5b9cca4f,0x682e6ff3,0x748f82ee,0x78a5636f,0x84c87814,0x8cc70208,0x90befffa,0xa4506ceb,0xbef9a3f7,0xc67178f2];
+  function rr(n,s){return(n>>>s)|(n<<(32-s));}
+  function sha256(bytes){
+    const length=bytes.length,total=Math.ceil((length+9)/64)*64,data=new Uint8Array(total);data.set(bytes);data[length]=128;
+    const view=new DataView(data.buffer);view.setUint32(total-8,Math.floor(length/536870912),false);view.setUint32(total-4,(length*8)>>>0,false);
+    const state=[0x6a09e667,0xbb67ae85,0x3c6ef372,0xa54ff53a,0x510e527f,0x9b05688c,0x1f83d9ab,0x5be0cd19],w=new Int32Array(64);
+    for(let p=0;p<total;p+=64){
+      for(let i=0;i<16;i++)w[i]=view.getInt32(p+i*4,false);
+      for(let i=16;i<64;i++){const a=w[i-15],b=w[i-2];w[i]=(w[i-16]+(rr(a,7)^rr(a,18)^(a>>>3))+w[i-7]+(rr(b,17)^rr(b,19)^(b>>>10)))|0;}
+      let [a,b,c,d,e,f,g,h]=state;
+      for(let i=0;i<64;i++){const t1=(h+(rr(e,6)^rr(e,11)^rr(e,25))+((e&f)^(~e&g))+K[i]+w[i])|0,t2=((rr(a,2)^rr(a,13)^rr(a,22))+((a&b)^(a&c)^(b&c)))|0;h=g;g=f;f=e;e=(d+t1)|0;d=c;c=b;b=a;a=(t1+t2)|0;}
+      [a,b,c,d,e,f,g,h].forEach((v,i)=>{state[i]=(state[i]+v)|0;});
+    }
+    return state.map(v=>(v>>>0).toString(16).padStart(8,"0")).join("");
+  }
+  function compute(text,at){
+    let time;try{time=instant(at);}catch(error){return{valid:false,error:"INVALID_TIMESTAMP",detail:error.message};}
+    const meta={timestamp:time.timestamp,engine_version:VERSION,checksum_format:FORMAT,normalization_profile:PROFILE,hash_algorithm:"sha256"};
+    if(typeof text!=="string")return Object.assign({valid:false,error:"EMPTY_OR_INVALID_PAYLOAD"},meta);
+    if(!scalarText(text))return Object.assign({valid:false,error:"INVALID_UNICODE"},meta);
+    if(text.length>LIMIT||encoder.encode(text).length>LIMIT)return Object.assign({valid:false,error:"PAYLOAD_TOO_LARGE"},meta);
+    const clean=normalize(text);if(!clean)return Object.assign({valid:false,error:"EMPTY_OR_INVALID_PAYLOAD"},meta);
+    const raw="BODUL_MATRIX::"+clean+"::"+time.date+"::OMEGA_FLOW";
+    return Object.assign({valid:true,input_payload:clean,seal_date:time.date,matrix_verification_seal:sha256(encoder.encode(raw))},meta);
+  }
+  const KNOWN="36e7be60a50a6d846b8b162c199a5e534c612ba171163d9c3406e2f2b12c0651";
+  function selftest(){
+    const tests=[sha256(encoder.encode(""))==="e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",sha256(encoder.encode("abc"))==="ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad",compute("Evidence before confidence.","2026-11-03T12:00:00Z").matrix_verification_seal===KNOWN,compute("  Evidence\u00a0before\nconfidence. ","2026-11-04T00:30:00+02:00").matrix_verification_seal===KNOWN,compute(" ","2026-11-03T12:00:00Z").valid===false,compute("x","2100-02-29T00:00:00Z").valid===false,compute("x","2126-11-03T12:00:00Z").valid===true,compute("x","2400-02-29T00:00:00Z").valid===true,compute("\ud800","2026-11-03T12:00:00Z").error==="INVALID_UNICODE"];
+    return{passed:tests.every(Boolean),checks:tests.length,scope:"local checksum vectors, Unicode and Gregorian boundary fixtures"};
+  }
+  const el=id=>document.getElementById(id);let last=null;
+  function show(){last=compute(el("payload").value,el("at").value);el("output").textContent=JSON.stringify(last,null,2);el("download").disabled=!last.valid;el("status").textContent=last.valid?"Checksum computed locally. No network request was made.":"Input rejected: "+last.error;}
+  function fixture(kind){el("payload").value=kind==="empty"?" \t\n":"Evidence before confidence.";el("at").value=kind==="boundary"?"2026-11-04T00:30:00+02:00":"2026-11-03T12:00:00+00:00";show();}
+  el("compute").addEventListener("click",show);el("sample").addEventListener("click",()=>fixture("sample"));el("boundary").addEventListener("click",()=>fixture("boundary"));el("empty").addEventListener("click",()=>fixture("empty"));
+  el("selftest").addEventListener("click",()=>{el("output").textContent=JSON.stringify(selftest(),null,2);el("status").textContent="Self-tests completed locally.";last=null;el("download").disabled=true;});
+  el("download").addEventListener("click",()=>{if(!last||!last.valid)return;const url=URL.createObjectURL(new Blob([JSON.stringify(last,null,2)+"\n"],{type:"application/json;charset=utf-8"})),a=document.createElement("a");a.href=url;a.download="matrix-result.json";a.click();setTimeout(()=>URL.revokeObjectURL(url),1000);});
+  window.BodulMatrix=Object.freeze({compute:compute,sha256:sha256,selftest:selftest,format:FORMAT,version:VERSION,whitespace:WHITE.slice()});
+}());
+</script></body></html>

offline_cli.py

@@ -0,0 +1,59 @@
+#!/usr/bin/env python3
+"""Offline JSON interface. No network, API keys, model download, or pip needed."""
+import argparse
+import sys
+from pathlib import Path
+from demo import evaluate_json
+from matrix_core import DeterministicMatrixCore, parse_instant, verify_result
+from safe_json import MAX_JSON_BYTES, strict_dumps, strict_loads
+
+
+def _read(path, limit=MAX_JSON_BYTES):
+    stream = sys.stdin.buffer if path == "-" else Path(path).open("rb")
+    try:
+        data = stream.read(limit + 1)
+    finally:
+        if path != "-":
+            stream.close()
+    if len(data) > limit:
+        raise ValueError("Input exceeds the documented size limit")
+    return data.decode("utf-8", errors="strict")
+
+
+def main(argv=None):
+    for stream in (sys.stdout, sys.stderr):
+        try:
+            stream.reconfigure(encoding="utf-8")
+        except (AttributeError, ValueError):
+            pass
+    parser = argparse.ArgumentParser(description=__doc__)
+    commands = parser.add_subparsers(dest="command", required=True)
+    matrix = commands.add_parser("matrix", help="Checksum a UTF-8 text file, or - for stdin")
+    matrix.add_argument("input")
+    matrix.add_argument("--at", required=True, help="Explicit timestamp for reproducible execution")
+    verify = commands.add_parser("verify-matrix", help="Verify a saved Matrix JSON result")
+    verify.add_argument("input")
+    claims = commands.add_parser("claims", help="Evaluate supplied evidence JSON at its evaluation_time")
+    claims.add_argument("input")
+    claims.add_argument("--batch", action="store_true")
+    args = parser.parse_args(argv)
+    try:
+        text = _read(args.input)
+        if args.command == "matrix":
+            result = DeterministicMatrixCore().enforce_zero_tolerance_matrix(text, parse_instant(args.at))
+            status = 0 if result["valid"] else 2
+        elif args.command == "verify-matrix":
+            result = verify_result(strict_loads(text))
+            status = 0 if result["verified"] else 2
+        else:
+            result = evaluate_json(text, batch=args.batch)
+            status = 0 if result.get("verdict") == "APPROVE" else 3
+    except (ValueError, TypeError, UnicodeError, OSError, OverflowError) as exc:
+        result = {"valid": False, "error": "INVALID_INPUT", "detail": str(exc)}
+        status = 2
+    print(strict_dumps(result))
+    return status
+
+
+if __name__ == "__main__":
+    sys.exit(main())

requirements.txt

@@ -1 +1,2 @@
-# Deterministic engine: Python 3.12+, standard library only.
+# Python 3.10+ standard library only for the core and offline CLI.
+# The hosted Gradio-Lite presentation manages its separately pinned browser dependencies.

run_example.py

@@ -1,3 +1,3 @@
-import json
-from demo import evaluate, example
-print(json.dumps(evaluate(example()), indent=2))
+import json
+from demo import evaluate, example
+print(json.dumps(evaluate(example()), indent=2))

safe_json.py

@@ -0,0 +1,86 @@
+"""Bounded UTF-8 JSON boundary, rejecting duplicate keys and non-finite values."""
+import json
+
+MAX_JSON_BYTES = 1_048_576
+MAX_JSON_DEPTH = 32
+
+
+def _pairs(pairs):
+    result = {}
+    for key, value in pairs:
+        if key in result:
+            raise ValueError("Duplicate JSON key")
+        result[key] = value
+    return result
+
+
+def _constant(value):
+    raise ValueError("Non-finite JSON number")
+
+
+def _float(value):
+    import math
+    parsed = float(value)
+    if not math.isfinite(parsed):
+        raise ValueError("Non-finite JSON number")
+    return parsed
+
+
+def _integer(value):
+    # Cross-runtime bound, independent of Python's changing int conversion cap.
+    if len(value.lstrip("-")) > 128:
+        raise ValueError("JSON integer exceeds 128 digits")
+    return int(value)
+
+
+def _check_text(text):
+    if not isinstance(text, str) or len(text) > MAX_JSON_BYTES:
+        raise ValueError("JSON input must be bounded UTF-8 text")
+    try:
+        if len(text.encode("utf-8", errors="strict")) > MAX_JSON_BYTES:
+            raise ValueError("JSON input too large")
+    except UnicodeEncodeError as exc:
+        raise ValueError("Invalid Unicode scalar value") from exc
+    # Limit nesting before asking a recursive JSON decoder to allocate objects.
+    depth = 0
+    quoted = escaped = False
+    for ch in text:
+        if quoted:
+            if escaped:
+                escaped = False
+            elif ch == "\\":
+                escaped = True
+            elif ch == '"':
+                quoted = False
+        elif ch == '"':
+            quoted = True
+        elif ch in "[{":
+            depth += 1
+            if depth > MAX_JSON_DEPTH:
+                raise ValueError("JSON nesting too deep")
+        elif ch in "]}":
+            depth -= 1
+
+
+def strict_loads(text):
+    _check_text(text)
+    try:
+        value = json.loads(text, object_pairs_hook=_pairs, parse_constant=_constant, parse_float=_float, parse_int=_integer)
+        # Escaped surrogate pairs are decoded normally; lone surrogates fail.
+        stack = [value]
+        while stack:
+            item = stack.pop()
+            if isinstance(item, str):
+                item.encode("utf-8", errors="strict")
+            elif isinstance(item, dict):
+                stack.extend(item.keys())
+                stack.extend(item.values())
+            elif isinstance(item, list):
+                stack.extend(item)
+        return value
+    except (UnicodeError, RecursionError) as exc:
+        raise ValueError("Invalid JSON Unicode or nesting") from exc
+
+
+def strict_dumps(value):
+    return json.dumps(value, ensure_ascii=True, sort_keys=True, indent=2, allow_nan=False)

schemas/matrix-result-v1.json

@@ -0,0 +1,105 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "urn:bodul:matrix-result:v1",
+  "title": "Bodul Matrix v1 result",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "valid": {
+      "type": "boolean"
+    },
+    "input_payload": {
+      "type": "string",
+      "minLength": 1
+    },
+    "seal_date": {
+      "type": "string",
+      "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$"
+    },
+    "matrix_verification_seal": {
+      "type": "string",
+      "pattern": "^[0-9a-f]{64}$"
+    },
+    "timestamp": {
+      "type": "string",
+      "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}(\\.[0-9]{6})?\\+00:00$"
+    },
+    "engine_version": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 128
+    },
+    "checksum_format": {
+      "const": "bodul-matrix-v1"
+    },
+    "normalization_profile": {
+      "const": "bodul-whitespace-v1"
+    },
+    "hash_algorithm": {
+      "const": "sha256"
+    },
+    "error": {
+      "enum": [
+        "EMPTY_OR_INVALID_PAYLOAD",
+        "INVALID_UNICODE",
+        "PAYLOAD_TOO_LARGE"
+      ]
+    }
+  },
+  "required": [
+    "valid",
+    "timestamp",
+    "engine_version",
+    "checksum_format",
+    "normalization_profile",
+    "hash_algorithm"
+  ],
+  "oneOf": [
+    {
+      "properties": {
+        "valid": {
+          "const": true
+        }
+      },
+      "required": [
+        "input_payload",
+        "seal_date",
+        "matrix_verification_seal"
+      ],
+      "not": {
+        "required": [
+          "error"
+        ]
+      }
+    },
+    {
+      "properties": {
+        "valid": {
+          "const": false
+        }
+      },
+      "required": [
+        "error"
+      ],
+      "not": {
+        "anyOf": [
+          {
+            "required": [
+              "input_payload"
+            ]
+          },
+          {
+            "required": [
+              "seal_date"
+            ]
+          },
+          {
+            "required": [
+              "matrix_verification_seal"
+            ]
+          }
+        ]
+      }
+    }
+  ]
+}

test_vectors.json

@@ -0,0 +1,110 @@
+{
+  "checksum_format": "bodul-matrix-v1",
+  "normalization_profile": "bodul-whitespace-v1",
+  "vectors": [
+    {
+      "id": "legacy-known",
+      "payload": "Evidence before confidence.",
+      "normalized": "Evidence before confidence.",
+      "at": "2026-11-03T12:00:00Z",
+      "utc_date": "2026-11-03",
+      "sha256": "36e7be60a50a6d846b8b162c199a5e534c612ba171163d9c3406e2f2b12c0651"
+    },
+    {
+      "id": "whitespace",
+      "payload": " \tEvidence\u00a0before\nconfidence. ",
+      "normalized": "Evidence before confidence.",
+      "at": "2026-11-03T12:00:00Z",
+      "utc_date": "2026-11-03",
+      "sha256": "36e7be60a50a6d846b8b162c199a5e534c612ba171163d9c3406e2f2b12c0651"
+    },
+    {
+      "id": "utc-boundary",
+      "payload": "Evidence before confidence.",
+      "normalized": "Evidence before confidence.",
+      "at": "2026-11-04T00:30:00+02:00",
+      "utc_date": "2026-11-03",
+      "sha256": "36e7be60a50a6d846b8b162c199a5e534c612ba171163d9c3406e2f2b12c0651"
+    },
+    {
+      "id": "croatian-emoji",
+      "payload": "\u010c\u0107\u0161\u0111\u017e \ud83d\ude00",
+      "normalized": "\u010c\u0107\u0161\u0111\u017e \ud83d\ude00",
+      "at": "2126-11-03T12:00:00Z",
+      "utc_date": "2126-11-03",
+      "sha256": "2b2080b121d8b9b26c9db80ee4fb38da7d1a4cefdccb1cf853abecf51df12468"
+    },
+    {
+      "id": "hundred-years",
+      "payload": "Evidence before confidence.",
+      "normalized": "Evidence before confidence.",
+      "at": "2126-11-03T12:00:00Z",
+      "utc_date": "2126-11-03",
+      "sha256": "fae53da0e322d987a3692f9764f76b8836741ce4832fa5c75a5bb2e7c16c1ec6"
+    },
+    {
+      "id": "gregorian-2400",
+      "payload": "leap",
+      "normalized": "leap",
+      "at": "2400-02-29T00:00:00Z",
+      "utc_date": "2400-02-29",
+      "sha256": "b94ffe1428617d114837b744c5f67b6346fa80bd79b3ba10c03486e31402be43"
+    },
+    {
+      "id": "minimum-year",
+      "payload": "origin",
+      "normalized": "origin",
+      "at": "0001-01-01T00:00:00Z",
+      "utc_date": "0001-01-01",
+      "sha256": "a5edb94148551dbe2410fe1830987ca50c9f1949c9169917324cfed8ec803275"
+    },
+    {
+      "id": "maximum-year",
+      "payload": "last",
+      "normalized": "last",
+      "at": "9999-12-31T23:59:59Z",
+      "utc_date": "9999-12-31",
+      "sha256": "e1692573d3bc5aae5ac5e7794f15ba550f8137dba78baca5928f21e6d9a244ca"
+    },
+    {
+      "id": "zero-width-preserved",
+      "payload": "a\u200bb",
+      "normalized": "a\u200bb",
+      "at": "2026-11-03T12:00:00.123456Z",
+      "utc_date": "2026-11-03",
+      "sha256": "997ae295d638782fa2844f9cdd36bbd20b359766bce16d01ad4f13bef0dc18ce"
+    },
+    {
+      "id": "decomposed",
+      "payload": "e\u0301",
+      "normalized": "e\u0301",
+      "at": "2126-11-03T12:00:00Z",
+      "utc_date": "2126-11-03",
+      "sha256": "73e5ba5a4bcef9c1a7ee0df380dd5c0f692d676c30477fccc4bda2fc30836d62"
+    },
+    {
+      "id": "composed",
+      "payload": "\u00e9",
+      "normalized": "\u00e9",
+      "at": "2126-11-03T12:00:00Z",
+      "utc_date": "2126-11-03",
+      "sha256": "fa36e13722a7c7a0377e18cc43566ecb5ef1a17b078259e2c4bca8a1266843ef"
+    },
+    {
+      "id": "literal-delimiters",
+      "payload": "a::b::OMEGA_FLOW",
+      "normalized": "a::b::OMEGA_FLOW",
+      "at": "2026-11-03T12:00:00Z",
+      "utc_date": "2026-11-03",
+      "sha256": "7a722c2f2ebc889f588b56131ffd64e222c2d7adc47b4e1fc3c5afae3464cb93"
+    },
+    {
+      "id": "utf8-bom-is-data",
+      "payload": "\ufefftest",
+      "normalized": "\ufefftest",
+      "at": "2026-11-03T12:00:00Z",
+      "utc_date": "2026-11-03",
+      "sha256": "435a547df74b925f80b707598ac0bbc9b76b2a64f731a0bca56e2780ed9295ab"
+    }
+  ]
+}

tests/test_longevity.py

@@ -0,0 +1,265 @@
+"""Regression checks for the portable source release; standard library only."""
+import copy
+import hashlib
+import json
+import os
+import random
+import socket
+import subprocess
+import sys
+import tempfile
+import unittest
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+from unittest.mock import patch
+
+from demo import evaluate, evaluate_json, example
+from matrix_core import (
+    CHECKSUM_FORMAT, ENGINE_VERSION, MAX_PAYLOAD_BYTES, WHITESPACE_CODEPOINTS,
+    DeterministicMatrixCore, checksum_for_date, normalize_payload, parse_instant, verify_result,
+)
+from safe_json import strict_loads
+from verify_release import verify_release
+
+ROOT = Path(__file__).resolve().parent.parent
+FIXED = datetime(2026, 11, 3, 12, tzinfo=timezone.utc)
+
+
+class LongevityTests(unittest.TestCase):
+    def setUp(self):
+        self.core = DeterministicMatrixCore()
+
+    def test_published_vectors_and_utc_dates(self):
+        vectors = json.loads((ROOT / "test_vectors.json").read_text(encoding="utf-8"))
+        for vector in vectors["vectors"]:
+            with self.subTest(id=vector["id"]):
+                result = self.core.enforce_zero_tolerance_matrix(vector["payload"], parse_instant(vector["at"]))
+                self.assertEqual(result["input_payload"], vector["normalized"])
+                self.assertEqual(result["seal_date"], vector["utc_date"])
+                self.assertEqual(result["matrix_verification_seal"], vector["sha256"])
+
+    def test_frozen_whitespace_table(self):
+        self.assertEqual(len(WHITESPACE_CODEPOINTS), 29)
+        for codepoint in WHITESPACE_CODEPOINTS:
+            self.assertEqual(normalize_payload(chr(codepoint) + "a" + chr(codepoint) * 3 + "b" + chr(codepoint)), "a b")
+
+    def test_non_whitespace_characters_are_preserved(self):
+        for codepoint in (0, 0x180E, 0x200B, 0x2060, 0xFEFF, 0x1F600):
+            payload = chr(codepoint) + "text" + chr(codepoint)
+            self.assertEqual(normalize_payload(payload), payload)
+
+    def test_no_implicit_unicode_normalization(self):
+        self.assertNotEqual(checksum_for_date("é", "2126-11-03"), checksum_for_date("e\u0301", "2126-11-03"))
+
+    def test_normalization_idempotence_for_seeded_unicode_inputs(self):
+        rng = random.Random(36500)
+        alphabet = ["a", "Č", "😀", "\u200b", "é"] + [chr(c) for c in WHITESPACE_CODEPOINTS]
+        for _ in range(100):
+            payload = "".join(rng.choice(alphabet) for _ in range(100))
+            clean = normalize_payload(payload)
+            self.assertEqual(normalize_payload(clean), clean)
+            if clean:
+                self.assertEqual(checksum_for_date(payload, "2126-11-03"), checksum_for_date(clean, "2126-11-03"))
+
+    def test_lone_surrogates_have_no_checksum(self):
+        for payload in ("\ud800", "x\udfff", "\ud800\udc00"):
+            result = self.core.enforce_zero_tolerance_matrix(payload, FIXED)
+            self.assertFalse(result["valid"])
+            self.assertEqual(result["error"], "INVALID_UNICODE")
+            self.assertNotIn("matrix_verification_seal", result)
+
+    def test_raw_utf8_size_limit_before_normalization(self):
+        for payload in (" " * (MAX_PAYLOAD_BYTES + 1), "😀" * (MAX_PAYLOAD_BYTES // 4 + 1)):
+            self.assertEqual(self.core.enforce_zero_tolerance_matrix(payload, FIXED)["error"], "PAYLOAD_TOO_LARGE")
+        self.assertTrue(self.core.enforce_zero_tolerance_matrix("a" * MAX_PAYLOAD_BYTES, FIXED)["valid"])
+
+    def test_future_gregorian_calendar_and_leap_rules(self):
+        for at in ("2126-11-03T12:00:00Z", "2400-02-29T12:00:00Z", "0001-01-01T00:00:00Z", "9999-12-31T23:59:59Z"):
+            self.assertTrue(self.core.enforce_zero_tolerance_matrix("x", parse_instant(at))["valid"])
+        for at in ("2100-02-29T12:00:00Z", "2200-02-29T12:00:00Z", "0000-01-01T00:00:00Z", "2026-02-30T12:00:00Z"):
+            with self.assertRaises(ValueError):
+                parse_instant(at)
+
+    def test_timestamp_grammar_is_explicit_and_ascii(self):
+        for at in ("2026-11-03", "2026-11-03 12:00:00Z", "20261103T120000Z", "2026-11-03T12:00:00-00:00", "2026-11-03T12:00:00+00:60", "2026-11-03T12:00:00+24:00", "2026-11-03T12:00:60Z", "2026-11-03T12:00:00.1234567Z"):
+            with self.subTest(at=at), self.assertRaises(ValueError):
+                parse_instant(at)
+
+    def test_utc_overflow_is_controlled(self):
+        for at in ("0001-01-01T00:00:00+01:00", "9999-12-31T23:59:59-01:00"):
+            with self.assertRaises(ValueError):
+                parse_instant(at)
+
+    def test_valid_export_roundtrips(self):
+        result = self.core.enforce_zero_tolerance_matrix("Č 😀", FIXED)
+        self.assertTrue(verify_result(strict_loads(json.dumps(result)))["verified"])
+        self.assertFalse(verify_result(result)["metadata_authenticated"])
+
+    def test_legacy_351_export_remains_readable(self):
+        legacy = self.core.enforce_zero_tolerance_matrix("Evidence before confidence.", FIXED)
+        for key in ("checksum_format", "normalization_profile", "hash_algorithm"):
+            legacy.pop(key)
+        legacy["engine_version"] = "3.5.1-OMEGA"
+        self.assertTrue(verify_result(legacy)["verified"])
+        legacy["engine_version"] = "unknown"
+        self.assertFalse(verify_result(legacy)["verified"])
+
+    def test_export_mutations_fail_closed(self):
+        result = self.core.enforce_zero_tolerance_matrix("Evidence before confidence.", FIXED)
+        mutations = {"valid": 1, "input_payload": "other", "seal_date": "2026-11-04", "timestamp": "2026-11-04T12:00:00Z", "matrix_verification_seal": "0" * 64, "checksum_format": "bodul-matrix-v999", "normalization_profile": "unicode-latest", "hash_algorithm": "md5", "engine_version": ""}
+        for key, value in mutations.items():
+            item = dict(result)
+            item[key] = value
+            with self.subTest(key=key):
+                self.assertFalse(verify_result(item)["verified"])
+        item = dict(result, extra="ignored?")
+        self.assertFalse(verify_result(item)["verified"])
+        item = dict(result)
+        del item["hash_algorithm"]
+        self.assertFalse(verify_result(item)["verified"])
+
+    def test_export_requires_canonical_payload(self):
+        result = self.core.enforce_zero_tolerance_matrix("x", FIXED)
+        result["input_payload"] = "  x "
+        self.assertEqual(verify_result(result)["error"], "NON_CANONICAL_PAYLOAD")
+
+    def test_metadata_is_not_authenticated(self):
+        result = self.core.enforce_zero_tolerance_matrix("x", FIXED)
+        result["engine_version"] = "different-but-unsealed-metadata"
+        result["timestamp"] = "2026-11-03T23:59:59Z"
+        self.assertTrue(verify_result(result)["verified"])
+
+    def test_duplicate_keys_and_nonfinite_numbers_are_rejected(self):
+        for text in ('{"a":1,"a":2}', '{"a":{"x":1,"x":2}}', '{"x":NaN}', '{"x":Infinity}', '{"x":1e9999}'):
+            with self.subTest(text=text), self.assertRaises(ValueError):
+                strict_loads(text)
+
+    def test_json_limits_and_surrogates(self):
+        for text in ('[' * 33 + '0' + ']' * 33, '"\\ud800"', '1' * 129):
+            with self.assertRaises(ValueError):
+                strict_loads(text)
+        self.assertEqual(strict_loads('"\\ud83d\\ude00"'), "😀")
+        self.assertEqual(strict_loads('{"text":"[[[{{{"}'), {"text": "[[[{{{"})
+
+    def test_malformed_public_inputs_never_approve(self):
+        for payload in (None, True, [], {}, {"claim": {}}, {"evidence": "wrong"}):
+            self.assertEqual(evaluate(payload)["verdict"], "BLOCK")
+        self.assertEqual(evaluate_json('{"claim":1,"claim":2}')["reason"], "invalid_json")
+
+    def test_public_boolean_types_are_not_integers(self):
+        payload = example(at=FIXED)
+        payload["evidence"][0]["supports"] = 1
+        self.assertEqual(evaluate(payload)["verdict"], "BLOCK")
+
+    def test_public_timestamps_are_frozen_and_utc_normalized(self):
+        payload = example(at=FIXED)
+        other = copy.deepcopy(payload)
+        other["evaluation_time"] = "2026-11-03T14:00:00+02:00"
+        other["evidence"][0]["observed_at"] = "2026-11-03T14:00:00+02:00"
+        self.assertEqual(evaluate(payload), evaluate(other))
+        payload["evaluation_time"] = "2026-11-03 12:00:00Z"
+        self.assertEqual(evaluate(payload)["verdict"], "BLOCK")
+
+    def test_public_approval_flags_cannot_authorize_high_risk_claims(self):
+        payload = example(at=FIXED)
+        payload["claim"]["risk"] = "high"
+        payload["human_approved"] = True
+        self.assertEqual(evaluate(payload)["verdict"], "ESCALATE")
+        self.assertEqual(evaluate(payload)["reason"], "human_approval_required")
+
+    def test_missing_stale_future_and_conflicting_evidence_block(self):
+        payload = example(at=FIXED)
+        self.assertEqual(evaluate(payload)["verdict"], "APPROVE")
+        missing = example("unsupported", at=FIXED)
+        self.assertEqual(evaluate(missing)["classification"], "UNKNOWN")
+        for seconds in (-301, 1):
+            item = copy.deepcopy(payload)
+            item["evidence"][0]["observed_at"] = (FIXED + timedelta(seconds=seconds)).isoformat()
+            self.assertEqual(evaluate(item)["verdict"], "BLOCK")
+        contradictory = dict(payload["evidence"][0], source_id="second", supports=False)
+        payload["evidence"].append(contradictory)
+        self.assertEqual(evaluate(payload)["classification"], "CONFLICT")
+        self.assertEqual(evaluate(payload)["verdict"], "BLOCK")
+
+    def test_source_duplicates_do_not_satisfy_independence_quorum(self):
+        payload = example(at=FIXED)
+        payload["claim"]["risk"] = "medium"
+        payload["evidence"].append(dict(payload["evidence"][0], evidence_id="copy"))
+        self.assertEqual(evaluate(payload)["verdict"], "ESCALATE")
+
+    def test_offline_execution_does_not_use_network(self):
+        with patch.object(socket, "socket", side_effect=AssertionError("Network use forbidden")):
+            self.assertTrue(self.core.enforce_zero_tolerance_matrix("x", FIXED)["valid"])
+            self.assertEqual(evaluate(example(at=FIXED))["verdict"], "APPROVE")
+
+    def test_explicit_future_evaluation_repeats(self):
+        payload = example(at=datetime(2126, 11, 3, tzinfo=timezone.utc))
+        expected = evaluate(payload)
+        self.assertEqual(expected["verdict"], "APPROVE")
+        for _ in range(25):
+            self.assertEqual(evaluate(payload), expected)
+
+    def test_offline_cli_matrix_and_saved_result(self):
+        with tempfile.TemporaryDirectory() as directory:
+            folder = Path(directory)
+            text = folder / "input.txt"
+            result_file = folder / "result.json"
+            text.write_text("Evidence before confidence.", encoding="utf-8")
+            run = subprocess.run([sys.executable, "-B", str(ROOT / "offline_cli.py"), "matrix", str(text), "--at", FIXED.isoformat()], capture_output=True, text=True, encoding="utf-8")
+            self.assertEqual(run.returncode, 0, run.stderr)
+            result_file.write_text(run.stdout, encoding="utf-8")
+            replay = subprocess.run([sys.executable, "-B", str(ROOT / "offline_cli.py"), "verify-matrix", str(result_file)], capture_output=True, text=True, encoding="utf-8")
+            self.assertEqual(replay.returncode, 0, replay.stderr)
+            self.assertTrue(json.loads(replay.stdout)["verified"])
+
+    def test_offline_cli_block_has_nonzero_exit(self):
+        with tempfile.TemporaryDirectory() as directory:
+            path = Path(directory) / "claim.json"
+            path.write_text(json.dumps(example("unsupported", at=FIXED)), encoding="utf-8")
+            run = subprocess.run([sys.executable, "-B", str(ROOT / "offline_cli.py"), "claims", str(path)], capture_output=True, text=True, encoding="utf-8")
+            self.assertEqual(run.returncode, 3)
+            self.assertEqual(json.loads(run.stdout)["verdict"], "BLOCK")
+
+
+class ArchiveIntegrityTests(unittest.TestCase):
+    def make_archive(self, folder):
+        data = b"portable source\n"
+        (folder / "source.txt").write_bytes(data)
+        manifest = {"manifest_format": "bodul-source-archive-v1", "files": {"source.txt": {"bytes": len(data), "sha256": hashlib.sha256(data).hexdigest(), "sha512": hashlib.sha512(data).hexdigest()}}}
+        (folder / "RELEASE_MANIFEST.json").write_text(json.dumps(manifest), encoding="utf-8")
+        return manifest
+
+    def test_clean_archive_and_tampering(self):
+        with tempfile.TemporaryDirectory() as directory:
+            root = Path(directory)
+            self.make_archive(root)
+            self.assertTrue(verify_release(root)["verified"])
+            (root / "source.txt").write_bytes(b"modified source\n")
+            self.assertFalse(verify_release(root)["verified"])
+
+    def test_missing_and_unlisted_files(self):
+        with tempfile.TemporaryDirectory() as directory:
+            root = Path(directory)
+            self.make_archive(root)
+            (root / "extra.txt").write_text("x")
+            self.assertFalse(verify_release(root)["verified"])
+            (root / "extra.txt").unlink()
+            (root / "source.txt").unlink()
+            self.assertFalse(verify_release(root)["verified"])
+
+    def test_unknown_format_and_unsafe_paths(self):
+        with tempfile.TemporaryDirectory() as directory:
+            root = Path(directory)
+            manifest = self.make_archive(root)
+            for path in ("../escape.txt", "/absolute.txt", "drive:path", "foo\\bar", "."):
+                bad = copy.deepcopy(manifest)
+                bad["files"][path] = bad["files"].pop("source.txt")
+                (root / "RELEASE_MANIFEST.json").write_text(json.dumps(bad), encoding="utf-8")
+                self.assertFalse(verify_release(root)["verified"])
+            manifest["manifest_format"] = "future-unknown-format"
+            (root / "RELEASE_MANIFEST.json").write_text(json.dumps(manifest), encoding="utf-8")
+            self.assertFalse(verify_release(root)["verified"])
+
+
+if __name__ == "__main__":
+    unittest.main()

verify_release.py

@@ -0,0 +1,66 @@
+#!/usr/bin/env python3
+"""Verify the bounded source archive against its manifest; this is not a signature."""
+import hashlib
+import json
+import re
+import sys
+from pathlib import Path, PurePosixPath
+from safe_json import strict_loads
+
+
+def verify_release(root):
+    root = Path(root).resolve()
+    failures = []
+    try:
+        manifest_file = root / "RELEASE_MANIFEST.json"
+        if manifest_file.is_symlink() or manifest_file.stat().st_size > 1_048_576:
+            raise ValueError("Unsafe manifest")
+        manifest = strict_loads(manifest_file.read_text(encoding="utf-8"))
+        if not isinstance(manifest, dict) or manifest.get("manifest_format") != "bodul-source-archive-v1":
+            raise ValueError("Unknown manifest format")
+        files = manifest.get("files")
+        if not isinstance(files, dict) or not 1 <= len(files) <= 500:
+            raise ValueError("Invalid file list")
+        folded = set()
+        for name, entry in files.items():
+            relative = PurePosixPath(name)
+            if not relative.parts or not re.fullmatch(r"[A-Za-z0-9_.\-/]+", name) or relative.is_absolute() or name != relative.as_posix() or any(part in (".", "..") for part in relative.parts) or name == "RELEASE_MANIFEST.json":
+                raise ValueError("Unsafe archive path")
+            if name.casefold() in folded:
+                raise ValueError("Case-insensitive archive path collision")
+            folded.add(name.casefold())
+            if not isinstance(entry, dict) or set(entry) != {"bytes", "sha256", "sha512"}:
+                raise ValueError("Invalid file entry")
+            if type(entry["bytes"]) is not int or not 0 <= entry["bytes"] <= 2_000_000:
+                raise ValueError("Invalid file size")
+            for algorithm, length in (("sha256", 64), ("sha512", 128)):
+                if not isinstance(entry[algorithm], str) or not re.fullmatch("[0-9a-f]{" + str(length) + "}", entry[algorithm]):
+                    raise ValueError("Invalid digest")
+            path = root.joinpath(*relative.parts)
+            if not path.is_relative_to(root) or any(parent.is_symlink() for parent in (path, *path.parents) if parent != root and parent.is_relative_to(root)):
+                failures.append(name + ": unsafe symlink")
+                continue
+            if not path.is_file() or path.stat().st_size != entry["bytes"]:
+                failures.append(name + ": missing file or changed length")
+                continue
+            data = path.read_bytes()
+            if any(hashlib.new(a, data).hexdigest() != entry[a] for a in ("sha256", "sha512")):
+                failures.append(name + ": digest mismatch")
+        # Ignore development machinery; reject extra source/data files.
+        for path in root.rglob("*"):
+            rel = path.relative_to(root)
+            if any(part in (".git", ".venv", "__pycache__") for part in rel.parts):
+                continue
+            if path.is_symlink():
+                failures.append(rel.as_posix() + ": unexpected symlink")
+            elif path.is_file() and rel.as_posix() not in files and rel.as_posix() != "RELEASE_MANIFEST.json":
+                failures.append(rel.as_posix() + ": unlisted file")
+        return {"verified": not failures, "files_checked": len(files), "scope": "archive_byte_integrity", "authenticated": False, "failures": failures}
+    except (ValueError, TypeError, OSError, KeyError, UnicodeError) as exc:
+        return {"verified": False, "scope": "archive_byte_integrity", "authenticated": False, "failures": [str(exc)]}
+
+
+if __name__ == "__main__":
+    result = verify_release(Path(__file__).resolve().parent)
+    print(json.dumps(result, sort_keys=True))
+    sys.exit(0 if result["verified"] else 2)