@riddledc/riddle-proof 0.8.82 → 0.8.84

package/dist/semantic-certificate.cjs

@@ -20,15 +20,24 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/semantic-certificate.ts
 var semantic_certificate_exports = {};
 __export(semantic_certificate_exports, {
+  RIDDLE_PROOF_SEMANTIC_CERTIFICATE_CLOSURE_MAX_CERTIFICATES: () => RIDDLE_PROOF_SEMANTIC_CERTIFICATE_CLOSURE_MAX_CERTIFICATES,
+  RIDDLE_PROOF_SEMANTIC_CERTIFICATE_CLOSURE_VERSION: () => RIDDLE_PROOF_SEMANTIC_CERTIFICATE_CLOSURE_VERSION,
   RIDDLE_PROOF_SEMANTIC_CERTIFICATE_VERSION: () => RIDDLE_PROOF_SEMANTIC_CERTIFICATE_VERSION,
+  composeRiddleProofSemanticCertificateClosures: () => composeRiddleProofSemanticCertificateClosures,
   composeRiddleProofSemanticCertificates: () => composeRiddleProofSemanticCertificates,
+  createRiddleProofSemanticAtomicCertificateClosure: () => createRiddleProofSemanticAtomicCertificateClosure,
   createRiddleProofSemanticCertificate: () => createRiddleProofSemanticCertificate,
+  matchRiddleProofSemanticCertificate: () => matchRiddleProofSemanticCertificate,
+  matchRiddleProofSemanticCertificateClosure: () => matchRiddleProofSemanticCertificateClosure,
   parseRiddleProofSemanticCertificate: () => parseRiddleProofSemanticCertificate,
-  riddleProofSemanticScopesEqual: () => riddleProofSemanticScopesEqual
+  riddleProofSemanticScopesEqual: () => riddleProofSemanticScopesEqual,
+  validateRiddleProofSemanticCertificateClosure: () => validateRiddleProofSemanticCertificateClosure
 });
 module.exports = __toCommonJS(semantic_certificate_exports);
 var import_node_crypto = require("crypto");
 var RIDDLE_PROOF_SEMANTIC_CERTIFICATE_VERSION = "riddle-proof.semantic-certificate.v0";
