@mnemom/mnemom 0.17.34-next.1 → 0.17.34-next.2

package/dist/vendor/shared/durable-contract/states.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Session states, the closed state_reason enum per state, effective-state derivation and the
+ * user-facing state mapping (design §3.3, §3.4; BACKBONE "state_reason values"; C11-R27).
+ */
+export declare const DURABLE_MODES: readonly ["tracked", "locked"];
+export type DurableMode = (typeof DURABLE_MODES)[number];
+export declare const SESSION_STATES: readonly ["resuming", "running", "detached", "parked", "suspended", "paused", "completed", "failed", "killed", "expired", "ready"];
+export type SessionState = (typeof SESSION_STATES)[number];
+export declare const TERMINAL_STATES: readonly ["completed", "failed", "killed", "expired"];
+export declare const NON_TERMINAL_STATES: readonly ["resuming", "running", "detached", "parked", "suspended", "paused", "ready"];
+export declare const DETACHED_REASONS: readonly ["lease_expired", "hello_missed", "seat_exited"];
+export declare const SUSPENDED_REASONS: readonly ["budget_reached", "enforce_refused", "charter_breach", "account_balance", "identity_mismatch", "grant_expired", "card_drift", "attestation_failed", "owner_departed", "respawn_failed", "approval_expired", "approval_denied"];
+/** breakglass is P0a-B; it stays in the enum so the CHECK never needs widening. */
+export declare const PAUSED_REASONS: readonly ["owner", "agent_contained", "breakglass"];
+export declare const FAILED_REASONS: readonly ["transcript_lost"];
+export declare const KILLED_REASONS: readonly ["agent_killed"];
+export type DetachedReason = (typeof DETACHED_REASONS)[number];
+export type SuspendedReason = (typeof SUSPENDED_REASONS)[number];
+export type PausedReason = (typeof PAUSED_REASONS)[number];
+export type StateReason = DetachedReason | SuspendedReason | PausedReason | (typeof FAILED_REASONS)[number] | (typeof KILLED_REASONS)[number];
+/**
+ * The closed state_reason enum per state. `null` in a list means NULL is allowed there and what it
+ * means: detached null = a lease that lapsed with no recorded cause; paused null = a plain pause
+ * (fixture only: owner pause writes `owner`); killed null = an owner kill. suspended and failed
+ * always carry a reason, so NULL there is a schema fault (503 at the gateway).
+ */
+export declare const STATE_REASONS: {
+    readonly [S in SessionState]: readonly (StateReason | null)[];
+};
+export declare const ALL_STATE_REASONS: readonly StateReason[];
+/** M1 writers exist for these suspended reasons; the others are fixture-only (P0a-B / P0b writers). */
+export declare const M1_WRITTEN_SUSPENDED_REASONS: readonly ["budget_reached", "identity_mismatch", "attestation_failed", "respawn_failed", "grant_expired", "approval_expired", "approval_denied"];
+/** M1's three wait reasons, then ruling 34.06's ci, question and budget (appended). */
+export declare const WAIT_REASONS: readonly ["approval", "moving", "mnemom_unavailable", "ci", "question", "budget"];
+export type WaitReason = (typeof WAIT_REASONS)[number];
+/**
+ * The wait reasons valid only with state 'parked' (ruling 34.06 (1), agent_sessions_wait_parked_ck).
+ * While wait_reason is one of these, every claim answers ineligible `waiting` (34.06 (3)).
+ */
+export declare const PARKED_ONLY_WAIT_REASONS: readonly ["ci", "question", "budget"];
+export type ParkedOnlyWaitReason = (typeof PARKED_ONLY_WAIT_REASONS)[number];
+export declare function isSessionState(v: unknown): v is SessionState;
+export declare function isTerminalState(s: SessionState): boolean;
+/** Whether `reason` is allowed with `state` by the closed enum. */
+export declare function isValidStateReason(state: SessionState, reason: unknown): boolean;
+/**
+ * The effective-state vocabulary: the persisted states plus `suspended_grant_expired`, the
+ * resolver's value for a lapsed executor grant (persisted or derived). It is the value set of the
+ * resolver's `effective_state` field and of the span attribute `durable_effective_state`.
+ */
+export declare const EFFECTIVE_STATES: readonly ["resuming", "running", "detached", "parked", "suspended", "suspended_grant_expired", "paused", "completed", "failed", "killed", "expired", "ready"];
+export type EffectiveState = (typeof EFFECTIVE_STATES)[number];
+export declare function isEffectiveState(v: unknown): v is EffectiveState;
+/** The effective state of a persisted (state, state_reason) with no derivation applied. */
+export declare function persistedEffectiveState(state: SessionState, reason: StateReason | null): EffectiveState;
+export interface EffectiveStateInput {
+    state: SessionState;
+    state_reason: StateReason | null;
+    /** agent_sessions.expires_at (NULL = never expires; always NULL on M1 write paths). */
+    expires_at: string | null;
+    /** The home executor's grant is live (grant_expires_at > now()). */
+    grant_live: boolean;
+    lease_expires_at: string | null;
+    /**
+     * The row is a pool session (rulings 34.04, 34.04.1): the caller computes home_executor_id IS
+     * NULL AND durable_mode = 'locked' AND the org is pool-enabled (poolClaimEnabled). A NULL home
+     * alone never means pool: A1's home FK is ON DELETE SET NULL, so erasure can leave a homed
+     * session with no home. Absent or false reads exactly as M1 (33f43de1).
+     */
+    pool?: boolean;
+}
+/**
+ * The effective state, first match wins (design §3.6 step 4, BACKBONE): expired > grant_expired >
+ * pool lease-ready (ruling 34.04 (1): a pool session whose lease lapsed reads `ready`) >
+ * lease-detached. Terminal rows never derive. The resolver computes this in SQL with Postgres
+ * now(); this is the reference the SQL is parity-tested against. Timestamps are ISO-8601.
+ */
+export declare function deriveEffectiveState(row: EffectiveStateInput, nowMs: number): EffectiveState;
+/**
+ * Whether `effective` is reachable from the persisted row by the derivation above. The admission
+ * input validator refuses any other pairing as a schema fault (503). `pool` is the same explicit
+ * input as EffectiveStateInput.pool (ruling 34.04.1); false answers exactly as M1.
+ */
+export declare function isEffectiveStateConsistent(state: SessionState, reason: StateReason | null, effective: EffectiveState, pool?: boolean): boolean;
+/** User-facing states (design §2, C11-R27), from the effective state. */
+export declare const USER_STATES: readonly ["running", "waiting", "stopped", "ended"];
+export type UserState = (typeof USER_STATES)[number];
+export declare function userStateOf(effective: EffectiveState): UserState;
+/** How the user-facing views word a ready session (ruling 34.02 (5), C11-R27). */
+export declare const READY_USER_TEXT = "waiting for a runner";
+export interface WireEnded {
+    state: "completed" | "failed" | "killed" | "expired";
+    state_reason: string | null;
+}
+/** The body of every 410 durable_session_ended (gateway and API): expired carries state_reason 'expired' (C11-R11). */
+export declare function endedBody(effective: EffectiveState, reason: StateReason | null): WireEnded | null;

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

