@riddledc/riddle-proof 0.8.83 → 0.8.85

package/README.md

@@ -92,8 +92,9 @@ produces no certificate:
 ```ts
 import {
   createRiddleProofSemanticCertificate,
-  composeRiddleProofSemanticCertificates,
-  matchRiddleProofSemanticCertificate,
+  createRiddleProofSemanticAtomicCertificateClosure,
+  composeRiddleProofSemanticCertificateClosures,
+  matchRiddleProofSemanticCertificateClosure,
 } from "@riddledc/riddle-proof/semantic-certificate";
 
 const quiet = createRiddleProofSemanticCertificate({
@@ -120,7 +121,16 @@ const quiet = createRiddleProofSemanticCertificate({
 
 if (!quiet.ok) throw new Error(quiet.error.message);
 
-const behavior = composeRiddleProofSemanticCertificates({
+const quietClosure = createRiddleProofSemanticAtomicCertificateClosure({
+  certificate: quiet.certificate,
+});
+const laterClosure = createRiddleProofSemanticAtomicCertificateClosure({
+  certificate: later.certificate,
+});
+if (!quietClosure.ok) throw new Error(quietClosure.error.message);
+if (!laterClosure.ok) throw new Error(laterClosure.error.message);
+
+const behavior = composeRiddleProofSemanticCertificateClosures({
   rule: {
     rule_id: "tidepool.quiet-then-collision",
     rule_version: "1",
@@ -128,39 +138,46 @@ const behavior = composeRiddleProofSemanticCertificates({
     premises: [quiet.certificate.claim, later.certificate.claim],
     conclusion: observedWaveCollisionBehaviorClaim,
   },
-  certificates: [quiet.certificate, later.certificate],
+  closures: [quietClosure.closure, laterClosure.closure],
 });
+
+if (!behavior.ok) throw new Error(behavior.error.message);
 ```
 
-A later agent can consume one exact certificate without reopening its receipt
-files. The expected content ID must arrive through the consumer's trusted
-handoff or configuration; copying it from the same untrusted certificate would
-not add trust:
+`riddle-proof.semantic-certificate-closure.v0` carries the root and every
+transitively referenced full certificate body. Closure composition validates
+each input, deduplicates shared descendants, creates the higher root, and then
+validates the complete result. Arbitrary transport order is accepted, but a
+successful validator returns one deterministic dependency-first, root-last
+order. A closure is bounded by the exported
+`RIDDLE_PROOF_SEMANTIC_CERTIFICATE_CLOSURE_MAX_CERTIFICATES` value (currently
+4,096 bodies). Missing bodies, duplicate IDs, snapshot/body disagreements,
+cycles, and unreachable extras fail closed.
+
+A later agent can validate the complete derivation without reopening receipt
+files. It still needs the expected root ID, scope, claim, and assurance from an
+independent trusted handoff or configuration; copying expectations from the
+same untrusted closure would not add trust:
 
 ```ts
-const match = matchRiddleProofSemanticCertificate({
-  certificate: JSON.parse(serializedCertificate),
-  expected_certificate_id: trustedHandoffCertificateId,
+const match = matchRiddleProofSemanticCertificateClosure({
+  closure: JSON.parse(serializedClosure),
+  expected_root_certificate_id: trustedHandoffCertificateId,
   expected_scope: scope,
   expected_claim: observedWaveCollisionBehaviorClaim,
   expected_assurance: "declared_runtime_rule",
 });
 
 if (!match.ok) throw new Error(match.error.message);
-// match.certificate is the exact scoped certificate this consumer requested.
+// match.closure contains every validated body; match.root_certificate is exact.
 ```
 
