@riddledc/riddle-proof 0.8.81 → 0.8.83

package/dist/index.cjs

@@ -3442,6 +3442,7 @@ __export(index_exports, {
   RIDDLE_PROOF_PR_COMMENT_MARKER: () => RIDDLE_PROOF_PR_COMMENT_MARKER,
   RIDDLE_PROOF_RUN_CARD_VERSION: () => RIDDLE_PROOF_RUN_CARD_VERSION,
   RIDDLE_PROOF_RUN_STATE_VERSION: () => RIDDLE_PROOF_RUN_STATE_VERSION,
+  RIDDLE_PROOF_SEMANTIC_CERTIFICATE_VERSION: () => RIDDLE_PROOF_SEMANTIC_CERTIFICATE_VERSION,
   RIDDLE_PROOF_VISUAL_SESSION_FINGERPRINT_VERSION: () => RIDDLE_PROOF_VISUAL_SESSION_FINGERPRINT_VERSION,
   RIDDLE_PROOF_VISUAL_SESSION_VERSION: () => RIDDLE_PROOF_VISUAL_SESSION_VERSION,
   RIDDLE_UNSUBMITTED_WAKE_HINT: () => RIDDLE_UNSUBMITTED_WAKE_HINT,
@@ -3483,6 +3484,7 @@ __export(index_exports, {
   compactBasicGameplayText: () => compactBasicGameplayText,
   compactRecord: () => compactRecord,
   compareVisualProofSessionFingerprint: () => compareVisualProofSessionFingerprint,
+  composeRiddleProofSemanticCertificates: () => composeRiddleProofSemanticCertificates,
   createBasicGameplayCatchRecords: () => createBasicGameplayCatchRecords,
   createBasicGameplayCatchSummary: () => createBasicGameplayCatchSummary,
   createCaptureDiagnostic: () => createCaptureDiagnostic,
@@ -3500,6 +3502,7 @@ __export(index_exports, {
   createRiddleProofProfileEnvironmentBlockedResult: () => createRiddleProofProfileEnvironmentBlockedResult,
   createRiddleProofProfileInsufficientResult: () => createRiddleProofProfileInsufficientResult,
   createRiddleProofRunCard: () => createRiddleProofRunCard,
+  createRiddleProofSemanticCertificate: () => createRiddleProofSemanticCertificate,
   createRunResult: () => createRunResult,
   createRunState: () => createRunState,
   createRunStatusSnapshot: () => createRunStatusSnapshot,
@@ -3517,6 +3520,7 @@ __export(index_exports, {
   isSuccessfulStatus: () => isSuccessfulStatus,
   isTerminalRiddleJobStatus: () => isTerminalRiddleJobStatus,
   isTerminalStatus: () => isTerminalStatus,
+  matchRiddleProofSemanticCertificate: () => matchRiddleProofSemanticCertificate,
   migrateRiddleProofChangeReceipt: () => migrateRiddleProofChangeReceipt,
   nonEmptyString: () => nonEmptyString,
   normalizeCheckpointResponse: () => normalizeCheckpointResponse,
@@ -3529,6 +3533,7 @@ __export(index_exports, {
   parseRiddleProofChangeReceipt: () => parseRiddleProofChangeReceipt,
   parseRiddleProofHandoffReceipt: () => parseRiddleProofHandoffReceipt,
   parseRiddleProofObservationReceipt: () => parseRiddleProofObservationReceipt,
+  parseRiddleProofSemanticCertificate: () => parseRiddleProofSemanticCertificate,
   parseRiddleViewport: () => parseRiddleViewport,
   parseVisualProofSession: () => parseVisualProofSession,
   pollRiddleJob: () => pollRiddleJob,
@@ -3552,6 +3557,7 @@ __export(index_exports, {
   riddleProofPublicStateAllowsClaim: () => riddleProofPublicStateAllowsClaim,
   riddleProofPublicStateAllowsMergeRecommendation: () => riddleProofPublicStateAllowsMergeRecommendation,
   riddleProofPublicStateMergeRecommendation: () => riddleProofPublicStateMergeRecommendation,
+  riddleProofSemanticScopesEqual: () => riddleProofSemanticScopesEqual,
   riddleRequestJson: () => riddleRequestJson,
   runCodexExecAgentDoctor: () => runCodexExecAgentDoctor,
   runLocalAgentDoctor: () => runCodexExecAgentDoctor,
@@ -20566,6 +20572,583 @@ function parseRiddleProofObservationReceipt(value) {
   return value;
 }
 
+// src/semantic-certificate.ts
+var import_node_crypto5 = require("crypto");
+var RIDDLE_PROOF_SEMANTIC_CERTIFICATE_VERSION = "riddle-proof.semantic-certificate.v0";
+var SCOPE_FIELDS = [
+  "repository",
+  "revision",
+  "environment",
+  "target",
+  "proof_attempt"
+];
+var AUTHORITY_FIELDS = [
+  "authority",
+  "status",
+  "verdict",
+  "ready_to_ship",
+  "merge_ready",
+  "sync_allowed",
+  "ship_authorized",
+  "shipping_authorized",
+  "shipping_disabled",
+  "merge_recommended",
+  "merge_recommendation",
+  "shipping_authorization"
+];
+var CERTIFICATE_FIELDS = /* @__PURE__ */ new Set([
+  "version",
+  "certificate_id",
+  "scope",
+  "claim",
+  "evidence",
+  "derivation",
+  "issued_at"
+]);
+function isRecord4(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+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)) {
+    if (!allowedSet.has(key)) {
+      throw new Error(`${context} contains unsupported field ${key}.`);
+    }
+  }
+}
+function requiredString2(record, key, context) {
+  const value = record[key];
+  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;
+  return requiredString2(record, key, context);
+}
+function isJsonValue(value, ancestors = /* @__PURE__ */ new Set()) {
+  if (value === null || typeof value === "string" || typeof value === "boolean") {
+    return true;
+  }
+  if (typeof value === "number") return Number.isFinite(value);
+  if (Array.isArray(value)) {
+    if (ancestors.has(value)) return false;
+    ancestors.add(value);
+    const valid2 = value.every((entry) => isJsonValue(entry, ancestors));
+    ancestors.delete(value);
+    return valid2;
+  }
+  if (!isRecord4(value)) return false;
+  const prototype = Object.getPrototypeOf(value);
+  if (prototype !== Object.prototype && prototype !== null) return false;
+  if (ancestors.has(value)) return false;
+  ancestors.add(value);
+  const valid = Object.values(value).every((entry) => isJsonValue(entry, ancestors));
+  ancestors.delete(value);
+  return valid;
+}
+function parseJsonObject2(value, context) {
+  if (value === void 0) return void 0;
+  if (!isRecord4(value) || !isJsonValue(value)) {
+    throw new Error(`${context} must be a JSON object.`);
+  }
+  const cloned = JSON.parse(JSON.stringify(value));
+  if (!isRecord4(cloned) || !isJsonValue(cloned)) {
+    throw new Error(`${context} must remain a JSON object when serialized.`);
+  }
+  return cloned;
+}
+function parseIssuedAt(value, context) {
+  if (typeof value !== "string" || !value.trim() || !Number.isFinite(Date.parse(value))) {
+    throw new Error(`${context} must be a valid timestamp.`);
+  }
+  return value.trim();
+}
+function parseScope(value, context) {
+  if (!isRecord4(value)) throw new Error(`${context} must be an object.`);
+  assertOnlyKeys(value, SCOPE_FIELDS, context);
+  return {
+    repository: requiredString2(value, "repository", context),
+    revision: requiredString2(value, "revision", context),
+    environment: requiredString2(value, "environment", context),
+    target: requiredString2(value, "target", context),
+    proof_attempt: requiredString2(value, "proof_attempt", context)
+  };
+}
+function parseClaimRef(value, context, allowedExtras = []) {
+  if (!isRecord4(value)) throw new Error(`${context} must be an object.`);
+  assertOnlyKeys(value, ["claim_id", "claim_version", "parameters", ...allowedExtras], context);
+  const parameters = parseJsonObject2(value.parameters, `${context}.parameters`);
+  return {
+    claim_id: requiredString2(value, "claim_id", context),
+    claim_version: requiredString2(value, "claim_version", context),
+    ...parameters ? { parameters } : {}
+  };
+}
+function parseClaim(value, context) {
+  if (!isRecord4(value)) throw new Error(`${context} must be an object.`);
+  return {
+    ...parseClaimRef(value, context, ["label"]),
+    label: requiredString2(value, "label", context)
+  };
+}
+function parseEvidenceRef(value, context) {
+  if (!isRecord4(value)) throw new Error(`${context} must be an object.`);
+  assertOnlyKeys(
+    value,
+    ["receipt_id", "artifact_digest", "role", "artifact_url", "artifact_path"],
+    context
+  );
+  const artifactDigest = requiredString2(value, "artifact_digest", context).toLowerCase();
+  if (!/^sha256:[0-9a-f]{64}$/u.test(artifactDigest)) {
+    throw new Error(`${context}.artifact_digest must be a full sha256 digest.`);
+  }
+  const artifactUrl = optionalString(value, "artifact_url", context);
+  const artifactPath = optionalString(value, "artifact_path", context);
+  return {
+    receipt_id: requiredString2(value, "receipt_id", context),
+    artifact_digest: artifactDigest,
+    role: requiredString2(value, "role", context),
+    ...artifactUrl ? { artifact_url: artifactUrl } : {},
+    ...artifactPath ? { artifact_path: artifactPath } : {}
+  };
+}
+function parseEvidenceBundle(value, context) {
+  if (!Array.isArray(value) || value.length === 0) {
+    throw new Error(`${context} must contain at least one evidence reference.`);
+  }
+  return value.map((entry, index) => parseEvidenceRef(entry, `${context}[${index}]`));
+}
+function parseContractRef(value, context) {
+  if (!isRecord4(value)) throw new Error(`${context} must be an object.`);
+  return {
+    contract_id: requiredString2(value, "contract_id", context),
+    contract_version: requiredString2(value, "contract_version", context),
+    label: requiredString2(value, "label", context)
+  };
+}
+function parseContract(value, context, allowRuntimePredicate = false) {
+  if (!isRecord4(value)) throw new Error(`${context} must be an object.`);
+  assertOnlyKeys(
+    value,
+    ["contract_id", "contract_version", "label", "claim", ...allowRuntimePredicate ? ["accepts"] : []],
+    context
+  );
+  if (allowRuntimePredicate && typeof value.accepts !== "function") {
+    throw new Error(`${context}.accepts must be a function.`);
+  }
+  return {
+    ...parseContractRef(value, context),
+    claim: parseClaim(value.claim, `${context}.claim`)
+  };
+}
+function parseRule(value, context, allowFullPremises = false) {
+  if (!isRecord4(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) {
+    throw new Error(`${context}.premises must contain at least one claim reference.`);
+  }
+  return {
+    rule_id: requiredString2(value, "rule_id", context),
+    rule_version: requiredString2(value, "rule_version", context),
+    label: requiredString2(value, "label", context),
+    premises: value.premises.map((premise, index) => parseClaimRef(
+      premise,
+      `${context}.premises[${index}]`,
+      allowFullPremises ? ["label"] : []
+    )),
+    conclusion: parseClaim(value.conclusion, `${context}.conclusion`)
+  };
+}
+function parsePremise(value, context) {
+  if (!isRecord4(value)) throw new Error(`${context} must be an object.`);
+  assertOnlyKeys(
+    value,
+    ["certificate_id", "derivation_kind", "assurance", "scope", "claim", "evidence"],
+    context
+  );
+  const derivationKind = requiredString2(value, "derivation_kind", context);
+  const assurance = requiredString2(value, "assurance", context);
+  const validAssurance = derivationKind === "contract" && assurance === "runtime_contract_accepted" || derivationKind === "composition" && assurance === "declared_runtime_rule";
+  if (!validAssurance) {
+    throw new Error(`${context} must preserve a valid derivation_kind and assurance pair.`);
+  }
+  return {
+    certificate_id: requiredString2(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`)
+  };
+}
+function stableJson3(value) {
+  if (Array.isArray(value)) return `[${value.map(stableJson3).join(",")}]`;
+  if (isRecord4(value)) {
+    return `{${Object.keys(value).filter((key) => value[key] !== void 0).sort().map((key) => `${JSON.stringify(key)}:${stableJson3(value[key])}`).join(",")}}`;
+  }
+  const encoded = JSON.stringify(value);
+  if (encoded === void 0) throw new Error("Semantic certificate contains a non-JSON value.");
+  return encoded;
+}
+function sameClaimRef(left, right) {
+  return left.claim_id === right.claim_id && left.claim_version === right.claim_version && stableJson3(left.parameters || {}) === stableJson3(right.parameters || {});
+}
+function sameEvidence(left, right) {
+  return stableJson3(left) === stableJson3(right);
+}
+function certificateId(body) {
+  const digest = (0, import_node_crypto5.createHash)("sha256").update(stableJson3(body)).digest("hex");
+  return `rpsc_${digest}`;
+}
+function withCertificateId(body) {
+  return { ...body, certificate_id: certificateId(body) };
+}
+function parseDerivation(value, context) {
+  if (!isRecord4(value)) throw new Error(`${context} must be an object.`);
+  const kind = requiredString2(value, "kind", context);
+  if (kind === "contract") {
+    assertOnlyKeys(value, ["kind", "assurance", "contract"], context);
+    if (value.assurance !== "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`)
+    };
+  }
+  if (kind === "composition") {
+    assertOnlyKeys(value, ["kind", "assurance", "rule", "premises"], context);
+    if (value.assurance !== "declared_runtime_rule") {
+      throw new Error(`${context}.assurance must be declared_runtime_rule.`);
+    }
+    if (!Array.isArray(value.premises) || value.premises.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}]`))
+    };
+  }
+  throw new Error(`${context}.kind must be contract or composition.`);
+}
+function riddleProofSemanticScopesEqual(left, right) {
+  return SCOPE_FIELDS.every((field) => left[field] === right[field]);
+}
+function createRiddleProofSemanticCertificate(input) {
+  if (!isRecord4(input)) throw new Error("Semantic certificate input must be an object.");
+  assertOnlyKeys(
+    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 contractRef = {
+    contract_id: contract.contract_id,
+    contract_version: contract.contract_version,
+    label: contract.label
+  };
+  const claim = contract.claim;
+  let accepted;
+  try {
+    accepted = input.contract.accepts({ ...scope }, input.observation) === true;
+  } catch (error) {
+    return {
+      ok: false,
+      error: {
+        code: "contract_error",
+        contract: contractRef,
+        message: `Semantic contract evaluation failed: ${error instanceof Error ? error.message : String(error)}.`
+      }
+    };
+  }
+  if (!accepted) {
+    return {
+      ok: false,
+      error: {
+        code: "contract_rejected",
+        contract: contractRef,
+        message: "Semantic contract rejected the supplied observation at this scope."
+      }
+    };
+  }
+  const body = {
+    version: RIDDLE_PROOF_SEMANTIC_CERTIFICATE_VERSION,
+    scope,
+    claim,
+    evidence,
+    derivation: { kind: "contract", assurance: "runtime_contract_accepted", contract },
+    issued_at: parseIssuedAt(input.issued_at || (/* @__PURE__ */ new Date()).toISOString(), "semantic certificate issued_at")
+  };
+  return { ok: true, certificate: withCertificateId(body) };
+}
+function parseRiddleProofSemanticCertificate(value) {
+  if (!isRecord4(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")}.`);
+  }
+  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");
+  if (derivation.kind === "contract" && !sameClaimRef(claim, derivation.contract.claim)) {
+    throw new Error("Semantic contract-derived claim must match its contract claim.");
+  }
+  if (derivation.kind === "composition") {
+    if (derivation.premises.length !== derivation.rule.premises.length) {
+      throw new Error("Semantic composition premises must match the rule premise count.");
+    }
+    derivation.premises.forEach((premise, index) => {
+      if (!riddleProofSemanticScopesEqual(scope, premise.scope)) {
+        throw new Error(`Semantic composition premise ${index} must have the certificate scope.`);
+      }
+      if (!sameClaimRef(premise.claim, derivation.rule.premises[index])) {
+        throw new Error(`Semantic composition premise ${index} must match its rule claim.`);
+      }
+    });
+    if (!sameClaimRef(claim, derivation.rule.conclusion)) {
+      throw new Error("Semantic composition claim must match its rule conclusion.");
+    }
+    const expectedEvidence = derivation.premises.flatMap((premise) => premise.evidence);
+    if (!sameEvidence(evidence, expectedEvidence)) {
+      throw new Error("Semantic composition evidence must be the ordered concatenation of premise evidence.");
+    }
+  }
+  const body = {
+    version: RIDDLE_PROOF_SEMANTIC_CERTIFICATE_VERSION,
+    scope,
+    claim,
+    evidence,
+    derivation,
+    issued_at: parseIssuedAt(value.issued_at, "semantic certificate issued_at")
+  };
+  const observedId = requiredString2(value, "certificate_id", "semantic certificate");
+  const expectedId = certificateId(body);
+  if (observedId !== expectedId) {
+    throw new Error("Semantic certificate_id must match its content.");
+  }
+  return { ...body, certificate_id: observedId };
+}
+function matchRiddleProofSemanticCertificate(input) {
+  if (!isRecord4(input)) throw new Error("Semantic certificate match input must be an object.");
+  assertOnlyKeys(
+    input,
+    [
+      "certificate",
+      "expected_certificate_id",
+      "expected_scope",
+      "expected_claim",
+      "expected_assurance"
+    ],
+    "semantic certificate match input"
+  );
+  const expectedCertificateId = requiredString2(
+    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(
+    input.expected_scope,
+    "semantic certificate match expected_scope"
+  );
+  const expectedClaim = parseClaimRef(
+    input.expected_claim,
+    "semantic certificate match expected_claim",
+    ["label"]
+  );
+  const expectedAssurance = requiredString2(
+    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(input.certificate);
+  } 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]) {
+      return { field, expected: expected[field], observed: observed[field] };
+    }
+  }
+  return void 0;
+}
+function premiseFromCertificate(certificate) {
+  return {
+    certificate_id: certificate.certificate_id,
+    derivation_kind: certificate.derivation.kind,
+    assurance: certificate.derivation.assurance,
+    scope: { ...certificate.scope },
+    claim: parseClaim(certificate.claim, "semantic composition premise claim"),
+    evidence: certificate.evidence.map((entry) => ({ ...entry }))
+  };
+}
+function composeRiddleProofSemanticCertificates(input) {
+  if (!isRecord4(input)) throw new Error("Semantic composition input must be an object.");
+  assertOnlyKeys(
+    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) {
+    throw new Error("Semantic composition requires at least one certificate.");
+  }
+  const certificates = input.certificates.map((certificate) => parseRiddleProofSemanticCertificate(certificate));
+  if (certificates.length !== rule.premises.length) {
+    return {
+      ok: false,
+      error: {
+        code: "premise_count_mismatch",
+        expected: rule.premises.length,
+        observed: certificates.length,
+        message: `Semantic rule expected ${rule.premises.length} certificate(s), received ${certificates.length}.`
+      }
+    };
+  }
+  const expectedScope = certificates[0].scope;
+  for (let index = 1; index < certificates.length; index += 1) {
+    const mismatch = firstScopeMismatch(expectedScope, certificates[index].scope);
+    if (mismatch) {
+      return {
+        ok: false,
+        error: {
+          code: "scope_mismatch",
+          input_index: index,
+          ...mismatch,
+          message: `Semantic certificate ${index} has a different ${mismatch.field}.`
+        }
+      };
+    }
+  }
+  for (let index = 0; index < certificates.length; index += 1) {
+    const expected = rule.premises[index];
+    const observed = certificates[index].claim;
+    if (!sameClaimRef(expected, observed)) {
+      return {
+        ok: false,
+        error: {
+          code: "premise_mismatch",
+          input_index: index,
+          expected,
+          observed: parseClaimRef(observed, "semantic composition observed claim", ["label"]),
+          message: `Semantic certificate ${index} does not satisfy its declared rule premise.`
+        }
+      };
+    }
+  }
+  const evidence = certificates.flatMap((certificate) => certificate.evidence);
+  const body = {
+    version: RIDDLE_PROOF_SEMANTIC_CERTIFICATE_VERSION,
+    scope: { ...expectedScope },
+    claim: { ...rule.conclusion },
+    evidence,
+    derivation: {
+      kind: "composition",
+      assurance: "declared_runtime_rule",
+      rule,
+      premises: certificates.map(premiseFromCertificate)
+    },
+    issued_at: parseIssuedAt(input.issued_at || (/* @__PURE__ */ new Date()).toISOString(), "semantic certificate issued_at")
+  };
+  return { ok: true, certificate: withCertificateId(body) };
+}
+
 // src/change-proof.ts
 var RIDDLE_PROOF_CHANGE_CONTRACT_VERSION = "riddle-proof.change-contract.v1";
 var RIDDLE_PROOF_CHANGE_RESULT_VERSION = "riddle-proof.change-result.v1";
@@ -21023,7 +21606,7 @@ function createRiddleProofChangeReceipt(input) {
     metadata: input.result.metadata
   };
 }
-function isRecord4(value) {
+function isRecord5(value) {
   return Boolean(value) && typeof value === "object" && !Array.isArray(value);
 }
 function migratedObservationFromLegacySide(side, legacy) {
@@ -21100,7 +21683,7 @@ function migrateRiddleProofChangeReceipt(legacy) {
   };
 }
 function parseRiddleProofChangeReceipt(value) {
-  if (!isRecord4(value)) throw new Error("Change receipt must be an object.");
+  if (!isRecord5(value)) throw new Error("Change receipt must be an object.");
   if (value.version === RIDDLE_PROOF_CHANGE_RECEIPT_V1_VERSION) {
     return migrateRiddleProofChangeReceipt(value);
   }
@@ -21144,8 +21727,8 @@ function createRiddleProofHandoffReceipt(changeReceipt, options = {}) {
   };
 }
 function parseRiddleProofHandoffReceipt(value) {
-  if (!isRecord4(value) || value.version !== RIDDLE_PROOF_HANDOFF_RECEIPT_VERSION) {
-    throw new Error(`Unsupported Handoff receipt version ${String(isRecord4(value) ? value.version || "missing" : "missing")}.`);
+  if (!isRecord5(value) || value.version !== RIDDLE_PROOF_HANDOFF_RECEIPT_VERSION) {
+    throw new Error(`Unsupported Handoff receipt version ${String(isRecord5(value) ? value.version || "missing" : "missing")}.`);
   }
   const receipt = value;
   if (!Number.isFinite(Date.parse(receipt.created_at))) {
@@ -22616,6 +23199,7 @@ function buildRiddleProofPrCommentMarkdown(input) {
   RIDDLE_PROOF_PR_COMMENT_MARKER,
   RIDDLE_PROOF_RUN_CARD_VERSION,
   RIDDLE_PROOF_RUN_STATE_VERSION,
+  RIDDLE_PROOF_SEMANTIC_CERTIFICATE_VERSION,
   RIDDLE_PROOF_VISUAL_SESSION_FINGERPRINT_VERSION,
   RIDDLE_PROOF_VISUAL_SESSION_VERSION,
   RIDDLE_UNSUBMITTED_WAKE_HINT,
@@ -22657,6 +23241,7 @@ function buildRiddleProofPrCommentMarkdown(input) {
   compactBasicGameplayText,
   compactRecord,
   compareVisualProofSessionFingerprint,
+  composeRiddleProofSemanticCertificates,
   createBasicGameplayCatchRecords,
   createBasicGameplayCatchSummary,
   createCaptureDiagnostic,
@@ -22674,6 +23259,7 @@ function buildRiddleProofPrCommentMarkdown(input) {
   createRiddleProofProfileEnvironmentBlockedResult,
   createRiddleProofProfileInsufficientResult,
   createRiddleProofRunCard,
+  createRiddleProofSemanticCertificate,
   createRunResult,
   createRunState,
   createRunStatusSnapshot,
@@ -22691,6 +23277,7 @@ function buildRiddleProofPrCommentMarkdown(input) {
   isSuccessfulStatus,
   isTerminalRiddleJobStatus,
   isTerminalStatus,
+  matchRiddleProofSemanticCertificate,
   migrateRiddleProofChangeReceipt,
   nonEmptyString,
   normalizeCheckpointResponse,
@@ -22703,6 +23290,7 @@ function buildRiddleProofPrCommentMarkdown(input) {
   parseRiddleProofChangeReceipt,
   parseRiddleProofHandoffReceipt,
   parseRiddleProofObservationReceipt,
+  parseRiddleProofSemanticCertificate,
   parseRiddleViewport,
   parseVisualProofSession,
   pollRiddleJob,
@@ -22726,6 +23314,7 @@ function buildRiddleProofPrCommentMarkdown(input) {
   riddleProofPublicStateAllowsClaim,
   riddleProofPublicStateAllowsMergeRecommendation,
   riddleProofPublicStateMergeRecommendation,
+  riddleProofSemanticScopesEqual,
   riddleRequestJson,
   runCodexExecAgentDoctor,
   runLocalAgentDoctor,