@@ -0,0 +1,218 @@
+// GENERATED from shared/durable-contract/src/states.ts by cli/scripts/sync-durable-contract.mjs; do not edit.
+/**
+ * Session states, the closed state_reason enum per state, effective-state derivation and the
+ * user-facing state mapping (design §3.3, §3.4; BACKBONE "state_reason values"; C11-R27).
+ */
+export const DURABLE_MODES = ["tracked", "locked"];
+export const SESSION_STATES = [
+    "resuming",
+    "running",
+    "detached",
+    "parked",
+    "suspended",
+    "paused",
+    "completed",
+    "failed",
+    "killed",
+    "expired",
+    // ruling 34.02: appended last so no existing index moves
+    "ready",
+];
+export const TERMINAL_STATES = [
+    "completed",
+    "failed",
+    "killed",
+    "expired",
+];
+export const NON_TERMINAL_STATES = [
+    "resuming",
+    "running",
+    "detached",
+    "parked",
+    "suspended",
+    "paused",
+    "ready",
+];
+export const DETACHED_REASONS = ["lease_expired", "hello_missed", "seat_exited"];
+export const SUSPENDED_REASONS = [
+    "budget_reached",
+    "enforce_refused",
+    "charter_breach",
+    "account_balance",
+    "identity_mismatch",
+    "grant_expired",
+    "card_drift",
+    "attestation_failed",
+    "owner_departed",
+    "respawn_failed",
+    /** ruling 34.22: a question wait's, or any non-budget approval wait's, approval expired or was denied; the owner resumes by hand. Budget waits keep budget_reached. */
+    "approval_expired",
+    "approval_denied",
+];
+/** breakglass is P0a-B; it stays in the enum so the CHECK never needs widening. */
+export const PAUSED_REASONS = ["owner", "agent_contained", "breakglass"];
+export const FAILED_REASONS = ["transcript_lost"];
+export const KILLED_REASONS = ["agent_killed"];
+/**
+ * The closed state_reason enum per state. `null` in a list means NULL is allowed there and what it
+ * means: detached null = a lease that lapsed with no recorded cause; paused null = a plain pause
+ * (fixture only: owner pause writes `owner`); killed null = an owner kill. suspended and failed
+ * always carry a reason, so NULL there is a schema fault (503 at the gateway).
+ */
+export const STATE_REASONS = {
+    resuming: [null],
+    running: [null],
+    detached: [null, ...DETACHED_REASONS],
+    parked: [null],
+    suspended: [...SUSPENDED_REASONS],
+    paused: [null, ...PAUSED_REASONS],
+    completed: [null],
+    failed: [...FAILED_REASONS],
+    killed: [null, ...KILLED_REASONS],
+    expired: [null],
+    /** ruling 34.02 (1): a ready row's state_reason is always NULL. */
+    ready: [null],
+};
+export const ALL_STATE_REASONS = [
+    ...DETACHED_REASONS,
+    ...SUSPENDED_REASONS,
+    ...PAUSED_REASONS,
+    ...FAILED_REASONS,
+    ...KILLED_REASONS,
+];
+/** M1 writers exist for these suspended reasons; the others are fixture-only (P0a-B / P0b writers). */
+export const M1_WRITTEN_SUSPENDED_REASONS = [
+    "budget_reached",
+    "identity_mismatch",
+    "attestation_failed",
+    "respawn_failed",
+    "grant_expired",
+    /** ruling 34.22: written by the approval-wait expiry/denial path. */
+    "approval_expired",
+    "approval_denied",
+];
+/** M1's three wait reasons, then ruling 34.06's ci, question and budget (appended). */
+export const WAIT_REASONS = [
+    "approval",
+    "moving",
+    "mnemom_unavailable",
+    "ci",
+    "question",
+    "budget",
+];
+/**
+ * The wait reasons valid only with state 'parked' (ruling 34.06 (1), agent_sessions_wait_parked_ck).
+ * While wait_reason is one of these, every claim answers ineligible `waiting` (34.06 (3)).
+ */
+export const PARKED_ONLY_WAIT_REASONS = [
+    "ci",
+    "question",
+    "budget",
+];
+export function isSessionState(v) {
+    return typeof v === "string" && SESSION_STATES.includes(v);
+}
+export function isTerminalState(s) {
+    return TERMINAL_STATES.includes(s);
+}
+/** Whether `reason` is allowed with `state` by the closed enum. */
+export function isValidStateReason(state, reason) {
+    if (reason !== null && typeof reason !== "string")
+        return false;
+    return STATE_REASONS[state].includes(reason);
+}
+/**
+ * The effective-state vocabulary: the persisted states plus `suspended_grant_expired`, the
+ * resolver's value for a lapsed executor grant (persisted or derived). It is the value set of the
+ * resolver's `effective_state` field and of the span attribute `durable_effective_state`.
+ */
+export const EFFECTIVE_STATES = [
+    "resuming",
+    "running",
+    "detached",
+    "parked",
+    "suspended",
+    "suspended_grant_expired",
+    "paused",
+    "completed",
+    "failed",
+    "killed",
+    "expired",
+    // ruling 34.02 (5): ready is persisted and never derived from another state, except 34.04's pool arm
+    "ready",
+];
+export function isEffectiveState(v) {
+    return typeof v === "string" && EFFECTIVE_STATES.includes(v);
+}
+/** The effective state of a persisted (state, state_reason) with no derivation applied. */
+export function persistedEffectiveState(state, reason) {
+    return state === "suspended" && reason === "grant_expired" ? "suspended_grant_expired" : state;
+}
+/**
+ * The effective state, first match wins (design §3.6 step 4, BACKBONE): expired > grant_expired >
+ * pool lease-ready (ruling 34.04 (1): a pool session whose lease lapsed reads `ready`) >
+ * lease-detached. Terminal rows never derive. The resolver computes this in SQL with Postgres
+ * now(); this is the reference the SQL is parity-tested against. Timestamps are ISO-8601.
+ */
+export function deriveEffectiveState(row, nowMs) {
+    if (isTerminalState(row.state))
+        return persistedEffectiveState(row.state, row.state_reason);
+    if (row.expires_at !== null && Date.parse(row.expires_at) <= nowMs)
+        return "expired";
+    if (!row.grant_live)
+        return "suspended_grant_expired";
+    const leaseLapsed = row.lease_expires_at !== null && Date.parse(row.lease_expires_at) < nowMs;
+    if ((row.state === "running" || row.state === "resuming") && leaseLapsed)
+        return row.pool === true ? "ready" : "detached";
+    return persistedEffectiveState(row.state, row.state_reason);
+}
+/**
+ * Whether `effective` is reachable from the persisted row by the derivation above. The admission
+ * input validator refuses any other pairing as a schema fault (503). `pool` is the same explicit
+ * input as EffectiveStateInput.pool (ruling 34.04.1); false answers exactly as M1.
+ */
+export function isEffectiveStateConsistent(state, reason, effective, pool = false) {
+    if (effective === persistedEffectiveState(state, reason))
+        return true;
+    if (isTerminalState(state))
+        return false;
+    if (effective === "expired" || effective === "suspended_grant_expired")
+        return true;
+    // a lapsed lease reads detached for a homed session, ready for a pool session (34.04, 34.04.1)
+    return (effective === (pool ? "ready" : "detached") && (state === "running" || state === "resuming"));
+}
+/** User-facing states (design §2, C11-R27), from the effective state. */
+export const USER_STATES = ["running", "waiting", "stopped", "ended"];
+export function userStateOf(effective) {
+    switch (effective) {
+        case "running":
+        case "resuming":
+            return "running";
+        case "parked":
+        case "detached":
+        case "ready":
+            return "waiting";
+        case "paused":
+        case "suspended":
+        case "suspended_grant_expired":
+            return "stopped";
+        default:
+            return "ended";
+    }
+}
+/** How the user-facing views word a ready session (ruling 34.02 (5), C11-R27). */
+export const READY_USER_TEXT = "waiting for a runner";
+/** The body of every 410 durable_session_ended (gateway and API): expired carries state_reason 'expired' (C11-R11). */
+export function endedBody(effective, reason) {
+    switch (effective) {
+        case "expired":
+            return { state: "expired", state_reason: "expired" };
+        case "completed":
+            return { state: "completed", state_reason: null };
+        case "failed":
+        case "killed":
+            return { state: effective, state_reason: reason };
+        default:
+            return null;
+    }
+}