-Matching first reparses the envelope and its content ID, then compares the
-trusted expected ID, all five scope fields, claim ID/version/parameters, and
-top-level assurance. It does no filesystem or network I/O, and a successful
-match does not authenticate the issuer or the referenced evidence.
-
-This is an exact root-certificate handoff, not independent proof-tree
-reconstruction. A composite certificate retains compact immediate-premise
-snapshots, not the full transitive certificate bodies. A consumer that does not
-already trust the expected root ID needs a complete certificate closure plus a
-contract/rule identity policy before it can independently inspect the whole
-derivation.
+Closure matching reparses and re-hashes every body, resolves every immediate
+premise snapshot to its exact full body, rejects bodies not reachable from the
+declared root, and only then compares the trusted root ID, all five scope
+fields, claim ID/version/parameters, and assurance. The original
+`matchRiddleProofSemanticCertificate` remains available for intentionally
+bounded, root-only handoffs.
 
 Composition requires the declared premise claims and exact scope equality. It
 copies compact premise snapshots into the derivation and sets the higher
@@ -170,13 +187,214 @@ declared runtime rule. The parser rechecks those relationships and the
 content-addressed certificate ID. The serialized v0 objects use exact keys and
 reject any `status`, verdict, merge, sync, ready-to-ship, shipping-authority,
 or free-form metadata field: semantic composition is deliberately separate
