problem-frame-gate 0.3.0__tar.gz → 1.0.0__tar.gz

{problem_frame_gate-0.3.0 → problem_frame_gate-1.0.0}/.gitignore

@@ -7,6 +7,7 @@ __pycache__/
 .ruff_cache/
 .coverage
 coverage.xml
+sbom.json
 dist/
 build/
 .env

{problem_frame_gate-0.3.0 → problem_frame_gate-1.0.0}/CITATION.cff

@@ -1,7 +1,7 @@
 cff-version: 1.2.0
 message: "If you use this software, cite the theory paper and this repository."
 title: "Problem Frame Gate"
-version: "0.3.0"
+version: "1.0.0"
 license: Apache-2.0
 repository-code: "https://github.com/kadubon/problem-frame-gate"
 references:

{problem_frame_gate-0.3.0 → problem_frame_gate-1.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: problem-frame-gate
-Version: 0.3.0
+Version: 1.0.0
 Summary: Audit logs and action gates for safer AI agents.
 Project-URL: Homepage, https://github.com/kadubon/problem-frame-gate
 Project-URL: Documentation, https://github.com/kadubon/problem-frame-gate/tree/main/docs
@@ -11,7 +11,7 @@ License-Expression: Apache-2.0
 License-File: LICENSE
 License-File: NOTICE
 Keywords: ai,ai-agents,audit-log,authorization,open-source,provenance,pypi,python,risk-management,security
-Classifier: Development Status :: 3 - Alpha
+Classifier: Development Status :: 5 - Production/Stable
 Classifier: Intended Audience :: Developers
 Classifier: Intended Audience :: Science/Research
 Classifier: License :: OSI Approved :: Apache Software License
@@ -21,6 +21,7 @@ Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Security
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: Typing :: Typed
@@ -71,20 +72,21 @@ Create a strict manifest:
 pfg init-manifest > horizon.json
 ```
 
-Validate and fold a log:
+Validate and fold a log.  The repository contains complete copy-paste JSON
+fixtures in `docs/examples/`:
 
 ```bash
-pfg validate-schema horizon horizon.json
-pfg validate-schema log log.json
-pfg verify-log --horizon horizon.json log.json
-pfg fold --horizon horizon.json log.json
+pfg validate-schema horizon docs/examples/horizon.json
+pfg validate-schema log docs/examples/log.json
+pfg verify-log --horizon docs/examples/horizon.json docs/examples/log.json
+pfg fold --horizon docs/examples/horizon.json docs/examples/log.json
 ```
 
 Check an action gate and emit the atomic bundle:
 
 ```bash
-pfg validate-schema gate-request gate-request.json
-pfg check-gate --horizon horizon.json --bundle gate-request.json log.json
+pfg validate-schema gate-request docs/examples/gate-request.json
+pfg check-gate --horizon docs/examples/horizon.json --bundle docs/examples/gate-request.json docs/examples/log.json
 ```
 
 The generated bundle contains exactly five protected rows:
@@ -98,21 +100,45 @@ The generated bundle contains exactly five protected rows:
 Each row must be written by the executor writer and committed in one atomic
 group.  A standalone `OutboxClaim` is rejected.
 
+For a new project, copy the three JSON files from `docs/examples/`, then change
+the writer ids, certificate issuers, frame id, action name, risk id, and resource
+ids to match your deployment.
+
 ## Python Example
 
 ```python
-from problem_frame_gate import Envelope, EnvelopeClass, ExecutorGate, GateRequest, Horizon
+from problem_frame_gate import (
+    Envelope,
+    EnvelopeClass,
+    ExecutorGate,
+    GateRequest,
+    Horizon,
+    RiskClaimRecord,
+    RiskRouteWitness,
+    digest_json,
+)
 
 horizon = Horizon.strict_default(agent_writers=("agent",))
 
 def env(eid: str, commit: int, kind: str, **payload: object) -> Envelope:
     return Envelope(eid, eid, "0", commit, "agent", "agent", 1, EnvelopeClass.NORMAL, {"kind": kind, **payload})
 
+family_check = {
+    "accepted": True,
+    "checker": "example-certificate-family-v1",
+    "transcript_digest": digest_json({"checker": "example-certificate-family-v1", "accepted": True}),
+    "dependency_digest": digest_json({"dependencies": [], "source_ids": []}),
+    "revocation_frontier": [],
+    "checked_at": 2,
+    "assumption": "CertificateFamilyChecker",
+}
+
 log = [
     env("e0", 0, "Frame", frame_id="p1", scope="lab", goal="test anomaly",
         evidence_ids=["u1"], actions=["run-check"], acceptance=["review"], risk_ids=["r1"]),
     env("e1", 1, "Evidence", evidence_id="u1", digest="sha256:source"),
-    env("e2", 2, "Issue", cert_id="c-risk", family="risk", issuer="agent", expires_at=99, family_check=True),
+    env("e2", 2, "Issue", cert_id="c-risk", family="risk", issuer="agent",
+        expires_at=99, family_check=family_check),
     env("e3", 3, "Activated", frame_id="p1"),
     env("e4", 4, "RiskReg", hypothesis_id="h1", family="fixed"),
     env("e5", 5, "RiskReserve", risk_id="r1", hypothesis_id="h1", frame_id="p1", eta="1/100"),
@@ -123,11 +149,28 @@ log = [
     env("e9", 9, "AuthorizeOutbox", outbox_id="out1", frame_id="p1", action="run-check"),
 ]
 
+risk_claim = RiskClaimRecord(
+    claim_id="q1",
+    risk_id="r1",
+    hypothesis_id="h1",
+    mode="fixed",
+    cert_id="c-risk",
+    eta="1/100",
+    event_id="F1",
+    standardized_event_id="F1",
+    route_witness=RiskRouteWitness(
+        accepted=True,
+        checker="example-risk-route-v1",
+        transcript_digest=digest_json({"checker": "example-risk-route-v1", "mode": "fixed"}),
+        route="fixed",
+    ),
+)
+
 request = GateRequest(
     gate_id="gate1", bundle_id="bundle1", frame_id="p1", action="run-check",
     outbox_id="out1", capability_id="cap1", lease_id="lease1",
     risk_id="r1", hypothesis_id="h1", risk_mode="fixed", risk_cert_id="c-risk",
-    source_time=9, commit_time=10,
+    source_time=9, commit_time=10, risk_claim=risk_claim.to_json(), risk_alpha="1/50",
 )
 
 gate = ExecutorGate()
@@ -142,8 +185,21 @@ The library proves finite audit consistency.  It does not prove external truth,
 cryptographic collision resistance, statistical model validity, or physical
 effect.  Those are explicit assumptions in checker results.
 
+Strict certificates require a finite family-check record with a checker name,
+transcript digest, dependency digest, revocation frontier, and check time.
+Boolean certificate flags are treated as legacy assumptions and fail strict
+v1.0.0 checks.
+
+There are two verification routes:
+
+- JSON-only use relies on manifest-declared environment assumptions such as
+  `CertificateFamilyChecker` and `StatisticalModel`.
+- Python deployments can register callable `CertificateFamily` and `RiskMode`
+  checkers.  The verifier reuses those registries when replaying embedded
+  `GateCheck` transcripts.
+
 See `docs/quickstart.md`, `docs/schema.md`, `docs/theory-mapping.md`, and
-`docs/operations.md` for operational use.
+`docs/issue-codes.md` for operational use.
 
 ## Release
 

{problem_frame_gate-0.3.0 → problem_frame_gate-1.0.0}/README.md

@@ -34,20 +34,21 @@ Create a strict manifest:
 pfg init-manifest > horizon.json
 ```
 
-Validate and fold a log:
+Validate and fold a log.  The repository contains complete copy-paste JSON
+fixtures in `docs/examples/`:
 
 ```bash
-pfg validate-schema horizon horizon.json
-pfg validate-schema log log.json
-pfg verify-log --horizon horizon.json log.json
-pfg fold --horizon horizon.json log.json
+pfg validate-schema horizon docs/examples/horizon.json
+pfg validate-schema log docs/examples/log.json
+pfg verify-log --horizon docs/examples/horizon.json docs/examples/log.json
+pfg fold --horizon docs/examples/horizon.json docs/examples/log.json
 ```
 
 Check an action gate and emit the atomic bundle:
 
 ```bash
-pfg validate-schema gate-request gate-request.json
-pfg check-gate --horizon horizon.json --bundle gate-request.json log.json
+pfg validate-schema gate-request docs/examples/gate-request.json
+pfg check-gate --horizon docs/examples/horizon.json --bundle docs/examples/gate-request.json docs/examples/log.json
 ```
 
 The generated bundle contains exactly five protected rows:
@@ -61,21 +62,45 @@ The generated bundle contains exactly five protected rows:
 Each row must be written by the executor writer and committed in one atomic
 group.  A standalone `OutboxClaim` is rejected.
 
+For a new project, copy the three JSON files from `docs/examples/`, then change
+the writer ids, certificate issuers, frame id, action name, risk id, and resource
+ids to match your deployment.
+
 ## Python Example
 
 ```python
-from problem_frame_gate import Envelope, EnvelopeClass, ExecutorGate, GateRequest, Horizon
+from problem_frame_gate import (
+    Envelope,
+    EnvelopeClass,
+    ExecutorGate,
+    GateRequest,
+    Horizon,
+    RiskClaimRecord,
+    RiskRouteWitness,
+    digest_json,
+)
 
 horizon = Horizon.strict_default(agent_writers=("agent",))
 
 def env(eid: str, commit: int, kind: str, **payload: object) -> Envelope:
     return Envelope(eid, eid, "0", commit, "agent", "agent", 1, EnvelopeClass.NORMAL, {"kind": kind, **payload})
 
+family_check = {
+    "accepted": True,
+    "checker": "example-certificate-family-v1",
+    "transcript_digest": digest_json({"checker": "example-certificate-family-v1", "accepted": True}),
+    "dependency_digest": digest_json({"dependencies": [], "source_ids": []}),
+    "revocation_frontier": [],
+    "checked_at": 2,
+    "assumption": "CertificateFamilyChecker",
+}
+
 log = [
     env("e0", 0, "Frame", frame_id="p1", scope="lab", goal="test anomaly",
         evidence_ids=["u1"], actions=["run-check"], acceptance=["review"], risk_ids=["r1"]),
     env("e1", 1, "Evidence", evidence_id="u1", digest="sha256:source"),
-    env("e2", 2, "Issue", cert_id="c-risk", family="risk", issuer="agent", expires_at=99, family_check=True),
+    env("e2", 2, "Issue", cert_id="c-risk", family="risk", issuer="agent",
+        expires_at=99, family_check=family_check),
     env("e3", 3, "Activated", frame_id="p1"),
     env("e4", 4, "RiskReg", hypothesis_id="h1", family="fixed"),
     env("e5", 5, "RiskReserve", risk_id="r1", hypothesis_id="h1", frame_id="p1", eta="1/100"),
@@ -86,11 +111,28 @@ log = [
     env("e9", 9, "AuthorizeOutbox", outbox_id="out1", frame_id="p1", action="run-check"),
 ]
 
+risk_claim = RiskClaimRecord(
+    claim_id="q1",
+    risk_id="r1",
+    hypothesis_id="h1",
+    mode="fixed",
+    cert_id="c-risk",
+    eta="1/100",
+    event_id="F1",
+    standardized_event_id="F1",
+    route_witness=RiskRouteWitness(
+        accepted=True,
+        checker="example-risk-route-v1",
+        transcript_digest=digest_json({"checker": "example-risk-route-v1", "mode": "fixed"}),
+        route="fixed",
+    ),
+)
+
 request = GateRequest(
     gate_id="gate1", bundle_id="bundle1", frame_id="p1", action="run-check",
     outbox_id="out1", capability_id="cap1", lease_id="lease1",
     risk_id="r1", hypothesis_id="h1", risk_mode="fixed", risk_cert_id="c-risk",
-    source_time=9, commit_time=10,
+    source_time=9, commit_time=10, risk_claim=risk_claim.to_json(), risk_alpha="1/50",
 )
 
 gate = ExecutorGate()
@@ -105,8 +147,21 @@ The library proves finite audit consistency.  It does not prove external truth,
 cryptographic collision resistance, statistical model validity, or physical
 effect.  Those are explicit assumptions in checker results.
 
+Strict certificates require a finite family-check record with a checker name,
+transcript digest, dependency digest, revocation frontier, and check time.
+Boolean certificate flags are treated as legacy assumptions and fail strict
+v1.0.0 checks.
+
+There are two verification routes:
+
+- JSON-only use relies on manifest-declared environment assumptions such as
+  `CertificateFamilyChecker` and `StatisticalModel`.
+- Python deployments can register callable `CertificateFamily` and `RiskMode`
+  checkers.  The verifier reuses those registries when replaying embedded
+  `GateCheck` transcripts.
+
 See `docs/quickstart.md`, `docs/schema.md`, `docs/theory-mapping.md`, and
-`docs/operations.md` for operational use.
+`docs/issue-codes.md` for operational use.
 
 ## Release
 

{problem_frame_gate-0.3.0 → problem_frame_gate-1.0.0}/SECURITY.md

@@ -24,4 +24,6 @@ uv run mypy
 uv run pytest
 uv run bandit -c pyproject.toml -r src
 uv run pip-audit
+uv build
+uv run python scripts/generate_sbom.py --output sbom.json
 ```

problem_frame_gate-1.0.0/docs/examples/gate-request.json

@@ -0,0 +1,39 @@
+{
+  "action": "run-check",
+  "bundle_id": "bundle1",
+  "capability_id": "cap1",
+  "commit_time": 10,
+  "frame_id": "p1",
+  "gate_id": "gate1",
+  "hypothesis_id": "h1",
+  "lease_id": "lease1",
+  "outbox_id": "out1",
+  "risk_alpha": "1/50",
+  "risk_cert_id": "c-risk",
+  "risk_claim": {
+    "assumption": "StatisticalModel",
+    "cert_id": "c-risk",
+    "claim_id": "q1",
+    "eta": "1/100",
+    "event_id": "F1",
+    "hypothesis_id": "h1",
+    "ledger_digest": null,
+    "mode": "fixed",
+    "risk_id": "r1",
+    "route_witness": {
+      "accepted": true,
+      "assumption": "StatisticalModel",
+      "checker": "example-risk-route-v1",
+      "route": "fixed",
+      "spend_before_selection": true,
+      "transcript_digest": "sha256:2dec4bbd2ff232e51a06953bc9bcbeedaa0b7ce22f74e6a10df924cb50343169"
+    },
+    "selection_event_id": null,
+    "selection_time": null,
+    "standardized_event_id": "F1",
+    "stopping_time_id": null
+  },
+  "risk_id": "r1",
+  "risk_mode": "fixed",
+  "source_time": 9
+}

problem_frame_gate-1.0.0/docs/examples/horizon.json

@@ -0,0 +1,100 @@
+{
+  "allow_local_paths": false,
+  "audit_order": [],
+  "availability_order": [],
+  "capacities": {
+    "abort": 100,
+    "failClosed": 10,
+    "normal": 100
+  },
+  "causal_order": [],
+  "certificate_families": {
+    "approval": [
+      "agent"
+    ],
+    "formation": [
+      "agent"
+    ],
+    "risk": [
+      "agent"
+    ],
+    "safety": [
+      "agent"
+    ],
+    "source": [
+      "agent"
+    ]
+  },
+  "clock_policy": "integer-commit-time",
+  "codebook": [
+    "fixed",
+    "selectedEvent",
+    "conditionalSelective",
+    "anytime"
+  ],
+  "commit_groups": {},
+  "env_assumptions": [
+    "CertificateFamilyChecker",
+    "StatisticalModel"
+  ],
+  "events": [],
+  "executor_writer": "executor-gate",
+  "gate_bundle_kinds": [
+    "GateCheck",
+    "OutboxClaim",
+    "UseCap",
+    "ConsumeResource",
+    "RiskClose"
+  ],
+  "protected_constructors": {
+    "ConsumeResource": [
+      "executor-gate"
+    ],
+    "GateCheck": [
+      "executor-gate"
+    ],
+    "OutboxClaim": [
+      "executor-gate"
+    ],
+    "RiskClose": [
+      "executor-gate"
+    ],
+    "UseCap": [
+      "executor-gate"
+    ]
+  },
+  "risk_modes": [
+    "fixed",
+    "selectedEvent",
+    "conditionalSelective",
+    "anytime"
+  ],
+  "strict": true,
+  "version_intervals": {
+    "*": {
+      "maximum": 1,
+      "minimum": 1
+    }
+  },
+  "writer_authority": {
+    "*": [
+      "agent",
+      "executor-gate"
+    ],
+    "ConsumeResource": [
+      "executor-gate"
+    ],
+    "GateCheck": [
+      "executor-gate"
+    ],
+    "OutboxClaim": [
+      "executor-gate"
+    ],
+    "RiskClose": [
+      "executor-gate"
+    ],
+    "UseCap": [
+      "executor-gate"
+    ]
+  }
+}

problem_frame_gate-1.0.0/docs/examples/log.json

@@ -0,0 +1,184 @@
+[
+  {
+    "class": "normal",
+    "commit": 0,
+    "eid": "e0",
+    "event": "e0",
+    "owner": "agent",
+    "payload": {
+      "acceptance": [
+        "human-review"
+      ],
+      "actions": [
+        "run-check"
+      ],
+      "evidence_ids": [
+        "u1"
+      ],
+      "frame_id": "p1",
+      "goal": "investigate a bounded anomaly",
+      "kind": "Frame",
+      "risk_ids": [
+        "r1"
+      ],
+      "scope": "agent-demo"
+    },
+    "slot": "0",
+    "version": 1,
+    "writer": "agent"
+  },
+  {
+    "class": "normal",
+    "commit": 1,
+    "eid": "e1",
+    "event": "e1",
+    "owner": "agent",
+    "payload": {
+      "digest": "sha256:source",
+      "evidence_id": "u1",
+      "kind": "Evidence"
+    },
+    "slot": "0",
+    "version": 1,
+    "writer": "agent"
+  },
+  {
+    "class": "normal",
+    "commit": 2,
+    "eid": "e2",
+    "event": "e2",
+    "owner": "agent",
+    "payload": {
+      "cert_id": "c-risk",
+      "expires_at": 99,
+      "family": "risk",
+        "family_check": {
+          "accepted": true,
+          "assumption": "CertificateFamilyChecker",
+          "checked_at": 2,
+          "checker": "example-certificate-family-v1",
+        "dependency_digest": "sha256:6dc416ab067f207d6c485f2dc657efb8587b03e29676982cdc9d239a627564f2",
+        "revocation_frontier": [],
+        "transcript_digest": "sha256:c6eb3ce40abe6b7d35e77c5494d579d7de737871da0c5be57aa1fa6a4f323b51"
+      },
+      "issuer": "agent",
+      "kind": "Issue"
+    },
+    "slot": "0",
+    "version": 1,
+    "writer": "agent"
+  },
+  {
+    "class": "normal",
+    "commit": 3,
+    "eid": "e3",
+    "event": "e3",
+    "owner": "agent",
+    "payload": {
+      "frame_id": "p1",
+      "kind": "Activated"
+    },
+    "slot": "0",
+    "version": 1,
+    "writer": "agent"
+  },
+  {
+    "class": "normal",
+    "commit": 4,
+    "eid": "e4",
+    "event": "e4",
+    "owner": "agent",
+    "payload": {
+      "family": "fixed",
+      "hypothesis_id": "h1",
+      "kind": "RiskReg"
+    },
+    "slot": "0",
+    "version": 1,
+    "writer": "agent"
+  },
+  {
+    "class": "normal",
+    "commit": 5,
+    "eid": "e5",
+    "event": "e5",
+    "owner": "agent",
+    "payload": {
+      "eta": "1/100",
+      "frame_id": "p1",
+      "hypothesis_id": "h1",
+      "kind": "RiskReserve",
+      "risk_id": "r1"
+    },
+    "slot": "0",
+    "version": 1,
+    "writer": "agent"
+  },
+  {
+    "class": "normal",
+    "commit": 6,
+    "eid": "e6",
+    "event": "e6",
+    "owner": "agent",
+    "payload": {
+      "cert_id": "c-risk",
+      "eta": "1/100",
+      "frame_id": "p1",
+      "hypothesis_id": "h1",
+      "kind": "RiskSpend",
+      "mode": "fixed",
+      "risk_id": "r1"
+    },
+    "slot": "0",
+    "version": 1,
+    "writer": "agent"
+  },
+  {
+    "class": "normal",
+    "commit": 7,
+    "eid": "e7",
+    "event": "e7",
+    "owner": "agent",
+    "payload": {
+      "frame_id": "p1",
+      "kind": "ReserveResource",
+      "lease_id": "lease1",
+      "token_id": "tool"
+    },
+    "slot": "0",
+    "version": 1,
+    "writer": "agent"
+  },
+  {
+    "class": "normal",
+    "commit": 8,
+    "eid": "e8",
+    "event": "e8",
+    "owner": "agent",
+    "payload": {
+      "action": "run-check",
+      "capability_id": "cap1",
+      "frame_id": "p1",
+      "kind": "MintCap"
+    },
+    "slot": "0",
+    "version": 1,
+    "writer": "agent"
+  },
+  {
+    "class": "normal",
+    "commit": 9,
+    "eid": "e9",
+    "event": "e9",
+    "owner": "agent",
+    "payload": {
+      "action": "run-check",
+      "frame_id": "p1",
+      "kind": "AuthorizeOutbox",
+      "outbox_id": "out1"
+    },
+    "slot": "0",
+    "version": 1,
+    "writer": "agent"
+  }
+]

problem_frame_gate-1.0.0/docs/issue-codes.md

@@ -0,0 +1,25 @@
+# Issue Codes
+
+Checker results use stable issue codes so operators can route failures without
+parsing prose messages.
+
+| Code | Meaning | Typical fix |
+| --- | --- | --- |
+| `incomplete-manifest` | Strict manifest is missing a required safety table. | Start from `pfg init-manifest` and fill capacities, writer authority, protected constructors, certificate families, and risk modes. |
+| `protected-writer-authority` | A protected constructor was written by a non-executor writer. | Route `GateCheck`, `OutboxClaim`, `UseCap`, `ConsumeResource`, and `RiskClose` through the executor gate only. |
+| `gate-bundle-coherence` | The five gate rows do not bind the same request tuple. | Recreate the bundle from one accepted `GateRequest`. |
+| `gate-semantic-transcript` | Embedded `GateCheck` transcript does not replay. | Re-run `ExecutorGate.check()` on the same source prefix and registry/assumption policy. |
+| `gate-risk-claim-missing` | Strict gate request has no accepted risk claim. | Add a `RiskClaimRecord` with route witness and declared assumption or registered checker. |
+| `risk-claim-eta` | Risk claim spend is not a finite fraction string. | Use values such as `0`, `1/100`, or `3/10`. |
+| `risk-alpha-format` | Risk budget is not a finite fraction string. | Use the same fraction format as risk spend values. |
+| `risk-alpha-bound` | Finite risk spend exceeds the declared budget. | Lower spend, increase the declared bound, or split the decision. |
+| `certificate-family-unregistered` | Strict certificate has no registered checker or declared assumption. | Register a `CertificateFamily` checker or declare the assumption in the manifest. |
+| `source-cut-digest` | Source cut digest does not match included rows. | Recompute the source cut from the exact prefix. |
+| `patch-affected-completeness` | A touched invariant was not listed for recheck. | Add the invariant to `affected_invariants` and provide a read/touch witness. |
+| `join-liveness-repair` | A branch conflict lacks a folded and rechecked repair witness. | Add repair rows and typed repair witnesses for the conflict key. |
+| `reach-witness-payload` | Reachability transition is digest-only. | Include a typed witness payload for `patch`, `join`, `gate`, `abort`, or `failClosed`. |
+| `reach-transcript-digest` | Reachability witness replay does not match the transcript digest. | Recompute the transition witness with the same checker and manifest. |
+| `sensitive-payload` | Log payload contains secret-looking data or a local machine path. | Replace raw secrets and local paths with stable identifiers or digests. |
+
+Commercial deployments should treat every error issue as fail-closed. Warning
+issues indicate weaker assumptions and should be reviewed before production use.