refactor(control-plane): one owner for the stored digest shape in TypeScript

loopx/control_plane/agents/supervisor_event_append.ts

@@ -2,6 +2,7 @@
 import type {JsonObject} from "../effect_program.ts";
 import {requireJsonObject, requireNonEmptyString} from "../runtime_decode.ts";
 import {EffectRuntimeRequestError} from "../effect_runtime_errors.ts";
+import { BARE_SHA256_PATTERN } from "../content_digest.ts";
 
 function sequence(value: unknown, minimum: number): number {
   if (typeof value !== "number" || !Number.isSafeInteger(value) || value < minimum) {
@@ -12,7 +13,7 @@ function sequence(value: unknown, minimum: number): number {
 function identity(value: unknown) {
   const row = requireJsonObject(value, "supervisor event identity");
   const fingerprint = requireNonEmptyString(row.fingerprint, "event fingerprint");
-  if (!/^[a-f0-9]{64}$/.test(fingerprint)) throw new EffectRuntimeRequestError("invalid event fingerprint");
+  if (!BARE_SHA256_PATTERN.test(fingerprint)) throw new EffectRuntimeRequestError("invalid event fingerprint");
   return {event_id: requireNonEmptyString(row.event_id, "event_id"), fingerprint};
 }
 export function planSupervisorEventAppend(value: unknown): JsonObject {

loopx/control_plane/capabilities/external_evidence.ts

@@ -7,6 +7,7 @@ import {
   requireNonEmptyString,
   requireStringLiteral,
 } from "../runtime_decode.ts";
+import { ENVELOPED_SHA256_PATTERN } from "../content_digest.ts";
 
 export const EXTERNAL_EVIDENCE_REQUEST_SCHEMA_VERSION =
   "loopx_external_evidence_request_v0";
@@ -27,7 +28,7 @@ const PROVIDER_KINDS = ["method", "connector"] as const;
 const RECEIPT_STATUSES = ["succeeded", "failed", "no_evidence"] as const;
 const EVIDENCE_BASES = ["stated", "observed", "tested", "inferred"] as const;
 const ADMISSION_DECISIONS = ["admit", "reject"] as const;
-const SHA256_RE = /^sha256:[0-9a-f]{64}$/;
+const SHA256_RE = ENVELOPED_SHA256_PATTERN;
 const PROVIDER_ID_RE = /^[a-z][a-z0-9_.:-]{1,95}$/;
 const SOURCE_REF_RE = /^(https?:\/\/|[a-z][a-z0-9+.-]*:\/\/|urn:)/;
 

loopx/control_plane/collaboration/delegation.ts

@@ -7,6 +7,7 @@ import {canonicalAuthoritySha256} from "../coordination/authority_store_codec.ts
 import {acceptanceValidationEffects, type AcceptanceCompletionRequirements} from "../goals/acceptance_contract.ts";
 import {normalizeTodoCompletionValidationDeclaration} from "../todos/completion_validation_declaration.ts";
 import {readTurnSelectionRejection, turnSelectionRejectionState} from "../turn_driver/selection_rejection.ts";
+import { BARE_SHA256_PATTERN, ENVELOPED_SHA256_PATTERN } from "../content_digest.ts";
 
 function requireThat(ok: unknown, message: string): asserts ok {
   if (!ok) throw new EffectRuntimeRequestError(message);
@@ -99,7 +100,7 @@ export function delegationTurnPlanDecision(params: JsonObject): JsonObject {
   };
   const transaction = requireJsonObject(plan.transaction, "Turn plan transaction");
   requireThat(typeof transaction.turn_key === "string"
-    && /^sha256:[a-f0-9]{64}$/.test(transaction.turn_key), "Turn plan transaction requires a valid turn_key");
+    && ENVELOPED_SHA256_PATTERN.test(transaction.turn_key), "Turn plan transaction requires a valid turn_key");
   return {
     schema_version: "loopx_delegation_turn_plan_decision_v0",
     state: "planned",
@@ -286,15 +287,15 @@ export function delegationInventoryQuery(params: JsonObject): JsonObject {
   const cursor = params.cursor ?? null;
   requireThat(Number.isInteger(limit) && Number(limit) >= 1 && Number(limit) <= 50,
     "delegation inventory limit must be between 1 and 50");
-  requireThat(cursor === null || (typeof cursor === "string" && /^[a-f0-9]{64}$/.test(cursor)),
+  requireThat(cursor === null || (typeof cursor === "string" && BARE_SHA256_PATTERN.test(cursor)),
     "invalid delegation inventory cursor");
   return {limit, cursor};
 }
 
 /** The host supplies a fresh Delegations.read result, never a saved status. */
 export function delegationInventoryItem(params: JsonObject): JsonObject {
   const record = requireJsonObject(params.record, "delegation inventory record");
-  requireThat(typeof record.record_id === "string" && /^[a-f0-9]{64}$/.test(record.record_id),
+  requireThat(typeof record.record_id === "string" && BARE_SHA256_PATTERN.test(record.record_id),
     "invalid delegation record address");
   requireThat(record.operation_id === null || (typeof record.operation_id === "string"
     && /^[A-Za-z0-9][A-Za-z0-9._-]{0,159}$/.test(record.operation_id)), "invalid delegation operation identity");
@@ -323,7 +324,7 @@ export function delegationInventoryItem(params: JsonObject): JsonObject {
     result.artifacts = observation.artifacts.map(value => {
       const artifact = requireJsonObject(value, "accepted artifact");
       requireThat(text(artifact.ref) && typeof artifact.sha256 === "string"
-        && /^[a-f0-9]{64}$/.test(artifact.sha256), "invalid accepted artifact reference");
+        && BARE_SHA256_PATTERN.test(artifact.sha256), "invalid accepted artifact reference");
       return {ref: artifact.ref, sha256: artifact.sha256};
     });
   }

loopx/control_plane/collaboration/return_delivery.ts

@@ -5,13 +5,14 @@ import {
   requireJsonObject,
   requireNonEmptyString,
 } from "../runtime_decode.ts";
+import { ENVELOPED_SHA256_PATTERN } from "../content_digest.ts";
 
 export const MANAGER_RETURN_DELIVERY_ATTEMPT_SCHEMA =
   "manager_return_delivery_attempt_v0";
 
 const PROVIDER = /^[a-z][a-z0-9_-]{0,31}$/;
 const OPAQUE_REF = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,511}$/;
-const DIGEST = /^sha256:[0-9a-f]{64}$/;
+const DIGEST = ENVELOPED_SHA256_PATTERN;
 const ATTEMPT_KEYS = [
   "schema_version",
   "provider",

loopx/control_plane/collaboration/semantic_request.ts

@@ -1,6 +1,7 @@
 import type { JsonObject } from "../effect_program.ts";
 import { EffectRuntimeRequestError } from "../effect_runtime_errors.ts";
 import { requireJsonObject, requireNonEmptyString } from "../runtime_decode.ts";
+import { BARE_SHA256_PATTERN } from "../content_digest.ts";
 
 const ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,159}$/;
 
@@ -55,7 +56,7 @@ export function normalizeCollaborationBrief(value: unknown): JsonObject {
     const ref = workspaceRef(input.ref);
     const result: JsonObject = { ref, description: text(input.description, "input.description", 1000) };
     if (input.sha256 !== undefined) {
-      if (typeof input.sha256 !== "string" || !/^[a-f0-9]{64}$/.test(input.sha256)) {
+      if (typeof input.sha256 !== "string" || !BARE_SHA256_PATTERN.test(input.sha256)) {
         throw new EffectRuntimeRequestError("input.sha256 must be a SHA256 digest");
       }
       result.sha256 = input.sha256;

loopx/control_plane/content_digest.ts

@@ -0,0 +1,3 @@
+/** One owner for the two shapes a stored SHA-256 digest takes in a record. */
+export const ENVELOPED_SHA256_PATTERN = /^sha256:[0-9a-f]{64}$/;
+export const BARE_SHA256_PATTERN = /^[0-9a-f]{64}$/;

loopx/control_plane/coordination/authority_archive_read.ts

@@ -8,10 +8,11 @@ import type {AuthorityStoreCommittedTransaction} from "./authority_store.ts";
 import {AuthorityStoreProtocolError, canonicalAuthorityObject, canonicalAuthorityObjectList,
   canonicalAuthoritySha256, hasExactAuthorityKeys, requireAuthorityStoreId} from "./authority_store_codec.ts";
 import {AuthorityStateReplay, decodeAuthorityStateDelta} from "./authority_state_log.ts";
+import { BARE_SHA256_PATTERN } from "../content_digest.ts";
 
 export const AUTHORITY_ARCHIVE_SCHEMA = "loopx_authority_archive_v0";
 const MAX_LINE_BYTES = 64 * 1024 * 1024;
-const HEX = /^[0-9a-f]{64}$/;
+const HEX = BARE_SHA256_PATTERN;
 export interface ArchiveHeader extends JsonObject {
   kind: "header";
   schema_version: typeof AUTHORITY_ARCHIVE_SCHEMA;

loopx/control_plane/coordination/authority_source.ts

@@ -5,6 +5,7 @@ import {readFile} from "node:fs/promises";
 import {isAbsolute} from "node:path";
 import type {JsonObject} from "../effect_program.ts";
 import {requireJsonObject} from "../runtime_decode.ts";
+import { BARE_SHA256_PATTERN } from "../content_digest.ts";
 
 export type AuthoritySourceCheck = () => Promise<boolean>;
 /** Legacy wires and service-owned callers retain their existing fact contract. */
@@ -25,7 +26,7 @@ export function registryAuthoritySourceCheck(
   }
   const source = requireJsonObject(input.registry_source, "registry_source");
   if (typeof source.path !== "string" || !isAbsolute(source.path) ||
-      typeof source.sha256 !== "string" || !/^[a-f0-9]{64}$/u.test(source.sha256)) {
+      typeof source.sha256 !== "string" || !BARE_SHA256_PATTERN.test(source.sha256)) {
     throw new TypeError("registry_source requires an absolute path and SHA-256 digest");
   }
   // Copy primitive values: later mutation of the decoded request cannot change

loopx/control_plane/coordination/local_authority_migration.ts

@@ -18,6 +18,7 @@ import {FileAuthorityStore, syncAuthorityDirectory} from "./file_authority_store
 import {SqliteAuthorityStore} from "./sqlite_authority_store.ts";
 import {localAuthorityProviderPaths, openLocalAuthorityStoreHandle, publishLocalAuthoritySelection,
   requireLocalAuthorityRuntimeRoot} from "./local_authority_provider.ts";
+import { BARE_SHA256_PATTERN } from "../content_digest.ts";
 
 type Provider = "file" | "sqlite";
 interface Source extends JsonObject {
@@ -43,7 +44,7 @@ interface Recovery extends JsonObject {
   target_store_identity: string;
   archive_sha256: string;
 }
-const HEX = /^[0-9a-f]{64}$/;
+const HEX = BARE_SHA256_PATTERN;
 function provider(value: unknown): Provider {
   if (value !== "file" && value !== "sqlite") throw new Error("Local migration requires file or sqlite");
   return value;

loopx/control_plane/coordination/local_authority_shadow.ts

@@ -42,6 +42,7 @@ import {
   LOCAL_AUTHORITY_SHADOW_TRANSACTION_PROJECTION_SCHEMA,
   LOCAL_AUTHORITY_SHADOW_TRANSACTION_RECEIPT_SCHEMA,
 } from "./coordination_state_contract.generated.ts";
+import { ENVELOPED_SHA256_PATTERN } from "../content_digest.ts";
 
 export {
   LOCAL_AUTHORITY_SHADOW_EVIDENCE_SCHEMA,
@@ -113,7 +114,7 @@ const READ_REQUEST_FIELDS = new Set([
   "scan_limit",
 ]);
 const ENTRY_ID_PATTERN = /^local-shadow-tx-[0-9a-f]{64}$/u;
-const DIGEST_PATTERN = /^sha256:[a-f0-9]{64}$/u;
+const DIGEST_PATTERN = ENVELOPED_SHA256_PATTERN;
 const MAX_SCAN_LIMIT = 10000;
 const REVISION_RETRY_ATTEMPTS = 3;
 

loopx/control_plane/coordination/local_authority_shadow_outbox.ts

@@ -14,6 +14,7 @@ import {
   LOCAL_AUTHORITY_SHADOW_OUTBOX_COMMIT_SCHEMA,
   LOCAL_AUTHORITY_SHADOW_OUTBOX_ENTRY_SCHEMA,
 } from "./coordination_state_contract.generated.ts";
+import { ENVELOPED_SHA256_PATTERN } from "../content_digest.ts";
 
 /**
  * Lease-partition side of the local authority shadow outbox.
@@ -128,7 +129,7 @@ export function decodeOutboxCursor(value: unknown, partition: string): JsonObjec
       typeof record.last_entry_id !== "string" ||
       !/^local-shadow-tx-[0-9a-f]{64}$/u.test(record.last_entry_id) ||
       (record.last_partition_digest !== null &&
-       (typeof record.last_partition_digest !== "string" || !/^sha256:[0-9a-f]{64}$/u.test(record.last_partition_digest))) ||
+       (typeof record.last_partition_digest !== "string" || !ENVELOPED_SHA256_PATTERN.test(record.last_partition_digest))) ||
       [record.last_cursor, record.last_provider_revision].some((part) => typeof part !== "string" || part.trim().length === 0)) {
     throw invalid();
   }

loopx/control_plane/coordination/reviewed_promotion_plan.ts

@@ -2,6 +2,7 @@
 import type { JsonObject } from "../effect_program.ts";
 import { requireJsonObject, requireBoolean } from "../runtime_decode.ts";
 import { canonicalAuthorityObject, requireAuthorityStoreId } from "./authority_store_codec.ts";
+import { BARE_SHA256_PATTERN } from "../content_digest.ts";
 
 export const REVIEWED_PROMOTION_PLAN_SCHEMA = "loopx_reviewed_coordination_promotion_v0";
 export const REVIEWED_PROMOTION_OPERATION_SCHEMA = "loopx_reviewed_coordination_promotion_operation_v0";
@@ -10,7 +11,7 @@ export const REVIEWED_PROMOTION_OPERATION_RESULT_SCHEMA =
 export type ReviewedPromotionAction = "apply" | "recover";
 
 export function promotionPlanDigest(value: unknown): string {
-  if (typeof value !== "string" || !/^[a-f0-9]{64}$/u.test(value)) {
+  if (typeof value !== "string" || !BARE_SHA256_PATTERN.test(value)) {
     throw new TypeError("reviewed promotion plan digest must be a lowercase SHA-256");
   }
   return value;

loopx/control_plane/coordination/runtime_shadow.ts

@@ -19,6 +19,7 @@ import {
   withShadowMaintenanceLock, ShadowManagementError, requireShadowPrimaryWriteAllowed,
 } from "./shadow_management.ts";
 import * as schemas from "./coordination_state_contract.generated.ts";
+import { ENVELOPED_SHA256_PATTERN } from "../content_digest.ts";
 
 export const COORDINATION_RUNTIME_SHADOW_REQUEST_SCHEMA = schemas.COORDINATION_RUNTIME_SHADOW_COMMIT_REQUEST_SCHEMA;
 export const COORDINATION_RUNTIME_SHADOW_RESULT_SCHEMA = schemas.COORDINATION_RUNTIME_SHADOW_COMMIT_RESULT_SCHEMA;
@@ -82,7 +83,7 @@ function sourceSnapshot(request: ShadowRequest): JsonObject {
   if (!isAbsolute(text(snapshot.state_path, "state_path")) ||
       !isAbsolute(text(snapshot.registered_runtime_root, "registered_runtime_root")) ||
       !isAbsolute(text(snapshot.registered_state_path, "registered_state_path")) ||
-      !/^sha256:[0-9a-f]{64}$/.test(text(snapshot.state_bytes_sha256, "state_bytes_sha256")) ||
+      !ENVELOPED_SHA256_PATTERN.test(text(snapshot.state_bytes_sha256, "state_bytes_sha256")) ||
       !Array.isArray(snapshot.lease_inventory) || !Array.isArray(snapshot.evidence_files) ||
       snapshot.projection_sha256 !== canonicalAuthoritySha256(request.projection)) {
     throw new ShadowManagementError("source_snapshot_invalid");

loopx/control_plane/coordination/shadow_drain_files.ts

@@ -15,6 +15,7 @@ import {sha256Digest, readOutboxCursor, outboxPartitionDirectory} from "./local_
 import {legacyCoordinationTodoLockPath, taskLeaseLockPath} from "./legacy_writer_lock_paths.ts";
 import {readShadowBootstrapSourcePath, type ShadowCaptureBinding} from "./shadow_management.ts";
 import {LOCAL_AUTHORITY_SHADOW_OUTBOX_ENTRY_SCHEMA, LOCAL_AUTHORITY_SHADOW_OUTBOX_COMMIT_SCHEMA} from "./coordination_state_contract.generated.ts";
+import { ENVELOPED_SHA256_PATTERN } from "../content_digest.ts";
 
 export type DrainPartition = "todos" | "leases";
 export interface DrainEntry {
@@ -56,7 +57,7 @@ export async function drainInventory(root: string, goal: string, partition: Drai
         record.goal_id === goal && record.partition === partition &&
         ["python", "typescript"].includes(String(writer.runtime)) && typeof writer.write_class === "string" && writer.write_class.length > 0 &&
         ["markdown_active_state", "state_event_log", "task_lease_record"].includes(String(source.kind)) &&
-        typeof record.source_root_digest === "string" && /^sha256:[0-9a-f]{64}$/.test(record.source_root_digest) && ref !== null &&
+        typeof record.source_root_digest === "string" && ENVELOPED_SHA256_PATTERN.test(record.source_root_digest) && ref !== null &&
         outboxEntryIdentity(goal, partition, seq, ref, record.capture_lineage_id, record.source_root_digest) === id);
       entry.prepared = true; entry.capture_lineage_id = record.capture_lineage_id; entry.prepared_sha256 = digest;
     } else {

loopx/control_plane/coordination/shadow_entry_delivery.ts

@@ -1,4 +1,5 @@
 import {outboxPartitionProjection} from "./shadow_entry_evidence.ts";
+import { ENVELOPED_SHA256_PATTERN } from "../content_digest.ts";
 /** Native delivery of an immutable, witnessed outbox entry. The host selects
  * evidence, never supplies the projection or decides whether a write committed. */
 import {lstat, readFile} from "node:fs/promises";
@@ -40,8 +41,8 @@ function decode(value: unknown): Selection {
     typeof r.seq === "number" && Number.isSafeInteger(r.seq) && r.seq > 0 && r.seq <= MAX_OUTBOX_SEQUENCE &&
     typeof r.entry_id === "string" && /^local-shadow-tx-[0-9a-f]{64}$/u.test(r.entry_id) &&
     typeof r.capture_lineage_id === "string" && r.capture_lineage_id.trim().length > 0 &&
-    typeof r.prepared_sha256 === "string" && /^sha256:[0-9a-f]{64}$/u.test(r.prepared_sha256) &&
-    (r.committed_sha256 === null || typeof r.committed_sha256 === "string" && /^sha256:[0-9a-f]{64}$/u.test(r.committed_sha256)),
+    typeof r.prepared_sha256 === "string" && ENVELOPED_SHA256_PATTERN.test(r.prepared_sha256) &&
+    (r.committed_sha256 === null || typeof r.committed_sha256 === "string" && ENVELOPED_SHA256_PATTERN.test(r.committed_sha256)),
   "shadow_entry_selection_invalid");
   return {runtime_root: r.runtime_root, goal_id: r.goal_id, partition: r.partition, seq: r.seq,
     entry_id: r.entry_id, capture_lineage_id: r.capture_lineage_id,

loopx/control_plane/coordination/shadow_management.ts

@@ -13,10 +13,11 @@ import { FileAuthorityStore } from "./file_authority_store.ts";
 import {
   SHADOW_MANAGEMENT_STATE_SCHEMA, SHADOW_MANAGEMENT_MANIFEST_SCHEMA, SHADOW_OUTBOX_MANIFEST_SCHEMA,
 } from "./coordination_state_contract.generated.ts";
+import { ENVELOPED_SHA256_PATTERN } from "../content_digest.ts";
 
 export { SHADOW_MANAGEMENT_STATE_SCHEMA, SHADOW_MANAGEMENT_MANIFEST_SCHEMA, SHADOW_OUTBOX_MANIFEST_SCHEMA };
 export const SHADOW_CAPTURE_PROFILE = "file_outbox_v1";
-const DIGEST = /^sha256:[0-9a-f]{64}$/;
+const DIGEST = ENVELOPED_SHA256_PATTERN;
 
 export interface ShadowCaptureBinding extends JsonObject {
   capture_profile: string;

loopx/control_plane/coordination/shadow_registry_source.ts

@@ -10,6 +10,7 @@ import {canonicalAuthorityBytes, hasExactAuthorityKeys} from "./authority_store_
 import {registryAuthoritySourceCheck} from "./authority_source.ts";
 import {ShadowManagementError} from "./shadow_management.ts";
 import {normalizeRegisteredTodoAgents} from "./todo_agents.ts";
+import { BARE_SHA256_PATTERN } from "../content_digest.ts";
 
 interface ShadowRegistrySource {
   path: string;
@@ -25,7 +26,7 @@ function registrySource(snapshot: JsonObject): ShadowRegistrySource {
   }
   const value = raw as JsonObject;
   if (typeof value.path !== "string" || !isAbsolute(value.path) ||
-      typeof value.sha256 !== "string" || !/^[a-f0-9]{64}$/.test(value.sha256) ||
+      typeof value.sha256 !== "string" || !BARE_SHA256_PATTERN.test(value.sha256) ||
       !Array.isArray(value.registered_agents) ||
       resolve(value.path) === resolve(String(snapshot.state_path))) {
     throw new ShadowManagementError("source_registry_witness_invalid");

loopx/control_plane/coordination/source_transfer.ts

@@ -13,6 +13,7 @@ import {
   COORDINATION_SOURCE_TRANSFER_REQUEST_SCHEMA as SOURCE_TRANSFER_SCHEMA,
   COORDINATION_SOURCE_TRANSFER_RESULT_SCHEMA as SOURCE_TRANSFER_RESULT_SCHEMA,
 } from "./coordination_state_contract.generated.ts";
+import { BARE_SHA256_PATTERN } from "../content_digest.ts";
 export {SOURCE_TRANSFER_SCHEMA, SOURCE_TRANSFER_RESULT_SCHEMA};
 export const MAX_SOURCE_TRANSFER_BYTES = COORDINATION_STATE_CONTRACT.source_transfer_limits.max_bytes;
 type Handler = (value: JsonObject) => unknown | Promise<unknown>;
@@ -28,7 +29,7 @@ export function withCoordinationSourceTransfer(method: string, handler: Handler)
     if (envelope.schema_version !== SOURCE_TRANSFER_SCHEMA) return handler(envelope);
     ensure(hasExactAuthorityKeys(envelope, ["schema_version", "method", "directory", "request_sha256", "request_bytes"]) &&
       envelope.method === method && typeof envelope.directory === "string" && isAbsolute(envelope.directory) &&
-      typeof envelope.request_sha256 === "string" && /^[a-f0-9]{64}$/u.test(envelope.request_sha256) &&
+      typeof envelope.request_sha256 === "string" && BARE_SHA256_PATTERN.test(envelope.request_sha256) &&
       typeof envelope.request_bytes === "number" && Number.isSafeInteger(envelope.request_bytes) &&
       envelope.request_bytes > 0 && envelope.request_bytes <= MAX_SOURCE_TRANSFER_BYTES,
     "invalid coordination source transfer envelope or artifact size");

loopx/control_plane/coordination/sqlite_authority_store.ts

@@ -24,11 +24,12 @@ import {
   isAuthorityStateCheckpoint,
   type AuthorityStateDelta,
 } from "./authority_state_log.ts";
+import { BARE_SHA256_PATTERN } from "../content_digest.ts";
 
 export const SQLITE_AUTHORITY_STORE_SCHEMA = "loopx_sqlite_authority_store_v2";
 const IDENTITY = /^sqlite:[0-9a-f]{32}$/;
 const REVISION = /^sqlite:([0-9a-f]{32}):([1-9]\d*)$/;
-const DIGEST = /^[0-9a-f]{64}$/;
+const DIGEST = BARE_SHA256_PATTERN;
 const MAX_SEQUENCE = 9223372036854775807n;
 const AUDIT_PAGE = 512;
 const COMMIT_COLUMNS = `CAST(cursor AS TEXT) AS sequence, operation_id, commit_digest, state_digest,