@mnemom/mnemom 0.17.33 → 0.17.34-next.2

package/dist/vendor/shared/durable-contract/events.js

@@ -0,0 +1,630 @@
+// GENERATED from shared/durable-contract/src/events.ts by cli/scripts/sync-durable-contract.mjs; do not edit.
+/**
+ * The journal: the closed event vocabulary (design §3.7, BACKBONE "Event kinds list", C10-R1..R25),
+ * writer classes, refs schemas, the server-generated detail, idempotency keys and the hash
+ * preimage (C10-R0 (a)-(m)).
+ *
+ * C10-R0 decisions frozen here:
+ *  (a) preimage fields: EVENT_PREIMAGE_FIELDS; hash = sha256(canonicalJson(preimage)).
+ *  (b) genesis prev_hash: GENESIS_PREV_HASH (64 zeros), never null.
+ *  (c) ts: stamped by the API process at append (Date, millisecond precision), stored timestamptz,
+ *      hashed as canonicalEventTs(ts): UTC, exactly 6 fraction digits, "Z" (survives PostgREST's
+ *      "+00:00" and psql's "+00" read-back forms).
+ *  (d) principal_ref: a stored column, HMAC-SHA256(hmac_salt, principal_uid) hex, null when the
+ *      writer has no principal (gateway, sweep, trigger).
+ *  (e) writer classes: EVENT_WRITER; executor list exactly [executor.spawned], plus session.waiting
+ *      from the Doors amendment (ruling 34.06) and executor.turn_continued (lead ruling 2026-10-28).
+ *  (f) executor.enrolled is journaled into no session in M1 (the agent_executors row is the record).
+ *  (h) an epoch-bump event is stamped with the NEW epoch.
+ *  (i)(j) codes.ts: durable_append_conflict, durable_lease_fenced, durable_idempotency_conflict.
+ *  (k) refs_schema is enforced inside durable_append_event (so a direct service_role RPC is refused).
+ *  (l) the gateway's internal route is GATEWAY_EVENTS_ROUTE on the API.
+ *  (m) DSR: phase user_erasure, treatment pseudonymize (nulls principal_uid, detail, refs).
+ */
+import { canonicalJson, hmacSha256Hex, sha256Hex, HEX64_RE } from "./canonical.js";
+import { DETACHED_REASONS, PAUSED_REASONS, SUSPENDED_REASONS, FAILED_REASONS, PARKED_ONLY_WAIT_REASONS, } from "./states.js";
+import { ATTESTATION_CHECKS_M1, CWD_CHECK_CAUSES } from "./codes.js";
+import { EVENT_DETAIL_MAX_CHARS } from "./constants.js";
+export const EVENT_GROUPS = [
+    "lifecycle",
+    "charter",
+    "lease",
+    "input",
+    "human",
+    "effects",
+    "governance",
+    "context",
+];
+/** The §3.7 table, all 88 kinds, by group. */
+export const DESIGN_EVENT_KINDS = {
+    lifecycle: [
+        "session.registered",
+        "session.locked",
+        "session.unlocked",
+        "session.resumed",
+        "session.detached",
+        "session.parked",
+        "session.suspended",
+        "session.paused",
+        "session.unpaused",
+        "session.moved",
+        "session.completed",
+        "session.failed",
+        "session.killed",
+        "session.expired",
+        "session.adopted",
+        "seat.hello",
+    ],
+    charter: [
+        "charter.sealed",
+        "charter.amended",
+        "charter.goal_sealed",
+        "charter.card_drift",
+        "profile.amended",
+        "executor.upgraded",
+        "attestation.passed",
+        "attestation.failed",
+    ],
+    lease: [
+        "lease.acquired",
+        "lease.reclaimed",
+        "lease.released",
+        "lease.expired",
+        "lease.fenced",
+        "lease.zombie_call",
+        "lease.stale_admit",
+        "executor.enrolled",
+        "executor.revoked",
+        "executor.spawned",
+        "executor.exited",
+        "executor.contract_violation",
+    ],
+    input: [
+        "inbox.admitted",
+        "inbox.rejected",
+        "inbox.coalesced",
+        "inbox.held_unsealed",
+        "inbox.queued_for_home",
+        "inbox.reverted",
+        "inbox.delivered",
+        "inbox.unmatched",
+        "inbox.acked",
+        "inbox.dead",
+        "timer.set",
+        "timer.fired",
+        "timer.cancelled",
+        "trigger.added",
+        "trigger.removed",
+        "trigger.fired",
+        "trigger.suppressed",
+        "trigger.over_cap",
+        "wake.undelivered",
+    ],
+    human: [
+        "question.asked",
+        "question.answered",
+        "approval.requested",
+        "approval.resolved",
+        "approval.consumed",
+        "approval.expired",
+        "approval.superseded",
+        "approval.single_person_override",
+    ],
+    effects: [
+        "intent.issued",
+        "intent.committed",
+        "intent.unknown",
+        "intent.resolved",
+        "intent.readmission_flagged",
+        "never.held",
+    ],
+    governance: [
+        "chain.posture",
+        "guard.refused",
+        "guard.unavailable",
+        "budget.reached",
+        "grant.renewed",
+        "grant.revoked",
+        "verdict.violation",
+        "identity.mismatch",
+        "containment.pause",
+        "containment.kill",
+        "containment.auto_pause",
+        "governance.degraded_admit",
+        "governance.outage_mode_set",
+        "policy.host_unattended_changed",
+    ],
+    context: [
+        "context.note",
+        "context.compacted",
+        "workspace.checkpointed",
+        "rearm.recorded",
+        "tip.signed",
+    ],
+};
+/** The 8 kinds L01 leaves out of the M1 seed: unknown kinds on every write path in M1. */
+export const M1_EXCLUDED_KINDS = [
+    "intent.issued",
+    "intent.committed",
+    "intent.unknown",
+    "intent.resolved",
+    "intent.readmission_flagged",
+    "context.note",
+    "context.compacted",
+    "inbox.acked",
+];
+/**
+ * Every M1 kind (80) with its group, in §3.7 order, then the Doors amendment's three (rulings
+ * 34.02, 34.06), appended so no existing index moves. Mirrors durable_event_kinds (parity test).
+ */
+export const DURABLE_EVENT_KINDS = [
+    "session.registered",
+    "session.locked",
+    "session.unlocked",
+    "session.resumed",
+    "session.detached",
+    "session.parked",
+    "session.suspended",
+    "session.paused",
+    "session.unpaused",
+    "session.moved",
+    "session.completed",
+    "session.failed",
+    "session.killed",
+    "session.expired",
+    "session.adopted",
+    "seat.hello",
+    "charter.sealed",
+    "charter.amended",
+    "charter.goal_sealed",
+    "charter.card_drift",
+    "profile.amended",
+    "executor.upgraded",
+    "attestation.passed",
+    "attestation.failed",
+    "lease.acquired",
+    "lease.reclaimed",
+    "lease.released",
+    "lease.expired",
+    "lease.fenced",
+    "lease.zombie_call",
+    "lease.stale_admit",
+    "executor.enrolled",
+    "executor.revoked",
+    "executor.spawned",
+    "executor.exited",
+    "executor.contract_violation",
+    "inbox.admitted",
+    "inbox.rejected",
+    "inbox.coalesced",
+    "inbox.held_unsealed",
+    "inbox.queued_for_home",
+    "inbox.reverted",
+    "inbox.delivered",
+    "inbox.unmatched",
+    "inbox.dead",
+    "timer.set",
+    "timer.fired",
+    "timer.cancelled",
+    "trigger.added",
+    "trigger.removed",
+    "trigger.fired",
+    "trigger.suppressed",
+    "trigger.over_cap",
+    "wake.undelivered",
+    "question.asked",
+    "question.answered",
+    "approval.requested",
+    "approval.resolved",
+    "approval.consumed",
+    "approval.expired",
+    "approval.superseded",
+    "approval.single_person_override",
+    "never.held",
+    "chain.posture",
+    "guard.refused",
+    "guard.unavailable",
+    "budget.reached",
+    "grant.renewed",
+    "grant.revoked",
+    "verdict.violation",
+    "identity.mismatch",
+    "containment.pause",
+    "containment.kill",
+    "containment.auto_pause",
+    "governance.degraded_admit",
+    "governance.outage_mode_set",
+    "policy.host_unattended_changed",
+    "workspace.checkpointed",
+    "rearm.recorded",
+    "tip.signed",
+    "session.ready",
+    "session.waiting",
+    "session.wait_cleared",
+    "executor.turn_continued",
+];
+export function isDurableEventKind(v) {
+    return typeof v === "string" && DURABLE_EVENT_KINDS.includes(v);
+}
+/**
+ * The kinds amendments add, with their group: the Doors amendment (rulings 34.02, 34.06), and
+ * executor.turn_continued (lead ruling 2026-10-28: the seat sent its one automatic "continue" to a
+ * turn a lock interrupted). They are not in the design's §3.7 table, so DESIGN_EVENT_KINDS stays the
+ * design's table and these are listed here.
+ */
+export const AMENDMENT_EVENT_GROUPS = Object.freeze({
+    "session.ready": "lifecycle",
+    "session.waiting": "lifecycle",
+    "session.wait_cleared": "lifecycle",
+    "executor.turn_continued": "lease",
+});
+export function eventGroupOf(kind) {
+    if (Object.prototype.hasOwnProperty.call(AMENDMENT_EVENT_GROUPS, kind))
+        return AMENDMENT_EVENT_GROUPS[kind];
+    for (const g of EVENT_GROUPS)
+        if (DESIGN_EVENT_KINDS[g].includes(kind))
+            return g;
+    throw new Error(`unreachable: ${kind} has no group`);
+}
+export const EVENT_WRITERS = ["executor", "gateway", "api"];
+/**
+ * M1: exactly [executor.spawned] (L01); the Doors amendment adds session.waiting (ruling 34.06), and
+ * the seat's one automatic continue adds executor.turn_continued (lead ruling 2026-10-28).
+ */
+export const EXECUTOR_WRITABLE_KINDS = [
+    "executor.spawned",
+    "session.waiting",
+    "executor.turn_continued",
+];
+/** Gateway: no session state in M1, so no containment.*, charter.* or lifecycle kind. */
+export const GATEWAY_WRITABLE_KINDS = [
+    "lease.zombie_call",
+    "identity.mismatch",
+    "guard.unavailable",
+];
+/** The one writer class allowed to append a kind; everything not executor- or gateway-writable is API-writable. */
+export function writerOf(kind) {
+    if (EXECUTOR_WRITABLE_KINDS.includes(kind))
+        return "executor";
+    if (GATEWAY_WRITABLE_KINDS.includes(kind))
+        return "gateway";
+    return "api";
+}
+/** Kinds with no M1 emitter: seeded for parity, never written by M1 code (C10-R4 static scan). */
+export const NO_M1_EMITTER_KINDS = [
+    "session.resumed",
+    "session.moved",
+    "charter.goal_sealed",
+    "profile.amended",
+    "executor.upgraded",
+    "lease.stale_admit",
+    "executor.enrolled",
+    "executor.contract_violation",
+    "inbox.admitted",
+    "inbox.rejected",
+    "inbox.coalesced",
+    "inbox.held_unsealed",
+    "inbox.queued_for_home",
+    "inbox.reverted",
+    "inbox.delivered",
+    "inbox.unmatched",
+    "inbox.dead",
+    "timer.set",
+    "timer.fired",
+    "timer.cancelled",
+    "trigger.added",
+    "trigger.removed",
+    "trigger.fired",
+    "trigger.suppressed",
+    "trigger.over_cap",
+    "wake.undelivered",
+    "question.asked",
+    "question.answered",
+    "approval.superseded",
+    "approval.single_person_override",
+    "never.held",
+    "verdict.violation",
+    "containment.auto_pause",
+    "governance.degraded_admit",
+    "governance.outage_mode_set",
+    "policy.host_unattended_changed",
+    "workspace.checkpointed",
+    "rearm.recorded",
+    "tip.signed",
+];
+const UUID_PATTERN = "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$";
+const HEX12_PATTERN = "^[0-9a-f]{12}$";
+const HEX64_PATTERN = "^[0-9a-f]{64}$";
+const HEX40_PATTERN = "^[0-9a-f]{40}$";
+const S = (extra = {}) => ({
+    type: "string",
+    maxLength: 64,
+    ...extra,
+});
+const UUID = S({ pattern: UUID_PATTERN, maxLength: 36 });
+const INT = (min = 0) => ({ type: "integer", minimum: min });
+const ENUM = (values) => ({
+    type: "string",
+    enum: values,
+    maxLength: 64,
+});
+const obj = (properties, required = Object.keys(properties), if_then) => if_then
+    ? { type: "object", additionalProperties: false, required, properties, if_then }
+    : { type: "object", additionalProperties: false, required, properties };
+const EMPTY = obj({});
+/** durable_approvals.kind values, as the approval.* refs enums carry them. */
+export const APPROVAL_KINDS = [
+    "question",
+    "ask",
+    "tool_confirmation",
+    "intent_rerun",
+    "card_drift",
+    "owner_mutation",
+    "grant_renewal",
+    "limit_raise",
+];
+/** session.ready refs.cause: how a session entered ready (ruling 34.02 (3)). */
+export const READY_CAUSES = ["dispatched", "lease_expired", "wait_cleared"];
+// question joins the M1 four (ruling 34.06.1.1): its wait parks on an owner_mutation approval.
+const OWNER_MUTATION_SUBJECTS = [
+    "unlock",
+    "unpause_contained",
+    "grant_renewal",
+    "budget_raise",
+    "question",
+];
+const KIND_REFS = {
+    "session.registered": obj({ durable_mode: ENUM(["tracked", "locked"]) }),
+    "session.locked": obj({ charter_version: INT(1) }),
+    "session.detached": obj({ reason: ENUM([...DETACHED_REASONS]) }),
+    "session.parked": obj({
+        from_state: ENUM(["resuming", "running", "detached", "suspended", "paused", "tracked"]),
+    }),
+    "session.suspended": obj({
+        reason: ENUM([...SUSPENDED_REASONS]),
+        check: ENUM([...ATTESTATION_CHECKS_M1]),
+        cause: ENUM([...CWD_CHECK_CAUSES]),
+    }, ["reason"]),
+    "session.paused": obj({ reason: ENUM([...PAUSED_REASONS]) }),
+    "session.unpaused": obj({
+        from_state: ENUM(["paused", "suspended"]),
+        from_reason: ENUM([
+            "owner",
+            "agent_contained",
+            "respawn_failed",
+            "attestation_failed",
+            "approval_expired",
+            "approval_denied",
+        ]),
+    }, ["from_state", "from_reason"], [
+        {
+            field: "from_state",
+            equals: "paused",
+            enums: { from_reason: ["owner", "agent_contained"] },
+        },
+        {
+            field: "from_state",
+            equals: "suspended",
+            enums: {
+                from_reason: [
+                    "respawn_failed",
+                    "attestation_failed",
+                    "approval_expired",
+                    "approval_denied",
+                ],
+            },
+        },
+    ]),
+    "session.failed": obj({ reason: ENUM([...FAILED_REASONS]) }),
+    "session.killed": obj({ reason: ENUM(["owner", "agent_killed"]) }),
+    "seat.hello": obj({ spawn_id: UUID }),
+    "charter.sealed": obj({
+        charter_version: INT(1),
+        hash_prefix: S({ pattern: HEX12_PATTERN, maxLength: 12 }),
+    }),
+    "charter.amended": obj({ charter_version: INT(2), change: ENUM(["budget_raise", "lowering"]) }),
+    "charter.card_drift": obj({
+        direction: ENUM(["tighten", "loosen", "unknown"]),
+        observed_hash_prefix: S({ pattern: HEX12_PATTERN, maxLength: 12 }),
+    }),
+    "attestation.passed": obj({
+        cli_version: S({ pattern: "^[0-9]+\\.[0-9]+\\.[0-9]+(-[0-9A-Za-z.-]+)?$", maxLength: 40 }),
+        plugin_hash: S({ pattern: HEX64_PATTERN, maxLength: 64 }),
+        renderer_version: INT(1),
+    }),
+    "attestation.failed": obj({ check: ENUM([...ATTESTATION_CHECKS_M1]), cause: ENUM([...CWD_CHECK_CAUSES]) }, ["check"]),
+    // ruling 34.03 (2): an acquire of a pool session carries pool: true
+    "lease.acquired": obj({ outcome: ENUM(["acquired", "epoch_bump"]), pool: { type: "boolean", const: true } }, ["outcome"]),
+    "lease.reclaimed": EMPTY,
+    "lease.released": EMPTY,
+    "lease.expired": EMPTY,
+    "lease.fenced": EMPTY,
+    "lease.zombie_call": obj({ admitted_epoch: INT(0), current_epoch: INT(0) }),
+    "executor.revoked": EMPTY,
+    "executor.spawned": obj({ spawn_id: UUID }),
+    "executor.exited": obj({
+        spawn_id: UUID,
+        exit_status: INT(0),
+        hello_accepted: { type: "boolean" },
+    }),
+    "approval.requested": obj({
+        approval_id: UUID,
+        approval_kind: ENUM(APPROVAL_KINDS),
+        subject: ENUM(OWNER_MUTATION_SUBJECTS),
+    }),
+    "approval.resolved": obj({
+        approval_id: UUID,
+        approval_kind: ENUM(APPROVAL_KINDS),
+        decision: ENUM(["approved", "denied"]),
+    }),
+    "approval.consumed": obj({
+        approval_id: UUID,
+        approval_kind: ENUM(APPROVAL_KINDS),
+        subject_hash: S({ pattern: HEX64_PATTERN, maxLength: 64 }),
+        sh_decision_id: UUID,
+    }, ["approval_id", "approval_kind", "subject_hash"], [{ field: "approval_kind", equals: "tool_confirmation", require: ["sh_decision_id"] }]),
+    "approval.expired": obj({ approval_id: UUID, approval_kind: ENUM(APPROVAL_KINDS) }),
+    "chain.posture": obj({ posture: ENUM(["attended", "unattended"]) }),
+    "guard.refused": obj({ sh_decision_id: UUID }, []),
+    "guard.unavailable": EMPTY,
+    "budget.reached": EMPTY,
+    "grant.renewed": obj({ approval_id: UUID }),
+    "grant.revoked": EMPTY,
+    "identity.mismatch": obj({
+        expected_agent_hash_prefix: S({ pattern: HEX12_PATTERN, maxLength: 12 }),
+        presented: ENUM(["absent", "mismatch"]),
+    }),
+    "containment.pause": obj({ action: ENUM(["pause"]) }),
+    "containment.kill": obj({ action: ENUM(["kill"]) }),
+    "never.held": obj({ sh_decision_id: UUID }),
+    // ---- Doors amendment (rulings 34.02, 34.06) ----
+    "session.ready": obj({ cause: ENUM(READY_CAUSES) }),
+    "session.waiting": obj({
+        wait_reason: ENUM(PARKED_ONLY_WAIT_REASONS),
+        head_sha: S({ pattern: HEX40_PATTERN, maxLength: 40 }),
+        approval_id: UUID,
+    }, ["wait_reason"], [
+        { field: "wait_reason", equals: "ci", require: ["head_sha"], forbid: ["approval_id"] },
+        { field: "wait_reason", equals: "question", require: ["approval_id"], forbid: ["head_sha"] },
+        { field: "wait_reason", equals: "budget", require: ["approval_id"], forbid: ["head_sha"] },
+    ]),
+    "session.wait_cleared": obj({ wait_reason: ENUM(PARKED_ONLY_WAIT_REASONS) }),
+    // ---- lead ruling 2026-10-28: the spawn that sent the continue; a separate fact, so
+    // executor.spawned's refs stay exactly {spawn_id} ----
+    "executor.turn_continued": obj({ spawn_id: UUID }),
+};
+/** refs_schema for every M1 kind; kinds without a specific schema take EMPTY (refs must be {}). */
+export function refsSchemaOf(kind) {
+    return KIND_REFS[kind] ?? EMPTY;
+}
+/** One refs property against its schema (pure; exported for its direct test). An integer with no minimum accepts any safe integer. */
+export function refsPropertyOk(p, v) {
+    if (p.type === "boolean")
+        return typeof v === "boolean" && (p.const === undefined || v === p.const);
+    if (p.type === "integer")
+        return Number.isSafeInteger(v) && v >= (p.minimum ?? Number.MIN_SAFE_INTEGER);
+    if (typeof v !== "string")
+        return false;
+    if (p.maxLength !== undefined && v.length > p.maxLength)
+        return false;
+    if (p.enum !== undefined && !p.enum.includes(v))
+        return false;
+    return p.pattern === undefined || new RegExp(p.pattern).test(v);
+}
+/** Reference validator for refs against refsSchemaOf(kind) (the RPC enforces the same rules). */
+export function validateRefs(kind, refs) {
+    if (refs === null || typeof refs !== "object" || Array.isArray(refs))
+        return false;
+    const schema = refsSchemaOf(kind);
+    const r = refs;
+    for (const key of Object.keys(r)) {
+        const p = schema.properties[key];
+        if (p === undefined || !refsPropertyOk(p, r[key]))
+            return false;
+    }
+    if (!schema.required.every((k) => k in r))
+        return false;
+    for (const rule of schema.if_then ?? []) {
+        if (r[rule.field] !== rule.equals)
+            continue;
+        if (rule.require && !rule.require.every((k) => k in r))
+            return false;
+        if (rule.forbid && rule.forbid.some((k) => k in r))
+            return false;
+        for (const [field, allowed] of Object.entries(rule.enums ?? {})) {
+            if (!allowed.includes(r[field]))
+                return false;
+        }
+    }
+    return true;
+}
+/** Server-generated detail (C10-R6, C18-R07): "<kind>" then " key=value" for each refs key, sorted. Content-free by construction. */
+export function eventDetail(kind, refs) {
+    const parts = Object.keys(refs)
+        .sort()
+        .map((k) => `${k}=${refs[k] === null ? "null" : String(refs[k])}`);
+    const text = [kind, ...parts].join(" ");
+    if (text.length > EVENT_DETAIL_MAX_CHARS)
+        throw new RangeError(`detail over ${EVENT_DETAIL_MAX_CHARS} chars`);
+    return text;
+}
+/** The closed shape every stored detail matches (the C18 structural checker's regex). */
+export const EVENT_DETAIL_RE = /^[a-z_]+\.[a-z_]+( [a-z_]+=[A-Za-z0-9_.:-]+)*$/;
+// ---- idempotency keys -------------------------------------------------------------------------
+export const idempotencyKeys = {
+    spawn: (sessionId, epoch, spawnId) => `spawn:${sessionId}:${epoch}:${spawnId}`,
+    zombie: (requestId) => `zombie:${requestId}`,
+    identityMismatch: (sessionId, epoch) => `idmm:${sessionId}:${epoch}`,
+    cardDrift: (sessionId, observedHash) => `drift:${sessionId}:${observedHash}`,
+    /** API transitions: one event per (session, kind, new epoch); a retried transition replays the row. */
+    transition: (sessionId, kind, epoch) => `tr:${sessionId}:${kind}:${epoch}`,
+};
+// ---- preimage ---------------------------------------------------------------------------------
+export const GENESIS_PREV_HASH = "0".repeat(64);
+export const GATEWAY_EVENTS_ROUTE = "/internal/durable/events";
+/**
+ * The journal kinds that mark a terminal transition, one per TERMINAL_STATES value in the same
+ * order (wave-0 fix ruling 1.06). contract_purge_after is stamped from the ts of this event
+ * (C18-R13).
+ */
+export const TERMINAL_EVENT_KINDS = [
+    "session.completed",
+    "session.failed",
+    "session.killed",
+    "session.expired",
+];
+export const EVENT_DSR = { phase: "user_erasure", treatment: "pseudonymize" };
+/** Hashed fields, in no particular order (canonicalJson sorts). Raw detail, refs and principal_uid are never hashed. */
+export const EVENT_PREIMAGE_FIELDS = [
+    "v",
+    "session_id",
+    "seq",
+    "ts",
+    "kind",
+    "epoch",
+    "idempotency_key",
+    "principal_ref",
+    "detail_sha256",
+    "refs_sha256",
+    "prev_hash",
+];
+const TS_RE = /^(\d{4}-\d{2}-\d{2})[T ](\d{2}:\d{2}:\d{2})(?:\.(\d{1,6}))?(Z|[+-]00(?::?00)?)$/;
+/** The canonical ts text: UTC, 6 fraction digits, "Z". Throws on a non-UTC or malformed value. */
+export function canonicalEventTs(ts) {
+    const m = TS_RE.exec(ts);
+    if (!m)
+        throw new RangeError(`not a UTC timestamp: ${ts}`);
+    return `${m[1]}T${m[2]}.${(m[3] ?? "").padEnd(6, "0")}Z`;
+}
+/** The API's stamper: millisecond Date, canonical form. */
+export function stampEventTs(epochMs) {
+    return canonicalEventTs(new Date(epochMs).toISOString());
+}
+/** The preimage object; absent principal_ref hashes like explicit null (C10-R8). */
+export function eventPreimage(input) {
+    if (!HEX64_RE.test(input.prev_hash))
+        throw new RangeError("prev_hash must be 64 lowercase hex");
+    return {
+        v: 1,
+        session_id: input.session_id,
+        seq: input.seq,
+        ts: canonicalEventTs(input.ts),
+        kind: input.kind,
+        epoch: input.epoch,
+        idempotency_key: input.idempotency_key,
+        principal_ref: input.principal_ref ?? null,
+        detail_sha256: input.detail_sha256,
+        refs_sha256: input.refs_sha256,
+        prev_hash: input.prev_hash,
+    };
+}
+export async function eventHash(input) {
+    return sha256Hex(canonicalJson(eventPreimage(input)));
+}
+export async function refsSha256(refs) {
+    return sha256Hex(canonicalJson(refs));
+}
+/** principal_ref = HMAC-SHA256(hmac_salt, principal_uid), lowercase hex (C10-R15). */
+export async function principalRef(hmacSalt, principalUid) {
+    return hmacSha256Hex(hmacSalt, principalUid);
+}