-from release policy.
+from release policy. Direct JavaScript inputs are treated as JSON data: object
+fields must be own enumerable data properties and structural arrays must be
+dense. Accessors, `toJSON` hooks, inherited fields, symbols, and hidden fields
+are rejected instead of being executed or silently discarded.
+
+The boundary remains explicit. Complete closure validation establishes
+structural and semantic linkage, not the truth of the leaves. Derivations say
+`runtime_contract_accepted` or `declared_runtime_rule`; JavaScript predicates
+and named rules are inspectable runtime models, not Lean proof terms.
+Certificate hashes are content identities, not signatures. Validation performs
+no filesystem or network I/O, does not authenticate an issuer, and does not
+authenticate or recompute browser, Git, CDN, screenshot, receipt, or artifact
+truth. Contract/rule IDs remain declared data, so consumers that care which
+models were used should apply their own allowlist or authenticated issuer
+policy in addition to anchoring the expected root ID.
+
+### Experimental Grounded Evidence
+
+The grounded-evidence layer extends Semantic certificates with a replayable
+path back to the exact captured bytes:
+
+1. `createRiddleProofSignedCaptureBundle` canonicalizes an artifact manifest,
+   binds it to a complete Semantic scope, a 32-byte challenge nonce, capture
+   time, collector, sensor, and verifier identity, and signs the protected
+   header plus statement with Ed25519.
+2. `verifyRiddleProofSignedCaptureBundle` independently checks the policy,
+   freshness window, trusted public-key fingerprint, signature, manifest, and
+   every inline artifact's length and SHA-256 digest. The callback registry path
+   runs a verifier twice on fresh byte copies and accepts only one identical
+   canonical JSON observation; the callback-free declarative path runs the
+   package's fixed, data-only JSON interpreter.
+3. `createRiddleProofGroundedSemanticCertificate` applies the registered
+   contract to that verifier-derived observation. It emits a content-addressed
+   grounded receipt and a contract-derived Semantic certificate whose evidence
+   begins with that exact receipt and then names every captured artifact.
+4. Atomic grounded closures can be composed. Validation or matching structurally
+   validates the complete Semantic closure, requires exactly one grounding for
+   every contract leaf and none for composition nodes, then replays every leaf
+   against independently supplied signer, verifier, contract, nonce, scope, and
+   time policy. Shared leaves are deduplicated, and a composition certificate
+   cannot predate any direct premise.
+
+The public surface is available from both the package root and
+`@riddledc/riddle-proof/grounded-evidence`. This example issues one grounded
+leaf, wraps it as a closure, and replays the complete handoff. The omitted
+values (`scope`, key material, artifacts, and identity objects) come from the
+collector and trust setup. In particular, policy and replay expectations must
+be independently configured rather than copied out of an untrusted bundle:
+
+```ts
+import {
+  type RiddleProofGroundedCaptureVerificationPolicy,
+  type RiddleProofGroundedReplayConfiguration,
+  createRiddleProofGroundedDeclarativeJsonContract,
+  createRiddleProofGroundedDeclarativeJsonVerifier,
+  createRiddleProofGroundedSemanticAtomicCertificateClosure,
+  createRiddleProofGroundedSemanticCertificate,
+  createRiddleProofSignedCaptureBundle,
+  matchRiddleProofGroundedSemanticCertificateClosure,
+} from "@riddledc/riddle-proof/grounded-evidence";
+
+const declarativeVerifier = createRiddleProofGroundedDeclarativeJsonVerifier({
+  verifier_id: "riddle-proof.profile-evidence-json",
+  verifier_version: "1",
+  program: {
+    artifact: {
+      artifact_id: "profile-evidence.json",
+      role: "profile_evidence",
+      media_type: "application/json",
+    },
+    pointer: "", // RFC 6901: select the parsed document root
+  },
+});
+if (!declarativeVerifier.ok) throw new Error(declarativeVerifier.error.message);
+
+const declarativeContract = createRiddleProofGroundedDeclarativeJsonContract({
+  contract_id: "riddle-proof.profile-passed",
+  contract_version: "1",
+  label: "The captured profile passed",
+  claim: passedProfileClaim,
+  program: {
+    all: [
+      { op: "type_is", source: "observation", pointer: "", type: "object" },
+      { op: "equals", source: "observation", pointer: "/status", value: "passed" },
+      { op: "equals", source: "scope", pointer: "/revision", value: scope.revision },
+    ],
+  },
+});
+if (!declarativeContract.ok) throw new Error(declarativeContract.error.message);
+
+const createdBundle = createRiddleProofSignedCaptureBundle({
+  scope,
+  nonce, // canonical base64url encoding of an independently issued 32-byte value
+  captured_at: "2026-07-19T14:30:00.000Z",
+  collector,
+  sensor,
+  verifier: declarativeVerifier.verifier_ref,
+  artifacts,
+  signing_key: {
+    key_id: "local-playwright-key",
+    private_key_pkcs8_base64: privateKeyPkcs8Base64,
+  },
+});
+if (!createdBundle.ok) throw new Error(createdBundle.error.message);
+
+const policy: RiddleProofGroundedCaptureVerificationPolicy = {
+  expected_scope: scope,
+  expected_nonce: nonce,
+  expected_collector: collector,
+  expected_sensor: sensor,
+  expected_verifier: declarativeVerifier.verifier_ref,
+  expected_signer: {
+    key_id: "local-playwright-key",
+    public_key_spki_sha256: trustedPublicKeySpkiSha256,
+  },
+  verification_time: "2026-07-19T14:30:01.000Z",
+  max_capture_age_ms: 60_000,
+  max_future_skew_ms: 1_000,
+  required_artifact_roles: ["profile_evidence"],
+};
+
+const configuration: RiddleProofGroundedReplayConfiguration = {
+  policy,
+  trusted_signers: [{
+    key_id: "local-playwright-key",
+    public_key_spki_base64: trustedPublicKeySpkiBase64,
+  }],
+  verifier_registry: [declarativeVerifier.registration],
+  contract_registry: [declarativeContract.registration],
+  expected_contract: declarativeContract.contract_ref,
+};
+
+const issued = createRiddleProofGroundedSemanticCertificate({
+  bundle: createdBundle.bundle,
+  ...configuration,
+  // Grounded leaf chronology is the independent verification time, not caller drift.
+  issued_at: policy.verification_time,
+});
+if (!issued.ok) throw new Error(issued.error.message);
+
+const atomic = createRiddleProofGroundedSemanticAtomicCertificateClosure({
+  certificate: issued.certificate,
+  grounding: issued.grounding,
+  configuration,
+});
+if (!atomic.ok) throw new Error(atomic.error.message);
+
+const checked = matchRiddleProofGroundedSemanticCertificateClosure({
+  grounded_closure: JSON.parse(JSON.stringify(atomic.grounded_closure)),
+  replay_contexts: [{
+    certificate_id: issued.certificate.certificate_id,
+    ...configuration,
+  }],
+  expected_root_certificate_id: trustedHandoffCertificateId,
+  expected_scope: scope,
+  expected_claim: passedProfileClaim,
+  expected_assurance: "runtime_contract_accepted",
+});
+if (!checked.ok) throw new Error(checked.error.message);
+```
 
