problem-frame-gate 0.3.0__py3-none-any.whl

problem_frame_gate/__init__.py

@@ -0,0 +1,104 @@
+"""Practical finite audit calculus for AI problem-frame activation."""
+
+from ._version import __version__
+from .certificates import CertificateFamily, all_certificates_live, check_certificate_live
+from .digest import canonical_json_bytes, digest_json, digest_many
+from .fold import FoldKernel, FoldState, default_components
+from .formation import FormationProof, check_formation, check_well_audited
+from .gate import ExecutorGate, GateBundle, GateRecord, GateRequest
+from .join import JoinChecker, JoinProposal, union_join
+from .model import (
+    AuditTranscript,
+    DependencyRef,
+    Envelope,
+    EnvelopeClass,
+    Frame,
+    Horizon,
+    OrderEdge,
+    Status,
+    StrictManifest,
+    VersionInterval,
+)
+from .patch import AffectedClauseSet, PatchChecker, PatchProposal, ReadFootprint, TouchMatrix, WriteClass
+from .records import (
+    ReachabilityTranscript,
+    ReplayCertificate,
+    SourceCut,
+    SwapCover,
+    TransitionRecord,
+    check_reachability,
+    check_replay_certificate,
+    check_source_cut,
+)
+from .result import CheckResult, Issue
+from .risk import (
+    RiskClaimRecord,
+    RiskLedgerSummary,
+    check_risk_claims,
+    check_risk_ledger,
+    check_risk_spend_live,
+    summarize_risk_ledger,
+)
+from .security import SensitiveDataIssue, scan_for_sensitive_data
+from .verifier import EnvelopeVerifier, canonical_order, digest_log, legal_log
+
+__all__ = [
+    "AffectedClauseSet",
+    "AuditTranscript",
+    "CertificateFamily",
+    "CheckResult",
+    "DependencyRef",
+    "Envelope",
+    "EnvelopeClass",
+    "EnvelopeVerifier",
+    "ExecutorGate",
+    "FoldKernel",
+    "FoldState",
+    "FormationProof",
+    "Frame",
+    "GateBundle",
+    "GateRecord",
+    "GateRequest",
+    "Horizon",
+    "Issue",
+    "JoinChecker",
+    "JoinProposal",
+    "OrderEdge",
+    "PatchChecker",
+    "PatchProposal",
+    "ReachabilityTranscript",
+    "ReadFootprint",
+    "ReplayCertificate",
+    "RiskClaimRecord",
+    "RiskLedgerSummary",
+    "SensitiveDataIssue",
+    "SourceCut",
+    "Status",
+    "StrictManifest",
+    "SwapCover",
+    "TouchMatrix",
+    "TransitionRecord",
+    "VersionInterval",
+    "WriteClass",
+    "__version__",
+    "all_certificates_live",
+    "canonical_json_bytes",
+    "canonical_order",
+    "check_certificate_live",
+    "check_formation",
+    "check_reachability",
+    "check_replay_certificate",
+    "check_risk_claims",
+    "check_risk_ledger",
+    "check_risk_spend_live",
+    "check_source_cut",
+    "check_well_audited",
+    "default_components",
+    "digest_json",
+    "digest_log",
+    "digest_many",
+    "legal_log",
+    "scan_for_sensitive_data",
+    "summarize_risk_ledger",
+    "union_join",
+]

problem_frame_gate/_version.py

@@ -0,0 +1 @@
+__version__ = "0.3.0"

problem_frame_gate/certificates.py