package/dist/vendor/shared/durable-contract/executor-state.d.ts

@@ -0,0 +1,41 @@
+/**
+ * The executor state file's shape (wave-0 fix ruling 24.14; C12-R05). EXECUTOR_STATE_FILE holds the
+ * executor key, the executor id, the nonce and the boot id the nonce is bound to, as one closed
+ * object. The host instance name is deliberately absent (C12-R04: read from config/env, so a copied
+ * file does not carry it). Internal: customers never read or edit this file; its location
+ * (paths.ts) is the customer-facing part.
+ */
+export declare const EXECUTOR_STATE_VERSION = 1;
+/** Field order is the file's key order. version is the integer EXECUTOR_STATE_VERSION. */
+export declare const EXECUTOR_STATE_SCHEMA: Readonly<{
+    readonly version: {
+        readonly type: "integer";
+        readonly nullable: false;
+    };
+    readonly executor_id: {
+        readonly type: "uuid";
+        readonly nullable: false;
+    };
+    /** The SECRET_KINDS executor_key spelling; this file is its only allowed home. */
+    readonly executor_key: {
+        readonly type: "string";
+        readonly nullable: false;
+    };
+    readonly nonce: {
+        readonly type: "string";
+        readonly nullable: false;
+    };
+    readonly boot_id: {
+        readonly type: "string";
+        readonly nullable: false;
+    };
+}>;
+export interface ExecutorState {
+    readonly version: typeof EXECUTOR_STATE_VERSION;
+    readonly executor_id: string;
+    readonly executor_key: string;
+    readonly nonce: string;
+    readonly boot_id: string;
+}
+/** True for exactly the frozen shape: every key present and well typed, no other key, version 1. */
+export declare function executorStateOk(v: unknown): v is ExecutorState;