package/dist/vendor/shared/durable-contract/telemetry.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Durable telemetry: span names, attribute keys and closed value sets, with the M1 allowlists
+ * (C19, C20-R14/R15; rulings r2 I04, I07, r3 I02, L01, L02, final F05). Spans only, never OTLP
+ * metrics (repo CLAUDE.md). Attribute keys are snake_case and low-cardinality; no identifier,
+ * content or free text ever rides on a durable span.
+ */
+/** The gateway's one admission span per mnm_ds_ request (a dedicated span; C19 OQ). */
+export declare const SPAN_DURABLE_ADMISSION = "durable_admission";
+export declare const SPAN_DURABLE_CLAIM = "durable_claim";
+export declare const SPAN_DURABLE_SEAT_HELLO = "durable_seat_hello";
+export declare const SPAN_DURABLE_SWEEP = "durable_sweep";
+/**
+ * The api's one C16 span (C16-R24, rulings I16): under DEVICE_VERIFY_AAL=observe an aal1 login-flow
+ * approval that `on` would refuse is allowed and emits exactly one span with this name, status ok,
+ * device_verify_would_refuse = "true". Never emitted under off, unset or on, and never for the
+ * owner_mutation mode (which always enforces).
+ */
+export declare const SPAN_DEVICE_VERIFY_WOULD_REFUSE = "device_verify_would_refuse";
+/**
+ * The api's executor enrollment span (C04-R16; wave-0 fix 3c): one per enrollment step, carrying
+ * durable_enrollment_outcome only (a separate key because `outcome` is frozen to the sweep's
+ * ok|error|disabled). Status error on every refused_*, denied and expired. Never carries the key,
+ * poll secret, user_code or owner credentials (SECRET_SCOPE).
+ */
+export declare const SPAN_DURABLE_ENROLLMENT = "durable_enrollment";
+export declare const DEVICE_VERIFY_AAL_VALUES: readonly ["off", "observe", "on"];
+export declare const DEVICE_VERIFY_AAL_DEFAULT = "off";
+export declare const M1_SPAN_NAMES: readonly ["durable_admission", "durable_claim", "durable_seat_hello", "durable_sweep", "device_verify_would_refuse", "durable_enrollment"];
+/** Forbidden in M1 by prefix (final F05; cut with PR 10). */
+export declare const FORBIDDEN_SPAN_PREFIXES_M1: readonly ["durable_resolve"];
+/** mnm_ds_ requests emit no gateway.auth span; the admission span replaces it (C19 OQ). */
+export declare const GATEWAY_AUTH_FOR_LEASE_KEYS: "not_emitted";
+/** durable_enrollment_outcome values (C04-R16). */
+export declare const ENROLLMENT_OUTCOMES: readonly ["started", "approved", "refused_aal", "refused_stale", "refused_not_self", "refused_machine", "refused_entitlement", "denied", "expired", "consumed", "replay"];
+export type EnrollmentOutcome = (typeof ENROLLMENT_OUTCOMES)[number];
+/** Span status of an enrollment outcome: error on every refused_*, denied and expired. */
+export declare function enrollmentSpanStatus(o: EnrollmentOutcome): "ok" | "error";
+export declare const REFUSAL_NONE = "none";
+export declare const REFUSAL_UNKNOWN_KEY = "unknown_key";
+export declare const ATTRIBUTE_VALUES: {
+    readonly durable_refusal: readonly ["none", "unknown_key", "durable_admission_unavailable", "durable_key_revoked", "durable_identity_mismatch", "durable_unlocked", "durable_session_ended", "durable_lease_fenced", "durable_session_stopped", "durable_guard_unavailable", "durable_unattended_unavailable", "goal_contract_enforce_refused", "durable_route_refused", "durable_executor_key_refused", "contract_mismatch"];
+    readonly durable_posture: readonly ["attended", "unattended"];
+    readonly durable_door: readonly ["match", "mismatch", "unmapped"];
+    readonly durable_effective_state: readonly ["resuming", "running", "detached", "parked", "suspended", "suspended_grant_expired", "paused", "completed", "failed", "killed", "expired", "ready", "unknown"];
+    /** `cache` is CUT M1 -> P1 (STALE_SERVE_M1=false). */
+    readonly durable_fence_source: readonly ["fresh", "nofence"];
+    readonly durable_charter_source: readonly ["pg", "rehydrated", "lru", "kv", "unavailable", "none"];
+    /**
+     * The applyDurableArm site that emitted this span (wave-0 fix ruling 5; C06-R21), on every path:
+     * admit, every refusal, resolver-fault 503. Whether the arm header was present is asserted on
+     * the response head (C06-R17), not here.
+     */
+    readonly durable_arm: readonly ["anchor", "key_gate"];
+    readonly durable_never_hold: readonly ["off"];
+    readonly durable_guard: readonly ["ok", "unavailable", "not_applicable"];
+    readonly durable_claim_outcome: readonly ["acquired", "reclaimed", "epoch_bump", "needs_key", "lost_race", "ineligible", "unavailable", "rate_limited"];
+    readonly durable_claim_cause: readonly ["schema", "arm_probe", "entitlement_lookup", "protection_probe", "guard", "lease_cap_config"];
+    readonly durable_hello_outcome: readonly ["accepted", "repeat", "late", "refused"];
+    readonly outcome: readonly ["ok", "error", "disabled"];
+    readonly budget_exhausted: readonly ["true", "false"];
+    readonly lag_bucket: readonly ["none", "<1m", "1-5m", "5-30m", ">30m"];
+    /** The frozen would-refuse marker: the only value it ever carries. */
+    readonly device_verify_would_refuse: readonly ["true"];
+    /** Why `on` would refuse: assurance below aal2, or the step older than DEVICE_STEP_FRESHNESS_S. */
+    readonly device_verify_reason: readonly ["aal", "freshness"];
+    /** The assurance the approval actually carried. */
+    readonly device_verify_assurance: readonly ["aal1", "aal2"];
+    /** C04-R16, exactly. */
+    readonly durable_enrollment_outcome: readonly ["started", "approved", "refused_aal", "refused_stale", "refused_not_self", "refused_machine", "refused_entitlement", "denied", "expired", "consumed", "replay"];
+};
+export type DurableAttributeKey = keyof typeof ATTRIBUTE_VALUES | "test_case";
+/** Allowed keys per span (closure: a key outside its span's list is a failure). */
+export declare const SPAN_ATTRIBUTE_KEYS: {
+    readonly [S in (typeof M1_SPAN_NAMES)[number]]: readonly DurableAttributeKey[];
+};
+/** Keys that must never appear on an M1 durable span (r3 L01, L02; I12; U24). */
+export declare const FORBIDDEN_ATTRIBUTE_KEYS_M1: readonly ["durable_degraded", "durable_hold_decision", "durable_host_policy", "durable_org_usage", "reaped", "expired", "lag_ms"];
+export declare const TEST_CASE_RE: RegExp;
+export declare const TEST_CASE_HEADER = "x-mnemom-test-case";
+/** Span status: refusals are error, admits ok (an attended guard fault is admitted, so ok). */
+export declare function spanStatusOf(refusal: string): "ok" | "error";
+/** The sweep's lag bucket for the oldest overdue row's lag (ms); null lag = nothing overdue. */
+export declare function lagBucket(lagMs: number | null): (typeof ATTRIBUTE_VALUES.lag_bucket)[number];
+/** budget_exhausted: rows persisted reached max_rows (an exact multiple counts) or the time budget elapsed. */
+export declare function budgetExhausted(persisted: number, maxRows: number, elapsedMs: number, budgetMs: number): boolean;
+/** The sweep log line (not a span): name and its closed field list, no session ids. */
+export declare const SWEEP_LOG_NAME = "durable_sweep_run";
+export declare const SWEEP_LOG_FIELDS: readonly ["reaped", "expired", "skipped_locked", "lag_ms"];
+export interface AttributeFinding {
+    key: string;
+    problem: "unknown_span" | "key_not_allowed" | "forbidden_key" | "value_not_allowed";
+}
+/** Closure check over one captured span (C19 allowlist_and_enum_closure reference). */
+export declare function checkDurableSpan(name: string, attrs: Readonly<Record<string, unknown>>, testCaseAllowed: boolean): AttributeFinding[];

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