-The boundary remains explicit. Derivations say `runtime_contract_accepted` or
-`declared_runtime_rule`; JavaScript predicates and named rules are inspectable
-runtime models, not Lean proof terms. Certificate hashes are content identities,
-not signatures, and receipt IDs and digests do not authenticate browser, Git,
-CDN, screenshot, or outside-world truth.
+Use `composeRiddleProofGroundedSemanticCertificateClosures` for higher claims.
+It takes a normal Semantic `rule`, one grounded closure per premise,
+`replay_contexts` for every distinct leaf, and an `issued_at` no earlier than
+the latest input root. `validateRiddleProofGroundedSemanticCertificateClosure`
+performs the same full leaf replay without applying trusted root expectations;
+`matchRiddleProofGroundedSemanticCertificateClosure` adds those expectations.
+
+The declarative builders above are the narrower primary path. They canonicalize
+the data-only program, domain-separate and SHA-256 hash the complete definition,
+set `trust_basis.kind` to `builtin_declarative_json`, and return a registration
+with no callback. During every issuance and replay, Riddle Proof recomputes that
+digest and uses only its fixed v0 interpreter. The verifier selects one exact
+`application/json` artifact by ID, role, and media type, parses strict UTF-8 JSON,
+and projects an RFC 6901 JSON Pointer. The contract supports a bounded `all`
+list of `exists`, exact `equals`, and `type_is` assertions over the observation
+or the five-field scope.
+
+The custom callback trust boundary remains deliberately visible. A verifier or
+contract reference with `trust_basis: { kind: "external_registry" }` means an
+independent registry selected that callback and vouches for its
+`implementation_digest`. Riddle Proof does not derive callback identity from
+`Function#toString` or prove that arbitrary JavaScript bytes correspond to the
+declared digest. Registry callbacks are invoked from snapshots without a
+receiver and with cloned inputs, but the registry remains part of the trusted
+computing base.
+
+Parsing is fail-closed for extra/hidden/accessor fields, sparse structural
+arrays, noncanonical base64, noncanonical timestamps, and noncanonical DER.
+The exported limits bound a capture to 64 artifacts, 16 MiB per artifact,
+64 MiB total decoded artifact bytes, and a 1 MiB canonical observation. A
+grounded closure additionally has 256 MiB aggregate replay-work and 64 MiB
+canonical metadata limits, plus aggregate replay-configuration, registry, and
+trusted-key limits. Declarative definitions are limited to 64 KiB, 64 contract
+assertions, and bounded JSON Pointer sizes and depth. These limits are
+denial-of-service boundaries; they do not make the evidence empirically true.
+
+The remaining outside-world boundary is also explicit. The signature proves
+that the trusted key signed this exact capture statement, and replay proves that
+the registered verifier and contract deterministically produce this exact leaf
+from the included bytes. It does not prove that the key was well kept, the
+collector's clock or nonce source was honest, the browser rendered the claimed
+URL faithfully, the sensor was well calibrated, or the included screenshot
+matches photons a human would have seen. The Playwright runner reduces that gap
+by signing the exact files it persisted and recording browser provenance, but
+its signer, browser process, machine, and capture policy still require trust.
+Lean proves the framework invariants that connect these stages; it does not
+turn those empirical assumptions into theorems.
 
 Persist a deploy result and its immutable receipt for later Change Proof input:
 

package/capabilities.json

@@ -0,0 +1,17 @@
+{
+  "version": "riddle-proof.package-capabilities.v1",
+  "package": "@riddledc/riddle-proof",
+  "capabilities": {
+    "network": true,
+    "filesystem": true,
+    "browser": true,
+    "subprocess": true,
+    "hosted_riddle": true,
+    "cryptography": true,
+    "ambient_clock": true
+  },
+  "notes": [
+    "This pre-1.0 package is the compatibility facade and intentionally exposes the union of core, local engine, and hosted-client capabilities.",
+    "Security-sensitive local consumers should install @riddledc/riddle-proof-core and a specific adapter instead."
+  ]
+}

package/dist/advanced/engine-harness.js