@@ -0,0 +1,116 @@
+"""Time-indexed certificate checks."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+from .fold import FoldState
+from .model import Horizon
+from .result import CheckBuilder, CheckResult
+
+
+@dataclass(frozen=True, slots=True)
+class CertificateFamily:
+    """Finite certificate-family policy."""
+
+    name: str
+    issuers: tuple[str, ...]
+    assumption: str = ""
+
+    def to_json(self) -> dict[str, Any]:
+        return {"name": self.name, "issuers": list(self.issuers), "assumption": self.assumption}
+
+
+def check_certificate_live(
+    state: FoldState, cert_id: str, at_time: int, *, horizon: Horizon | None = None
+) -> CheckResult:
+    """Check that a certificate was issued and not revoked or expired at a time."""
+
+    builder = CheckBuilder(footprint={"IssuerAuthentication", "RevocationOracle", "ClockWatermark"})
+    certs: dict[str, dict[str, Any]] = state.component("certificates")
+    cert = certs.get(cert_id)
+    if cert is None or not cert.get("issued"):
+        builder.error("certificate-missing", "certificate is not issued", location=cert_id)
+        return builder.result()
+
+    issued_at = int(cert.get("issued_at", 0))
+    if issued_at > at_time:
+        builder.error(
+            "certificate-issued-after-use",
+            "certificate issue time is after the checked time",
+            location=cert_id,
+            details={"issued_at": issued_at, "at_time": at_time},
+        )
+
+    revoked_at = cert.get("revoked_at")
+    if revoked_at is not None and int(revoked_at) <= at_time:
+        builder.error(
+            "certificate-revoked",
+            "certificate is revoked at the checked time",
+            location=cert_id,
+            details={"revoked_at": revoked_at, "at_time": at_time},
+        )
+
+    expires_at = cert.get("expires_at")
+    if expires_at is not None and int(expires_at) <= at_time:
+        builder.error(
+            "certificate-expired",
+            "certificate is expired at the checked time",
+            location=cert_id,
+            details={"expires_at": expires_at, "at_time": at_time},
+        )
+
+    family = str(cert.get("family", ""))
+    issuer = str(cert.get("issuer", ""))
+    if horizon is not None and horizon.strict:
+        allowed_issuers = horizon.certificate_families.get(family)
+        if allowed_issuers is None:
+            builder.error("certificate-family", "certificate family is not declared by the manifest", location=cert_id)
+        elif issuer not in allowed_issuers:
+            builder.error(
+                "certificate-issuer",
+                "certificate issuer is not authorized for its family",
+                location=cert_id,
+                details={"family": family, "issuer": issuer, "allowed": list(allowed_issuers)},
+            )
+        if cert.get("family_check") not in {True, "ok", "OK"}:
+            builder.error(
+                "certificate-family-check",
+                "strict certificate must carry an accepted finite family check",
+                location=cert_id,
+            )
+
+    ordered = set(state.ordered_eids)
+    evidence = state.component("evidence")
+    for dep in cert.get("dependencies", ()):
+        dep_id = str(dep)
+        if dep_id not in ordered and dep_id not in evidence and dep_id not in certs:
+            builder.error(
+                "certificate-dependency",
+                "certificate dependency is absent from the source prefix",
+                location=cert_id,
+                details={"dependency": dep_id},
+            )
+    for source_id in cert.get("source_ids", ()):
+        source = evidence.get(str(source_id))
+        if source is None:
+            builder.error("certificate-source", "certificate source object is absent", location=str(source_id))
+        elif int(source.get("committed_at", 0)) > at_time:
+            builder.error(
+                "certificate-source-time",
+                "certificate source object is committed after the checked time",
+                location=str(source_id),
+            )
+    if cert.get("assumption"):
+        builder.add_assumption(str(cert["assumption"]))
+    return builder.result()
+
+
+def all_certificates_live(
+    state: FoldState, cert_ids: tuple[str, ...], at_time: int, *, horizon: Horizon | None = None
+) -> CheckResult:
+    result = CheckResult.success(footprint={"IssuerAuthentication", "RevocationOracle", "ClockWatermark"})
+    for cert_id in cert_ids:
+        result = result.merge(check_certificate_live(state, cert_id, at_time, horizon=horizon))
+    return result

problem_frame_gate/cli.py

@@ -0,0 +1,183 @@
+"""Command line interface."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from typing import Any
+
+from .digest import digest_json
+from .fold import FoldKernel
+from .gate import ExecutorGate, GateRequest
+from .model import Envelope, Horizon
+from .security import scan_for_sensitive_data
+from .verifier import EnvelopeVerifier
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="pfg", description="Finite audit-log checker for AI action gates")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    init_cmd = sub.add_parser("init-manifest", help="print a strict starter manifest")
+    init_cmd.add_argument("--agent-writer", default="agent")
+    init_cmd.add_argument("--executor-writer", default="executor-gate")
+
+    digest_cmd = sub.add_parser("digest", help="print the canonical SHA-256 digest of a JSON file")
+    digest_cmd.add_argument("path")
+
+    scan_cmd = sub.add_parser("scan", help="scan a JSON file for secrets and machine-local paths")
+    scan_cmd.add_argument("path")
+    scan_cmd.add_argument("--allow-local-paths", action="store_true")
+
+    verify_cmd = sub.add_parser("verify-log", help="verify a JSON envelope log")
+    verify_cmd.add_argument("log")
+    verify_cmd.add_argument("--horizon", required=True)
+
+    fold_cmd = sub.add_parser("fold", help="fold a JSON envelope log with default components")
+    fold_cmd.add_argument("log")
+    fold_cmd.add_argument("--horizon", required=True)
+
+    gate_cmd = sub.add_parser("check-gate", help="check a gate request against a JSON envelope log")
+    gate_cmd.add_argument("request")
+    gate_cmd.add_argument("log")
+    gate_cmd.add_argument("--horizon", required=True)
+    gate_cmd.add_argument("--bundle", action="store_true", help="print the accepted gate bundle")
+
+    schema_cmd = sub.add_parser("validate-schema", help="validate a known JSON artifact shape")
+    schema_cmd.add_argument("kind", choices=["horizon", "log", "gate-request"])
+    schema_cmd.add_argument("path")
+
+    explain_cmd = sub.add_parser("explain", help="explain a checker issue code")
+    explain_cmd.add_argument("code")
+
+    args = parser.parse_args(argv)
+    if args.command == "init-manifest":
+        horizon = Horizon.strict_default(agent_writers=(args.agent_writer,), executor_writer=args.executor_writer)
+        print(json.dumps(horizon.to_json(), indent=2, sort_keys=True))
+        return 0
+    if args.command == "digest":
+        print(digest_json(_read_json(args.path)))
+        return 0
+    if args.command == "scan":
+        issues = scan_for_sensitive_data(_read_json(args.path), allow_local_paths=args.allow_local_paths)
+        print(json.dumps([issue.to_json() for issue in issues], indent=2, sort_keys=True))
+        return 1 if issues else 0
+    if args.command == "verify-log":
+        horizon = Horizon.from_mapping(_read_json(args.horizon))
+        envelopes = _read_log(args.log)
+        result = EnvelopeVerifier().verify(horizon, envelopes)
+        print(json.dumps(result.to_json(), indent=2, sort_keys=True))
+        return 0 if result.ok else 1
+    if args.command == "fold":
+        horizon = Horizon.from_mapping(_read_json(args.horizon))
+        envelopes = _read_log(args.log)
+        state = FoldKernel().fold(horizon, envelopes)
+        print(json.dumps(state.to_json(), indent=2, sort_keys=True, default=str))
+        return 0
+    if args.command == "check-gate":
+        horizon = Horizon.from_mapping(_read_json(args.horizon))
+        envelopes = _read_log(args.log)
+        request = _read_gate_request(args.request)
+        gate = ExecutorGate()
+        result = gate.check(horizon, envelopes, request)
+        if args.bundle and result.ok:
+            bundle = gate.create_bundle(horizon, envelopes, request)
+            print(json.dumps(bundle.to_json(), indent=2, sort_keys=True, default=str))
+        else:
+            print(json.dumps(result.to_json(), indent=2, sort_keys=True))
+        return 0 if result.ok else 1
+    if args.command == "validate-schema":
+        errors = _validate_schema(args.kind, _read_json(args.path))
+        print(json.dumps({"ok": not errors, "errors": errors}, indent=2, sort_keys=True))
+        return 0 if not errors else 1
+    if args.command == "explain":
+        print(_explain(args.code))
+        return 0
+    return 2
+
+
+def _read_json(path: str | Path) -> Any:
+    with Path(path).open("r", encoding="utf-8") as handle:
+        return json.load(handle)
+
+
+def _read_log(path: str | Path) -> tuple[Envelope, ...]:
+    data = _read_json(path)
+    if not isinstance(data, list):
+        raise ValueError("log JSON must be an array of envelopes")
+    return tuple(Envelope.from_mapping(item) for item in data)
+
+
+def _read_gate_request(path: str | Path) -> GateRequest:
+    data = _read_json(path)
+    if not isinstance(data, dict):
+        raise ValueError("gate request JSON must be an object")
+    return GateRequest(**data)
+
+
+def _validate_schema(kind: str, data: Any) -> list[str]:
+    errors: list[str] = []
+    if kind == "horizon":
+        if not isinstance(data, dict):
+            return ["horizon must be a JSON object"]
+        required_horizon: tuple[str, ...] = (
+            "capacities",
+            "writer_authority",
+            "version_intervals",
+            "protected_constructors",
+            "certificate_families",
+            "risk_modes",
+        )
+        errors.extend(f"missing {field}" for field in required_horizon if field not in data)
+    elif kind == "log":
+        if not isinstance(data, list):
+            return ["log must be a JSON array"]
+        for index, item in enumerate(data):
+            if not isinstance(item, dict):
+                errors.append(f"log[{index}] must be an object")
+                continue
+            if "payload" not in item or not isinstance(item["payload"], dict) or "kind" not in item["payload"]:
+                errors.append(f"log[{index}] must contain payload.kind")
+    elif kind == "gate-request":
+        if not isinstance(data, dict):
+            return ["gate request must be a JSON object"]
+        required_gate: tuple[str, ...] = (
+            "gate_id",
+            "bundle_id",
+            "frame_id",
+            "action",
+            "outbox_id",
+            "capability_id",
+            "lease_id",
+            "risk_id",
+            "hypothesis_id",
+            "risk_mode",
+            "risk_cert_id",
+            "source_time",
+            "commit_time",
+        )
+        errors.extend(f"missing {field}" for field in required_gate if field not in data)
+    return errors
+
+
+def _explain(code: str) -> str:
+    explanations = {
+        "incomplete-manifest": (
+            "Strict manifests must declare capacities, writer authority, versions, protected constructors, "
+            "certificate families, and risk modes."
+        ),
+        "protected-writer-authority": "A protected action constructor was written by a non-reserved writer.",
+        "gate-bundle-missing-group": "Gate rows must be committed as one atomic group.",
+        "gate-bundle-coherence": "The five gate rows do not bind the same GateCheck tuple.",
+        "certificate-family-check": "A strict certificate must carry an accepted finite family-specific check.",
+        "risk-alpha-bound": "Installed finite risk claims exceed the declared risk budget.",
+        "patch-affected-completeness": "A touched invariant was not listed for recheck.",
+        "join-ancestor-missing": "Join proposals must cite a common ancestor.",
+    }
+    return explanations.get(code, "No detailed explanation is registered for this issue code.")
+
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit(main())