@@ -0,0 +1,180 @@
+// GENERATED from shared/durable-contract/src/telemetry.ts by cli/scripts/sync-durable-contract.mjs; do not edit.
+/**
+ * Durable telemetry: span names, attribute keys and closed value sets, with the M1 allowlists
+ * (C19, C20-R14/R15; rulings r2 I04, I07, r3 I02, L01, L02, final F05). Spans only, never OTLP
+ * metrics (repo CLAUDE.md). Attribute keys are snake_case and low-cardinality; no identifier,
+ * content or free text ever rides on a durable span.
+ */
+import { CLAIM_OUTCOMES, CLAIM_UNAVAILABLE_CAUSES, GATEWAY_REFUSAL_CODES } from "./codes.js";
+import { EFFECTIVE_STATES } from "./states.js";
+import { DOOR_VALUES } from "./cell-id.js";
+/** The gateway's one admission span per mnm_ds_ request (a dedicated span; C19 OQ). */
+export const SPAN_DURABLE_ADMISSION = "durable_admission";
+export const SPAN_DURABLE_CLAIM = "durable_claim";
+export const SPAN_DURABLE_SEAT_HELLO = "durable_seat_hello";
+export const SPAN_DURABLE_SWEEP = "durable_sweep";
+/**
+ * The api's one C16 span (C16-R24, rulings I16): under DEVICE_VERIFY_AAL=observe an aal1 login-flow
+ * approval that `on` would refuse is allowed and emits exactly one span with this name, status ok,
+ * device_verify_would_refuse = "true". Never emitted under off, unset or on, and never for the
+ * owner_mutation mode (which always enforces).
+ */
+export const SPAN_DEVICE_VERIFY_WOULD_REFUSE = "device_verify_would_refuse";
+/**
+ * The api's executor enrollment span (C04-R16; wave-0 fix 3c): one per enrollment step, carrying
+ * durable_enrollment_outcome only (a separate key because `outcome` is frozen to the sweep's
+ * ok|error|disabled). Status error on every refused_*, denied and expired. Never carries the key,
+ * poll secret, user_code or owner credentials (SECRET_SCOPE).
+ */
+export const SPAN_DURABLE_ENROLLMENT = "durable_enrollment";
+export const DEVICE_VERIFY_AAL_VALUES = ["off", "observe", "on"];
+export const DEVICE_VERIFY_AAL_DEFAULT = "off";
+export const M1_SPAN_NAMES = [
+    SPAN_DURABLE_ADMISSION,
+    SPAN_DURABLE_CLAIM,
+    SPAN_DURABLE_SEAT_HELLO,
+    SPAN_DURABLE_SWEEP,
+    SPAN_DEVICE_VERIFY_WOULD_REFUSE,
+    SPAN_DURABLE_ENROLLMENT,
+];
+/** Forbidden in M1 by prefix (final F05; cut with PR 10). */
+export const FORBIDDEN_SPAN_PREFIXES_M1 = ["durable_resolve"];
+/** mnm_ds_ requests emit no gateway.auth span; the admission span replaces it (C19 OQ). */
+export const GATEWAY_AUTH_FOR_LEASE_KEYS = "not_emitted";
+/** durable_enrollment_outcome values (C04-R16). */
+export const ENROLLMENT_OUTCOMES = [
+    "started",
+    "approved",
+    "refused_aal",
+    "refused_stale",
+    "refused_not_self",
+    "refused_machine",
+    "refused_entitlement",
+    "denied",
+    "expired",
+    "consumed",
+    "replay",
+];
+/** Span status of an enrollment outcome: error on every refused_*, denied and expired. */
+export function enrollmentSpanStatus(o) {
+    return o.startsWith("refused_") || o === "denied" || o === "expired" ? "error" : "ok";
+}
+export const REFUSAL_NONE = "none";
+export const REFUSAL_UNKNOWN_KEY = "unknown_key";
+export const ATTRIBUTE_VALUES = {
+    durable_refusal: [REFUSAL_NONE, REFUSAL_UNKNOWN_KEY, ...GATEWAY_REFUSAL_CODES],
+    durable_posture: ["attended", "unattended"],
+    durable_door: DOOR_VALUES,
+    durable_effective_state: [...EFFECTIVE_STATES, "unknown"],
+    /** `cache` is CUT M1 -> P1 (STALE_SERVE_M1=false). */
+    durable_fence_source: ["fresh", "nofence"],
+    durable_charter_source: ["pg", "rehydrated", "lru", "kv", "unavailable", "none"],
+    /**
+     * The applyDurableArm site that emitted this span (wave-0 fix ruling 5; C06-R21), on every path:
+     * admit, every refusal, resolver-fault 503. Whether the arm header was present is asserted on
+     * the response head (C06-R17), not here.
+     */
+    durable_arm: ["anchor", "key_gate"],
+    durable_never_hold: ["off"],
+    durable_guard: ["ok", "unavailable", "not_applicable"],
+    durable_claim_outcome: CLAIM_OUTCOMES,
+    durable_claim_cause: CLAIM_UNAVAILABLE_CAUSES,
+    durable_hello_outcome: ["accepted", "repeat", "late", "refused"],
+    outcome: ["ok", "error", "disabled"],
+    budget_exhausted: ["true", "false"],
+    lag_bucket: ["none", "<1m", "1-5m", "5-30m", ">30m"],
+    /** The frozen would-refuse marker: the only value it ever carries. */
+    device_verify_would_refuse: ["true"],
+    /** Why `on` would refuse: assurance below aal2, or the step older than DEVICE_STEP_FRESHNESS_S. */
+    device_verify_reason: ["aal", "freshness"],
+    /** The assurance the approval actually carried. */
+    device_verify_assurance: ["aal1", "aal2"],
+    /** C04-R16, exactly. */
+    durable_enrollment_outcome: ENROLLMENT_OUTCOMES,
+};
+/** Allowed keys per span (closure: a key outside its span's list is a failure). */
+export const SPAN_ATTRIBUTE_KEYS = {
+    durable_admission: [
+        "durable_refusal",
+        "durable_posture",
+        "durable_door",
+        "durable_effective_state",
+        "durable_fence_source",
+        "durable_charter_source",
+        "durable_arm",
+        "durable_never_hold",
+        "durable_guard",
+        "test_case",
+    ],
+    durable_claim: ["durable_claim_outcome", "durable_claim_cause", "test_case"],
+    durable_seat_hello: ["durable_hello_outcome", "test_case"],
+    durable_sweep: ["outcome", "budget_exhausted", "lag_bucket", "test_case"],
+    device_verify_would_refuse: [
+        "device_verify_would_refuse",
+        "device_verify_reason",
+        "device_verify_assurance",
+        "test_case",
+    ],
+    durable_enrollment: ["durable_enrollment_outcome", "test_case"],
+};
+/** Keys that must never appear on an M1 durable span (r3 L01, L02; I12; U24). */
+export const FORBIDDEN_ATTRIBUTE_KEYS_M1 = [
+    "durable_degraded",
+    "durable_hold_decision",
+    "durable_host_policy",
+    "durable_org_usage",
+    "reaped",
+    "expired",
+    "lag_ms",
+];
+export const TEST_CASE_RE = /^[a-z0-9-]{1,40}$/;
+export const TEST_CASE_HEADER = "x-mnemom-test-case";
+/** Span status: refusals are error, admits ok (an attended guard fault is admitted, so ok). */
+export function spanStatusOf(refusal) {
+    return refusal === REFUSAL_NONE ? "ok" : "error";
+}
+/** The sweep's lag bucket for the oldest overdue row's lag (ms); null lag = nothing overdue. */
+export function lagBucket(lagMs) {
+    if (lagMs === null || lagMs <= 0)
+        return "none";
+    if (lagMs < 60_000)
+        return "<1m";
+    if (lagMs < 300_000)
+        return "1-5m";
+    if (lagMs < 1_800_000)
+        return "5-30m";
+    return ">30m";
+}
+/** budget_exhausted: rows persisted reached max_rows (an exact multiple counts) or the time budget elapsed. */
+export function budgetExhausted(persisted, maxRows, elapsedMs, budgetMs) {
+    return persisted >= maxRows || elapsedMs >= budgetMs;
+}
+/** The sweep log line (not a span): name and its closed field list, no session ids. */
+export const SWEEP_LOG_NAME = "durable_sweep_run";
+export const SWEEP_LOG_FIELDS = ["reaped", "expired", "skipped_locked", "lag_ms"];
+/** Closure check over one captured span (C19 allowlist_and_enum_closure reference). */
+export function checkDurableSpan(name, attrs, testCaseAllowed) {
+    if (!M1_SPAN_NAMES.includes(name))
+        return [{ key: name, problem: "unknown_span" }];
+    const allowed = SPAN_ATTRIBUTE_KEYS[name];
+    const out = [];
+    for (const [key, value] of Object.entries(attrs)) {
+        if (FORBIDDEN_ATTRIBUTE_KEYS_M1.includes(key)) {
+            out.push({ key, problem: "forbidden_key" });
+        }
+        else if (!allowed.includes(key) ||
+            (key === "test_case" && !testCaseAllowed)) {
+            out.push({ key, problem: "key_not_allowed" });
+        }
+        else if (key === "test_case") {
+            if (typeof value !== "string" || !TEST_CASE_RE.test(value))
+                out.push({ key, problem: "value_not_allowed" });
+        }
+        else {
+            const values = ATTRIBUTE_VALUES[key];
+            if (!values.includes(String(value)))
+                out.push({ key, problem: "value_not_allowed" });
+        }
+    }
+    return out;
+}