+var RIDDLE_PROOF_SEMANTIC_CERTIFICATE_CLOSURE_VERSION = "riddle-proof.semantic-certificate-closure.v0";
+var RIDDLE_PROOF_SEMANTIC_CERTIFICATE_CLOSURE_MAX_CERTIFICATES = 4096;
 var SCOPE_FIELDS = [
   "repository",
   "revision",
@@ -60,55 +69,146 @@ var CERTIFICATE_FIELDS = /* @__PURE__ */ new Set([
   "issued_at"
 ]);
 function isRecord(value) {
-  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}
+function safeErrorMessage(error) {
+  try {
+    if (error instanceof Error) return String(error.message);
+  } catch {
+  }
+  try {
+    return String(error);
+  } catch {
+    return "unprintable thrown value";
+  }
 }
 function assertOnlyKeys(record, allowed, context) {
   const allowedSet = new Set(allowed);
-  for (const key of Object.keys(record)) {
+  for (const key of Reflect.ownKeys(record)) {
+    if (typeof key !== "string") {
+      throw new Error(`${context} contains an unsupported symbol field.`);
+    }
     if (!allowedSet.has(key)) {
       throw new Error(`${context} contains unsupported field ${key}.`);
     }
+    const descriptor = Object.getOwnPropertyDescriptor(record, key);
+    if (!descriptor || descriptor.enumerable !== true || descriptor.get !== void 0 || descriptor.set !== void 0) {
+      throw new Error(`${context}.${key} must be an enumerable data field.`);
+    }
   }
 }
+function readDenseDataArray(value, context, maximumLength) {
+  if (!Array.isArray(value) || Object.getPrototypeOf(value) !== Array.prototype) {
+    throw new Error(`${context} must be a plain array.`);
+  }
+  const lengthDescriptor = Object.getOwnPropertyDescriptor(value, "length");
+  if (!lengthDescriptor || typeof lengthDescriptor.value !== "number" || !Number.isSafeInteger(lengthDescriptor.value) || lengthDescriptor.value < 0) {
+    throw new Error(`${context}.length must be an own data field.`);
+  }
+  const length = lengthDescriptor.value;
+  if (maximumLength !== void 0 && length > maximumLength) {
+    throw new Error(`${context} exceeds ${maximumLength} entries.`);
+  }
+  const indexedElements = [];
+  let elementCount = 0;
+  for (const key of Reflect.ownKeys(value)) {
+    if (key === "length") continue;
+    if (typeof key !== "string") {
+      throw new Error(`${context} contains an unsupported symbol field.`);
+    }
+    const index = Number(key);
+    if (!Number.isInteger(index) || index < 0 || index >= length || index >= 2 ** 32 - 1 || String(index) !== key) {
+      throw new Error(`${context} contains unsupported array field ${key}.`);
+    }
+    const descriptor = Object.getOwnPropertyDescriptor(value, key);
+    if (!descriptor || descriptor.enumerable !== true || descriptor.get !== void 0 || descriptor.set !== void 0) {
+      throw new Error(`${context}[${key}] must be an enumerable data field.`);
+    }
+    indexedElements.push([index, descriptor.value]);
+    elementCount += 1;
+  }
+  if (elementCount !== length) {
+    throw new Error(`${context} must not contain sparse or inherited entries.`);
+  }
+  indexedElements.sort(([left], [right]) => left - right);
+  return indexedElements.map(([, entry]) => entry);
+}
+function requiredField(record, key, context) {
+  const descriptor = Object.getOwnPropertyDescriptor(record, key);
+  if (!descriptor) {
+    throw new Error(`${context}.${key} is required.`);
+  }
+  if (descriptor.enumerable !== true || descriptor.get !== void 0 || descriptor.set !== void 0) {
+    throw new Error(`${context}.${key} must be an enumerable data field.`);
+  }
+  return descriptor.value;
+}
+function optionalField(record, key) {
+  const descriptor = Object.getOwnPropertyDescriptor(record, key);
+  if (!descriptor) return void 0;
+  if (descriptor.enumerable !== true || descriptor.get !== void 0 || descriptor.set !== void 0) {
+    throw new Error(`${key} must be an enumerable data field.`);
+  }
+  return descriptor.value;
+}
 function requiredString(record, key, context) {
-  const value = record[key];
+  const value = requiredField(record, key, context);
   if (typeof value !== "string" || !value.trim()) {
     throw new Error(`${context}.${key} must be a non-empty string.`);
   }
   return value.trim();
 }
 function optionalString(record, key, context) {
-  if (record[key] === void 0) return void 0;
+  if (optionalField(record, key) === void 0) return void 0;
   return requiredString(record, key, context);
 }
-function isJsonValue(value, ancestors = /* @__PURE__ */ new Set()) {
+function cloneJsonValue(value, context, ancestors = /* @__PURE__ */ new Set()) {
   if (value === null || typeof value === "string" || typeof value === "boolean") {
-    return true;
+    return value;
+  }
+  if (typeof value === "number") {
+    if (!Number.isFinite(value)) throw new Error(`${context} must contain only finite numbers.`);
+    return value;
   }
-  if (typeof value === "number") return Number.isFinite(value);
   if (Array.isArray(value)) {
-    if (ancestors.has(value)) return false;
+    const elements = readDenseDataArray(value, context);
+    if (ancestors.has(value)) throw new Error(`${context} must not be cyclic.`);
     ancestors.add(value);
-    const valid2 = value.every((entry) => isJsonValue(entry, ancestors));
+    const cloned2 = elements.map((entry, index) => cloneJsonValue(entry, `${context}[${index}]`, ancestors));
     ancestors.delete(value);
-    return valid2;
+    return cloned2;
   }
-  if (!isRecord(value)) return false;
-  const prototype = Object.getPrototypeOf(value);
-  if (prototype !== Object.prototype && prototype !== null) return false;
-  if (ancestors.has(value)) return false;
+  if (!isRecord(value)) throw new Error(`${context} must contain only JSON values.`);
+  if (ancestors.has(value)) throw new Error(`${context} must not be cyclic.`);
   ancestors.add(value);
-  const valid = Object.values(value).every((entry) => isJsonValue(entry, ancestors));
+  const cloned = {};
+  for (const key of Reflect.ownKeys(value)) {
+    if (typeof key !== "string") {
+      throw new Error(`${context} contains an unsupported symbol field.`);
+    }
+    const descriptor = Object.getOwnPropertyDescriptor(value, key);
+    if (!descriptor || descriptor.enumerable !== true || descriptor.get !== void 0 || descriptor.set !== void 0) {
+      throw new Error(`${context}.${key} must be an enumerable data field.`);
+    }
+    Object.defineProperty(cloned, key, {
+      value: cloneJsonValue(descriptor.value, `${context}.${key}`, ancestors),
+      enumerable: true,
+      configurable: true,
+      writable: true
+    });
+  }
   ancestors.delete(value);
-  return valid;
+  return cloned;
 }
 function parseJsonObject(value, context) {
   if (value === void 0) return void 0;
-  if (!isRecord(value) || !isJsonValue(value)) {
+  if (!isRecord(value)) {
     throw new Error(`${context} must be a JSON object.`);
   }
-  const cloned = JSON.parse(JSON.stringify(value));
-  if (!isRecord(cloned) || !isJsonValue(cloned)) {
+  const cloned = cloneJsonValue(value, context);
+  if (!isRecord(cloned)) {
     throw new Error(`${context} must remain a JSON object when serialized.`);
   }
   return cloned;
@@ -133,7 +233,7 @@ function parseScope(value, context) {
 function parseClaimRef(value, context, allowedExtras = []) {
   if (!isRecord(value)) throw new Error(`${context} must be an object.`);
   assertOnlyKeys(value, ["claim_id", "claim_version", "parameters", ...allowedExtras], context);
-  const parameters = parseJsonObject(value.parameters, `${context}.parameters`);
+  const parameters = parseJsonObject(optionalField(value, "parameters"), `${context}.parameters`);
   return {
     claim_id: requiredString(value, "claim_id", context),
     claim_version: requiredString(value, "claim_version", context),
@@ -169,10 +269,11 @@ function parseEvidenceRef(value, context) {
   };
 }
 function parseEvidenceBundle(value, context) {
-  if (!Array.isArray(value) || value.length === 0) {
+  const entries = readDenseDataArray(value, context);
+  if (entries.length === 0) {
     throw new Error(`${context} must contain at least one evidence reference.`);
   }
-  return value.map((entry, index) => parseEvidenceRef(entry, `${context}[${index}]`));
+  return entries.map((entry, index) => parseEvidenceRef(entry, `${context}[${index}]`));
 }
 function parseContractRef(value, context) {
   if (!isRecord(value)) throw new Error(`${context} must be an object.`);
@@ -189,30 +290,32 @@ function parseContract(value, context, allowRuntimePredicate = false) {
     ["contract_id", "contract_version", "label", "claim", ...allowRuntimePredicate ? ["accepts"] : []],
     context
   );
-  if (allowRuntimePredicate && typeof value.accepts !== "function") {
+  if (allowRuntimePredicate && typeof requiredField(value, "accepts", context) !== "function") {
     throw new Error(`${context}.accepts must be a function.`);
   }
   return {
     ...parseContractRef(value, context),
-    claim: parseClaim(value.claim, `${context}.claim`)
+    claim: parseClaim(requiredField(value, "claim", context), `${context}.claim`)
   };
 }
 function parseRule(value, context, allowFullPremises = false) {
   if (!isRecord(value)) throw new Error(`${context} must be an object.`);
   assertOnlyKeys(value, ["rule_id", "rule_version", "label", "premises", "conclusion"], context);
-  if (!Array.isArray(value.premises) || value.premises.length === 0) {
+  const premises = requiredField(value, "premises", context);
+  const premiseValues = readDenseDataArray(premises, `${context}.premises`);
+  if (premiseValues.length === 0) {
     throw new Error(`${context}.premises must contain at least one claim reference.`);
   }
   return {
     rule_id: requiredString(value, "rule_id", context),
     rule_version: requiredString(value, "rule_version", context),
     label: requiredString(value, "label", context),
-    premises: value.premises.map((premise, index) => parseClaimRef(
+    premises: premiseValues.map((premise, index) => parseClaimRef(
       premise,
       `${context}.premises[${index}]`,
       allowFullPremises ? ["label"] : []
     )),
-    conclusion: parseClaim(value.conclusion, `${context}.conclusion`)
+    conclusion: parseClaim(requiredField(value, "conclusion", context), `${context}.conclusion`)
   };
 }
 function parsePremise(value, context) {
@@ -232,9 +335,9 @@ function parsePremise(value, context) {
     certificate_id: requiredString(value, "certificate_id", context),
     derivation_kind: derivationKind,
     assurance,
-    scope: parseScope(value.scope, `${context}.scope`),
-    claim: parseClaim(value.claim, `${context}.claim`),
-    evidence: parseEvidenceBundle(value.evidence, `${context}.evidence`)
+    scope: parseScope(requiredField(value, "scope", context), `${context}.scope`),
+    claim: parseClaim(requiredField(value, "claim", context), `${context}.claim`),
+    evidence: parseEvidenceBundle(requiredField(value, "evidence", context), `${context}.evidence`)
   };
 }
 function stableJson(value) {
@@ -264,28 +367,30 @@ function parseDerivation(value, context) {
   const kind = requiredString(value, "kind", context);
   if (kind === "contract") {
     assertOnlyKeys(value, ["kind", "assurance", "contract"], context);
-    if (value.assurance !== "runtime_contract_accepted") {
+    if (requiredField(value, "assurance", context) !== "runtime_contract_accepted") {
       throw new Error(`${context}.assurance must be runtime_contract_accepted.`);
     }
     return {
       kind,
       assurance: "runtime_contract_accepted",
-      contract: parseContract(value.contract, `${context}.contract`)
+      contract: parseContract(requiredField(value, "contract", context), `${context}.contract`)
     };
   }
   if (kind === "composition") {
     assertOnlyKeys(value, ["kind", "assurance", "rule", "premises"], context);
-    if (value.assurance !== "declared_runtime_rule") {
+    if (requiredField(value, "assurance", context) !== "declared_runtime_rule") {
       throw new Error(`${context}.assurance must be declared_runtime_rule.`);
     }
-    if (!Array.isArray(value.premises) || value.premises.length === 0) {
+    const premises = requiredField(value, "premises", context);
+    const premiseValues = readDenseDataArray(premises, `${context}.premises`);
+    if (premiseValues.length === 0) {
       throw new Error(`${context}.premises must contain at least one certificate premise.`);
     }
     return {
       kind,
       assurance: "declared_runtime_rule",
-      rule: parseRule(value.rule, `${context}.rule`),
-      premises: value.premises.map((premise, index) => parsePremise(premise, `${context}.premises[${index}]`))
+      rule: parseRule(requiredField(value, "rule", context), `${context}.rule`),
+      premises: premiseValues.map((premise, index) => parsePremise(premise, `${context}.premises[${index}]`))
     };
   }
   throw new Error(`${context}.kind must be contract or composition.`);
@@ -300,9 +405,25 @@ function createRiddleProofSemanticCertificate(input) {
     ["scope", "evidence", "observation", "contract", "issued_at"],
     "semantic certificate input"
   );
-  const scope = parseScope(input.scope, "semantic certificate scope");
-  const evidence = parseEvidenceBundle(input.evidence, "semantic certificate evidence");
-  const contract = parseContract(input.contract, "semantic certificate contract", true);
+  const scope = parseScope(requiredField(input, "scope", "semantic certificate input"), "semantic certificate scope");
+  const evidence = parseEvidenceBundle(
+    requiredField(input, "evidence", "semantic certificate input"),
+    "semantic certificate evidence"
+  );
+  const runtimeContract = requiredField(
+    input,
+    "contract",
+    "semantic certificate input"
+  );
+  const contract = parseContract(runtimeContract, "semantic certificate contract", true);
+  const accepts = requiredField(
+    runtimeContract,
+    "accepts",
+    "semantic certificate contract"
+  );
+  if (typeof accepts !== "function") {
+    throw new Error("semantic certificate contract.accepts must be a function.");
+  }
   const contractRef = {
     contract_id: contract.contract_id,
     contract_version: contract.contract_version,
@@ -311,14 +432,17 @@ function createRiddleProofSemanticCertificate(input) {
   const claim = contract.claim;
   let accepted;
   try {
-    accepted = input.contract.accepts({ ...scope }, input.observation) === true;
+    accepted = accepts(
+      { ...scope },
+      requiredField(input, "observation", "semantic certificate input")
+    ) === true;
   } catch (error) {
     return {
       ok: false,
       error: {
         code: "contract_error",
         contract: contractRef,
-        message: `Semantic contract evaluation failed: ${error instanceof Error ? error.message : String(error)}.`
+        message: `Semantic contract evaluation failed: ${safeErrorMessage(error)}.`
       }
     };
   }
@@ -338,29 +462,35 @@ function createRiddleProofSemanticCertificate(input) {
     claim,
     evidence,
     derivation: { kind: "contract", assurance: "runtime_contract_accepted", contract },
-    issued_at: parseIssuedAt(input.issued_at || (/* @__PURE__ */ new Date()).toISOString(), "semantic certificate issued_at")
+    issued_at: parseIssuedAt(
+      optionalField(input, "issued_at") || (/* @__PURE__ */ new Date()).toISOString(),
+      "semantic certificate issued_at"
+    )
   };
   return { ok: true, certificate: withCertificateId(body) };
 }
 function parseRiddleProofSemanticCertificate(value) {
   if (!isRecord(value)) throw new Error("Semantic certificate must be an object.");
-  if (value.version !== RIDDLE_PROOF_SEMANTIC_CERTIFICATE_VERSION) {
-    throw new Error(`Unsupported Semantic certificate version ${String(value.version || "missing")}.`);
+  const version = optionalField(value, "version");
+  if (version !== RIDDLE_PROOF_SEMANTIC_CERTIFICATE_VERSION) {
+    throw new Error(`Unsupported Semantic certificate version ${String(version || "missing")}.`);
   }
   for (const field of AUTHORITY_FIELDS) {
     if (Object.prototype.hasOwnProperty.call(value, field)) {
       throw new Error(`Semantic certificate must not contain authority field ${field}.`);
     }
   }
-  for (const field of Object.keys(value)) {
-    if (!CERTIFICATE_FIELDS.has(field)) {
-      throw new Error(`Semantic certificate contains unsupported field ${field}.`);
-    }
-  }
-  const scope = parseScope(value.scope, "semantic certificate scope");
-  const claim = parseClaim(value.claim, "semantic certificate claim");
-  const evidence = parseEvidenceBundle(value.evidence, "semantic certificate evidence");
-  const derivation = parseDerivation(value.derivation, "semantic certificate derivation");
+  assertOnlyKeys(value, [...CERTIFICATE_FIELDS], "Semantic certificate");
+  const scope = parseScope(requiredField(value, "scope", "semantic certificate"), "semantic certificate scope");
+  const claim = parseClaim(requiredField(value, "claim", "semantic certificate"), "semantic certificate claim");
+  const evidence = parseEvidenceBundle(
+    requiredField(value, "evidence", "semantic certificate"),
+    "semantic certificate evidence"
+  );
+  const derivation = parseDerivation(
+    requiredField(value, "derivation", "semantic certificate"),
+    "semantic certificate derivation"
+  );
   if (derivation.kind === "contract" && !sameClaimRef(claim, derivation.contract.claim)) {
     throw new Error("Semantic contract-derived claim must match its contract claim.");
   }
@@ -390,7 +520,10 @@ function parseRiddleProofSemanticCertificate(value) {
     claim,
     evidence,
     derivation,
-    issued_at: parseIssuedAt(value.issued_at, "semantic certificate issued_at")
+    issued_at: parseIssuedAt(
+      requiredField(value, "issued_at", "semantic certificate"),
+      "semantic certificate issued_at"
+    )
   };
   const observedId = requiredString(value, "certificate_id", "semantic certificate");
   const expectedId = certificateId(body);
@@ -399,6 +532,112 @@ function parseRiddleProofSemanticCertificate(value) {
   }
   return { ...body, certificate_id: observedId };
 }
+function matchRiddleProofSemanticCertificate(input) {
+  if (!isRecord(input)) throw new Error("Semantic certificate match input must be a plain object.");
+  assertOnlyKeys(
+    input,
+    [
+      "certificate",
+      "expected_certificate_id",
+      "expected_scope",
+      "expected_claim",
+      "expected_assurance"
+    ],
+    "semantic certificate match input"
+  );
+  const expectedCertificateId = requiredString(
+    input,
+    "expected_certificate_id",
+    "semantic certificate match input"
+  );
+  if (!/^rpsc_[0-9a-f]{64}$/u.test(expectedCertificateId)) {
+    throw new Error(
+      "Semantic certificate match input.expected_certificate_id must be a full rpsc content ID."
+    );
+  }
+  const expectedScope = parseScope(
+    requiredField(input, "expected_scope", "semantic certificate match input"),
+    "semantic certificate match expected_scope"
+  );
+  const expectedClaim = parseClaimRef(
+    requiredField(input, "expected_claim", "semantic certificate match input"),
+    "semantic certificate match expected_claim",
+    ["label"]
+  );
+  const expectedAssurance = requiredString(
+    input,
+    "expected_assurance",
+    "semantic certificate match input"
+  );
+  if (expectedAssurance !== "runtime_contract_accepted" && expectedAssurance !== "declared_runtime_rule") {
+    throw new Error(
+      "Semantic certificate match input.expected_assurance must be runtime_contract_accepted or declared_runtime_rule."
+    );
+  }
+  let certificate;
+  try {
+    certificate = parseRiddleProofSemanticCertificate(
+      requiredField(input, "certificate", "semantic certificate match input")
+    );
+  } catch (error) {
+    return {
+      ok: false,
+      error: {
+        code: "invalid_certificate",
+        message: `Semantic certificate did not parse: ${safeErrorMessage(error)}`
+      }
+    };
+  }
+  if (certificate.certificate_id !== expectedCertificateId) {
+    return {
+      ok: false,
+      error: {
+        code: "certificate_id_mismatch",
+        expected: expectedCertificateId,
+        observed: certificate.certificate_id,
+        message: "Semantic certificate does not match the trusted expected content ID."
+      }
+    };
+  }
+  const scopeMismatch = firstScopeMismatch(expectedScope, certificate.scope);
+  if (scopeMismatch) {
+    return {
+      ok: false,
+      error: {
+        code: "scope_mismatch",
+        ...scopeMismatch,
+        message: `Semantic certificate has a different ${scopeMismatch.field} than the consumer expected.`
+      }
+    };
+  }
+  if (!sameClaimRef(expectedClaim, certificate.claim)) {
+    return {
+      ok: false,
+      error: {
+        code: "claim_mismatch",
+        expected: expectedClaim,
+        observed: parseClaimRef(
+          certificate.claim,
+          "semantic certificate match observed claim",
+          ["label"]
+        ),
+        message: "Semantic certificate does not state the claim the consumer expected."
+      }
+    };
+  }
+  if (certificate.derivation.assurance !== expectedAssurance) {
+    return {
+      ok: false,
+      error: {
+        code: "assurance_mismatch",
+        expected: expectedAssurance,
+        observed: certificate.derivation.assurance,
+        message: "Semantic certificate does not have the assurance the consumer expected."
+      }
+    };
+  }
+  return { ok: true, certificate };
+}
 function firstScopeMismatch(expected, observed) {
   for (const field of SCOPE_FIELDS) {
     if (expected[field] !== observed[field]) {
@@ -424,11 +663,20 @@ function composeRiddleProofSemanticCertificates(input) {
     ["rule", "certificates", "issued_at"],
     "semantic composition input"
   );
-  const rule = parseRule(input.rule, "semantic composition rule", true);
-  if (!Array.isArray(input.certificates) || input.certificates.length === 0) {
+  const rule = parseRule(
+    requiredField(input, "rule", "semantic composition input"),
+    "semantic composition rule",
+    true
+  );
+  const inputCertificates = requiredField(input, "certificates", "semantic composition input");
+  const certificateValues = readDenseDataArray(
+    inputCertificates,
+    "semantic composition input.certificates"
+  );
+  if (certificateValues.length === 0) {
     throw new Error("Semantic composition requires at least one certificate.");
   }
-  const certificates = input.certificates.map((certificate) => parseRiddleProofSemanticCertificate(certificate));
+  const certificates = certificateValues.map((certificate) => parseRiddleProofSemanticCertificate(certificate));
   if (certificates.length !== rule.premises.length) {
     return {
       ok: false,
@@ -483,15 +731,391 @@ function composeRiddleProofSemanticCertificates(input) {
       rule,
       premises: certificates.map(premiseFromCertificate)
     },
-    issued_at: parseIssuedAt(input.issued_at || (/* @__PURE__ */ new Date()).toISOString(), "semantic certificate issued_at")
+    issued_at: parseIssuedAt(
+      optionalField(input, "issued_at") || (/* @__PURE__ */ new Date()).toISOString(),
+      "semantic certificate issued_at"
+    )
   };
   return { ok: true, certificate: withCertificateId(body) };
 }
+function invalidClosure(message) {
+  return { ok: false, error: { code: "invalid_closure", message } };
+}
+function firstPremiseSnapshotMismatch(snapshot, certificate) {
+  const observed = premiseFromCertificate(certificate);
+  if (snapshot.derivation_kind !== observed.derivation_kind) return "derivation_kind";
+  if (snapshot.assurance !== observed.assurance) return "assurance";
+  if (stableJson(snapshot.scope) !== stableJson(observed.scope)) return "scope";
+  if (stableJson(snapshot.claim) !== stableJson(observed.claim)) return "claim";
+  if (stableJson(snapshot.evidence) !== stableJson(observed.evidence)) return "evidence";
+  return void 0;
+}
+function validateSemanticCertificateClosureInternal(value) {
+  if (!isRecord(value)) {
+    return invalidClosure("Semantic certificate closure must be a plain object.");
+  }
+  assertOnlyKeys(
+    value,
+    ["version", "root_certificate_id", "certificates"],
+    "Semantic certificate closure"
+  );
+  if (requiredField(value, "version", "Semantic certificate closure") !== RIDDLE_PROOF_SEMANTIC_CERTIFICATE_CLOSURE_VERSION) {
+    return invalidClosure("Unsupported Semantic certificate closure version.");
+  }
+  const rootCertificateId = requiredString(
+    value,
+    "root_certificate_id",
+    "Semantic certificate closure"
+  );
+  if (!/^rpsc_[0-9a-f]{64}$/u.test(rootCertificateId)) {
+    return invalidClosure(
+      "Semantic certificate closure.root_certificate_id must be a full rpsc content ID."
+    );
+  }
+  const inputCertificates = requiredField(
+    value,
+    "certificates",
+    "Semantic certificate closure"
+  );
+  const certificateValues = readDenseDataArray(
+    inputCertificates,
+    "Semantic certificate closure.certificates",
+    RIDDLE_PROOF_SEMANTIC_CERTIFICATE_CLOSURE_MAX_CERTIFICATES
+  );
+  if (certificateValues.length === 0) {
+    return invalidClosure("Semantic certificate closure must contain at least one certificate.");
+  }
+  const certificates = [];
+  for (let index = 0; index < certificateValues.length; index += 1) {
+    try {
+      certificates.push(parseRiddleProofSemanticCertificate(certificateValues[index]));
+    } catch (error) {
+      return {
+        ok: false,
+        error: {
+          code: "invalid_closure_certificate",
+          input_index: index,
+          message: `Semantic certificate closure certificate ${index} did not parse: ${safeErrorMessage(error)}`
+        }
+      };
+    }
+  }
+  const certificatesById = /* @__PURE__ */ new Map();
+  const firstIndexById = /* @__PURE__ */ new Map();
+  for (let index = 0; index < certificates.length; index += 1) {
+    const certificate = certificates[index];
+    const firstIndex = firstIndexById.get(certificate.certificate_id);
+    if (firstIndex !== void 0) {
+      return {
+        ok: false,
+        error: {
+          code: "duplicate_certificate_id",
+          certificate_id: certificate.certificate_id,
+          first_index: firstIndex,
+          duplicate_index: index,
+          message: `Semantic certificate closure repeats certificate ${certificate.certificate_id}.`
+        }
+      };
+    }
+    firstIndexById.set(certificate.certificate_id, index);
+    certificatesById.set(certificate.certificate_id, certificate);
+  }
+  const rootCertificate = certificatesById.get(rootCertificateId);
+  if (!rootCertificate) {
+    return {
+      ok: false,
+      error: {
+        code: "root_certificate_missing",
+        root_certificate_id: rootCertificateId,
+        message: "Semantic certificate closure does not contain its declared root certificate."
+      }
+    };
+  }
+  const states = /* @__PURE__ */ new Map();
+  const stack = [{ certificate: rootCertificate, next_premise_index: 0 }];
+  const dependencyFirst = [];
+  states.set(rootCertificateId, "visiting");
+  while (stack.length > 0) {
+    const frame = stack[stack.length - 1];
+    const premises = frame.certificate.derivation.kind === "composition" ? frame.certificate.derivation.premises : [];
+    if (frame.next_premise_index < premises.length) {
+      const premiseIndex = frame.next_premise_index;
+      frame.next_premise_index += 1;
+      const snapshot = premises[premiseIndex];
+      const child = certificatesById.get(snapshot.certificate_id);
+      if (!child) {
+        return {
+          ok: false,
+          error: {
+            code: "dangling_premise",
+            parent_certificate_id: frame.certificate.certificate_id,
+            premise_index: premiseIndex,
+            premise_certificate_id: snapshot.certificate_id,
+            message: `Semantic certificate ${frame.certificate.certificate_id} premise ${premiseIndex} has no full certificate body.`
+          }
+        };
+      }
+      const mismatch = firstPremiseSnapshotMismatch(snapshot, child);
+      if (mismatch) {
+        return {
+          ok: false,
+          error: {
+            code: "premise_snapshot_mismatch",
+            parent_certificate_id: frame.certificate.certificate_id,
+            premise_index: premiseIndex,
+            premise_certificate_id: snapshot.certificate_id,
+            field: mismatch,
+            message: `Semantic certificate ${frame.certificate.certificate_id} premise ${premiseIndex} has a different ${mismatch} than its full certificate body.`
+          }
+        };
+      }
+      const childState = states.get(child.certificate_id);
+      if (childState === "visiting") {
+        const cycleStart = stack.findIndex(
+          (candidate) => candidate.certificate.certificate_id === child.certificate_id
+        );
+        const certificateIds = stack.slice(Math.max(0, cycleStart)).map((candidate) => candidate.certificate.certificate_id);
+        certificateIds.push(child.certificate_id);
+        return {
+          ok: false,
+          error: {
+            code: "certificate_cycle",
+            certificate_ids: certificateIds,
+            message: "Semantic certificate closure contains a certificate cycle."
+          }
+        };
+      }
+      if (childState !== "visited") {
+        states.set(child.certificate_id, "visiting");
+        stack.push({ certificate: child, next_premise_index: 0 });
+      }
+      continue;
+    }
+    stack.pop();
+    states.set(frame.certificate.certificate_id, "visited");
+    dependencyFirst.push(frame.certificate);
+  }
+  if (dependencyFirst.length !== certificates.length) {
+    const reachable = new Set(dependencyFirst.map((certificate) => certificate.certificate_id));
+    const unreachable = certificates.filter((certificate) => !reachable.has(certificate.certificate_id)).map((certificate) => certificate.certificate_id).sort();
+    return {
+      ok: false,
+      error: {
+        code: "unreachable_certificates",
+        certificate_ids: unreachable,
+        message: "Semantic certificate closure contains certificates unreachable from its root."
+      }
+    };
+  }
+  const closure = {
+    version: RIDDLE_PROOF_SEMANTIC_CERTIFICATE_CLOSURE_VERSION,
+    root_certificate_id: rootCertificateId,
+    certificates: dependencyFirst
+  };
+  return { ok: true, closure, root_certificate: rootCertificate };
+}
+function validateRiddleProofSemanticCertificateClosure(value) {
+  try {
+    return validateSemanticCertificateClosureInternal(value);
+  } catch (error) {
+    return invalidClosure(
+      `Semantic certificate closure did not parse: ${safeErrorMessage(error)}`
+    );
+  }
+}
+function createRiddleProofSemanticAtomicCertificateClosure(input) {
+  if (!isRecord(input)) throw new Error("Semantic certificate closure input must be a plain object.");
+  assertOnlyKeys(input, ["certificate"], "Semantic certificate closure input");
+  const certificate = requiredField(input, "certificate", "Semantic certificate closure input");
+  let parsedCertificate;
+  try {
+    parsedCertificate = parseRiddleProofSemanticCertificate(certificate);
+  } catch (error) {
+    return {
+      ok: false,
+      error: {
+        code: "invalid_closure_certificate",
+        input_index: 0,
+        message: `Semantic certificate closure certificate 0 did not parse: ${safeErrorMessage(error)}`
+      }
+    };
+  }
+  if (parsedCertificate.derivation.kind !== "contract") {
+    return invalidClosure(
+      "An atomic Semantic certificate closure requires a contract-derived certificate."
+    );
+  }
+  return validateRiddleProofSemanticCertificateClosure({
+    version: RIDDLE_PROOF_SEMANTIC_CERTIFICATE_CLOSURE_VERSION,
+    root_certificate_id: parsedCertificate.certificate_id,
+    certificates: [certificate]
+  });
+}
+function composeRiddleProofSemanticCertificateClosures(input) {
+  if (!isRecord(input)) throw new Error("Semantic closure composition input must be a plain object.");
+  assertOnlyKeys(
+    input,
+    ["rule", "closures", "issued_at"],
+    "Semantic closure composition input"
+  );
+  const inputClosures = requiredField(
+    input,
+    "closures",
+    "Semantic closure composition input"
+  );
+  const closureValues = readDenseDataArray(
+    inputClosures,
+    "Semantic closure composition input.closures"
+  );
+  if (closureValues.length === 0) {
+    throw new Error("Semantic closure composition requires at least one closure.");
+  }
+  const validatedClosures = [];
+  for (let index = 0; index < closureValues.length; index += 1) {
+    const result = validateRiddleProofSemanticCertificateClosure(closureValues[index]);
+    if (!result.ok) {
+      return {
+        ok: false,
+        error: {
+          code: "input_closure_invalid",
+          input_index: index,
+          cause: result.error,
+          message: `Semantic input closure ${index} is invalid: ${result.error.message}`
+        }
+      };
+    }
+    validatedClosures.push(result);
+  }
+  const roots = validatedClosures.map((result) => {
+    if (!result.ok) throw new Error("Validated Semantic closure unexpectedly became invalid.");
+    return result.root_certificate;
+  });
+  const composition = composeRiddleProofSemanticCertificates({
+    rule: requiredField(input, "rule", "Semantic closure composition input"),
+    certificates: roots,
+    issued_at: optionalField(input, "issued_at")
+  });
+  if (!composition.ok) return composition;
+  const merged = [];
+  const byId = /* @__PURE__ */ new Map();
+  for (const result of validatedClosures) {
+    if (!result.ok) continue;
+    for (const certificate of result.closure.certificates) {
+      const existing = byId.get(certificate.certificate_id);
+      if (existing) {
+        if (stableJson(existing) !== stableJson(certificate)) {
+          return {
+            ok: false,
+            error: {
+              code: "certificate_id_collision",
+              certificate_id: certificate.certificate_id,
+              message: `Semantic closures contain unequal bodies for ${certificate.certificate_id}.`
+            }
+          };
+        }
+        continue;
+      }
+      byId.set(certificate.certificate_id, certificate);
+      merged.push(certificate);
+    }
+  }
+  if (byId.has(composition.certificate.certificate_id)) {
+    return {
+      ok: false,
+      error: {
+        code: "certificate_id_collision",
+        certificate_id: composition.certificate.certificate_id,
+        message: "Semantic composition produced a root ID already present in its premise closures."
+      }
+    };
+  }
+  merged.push(composition.certificate);
+  const validation = validateRiddleProofSemanticCertificateClosure({
+    version: RIDDLE_PROOF_SEMANTIC_CERTIFICATE_CLOSURE_VERSION,
+    root_certificate_id: composition.certificate.certificate_id,
+    certificates: merged
+  });
+  if (!validation.ok) {
+    return {
+      ok: false,
+      error: {
+        code: "closure_construction_failed",
+        cause: validation.error,
+        message: `Semantic closure construction failed: ${validation.error.message}`
+      }
+    };
+  }
+  return {
+    ok: true,
+    certificate: composition.certificate,
+    closure: validation.closure
+  };
+}
+function matchRiddleProofSemanticCertificateClosure(input) {
+  if (!isRecord(input)) throw new Error("Semantic certificate closure match input must be a plain object.");
+  assertOnlyKeys(
+    input,
+    [
+      "closure",
+      "expected_root_certificate_id",
+      "expected_scope",
+      "expected_claim",
+      "expected_assurance"
+    ],
+    "Semantic certificate closure match input"
+  );
+  const validation = validateRiddleProofSemanticCertificateClosure(
+    requiredField(input, "closure", "Semantic certificate closure match input")
+  );
+  if (!validation.ok) return validation;
+  const expectedRootCertificateId = requiredString(
+    input,
+    "expected_root_certificate_id",
+    "Semantic certificate closure match input"
+  );
+  if (!/^rpsc_[0-9a-f]{64}$/u.test(expectedRootCertificateId)) {
+    throw new Error(
+      "Semantic certificate closure match input.expected_root_certificate_id must be a full rpsc content ID."
+    );
+  }
+  const rootMatch = matchRiddleProofSemanticCertificate({
+    certificate: validation.root_certificate,
+    expected_certificate_id: expectedRootCertificateId,
+    expected_scope: requiredField(
+      input,
+      "expected_scope",
+      "Semantic certificate closure match input"
+    ),
+    expected_claim: requiredField(
+      input,
+      "expected_claim",
+      "Semantic certificate closure match input"
+    ),
+    expected_assurance: requiredField(
+      input,
+      "expected_assurance",
+      "Semantic certificate closure match input"
+    )
+  });
+  if (!rootMatch.ok) return rootMatch;
+  return {
+    ok: true,
+    closure: validation.closure,
+    root_certificate: rootMatch.certificate
+  };
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  RIDDLE_PROOF_SEMANTIC_CERTIFICATE_CLOSURE_MAX_CERTIFICATES,
+  RIDDLE_PROOF_SEMANTIC_CERTIFICATE_CLOSURE_VERSION,
   RIDDLE_PROOF_SEMANTIC_CERTIFICATE_VERSION,
+  composeRiddleProofSemanticCertificateClosures,
   composeRiddleProofSemanticCertificates,
+  createRiddleProofSemanticAtomicCertificateClosure,
   createRiddleProofSemanticCertificate,
+  matchRiddleProofSemanticCertificate,
+  matchRiddleProofSemanticCertificateClosure,
   parseRiddleProofSemanticCertificate,
-  riddleProofSemanticScopesEqual
+  riddleProofSemanticScopesEqual,
+  validateRiddleProofSemanticCertificateClosure
 });