@synapsor/runner 1.5.4 → 1.6.1

package/dist/shadow.mjs

@@ -64,6 +64,8 @@ var protocolVersions = {
   runnerProposal: "synapsor.runner-proposal.v1",
   runnerActivity: "synapsor.runner-activity.v1",
   principalScope: "synapsor.principal-scope.v1",
+  freshnessAuthority: "synapsor.freshness-authority.v1",
+  freshnessProof: "synapsor.freshness-proof.v1",
   legacyWritebackJob: "1.0",
   normalizedWritebackJobV2: "2.0",
   normalizedWritebackJobV3: "3.0",
@@ -111,6 +113,101 @@ var principalScopeGuardSchema = z.object({
     ctx.addIssue({ code: z.ZodIssueCode.custom, message: "principal scope fingerprint does not match its trusted value", path: ["value_fingerprint"] });
   }
 });
+var freshnessDependencyUnsignedSchema = z.object({
+  id: safeIdentifier,
+  capability: z.string().regex(/^[A-Za-z_][A-Za-z0-9_.-]*\.[A-Za-z_][A-Za-z0-9_.-]*$/, "expected reviewed capability name"),
+  source_id: z.string().min(1).max(160),
+  engine: writebackEngineSchema,
+  target: z.object({
+    schema: safeIdentifier,
+    table: safeIdentifier,
+    primary_key: columnValueSchema,
+    tenant_column: safeIdentifier,
+    principal_column: safeIdentifier.optional()
+  }),
+  expected_version: columnValueSchema,
+  evidence: z.object({
+    bundle_id: z.string().min(1).max(200),
+    query_fingerprint: sha256
+  })
+});
+var freshnessDependencyV1Schema = freshnessDependencyUnsignedSchema.extend({
+  descriptor_digest: sha256
+}).superRefine((dependency, ctx) => {
+  const { descriptor_digest: _digest, ...unsigned } = dependency;
+  if (canonicalJsonDigest(unsigned) !== dependency.descriptor_digest) {
+    ctx.addIssue({ code: z.ZodIssueCode.custom, message: "freshness dependency digest mismatch", path: ["descriptor_digest"] });
+  }
+});
+var freshnessAuthorityUnsignedSchema = z.object({
+  schema_version: z.literal(protocolVersions.freshnessAuthority),
+  required: z.literal(true),
+  target: z.object({
+    mode: z.enum(["exact_guard", "frozen_set", "not_applicable"]),
+    member_count: z.number().int().min(0).max(100)
+  }),
+  dependencies: z.array(freshnessDependencyV1Schema).max(16)
+});
+var freshnessAuthorityV1Schema = freshnessAuthorityUnsignedSchema.extend({
+  dependency_set_digest: sha256
+}).superRefine((authority, ctx) => {
+  const identities = authority.dependencies.map((dependency) => dependency.id);
+  if (new Set(identities).size !== identities.length) {
+    ctx.addIssue({ code: z.ZodIssueCode.custom, message: "freshness dependency ids must be unique", path: ["dependencies"] });
+  }
+  const sorted = [...authority.dependencies].sort((left, right) => left.source_id.localeCompare(right.source_id) || left.target.schema.localeCompare(right.target.schema) || left.target.table.localeCompare(right.target.table) || JSON.stringify(left.target.primary_key.value).localeCompare(JSON.stringify(right.target.primary_key.value)) || left.id.localeCompare(right.id));
+  if (JSON.stringify(sorted) !== JSON.stringify(authority.dependencies)) {
+    ctx.addIssue({ code: z.ZodIssueCode.custom, message: "freshness dependencies must use deterministic lock order", path: ["dependencies"] });
+  }
+  const { dependency_set_digest: _digest, ...unsigned } = authority;
+  if (canonicalJsonDigest(unsigned) !== authority.dependency_set_digest) {
+    ctx.addIssue({ code: z.ZodIssueCode.custom, message: "freshness dependency-set digest mismatch", path: ["dependency_set_digest"] });
+  }
+});
+var freshnessCheckStatusSchema = z.enum(["fresh", "stale", "unavailable", "invalid", "unsupported"]);
+var freshnessItemResultSchema = z.object({
+  id: z.string().min(1).max(160),
+  kind: z.enum(["target", "supporting"]),
+  status: z.enum(["fresh", "stale", "not_applicable", "unavailable", "invalid", "unsupported"]),
+  safe_code: z.string().regex(/^[A-Z][A-Z0-9_]*$/),
+  expected_version_digest: sha256.optional(),
+  observed_version_digest: sha256.optional()
+});
+var freshnessProofUnsignedSchema = z.object({
+  schema_version: z.literal(protocolVersions.freshnessProof),
+  proposal_id: z.string().min(1),
+  proposal_hash: sha256,
+  proposal_version: z.number().int().positive(),
+  dependency_set_digest: sha256,
+  checked_at: z.string().datetime(),
+  valid_until: z.string().datetime(),
+  source_adapters: z.array(z.object({
+    source_id: z.string().min(1).max(160),
+    engine: writebackEngineSchema
+  })).min(1).max(8),
+  result: freshnessCheckStatusSchema,
+  safe_code: z.string().regex(/^[A-Z][A-Z0-9_]*$/),
+  target_count: z.number().int().min(0).max(100),
+  supporting_count: z.number().int().min(0).max(16),
+  checks: z.array(freshnessItemResultSchema).max(116)
+});
+var freshnessProofV1Schema = freshnessProofUnsignedSchema.extend({
+  proof_digest: sha256
+}).superRefine((proof, ctx) => {
+  if (Date.parse(proof.valid_until) < Date.parse(proof.checked_at)) {
+    ctx.addIssue({ code: z.ZodIssueCode.custom, message: "freshness proof validity ends before it was checked", path: ["valid_until"] });
+  }
+  if (proof.checks.filter((check) => check.kind === "target").length !== proof.target_count) {
+    ctx.addIssue({ code: z.ZodIssueCode.custom, message: "freshness target count mismatch", path: ["target_count"] });
+  }
+  if (proof.checks.filter((check) => check.kind === "supporting").length !== proof.supporting_count) {
+    ctx.addIssue({ code: z.ZodIssueCode.custom, message: "freshness supporting count mismatch", path: ["supporting_count"] });
+  }
+  const { proof_digest: _digest, ...unsigned } = proof;
+  if (canonicalJsonDigest(unsigned) !== proof.proof_digest) {
+    ctx.addIssue({ code: z.ZodIssueCode.custom, message: "freshness proof digest mismatch", path: ["proof_digest"] });
+  }
+});
 var resolvedDeduplicationComponentSchema = z.object({
   column: safeIdentifier,
   value: scalar,
@@ -240,6 +337,7 @@ var changeSetV1Schema = z.object({
     allowed_columns: z.array(z.string().min(1)).min(1),
     expected_version: columnValueSchema
   }),
+  freshness: freshnessAuthorityV1Schema.optional(),
   evidence: z.object({
     bundle_id: z.string().min(1),
     query_fingerprint: sha256,
@@ -260,6 +358,7 @@ var changeSetV1Schema = z.object({
   }),
   created_at: z.string().min(1)
 }).superRefine((changeSet, ctx) => {
+  validateFreshnessBinding(changeSet.freshness, changeSet.source.source_id, sourceEngine(changeSet.source.kind), "exact_guard", 1, ctx);
   const allowed = new Set(changeSet.guards.allowed_columns);
   for (const column of Object.keys(changeSet.patch)) {
     if (!allowed.has(column)) {
@@ -327,6 +426,7 @@ var changeSetV2Schema = z.object({
     version_advance: versionAdvanceSchema.optional(),
     deduplication: z.object({ components: z.array(resolvedDeduplicationComponentSchema).min(1).max(8) }).optional()
   }),
+  freshness: freshnessAuthorityV1Schema.optional(),
   reversibility: reversibilityRequestSchema.optional(),
   evidence: z.object({
     bundle_id: z.string().min(1),
@@ -346,6 +446,14 @@ var changeSetV2Schema = z.object({
   integrity: z.object({ proposal_hash: sha256 }),
   created_at: z.string().min(1)
 }).superRefine((changeSet, ctx) => {
+  validateFreshnessBinding(
+    changeSet.freshness,
+    changeSet.source.source_id,
+    sourceEngine(changeSet.source.kind),
+    changeSet.operation === "single_row_insert" ? "not_applicable" : "exact_guard",
+    changeSet.operation === "single_row_insert" ? 0 : 1,
+    ctx
+  );
   const allowed = new Set(changeSet.guards.allowed_columns);
   for (const column of Object.keys(changeSet.patch)) {
     if (!allowed.has(column)) ctx.addIssue({ code: z.ZodIssueCode.custom, message: `patch column not allowed: ${column}`, path: ["patch", column] });
@@ -412,6 +520,7 @@ var changeSetV3Schema = z.object({
     expected_version: columnValueSchema.optional(),
     version_advance: versionAdvanceSchema.optional()
   }),
+  freshness: freshnessAuthorityV1Schema.optional(),
   frozen_set: frozenSetSchema,
   reversibility: reversibilityRequestSchema.optional(),
   evidence: z.object({ bundle_id: z.string().min(1), query_fingerprint: sha256, items: z.array(z.unknown()).max(100) }).passthrough(),
@@ -426,6 +535,14 @@ var changeSetV3Schema = z.object({
   integrity: z.object({ proposal_hash: sha256 }),
   created_at: z.string().min(1)
 }).superRefine((changeSet, ctx) => {
+  validateFreshnessBinding(
+    changeSet.freshness,
+    changeSet.source.source_id,
+    sourceEngine(changeSet.source.kind),
+    changeSet.operation === "batch_insert" ? "not_applicable" : "frozen_set",
+    changeSet.operation === "batch_insert" ? 0 : changeSet.frozen_set.row_count,
+    ctx
+  );
   if (changeSet.source.primary_key.value !== void 0 || changeSet.guards.expected_version) ctx.addIssue({ code: z.ZodIssueCode.custom, message: "set guards live on frozen members, not the top-level envelope", path: ["frozen_set"] });
   const allowed = new Set(changeSet.guards.allowed_columns);
   for (const column of Object.keys(changeSet.patch)) if (!allowed.has(column)) ctx.addIssue({ code: z.ZodIssueCode.custom, message: `patch column not allowed: ${column}`, path: ["patch", column] });
@@ -521,6 +638,7 @@ var writebackJobV1Schema = z.object({
   allowed_columns: z.array(safeIdentifier).min(1),
   patch: scalarMap,
   conflict_guard: publicConflictGuardSchema,
+  freshness: freshnessAuthorityV1Schema.optional(),
   idempotency_key: z.string().min(1),
   lease: z.object({
     lease_id: z.string().min(1),
@@ -528,6 +646,7 @@ var writebackJobV1Schema = z.object({
     expires_at: z.string().min(1)
   })
 }).superRefine((job, ctx) => {
+  validateFreshnessBinding(job.freshness, job.runner_scope.source_id, job.engine, "exact_guard", 1, ctx);
   validateAllowedPatchColumns(job.allowed_columns, Object.keys(job.patch), job.target.primary_key.column, job.tenant_guard.column, ctx);
   if (job.principal_scope && job.allowed_columns.includes(job.principal_scope.column)) ctx.addIssue({ code: z.ZodIssueCode.custom, message: "principal scope column must not be patch-allowlisted", path: ["allowed_columns"] });
 });
@@ -549,6 +668,7 @@ var normalizedWritebackJobV1Schema = writebackJobV1Schema.transform((job) => ({
   allowed_columns: job.allowed_columns,
   patch: job.patch,
   conflict_guard: normalizeConflictGuard(job.conflict_guard),
+  ...job.freshness ? { freshness: job.freshness } : {},
   idempotency_key: job.idempotency_key,
   lease_expires_at: job.lease.expires_at,
   attempt_count: job.lease.attempt
@@ -582,10 +702,12 @@ var legacyWritebackJobSchema = z.object({
     z.object({ kind: z.literal("row_hash"), expected_hash: z.string().min(1) }),
     z.object({ kind: z.literal("none") })
   ]),
+  freshness: freshnessAuthorityV1Schema.optional(),
   idempotency_key: z.string().min(1),
   lease_expires_at: z.union([z.string(), z.number()]),
   attempt_count: z.number().int().nonnegative().optional()
 }).superRefine((job, ctx) => {
+  validateFreshnessBinding(job.freshness, job.source_id, job.engine, "exact_guard", 1, ctx);
   validateAllowedPatchColumns(job.allowed_columns, Object.keys(job.patch), job.target.primary_key.column, job.target.tenant_guard.column, ctx);
   if (job.target.principal_scope && job.allowed_columns.includes(job.target.principal_scope.column)) ctx.addIssue({ code: z.ZodIssueCode.custom, message: "principal scope column must not be patch-allowlisted", path: ["allowed_columns"] });
 });
@@ -612,6 +734,7 @@ var normalizedWritebackJobV2InputSchema = z.object({
     z.object({ kind: z.literal("row_hash"), expected_hash: z.string().min(1) }),
     z.object({ kind: z.literal("none") })
   ]),
+  freshness: freshnessAuthorityV1Schema.optional(),
   version_advance: versionAdvanceSchema.optional(),
   deduplication: z.object({ components: z.array(resolvedDeduplicationComponentSchema).min(1).max(8) }).optional(),
   idempotency_key: z.string().min(1),
@@ -619,6 +742,14 @@ var normalizedWritebackJobV2InputSchema = z.object({
   attempt_count: z.number().int().positive(),
   inverse_capture: inverseDescriptorV1Schema.optional()
 }).superRefine((job, ctx) => {
+  validateFreshnessBinding(
+    job.freshness,
+    job.source_id,
+    job.engine,
+    job.operation === "single_row_insert" ? "not_applicable" : "exact_guard",
+    job.operation === "single_row_insert" ? 0 : 1,
+    ctx
+  );
   if (job.operation !== "single_row_insert" && job.target.primary_key.value === void 0) {
     ctx.addIssue({ code: z.ZodIssueCode.custom, message: "UPDATE and DELETE require a primary-key value", path: ["target", "primary_key", "value"] });
   }
@@ -684,6 +815,7 @@ var writebackJobV2Schema = z.object({
   principal_scope: principalScopeGuardSchema.optional(),
   allowed_columns: z.array(safeIdentifier),
   mutation: writebackMutationV2Schema,
+  freshness: freshnessAuthorityV1Schema.optional(),
   idempotency_key: z.string().min(1),
   inverse_capture: inverseDescriptorV1Schema.optional(),
   lease: z.object({
@@ -692,6 +824,14 @@ var writebackJobV2Schema = z.object({
     expires_at: z.string().min(1)
   })
 }).superRefine((job, ctx) => {
+  validateFreshnessBinding(
+    job.freshness,
+    job.runner_scope.source_id,
+    job.engine,
+    job.mutation.kind === "single_row_insert" ? "not_applicable" : "exact_guard",
+    job.mutation.kind === "single_row_insert" ? 0 : 1,
+    ctx
+  );
   const mutation = job.mutation;
   if (mutation.kind !== "single_row_insert" && job.target.primary_key.value === void 0) {
     ctx.addIssue({ code: z.ZodIssueCode.custom, message: "UPDATE and DELETE require a primary-key value", path: ["target", "primary_key", "value"] });
@@ -730,6 +870,7 @@ var writebackJobV2Schema = z.object({
   conflict_guard: job.mutation.kind === "single_row_insert" ? { kind: "none" } : normalizeConflictGuard(job.mutation.conflict_guard),
   ...job.mutation.kind === "single_row_update" && job.mutation.version_advance ? { version_advance: job.mutation.version_advance } : {},
   ...job.mutation.kind === "single_row_insert" ? { deduplication: job.mutation.deduplication } : {},
+  ...job.freshness ? { freshness: job.freshness } : {},
   idempotency_key: job.idempotency_key,
   ...job.inverse_capture ? { inverse_capture: job.inverse_capture } : {},
   lease_expires_at: job.lease.expires_at,
@@ -748,6 +889,7 @@ var normalizedWritebackJobV3InputSchema = z.object({
   allowed_columns: z.array(safeIdentifier).max(256),
   patch: boundedScalarRecord,
   conflict_guard: z.object({ kind: z.literal("none") }).default({ kind: "none" }),
+  freshness: freshnessAuthorityV1Schema.optional(),
   version_advance: versionAdvanceSchema.optional(),
   frozen_set: frozenSetSchema,
   idempotency_key: z.string().min(1),
@@ -755,6 +897,14 @@ var normalizedWritebackJobV3InputSchema = z.object({
   attempt_count: z.number().int().positive(),
   inverse_capture: inverseDescriptorV1Schema.optional()
 }).superRefine((job, ctx) => {
+  validateFreshnessBinding(
+    job.freshness,
+    job.source_id,
+    job.engine,
+    job.operation === "batch_insert" ? "not_applicable" : "frozen_set",
+    job.operation === "batch_insert" ? 0 : job.frozen_set.row_count,
+    ctx
+  );
   if (job.target.principal_scope && job.allowed_columns.includes(job.target.principal_scope.column)) ctx.addIssue({ code: z.ZodIssueCode.custom, message: "principal scope column must not be patch-allowlisted", path: ["allowed_columns"] });
   if (job.operation === "set_delete" && (job.allowed_columns.length || Object.keys(job.patch).length || job.version_advance)) ctx.addIssue({ code: z.ZodIssueCode.custom, message: "set DELETE cannot carry patch authority", path: ["patch"] });
   if (job.operation === "set_update" && (!Object.keys(job.patch).length || !job.version_advance)) ctx.addIssue({ code: z.ZodIssueCode.custom, message: "set UPDATE requires patch and version advance", path: ["patch"] });
@@ -776,9 +926,19 @@ var writebackJobV3Schema = z.object({
   patch: boundedScalarRecord,
   version_advance: versionAdvanceSchema.optional(),
   frozen_set: frozenSetSchema,
+  freshness: freshnessAuthorityV1Schema.optional(),
   idempotency_key: z.string().min(1),
   inverse_capture: inverseDescriptorV1Schema.optional(),
   lease: z.object({ lease_id: z.string().min(1), attempt: z.number().int().positive(), expires_at: z.string().min(1) })
+}).superRefine((job, ctx) => {
+  validateFreshnessBinding(
+    job.freshness,
+    job.runner_scope.source_id,
+    job.engine,
+    job.operation === "batch_insert" ? "not_applicable" : "frozen_set",
+    job.operation === "batch_insert" ? 0 : job.frozen_set.row_count,
+    ctx
+  );
 }).transform((job) => ({
   protocol_version: protocolVersions.normalizedWritebackJobV3,
   job_id: job.writeback_job_id,
@@ -793,6 +953,7 @@ var writebackJobV3Schema = z.object({
   conflict_guard: { kind: "none" },
   ...job.version_advance ? { version_advance: job.version_advance } : {},
   frozen_set: job.frozen_set,
+  ...job.freshness ? { freshness: job.freshness } : {},
   idempotency_key: job.idempotency_key,
   ...job.inverse_capture ? { inverse_capture: job.inverse_capture } : {},
   lease_expires_at: job.lease.expires_at,
@@ -1146,6 +1307,38 @@ var runnerActivityV1Schema = z.object({
   detail: z.record(z.unknown()).optional(),
   occurred_at: z.string().min(1).max(80).optional()
 }).strict();
+function sourceEngine(kind) {
+  if (kind === "external_postgres") return "postgres";
+  if (kind === "external_mysql") return "mysql";
+  return void 0;
+}
+function validateFreshnessBinding(freshness, sourceId, engine, expectedTargetMode, expectedMemberCount, ctx) {
+  if (!freshness) return;
+  if (!engine) {
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      message: "freshness authority requires an external PostgreSQL or MySQL source",
+      path: ["freshness"]
+    });
+    return;
+  }
+  if (freshness.target.mode !== expectedTargetMode || freshness.target.member_count !== expectedMemberCount) {
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      message: `freshness target authority must be ${expectedTargetMode} with ${expectedMemberCount} reviewed member(s)`,
+      path: ["freshness", "target"]
+    });
+  }
+  for (const [index, dependency] of freshness.dependencies.entries()) {
+    if (dependency.source_id !== sourceId || dependency.engine !== engine) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: "freshness dependencies must use the proposal/writeback source and engine",
+        path: ["freshness", "dependencies", index, "source_id"]
+      });
+    }
+  }
+}
 function validateAllowedPatchColumns(allowedColumns, patchColumns, primaryKeyColumn, tenantGuardColumn, ctx) {
   const allow = new Set(allowedColumns);
   for (const column of patchColumns) {
@@ -1206,6 +1399,12 @@ function normalizeConflictGuard(guard) {
 function parseChangeSet(input) {
   return z.union([changeSetV1Schema, changeSetV2Schema, changeSetV3Schema, compensationChangeSetV1Schema]).parse(input);
 }
+function parseFreshnessAuthority(input) {
+  return freshnessAuthorityV1Schema.parse(input);
+}
+function parseFreshnessProof(input) {
+  return freshnessProofV1Schema.parse(input);
+}
 function parseWritebackJob(input) {
   return writebackJobSchema.parse(input);
 }
@@ -1395,6 +1594,7 @@ var ProposalStore = class {
         decision_hash TEXT,
         signature TEXT,
         integrity_hash TEXT,
+        freshness_proof_digest TEXT,
         created_at TEXT NOT NULL,
         FOREIGN KEY (proposal_id) REFERENCES proposals(proposal_id)
       );
@@ -1668,6 +1868,7 @@ var ProposalStore = class {
     this.ensureColumn("approvals", "decision_hash", "TEXT");
     this.ensureColumn("approvals", "signature", "TEXT");
     this.ensureColumn("approvals", "integrity_hash", "TEXT");
+    this.ensureColumn("approvals", "freshness_proof_digest", "TEXT");
   }
   ensureSearchIndexes() {
     this.db.exec(`
@@ -1958,6 +2159,75 @@ var ProposalStore = class {
     const row = this.db.prepare("SELECT proposal_id FROM query_audit WHERE evidence_bundle_id = ? AND proposal_id IS NOT NULL ORDER BY created_at DESC LIMIT 1").get(evidenceBundleId);
     return isRecord(row) && row.proposal_id != null ? String(row.proposal_id) : void 0;
   }
+  recordFreshnessProof(input) {
+    const proof = parseFreshnessProof(input);
+    const proposal = this.requireProposal(proof.proposal_id);
+    assertProposalIdentity(proposal, proof.proposal_hash, proof.proposal_version);
+    const authority = proposalFreshnessAuthority(proposal);
+    if (!authority) {
+      throw new ProposalStoreError(
+        "FRESHNESS_NOT_REQUIRED",
+        `proposal ${proof.proposal_id} has no reviewed freshness authority`
+      );
+    }
+    if (proof.dependency_set_digest !== authority.dependency_set_digest) {
+      throw new ProposalStoreError(
+        "FRESHNESS_PROOF_AUTHORITY_MISMATCH",
+        `freshness proof does not match proposal ${proof.proposal_id}`
+      );
+    }
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    this.transaction(() => {
+      this.appendEvent(proof.proposal_id, "proposal_freshness_checked", "runner", { proof });
+      if (proof.result === "stale") {
+        const current = this.requireProposal(proof.proposal_id);
+        if (current.state === "pending_review" || current.state === "approved" || current.state === "pending_worker") {
+          this.db.prepare("UPDATE proposals SET state = ?, updated_at = ? WHERE proposal_id = ?").run("conflict", now, proof.proposal_id);
+          this.appendEvent(proof.proposal_id, "proposal_conflict", "runner", {
+            reason: "freshness_stale",
+            safe_code: proof.safe_code,
+            proof_digest: proof.proof_digest
+          });
+        }
+      }
+    });
+    return proof;
+  }
+  latestFreshnessProof(proposalId) {
+    this.requireProposal(proposalId);
+    const row = this.db.prepare(`
+      SELECT payload_json
+      FROM proposal_events
+      WHERE proposal_id = ? AND kind = 'proposal_freshness_checked'
+      ORDER BY event_id DESC
+      LIMIT 1
+    `).get(proposalId);
+    if (!isRecord(row)) return void 0;
+    try {
+      const payload = JSON.parse(String(row.payload_json));
+      return parseFreshnessProof(payload.proof);
+    } catch {
+      throw new ProposalStoreError(
+        "FRESHNESS_PROOF_TAMPERED",
+        `stored freshness proof for proposal ${proposalId} failed integrity validation`
+      );
+    }
+  }
+  recordFreshnessApprovalBlocked(proposalId, input) {
+    this.requireProposal(proposalId);
+    const proof = this.latestFreshnessProof(proposalId);
+    if (!proof || proof.proof_digest !== input.proof_digest || proof.result === "fresh") {
+      throw new ProposalStoreError(
+        "FRESHNESS_BLOCK_RECORD_INVALID",
+        `freshness block for proposal ${proposalId} does not match its latest non-fresh proof`
+      );
+    }
+    this.appendEvent(proposalId, "proposal_approval_blocked_freshness", input.actor, {
+      proof_digest: proof.proof_digest,
+      safe_code: input.safe_code,
+      result: proof.result
+    });
+  }
   approveProposal(proposalId, options) {
     const proposal = this.requireProposal(proposalId);
     assertWritebackAllowed(proposal, "approved");
@@ -1978,11 +2248,12 @@ var ProposalStore = class {
       if (isRecord(existing)) {
         throw new ProposalStoreError("APPROVER_ALREADY_COUNTED", `operator ${options.approver} already recorded a decision for proposal ${proposalId}`);
       }
+      this.assertApprovalFreshness(current, options.freshness_proof_digest, now);
       this.db.prepare(`
         INSERT INTO approvals (
           proposal_id, proposal_version, proposal_hash, approver, status, reason,
-          identity_json, decision_hash, signature, integrity_hash, created_at
-        ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+          identity_json, decision_hash, signature, integrity_hash, freshness_proof_digest, created_at
+        ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
       `).run(
         proposalId,
         options.proposal_version,
@@ -1994,6 +2265,7 @@ var ProposalStore = class {
         options.identity?.decision_hash ?? null,
         options.identity?.signature ?? null,
         options.identity?.integrity_hash ?? null,
+        options.freshness_proof_digest ?? null,
         now
       );
       const progress = this.approvalProgress(proposalId);
@@ -2006,6 +2278,7 @@ var ProposalStore = class {
         proposal_version: options.proposal_version,
         reason: options.reason ?? null,
         identity: publicIdentitySummary(options.identity),
+        freshness_proof_digest: options.freshness_proof_digest ?? null,
         approvals: progress.approved,
         required_approvals: progress.required,
         remaining_approvals: progress.remaining
@@ -2114,17 +2387,31 @@ var ProposalStore = class {
         });
         return;
       }
+      this.assertApprovalFreshness(proposal, options.freshness_proof_digest, now);
       this.db.prepare("UPDATE proposals SET state = ?, updated_at = ? WHERE proposal_id = ?").run("approved", now, proposalId);
       this.db.prepare(`
-        INSERT INTO approvals (proposal_id, proposal_version, proposal_hash, approver, status, reason, created_at)
-        VALUES (?, ?, ?, ?, ?, ?, ?)
-      `).run(proposalId, options.proposal_version, options.proposal_hash, actor, "approved", options.reason, now);
+        INSERT INTO approvals (
+          proposal_id, proposal_version, proposal_hash, approver, status, reason,
+          freshness_proof_digest, created_at
+        )
+        VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+      `).run(
+        proposalId,
+        options.proposal_version,
+        options.proposal_hash,
+        actor,
+        "approved",
+        options.reason,
+        options.freshness_proof_digest ?? null,
+        now
+      );
       this.appendEvent(proposalId, "proposal_approved", actor, {
         proposal_hash: options.proposal_hash,
         proposal_version: options.proposal_version,
         reason: options.reason,
         policy: options.policy,
-        aggregate_limits: options.limits ?? []
+        aggregate_limits: options.limits ?? [],
+        freshness_proof_digest: options.freshness_proof_digest ?? null
       });
     });
     return {
@@ -2472,7 +2759,8 @@ var ProposalStore = class {
       writeback_job_id: receipt.writeback_job_id,
       rows_affected: receipt.rows_affected,
       source_database_mutated: receipt.source_database_mutated,
-      receipt_hash: receipt.receipt_hash
+      receipt_hash: receipt.receipt_hash,
+      safe_error_code: "safe_error_code" in receipt ? receipt.safe_error_code ?? null : null
     });
   }
   recordHandlerWritebackJob(input) {
@@ -2556,6 +2844,7 @@ var ProposalStore = class {
       tenant_guard: changeSet.guards.tenant,
       ...changeSet.guards.principal_scope ? { principal_scope: changeSet.guards.principal_scope } : {},
       allowed_columns: changeSet.guards.allowed_columns,
+      ..."freshness" in changeSet && changeSet.freshness ? { freshness: parseFreshnessAuthority(changeSet.freshness) } : {},
       idempotency_key: `${proposal.proposal_id}:${proposal.object_id}`,
       lease
     };
@@ -3009,7 +3298,21 @@ var ProposalStore = class {
       const key = `${tenantId}\0${capability}`;
       let row = rows.get(key);
       if (!row) {
-        row = { tenant_id: tenantId, capability, worker_retries: 0, dead_letters: 0, auto_approval_limit_trips: 0 };
+        row = {
+          tenant_id: tenantId,
+          capability,
+          worker_retries: 0,
+          dead_letters: 0,
+          auto_approval_limit_trips: 0,
+          freshness_checks: 0,
+          freshness_fresh: 0,
+          freshness_stale_target: 0,
+          freshness_stale_supporting: 0,
+          freshness_unavailable: 0,
+          freshness_unsupported: 0,
+          freshness_approval_blocked: 0,
+          freshness_apply_blocked: 0
+        };
         rows.set(key, row);
       }
       return row;
@@ -3017,7 +3320,14 @@ var ProposalStore = class {
     const events = this.db.prepare(`
       SELECT p.tenant_id, p.action, e.kind, e.payload_json
       FROM proposal_events e JOIN proposals p ON p.proposal_id = e.proposal_id
-      WHERE e.kind IN ('writeback_retry_scheduled', 'writeback_dead_lettered', 'policy_auto_approval_deferred')
+      WHERE e.kind IN (
+        'writeback_retry_scheduled',
+        'writeback_dead_lettered',
+        'policy_auto_approval_deferred',
+        'proposal_freshness_checked',
+        'proposal_approval_blocked_freshness',
+        'writeback_conflict'
+      )
         AND (? IS NULL OR p.tenant_id = ?)
         AND (? IS NULL OR p.action = ?)
     `).all(filters.tenant ?? null, filters.tenant ?? null, filters.capability ?? null, filters.capability ?? null);
@@ -3026,13 +3336,29 @@ var ProposalStore = class {
       const row = ensure(String(raw.tenant_id), String(raw.action));
       if (raw.kind === "writeback_retry_scheduled") row.worker_retries += 1;
       if (raw.kind === "writeback_dead_lettered") row.dead_letters += 1;
-      if (raw.kind === "policy_auto_approval_deferred") {
-        try {
-          const payload = JSON.parse(String(raw.payload_json));
-          if (Array.isArray(payload.tripped_limits) && payload.tripped_limits.length > 0) row.auto_approval_limit_trips += 1;
-        } catch {
+      let payload = {};
+      try {
+        const parsed = JSON.parse(String(raw.payload_json));
+        if (isRecord(parsed)) payload = parsed;
+      } catch {
+      }
+      if (raw.kind === "proposal_freshness_checked") {
+        row.freshness_checks += 1;
+        const proof = isRecord(payload.proof) ? payload.proof : {};
+        if (proof.result === "fresh") row.freshness_fresh += 1;
+        if (proof.result === "unavailable") row.freshness_unavailable += 1;
+        if (proof.result === "unsupported") row.freshness_unsupported += 1;
+        if (proof.result === "stale") {
+          const checks = Array.isArray(proof.checks) ? proof.checks.filter(isRecord) : [];
+          if (checks.some((check) => check.kind === "target" && check.status === "stale")) row.freshness_stale_target += 1;
+          if (checks.some((check) => check.kind === "supporting" && check.status === "stale")) row.freshness_stale_supporting += 1;
         }
       }
+      if (raw.kind === "proposal_approval_blocked_freshness") row.freshness_approval_blocked += 1;
+      if (raw.kind === "writeback_conflict" && /^FRESHNESS_/.test(String(payload.safe_error_code ?? ""))) row.freshness_apply_blocked += 1;
+      if (raw.kind === "policy_auto_approval_deferred") {
+        if (Array.isArray(payload.tripped_limits) && payload.tripped_limits.length > 0) row.auto_approval_limit_trips += 1;
+      }
     }
     return [...rows.values()].sort((left, right) => left.tenant_id.localeCompare(right.tenant_id) || left.capability.localeCompare(right.capability));
   }
@@ -3880,6 +4206,61 @@ var ProposalStore = class {
     }
     return proposal;
   }
+  assertApprovalFreshness(proposal, proofDigest, now) {
+    const authority = proposalFreshnessAuthority(proposal);
+    if (!authority) {
+      if (proofDigest !== void 0) {
+        throw new ProposalStoreError(
+          "FRESHNESS_PROOF_UNEXPECTED",
+          `proposal ${proposal.proposal_id} does not require a freshness proof`
+        );
+      }
+      return;
+    }
+    if (!proofDigest) {
+      throw new ProposalStoreError(
+        "FRESHNESS_PROOF_REQUIRED",
+        `proposal ${proposal.proposal_id} requires a fresh live proof before approval`
+      );
+    }
+    const proof = this.latestFreshnessProof(proposal.proposal_id);
+    if (!proof || proof.proof_digest !== proofDigest) {
+      throw new ProposalStoreError(
+        "FRESHNESS_PROOF_MISSING",
+        `the latest freshness proof for proposal ${proposal.proposal_id} was not supplied`
+      );
+    }
+    if (proof.proposal_hash !== proposal.proposal_hash || proof.proposal_version !== proposal.proposal_version || proof.dependency_set_digest !== authority.dependency_set_digest) {
+      throw new ProposalStoreError(
+        "FRESHNESS_PROOF_AUTHORITY_MISMATCH",
+        `freshness proof does not match proposal ${proposal.proposal_id}`
+      );
+    }
+    if (proof.result !== "fresh") {
+      throw new ProposalStoreError(
+        proof.result === "stale" ? "FRESHNESS_STALE" : "FRESHNESS_NOT_VERIFIED",
+        `proposal ${proposal.proposal_id} freshness result is ${proof.result}`
+      );
+    }
+    if (Date.parse(proof.valid_until) < Date.parse(now)) {
+      throw new ProposalStoreError(
+        "FRESHNESS_PROOF_EXPIRED",
+        `freshness proof for proposal ${proposal.proposal_id} has expired`
+      );
+    }
+    const used = this.db.prepare(`
+      SELECT approval_id
+      FROM approvals
+      WHERE proposal_id = ? AND freshness_proof_digest = ?
+      LIMIT 1
+    `).get(proposal.proposal_id, proofDigest);
+    if (isRecord(used)) {
+      throw new ProposalStoreError(
+        "FRESHNESS_PROOF_ALREADY_USED",
+        `freshness proof for proposal ${proposal.proposal_id} already authorized a reviewer decision`
+      );
+    }
+  }
   setState(proposalId, state, actor, payload) {
     const now = (/* @__PURE__ */ new Date()).toISOString();
     this.transaction(() => {
@@ -4040,6 +4421,17 @@ function stateFromChangeSet(changeSet) {
   if (changeSet.approval.status === "canceled") return "canceled";
   return "pending_review";
 }
+function proposalFreshnessAuthority(proposal) {
+  if (!("freshness" in proposal.change_set) || proposal.change_set.freshness === void 0) return void 0;
+  try {
+    return parseFreshnessAuthority(proposal.change_set.freshness);
+  } catch {
+    throw new ProposalStoreError(
+      "FRESHNESS_AUTHORITY_TAMPERED",
+      `stored freshness authority for proposal ${proposal.proposal_id} failed integrity validation`
+    );
+  }
+}
 function requiredApprovalCount(proposal) {
   const configured = proposal.change_set.approval.required_approvals;
   return typeof configured === "number" && Number.isSafeInteger(configured) && configured >= 1 ? configured : 1;
@@ -4566,6 +4958,7 @@ function rowToApproval(row) {
     decision_hash: row.decision_hash == null ? void 0 : String(row.decision_hash),
     signature: row.signature == null ? void 0 : String(row.signature),
     integrity_hash: row.integrity_hash == null ? void 0 : String(row.integrity_hash),
+    freshness_proof_digest: row.freshness_proof_digest == null ? void 0 : String(row.freshness_proof_digest),
     created_at: String(row.created_at)
   };
 }
@@ -4942,7 +5335,7 @@ var sharedLedgerRestoreSpecs = {
     "updated_at"
   ], ["proposal_id", "proposal_version", "proposal_hash", "action", "state", "tenant_id", "business_object", "object_id", "source_kind", "source_id", "source_schema", "source_table", "source_database_mutated", "change_set_json", "created_at", "updated_at"]),
   proposal_events: restoreSpec("event_id", ["event_id", "proposal_id", "kind", "actor", "payload_json", "created_at"], ["event_id", "proposal_id", "kind", "actor", "payload_json", "created_at"]),
-  approvals: restoreSpec("approval_id", ["approval_id", "proposal_id", "proposal_version", "proposal_hash", "approver", "status", "reason", "identity_json", "decision_hash", "signature", "integrity_hash", "created_at"], ["approval_id", "proposal_id", "proposal_version", "proposal_hash", "approver", "status", "created_at"]),
+  approvals: restoreSpec("approval_id", ["approval_id", "proposal_id", "proposal_version", "proposal_hash", "approver", "status", "reason", "identity_json", "decision_hash", "signature", "integrity_hash", "freshness_proof_digest", "created_at"], ["approval_id", "proposal_id", "proposal_version", "proposal_hash", "approver", "status", "created_at"]),
   writeback_jobs: restoreSpec("writeback_job_id", ["writeback_job_id", "proposal_id", "proposal_hash", "status", "job_json", "created_at", "updated_at"], ["writeback_job_id", "proposal_id", "proposal_hash", "status", "job_json", "created_at", "updated_at"]),
   writeback_intents: restoreSpec("intent_id", ["intent_id", "idempotency_key", "writeback_job_id", "proposal_id", "proposal_hash", "runner_id", "operation", "status", "intent_json", "result_json", "reconciliation_reason", "created_at", "updated_at"], ["intent_id", "idempotency_key", "writeback_job_id", "proposal_id", "proposal_hash", "runner_id", "operation", "status", "intent_json", "created_at", "updated_at"]),
   idempotency_receipts: restoreSpec("idempotency_key", ["idempotency_key", "writeback_job_id", "proposal_id", "receipt_status", "receipt_json", "created_at"], ["idempotency_key", "writeback_job_id", "proposal_id", "receipt_status", "receipt_json", "created_at"]),