package/dist/vendor/shared/durable-contract/test-mode.d.ts

@@ -0,0 +1,62 @@
+/**
+ * The closed TEST_MODE seam list T1-T12 and the per-repo guard lists (C17-R16, rulings I06, I22,
+ * I29; BACKBONE "TEST_MODE"). A seam is honoured only when DURABLE_SESSIONS_TEST_MODE is exactly
+ * "1" AND every URL on the repo's guard list is a loopback literal; an unset URL fails. Each repo
+ * reads the env in exactly one module (TEST_MODE_MODULE).
+ */
+export declare const TEST_MODE_ENV = "DURABLE_SESSIONS_TEST_MODE";
+export declare const REPOS: readonly ["cli", "api", "gateway"];
+export type Repo = (typeof REPOS)[number];
+export interface Seam {
+    id: string;
+    repo: Repo | "api+gateway";
+    kind: "env" | "route" | "header" | "body";
+    names: readonly string[];
+}
+export declare const TEST_SEAMS: readonly Seam[];
+export declare const T2_PAUSE_POINTS: readonly ["after_claim_before_spawn", "after_spawn_before_register", "after_register_before_hello", "after_first_batch", "after_verify_before_exec"];
+export declare const T5_BARRIERS: readonly ["lock.after_preconditions", "lock.before_commit", "session_create.before_insert", "session_key_mint.before_insert"];
+export declare const T6_FAULTS: readonly ["drop_response_after_commit"];
+export declare const T9_SWEEP_FAULTS: readonly ["after_update"];
+/** Dropped seams: must be absent from every repo (C17-R16). */
+export declare const DROPPED_SEAMS: readonly ["DURABLE_CLAUDE_BIN", "DURABLE_SPAWN_PAUSE_AFTER_VERIFY_MS", "DURABLE_SWEEP_BUDGET", "/internal/durable/test/lru-flush", "durable_test_barrier", "test_barriers_enabled"];
+export declare const GUARD_LISTS: {
+    readonly [R in Repo]: readonly string[];
+};
+/** The one module per repo that reads TEST_MODE and holds every seam getter (repo-relative). */
+export declare const TEST_MODE_MODULE: {
+    readonly [R in Repo]: string;
+};
+export declare function seamsOf(repo: Repo): string[];
+export declare const LOOPBACK_HOSTS: readonly ["127.0.0.1", "[::1]", "localhost"];
+/** A URL whose host is exactly a loopback literal (look-alikes such as 127.0.0.1.nip.io fail). */
+export declare function isLoopbackUrl(value: string | undefined): boolean;
+/** The seam guard: TEST_MODE exactly "1" and every guard URL a loopback literal. */
+export declare function testModeActive(repo: Repo, env: Readonly<Record<string, string | undefined>>): boolean;
+/**
+ * The C17-R18 integrity allowlist (ruling 31(2)): the pre-existing tests and generated snapshots
+ * that M1 may legitimately change, so the test_integrity tool does not count their edits as a
+ * deletion, skip or weakening. Closed to R18's three kinds. Each entry is a literal repo-relative
+ * path (the narrowest glob): spec coverage is the api's spec-coverage gates, route inventory is
+ * `npm run inventory:check` (the extractor's tests and its exempt lists), openapi snapshots are
+ * the two files `npm run openapi:check` diffs. Repos use the vitest_suite enum; gateway, cli and
+ * the api postgrest suite hold no file of these kinds.
+ */
+export declare const TEST_ALLOWLIST_KINDS: readonly ["spec_coverage", "route_inventory", "openapi_snapshot"];
+export type TestAllowlistKind = (typeof TEST_ALLOWLIST_KINDS)[number];
+export declare const TEST_ALLOWLIST_REPOS: readonly ["gateway", "api", "api_postgrest", "cli", "durable_contract"];
+export type TestAllowlistRepo = (typeof TEST_ALLOWLIST_REPOS)[number];
+export interface TestAllowlistEntry {
+    readonly repo: TestAllowlistRepo;
+    readonly kind: TestAllowlistKind;
+    readonly path: string;
+}
+/**
+ * test_integrity baseline runs (ruling 31.1): the merge-base suites run this many times to record
+ * flaky tests (passes and fails across runs) and baseline_failing ones (fails every run); also the
+ * most attempts a test recorded flaky gets in the candidate run.
+ */
+export declare const TEST_FLAKY_RUNS = 3;
+export declare const TEST_ALLOWLIST: readonly TestAllowlistEntry[];
+/** Whether `path` (repo-relative, exact) is on TEST_ALLOWLIST for `repo`. */
+export declare function isTestAllowlisted(repo: TestAllowlistRepo, path: string): boolean;