@@ -2,10 +2,10 @@ import {
   createDisabledRiddleProofAgentAdapter,
   readRiddleProofRunStatus,
   runRiddleProofEngineHarness
-} from "../chunk-WLUMLHII.js";
+} from "../chunk-BID7CKMM.js";
+import "../chunk-EKZXU6MU.js";
 import "../chunk-CGJX7LJO.js";
 import "../chunk-UTCL7FEZ.js";
-import "../chunk-EKZXU6MU.js";
 import "../chunk-DYE3URAQ.js";
 import "../chunk-NKHZASNQ.js";
 import "../chunk-ZAR7BWMN.js";

package/dist/advanced/index.d.cts

@@ -1,6 +1,6 @@
 export { b as runner } from '../runner-4LJ5z0D-.cjs';
 export { l as engineHarness } from '../engine-harness-LBfqbFSe.cjs';
 export { p as proofRunCore } from '../proof-run-core-7Dqm7RKM.cjs';
-export { p as proofRunEngine } from '../proof-run-engine-Baiv6l3A.cjs';
+export { p as proofRunEngine } from '../proof-run-engine-DpChFR5H.cjs';
 import '../types.cjs';
 import '../public-state.cjs';

package/dist/advanced/index.d.ts

@@ -1,6 +1,6 @@
 export { b as runner } from '../runner-BdQpOkZD.js';
 export { l as engineHarness } from '../engine-harness-CMACHP6A.js';
 export { p as proofRunCore } from '../proof-run-core-7Dqm7RKM.js';
-export { p as proofRunEngine } from '../proof-run-engine-MiKZt9oY.js';
+export { p as proofRunEngine } from '../proof-run-engine-BqRoA3Do.js';
 import '../types.js';
 import '../public-state.js';

package/dist/advanced/index.js

@@ -3,15 +3,15 @@ import {
 } from "../chunk-VYJD6XYF.js";
 import {
   runner_exports
-} from "../chunk-YH7ADFY4.js";
+} from "../chunk-IVSP24XI.js";
 import {
   engine_harness_exports
-} from "../chunk-WLUMLHII.js";
-import "../chunk-CGJX7LJO.js";
-import "../chunk-UTCL7FEZ.js";
+} from "../chunk-BID7CKMM.js";
 import {
   proof_run_core_exports
 } from "../chunk-EKZXU6MU.js";
+import "../chunk-CGJX7LJO.js";
+import "../chunk-UTCL7FEZ.js";
 import "../chunk-DYE3URAQ.js";
 import "../chunk-NKHZASNQ.js";
 import "../chunk-ZAR7BWMN.js";

package/dist/advanced/proof-run-engine.d.cts

@@ -1,2 +1,2 @@
-export { R as RiddleProofEngine, c as createRiddleProofEngine, e as executeWorkflow } from '../proof-run-engine-Baiv6l3A.cjs';
+export { R as RiddleProofEngine, c as createRiddleProofEngine, e as executeWorkflow } from '../proof-run-engine-DpChFR5H.cjs';
 import '../proof-run-core-7Dqm7RKM.cjs';

package/dist/advanced/proof-run-engine.d.ts

@@ -1,2 +1,2 @@
-export { R as RiddleProofEngine, c as createRiddleProofEngine, e as executeWorkflow } from '../proof-run-engine-MiKZt9oY.js';
+export { R as RiddleProofEngine, c as createRiddleProofEngine, e as executeWorkflow } from '../proof-run-engine-BqRoA3Do.js';
 import '../proof-run-core-7Dqm7RKM.js';

package/dist/advanced/runner.js

@@ -1,9 +1,9 @@
 import {
   runRiddleProof
-} from "../chunk-YH7ADFY4.js";
+} from "../chunk-IVSP24XI.js";
+import "../chunk-EKZXU6MU.js";
 import "../chunk-CGJX7LJO.js";
 import "../chunk-UTCL7FEZ.js";
-import "../chunk-EKZXU6MU.js";
 import "../chunk-DYE3URAQ.js";
 import "../chunk-NKHZASNQ.js";
 import "../chunk-ZAR7BWMN.js";