problem_frame_gate/digest.py

@@ -0,0 +1,69 @@
+"""Deterministic JSON encoding and digest helpers.
+
+The public wire format is deliberately plain JSON.  Other implementations only
+need sorted-object canonicalization, UTF-8, and SHA-256 to interoperate.
+"""
+
+from __future__ import annotations
+
+import dataclasses
+import hashlib
+import json
+import math
+from collections.abc import Iterable, Mapping
+from enum import Enum
+from fractions import Fraction
+from typing import Any
+
+
+def normalize_json(value: Any) -> Any:
+    """Convert common Python objects into canonical JSON-compatible values."""
+
+    if hasattr(value, "to_json") and callable(value.to_json):
+        return normalize_json(value.to_json())
+    if dataclasses.is_dataclass(value) and not isinstance(value, type):
+        return normalize_json(dataclasses.asdict(value))
+    if isinstance(value, Enum):
+        return value.value
+    if isinstance(value, Fraction):
+        return f"{value.numerator}/{value.denominator}"
+    if isinstance(value, Mapping):
+        return {str(k): normalize_json(v) for k, v in sorted(value.items(), key=lambda item: str(item[0]))}
+    if isinstance(value, tuple | list):
+        return [normalize_json(v) for v in value]
+    if isinstance(value, set | frozenset):
+        return sorted((normalize_json(v) for v in value), key=lambda item: json.dumps(item, sort_keys=True))
+    if isinstance(value, bytes):
+        raise TypeError("bytes are not allowed in canonical JSON; pass an encoded string")
+    if isinstance(value, float) and not math.isfinite(value):
+        raise ValueError("non-finite floats are not allowed in canonical JSON")
+    if value is None or isinstance(value, str | int | float | bool):
+        return value
+    raise TypeError(f"unsupported canonical JSON value: {type(value).__name__}")
+
+
+def canonical_json_bytes(value: Any) -> bytes:
+    """Return RFC-8259-compatible canonical bytes for a JSON value."""
+
+    normalized = normalize_json(value)
+    return json.dumps(
+        normalized,
+        sort_keys=True,
+        separators=(",", ":"),
+        ensure_ascii=False,
+        allow_nan=False,
+    ).encode("utf-8")
+
+
+def digest_json(value: Any, *, algorithm: str = "sha256") -> str:
+    """Digest a JSON-like value and prefix the algorithm name."""
+
+    if algorithm != "sha256":
+        raise ValueError("only sha256 is currently supported")
+    return f"sha256:{hashlib.sha256(canonical_json_bytes(value)).hexdigest()}"
+
+
+def digest_many(values: Iterable[Any], *, algorithm: str = "sha256") -> str:
+    """Digest a finite sequence as one canonical JSON array."""
+
+    return digest_json(list(values), algorithm=algorithm)

problem_frame_gate/errors.py

@@ -0,0 +1,17 @@
+"""Package exceptions."""
+
+
+class ProblemFrameGateError(Exception):
+    """Base class for package-specific errors."""
+
+
+class SecurityError(ProblemFrameGateError):
+    """Raised when a payload contains data that should not enter an audit log."""
+
+
+class LogVerificationError(ProblemFrameGateError):
+    """Raised when an envelope log is not legal for a horizon."""
+
+
+class FoldError(ProblemFrameGateError):
+    """Raised when a deterministic component replay rejects an envelope."""