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

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

@@ -0,0 +1,205 @@
+/**
+ * The executor and internal route table (wave-0 fix rulings 1.02 and 3a; BACKBONE A3; C04). One
+ * table for enrollment, the executor contract and the gateway internal routes, in the shape the
+ * datasets cite: a fixed route carries `path`; a route scoped to one id carries `pre` and `post`,
+ * and its path is `${pre}${id}${post}`. Not customer facing: the executor contract is called only
+ * by Mnemom's own daemon, and enrollment only through `mnemom agent host install` / `renew`.
+ *
+ * `auth` names the credential the route takes: the owner's JWT, the enrollment poll secret, the
+ * executor key from EXECUTOR_STATE_FILE, or the gateway-internal service credential. `owner` (ruling
+ * 33.22) is the owner's JWT, or the owner's personal org API key where the S1 owner-credential rule
+ * allows it.
+ *
+ * Owner session verbs (ruling 33.22; design-v3 section 3.5, BACKBONE A2): scoped on the
+ * conversation id under /v1/agent/sessions/; the `?agent_id=` query is not part of the match. Not
+ * frozen: move, inbox, triggers and profiles (not in A2), the pre-existing GET /{cid} and POST
+ * /{cid}/contract, and create and list (their methods are not spelled in the sources).
+ *
+ * Doors amendment (ruling 34.03): exec_ready_list (the pool discovery read) and exec_oidc_exchange
+ * (the CI runner's GitHub OIDC exchange for a one-lease org-scope key). S1 picks the literal paths;
+ * neither sits under /v1/executor/sessions/, so no session id can collide with them.
+ *
+ * Charter by hash (ruling 33.32, logged as 33.29 in the W1 build log; design-v3 section 3.5
+ * Internal): int_charter is the api route the gateway's durable seal calls on a cold charter LRU.
+ * The api serves it (A2: only the api holds the charter DEK); the gateway sends
+ * CHARTER_BY_HASH_BODY_KEYS with INTERNAL_KEY_HEADER and reads CHARTER_BY_HASH_RESPONSE.
+ */
+export type RouteMethod = "GET" | "POST" | "DELETE";
+/** github_oidc (ruling 34.03 (1)): a GitHub Actions workflow OIDC token, in the body, exchanged for a one-lease key. */
+export type RouteAuth = "owner_jwt" | "owner" | "poll_secret" | "executor_key" | "internal" | "github_oidc";
+export interface FixedRoute {
+    readonly method: RouteMethod;
+    readonly auth: RouteAuth;
+    readonly path: string;
+}
+export interface ScopedRoute {
+    readonly method: RouteMethod;
+    readonly auth: RouteAuth;
+    readonly pre: string;
+    readonly post: string;
+}
+export declare const ROUTES: Readonly<{
+    /** Start an enrollment (device code). */
+    exec_enroll: FixedRoute;
+    /** Poll an enrollment; errors are ENROLL_POLL_ERRORS. */
+    exec_enroll_poll: FixedRoute;
+    exec_list: FixedRoute;
+    exec_revoke: ScopedRoute;
+    exec_renew: ScopedRoute;
+    /** Polled every EXECUTOR_POLL_S. */
+    exec_sessions: FixedRoute;
+    exec_attest: ScopedRoute;
+    exec_claim: ScopedRoute;
+    exec_hello: ScopedRoute;
+    exec_release: ScopedRoute;
+    exec_append: ScopedRoute;
+    exec_seat_exit: ScopedRoute;
+    exec_fail: ScopedRoute;
+    /** One call per executor, batched over its sessions. */
+    exec_heartbeat: FixedRoute;
+    /** The org-scope executor's claimable pool sessions, oldest first; `?limit=` (READY_SESSIONS_LIMIT_MIN..MAX) is not part of the match. */
+    exec_ready_list: FixedRoute;
+    /** Body {oidc_token}; answers a one-lease org-scope executor key or an OIDC_EXCHANGE_REFUSALS refusal. */
+    exec_oidc_exchange: FixedRoute;
+    own_lock: ScopedRoute;
+    own_unlock: ScopedRoute;
+    own_pause: ScopedRoute;
+    own_resume: ScopedRoute;
+    own_complete: ScopedRoute;
+    own_kill: ScopedRoute;
+    own_amend: ScopedRoute;
+    own_fail: ScopedRoute;
+    own_events: ScopedRoute;
+    int_events: FixedRoute;
+    int_arm: FixedRoute;
+    int_sweep: FixedRoute;
+    /** Charter by hash (ruling 33.32): body CHARTER_BY_HASH_BODY_KEYS, answer CHARTER_BY_HASH_RESPONSE. */
+    int_charter: FixedRoute;
+}>;
+export type RouteName = keyof typeof ROUTES;
+/**
+ * The concrete path of a route: a fixed route takes no id; a scoped route takes exactly one safe id
+ * (letters, digits, '-'; at most 64), so a path never gains a segment.
+ */
+export declare function routePath(name: RouteName, id?: string): string;
+/**
+ * The GET ROUTES.exec_sessions body (rulings 24.16, 33.28 (4), 33.28.2), in one of two forms:
+ *  - `sessions`: `{sessions: [item, ...]}`, each item exactly the ten keys below. id is the
+ *    agent_sessions.id uuid in lowercase, the id every scoped executor route takes; spec is the
+ *    current charter version's launch_spec (null with no charter). No item carries a secret.
+ *  - `grant_expired`: `{sessions: [], grant_expires_at, grant_expired: true}` when the executor's
+ *    grant has lapsed. The daemon reports it in host status; it is not a malformed answer.
+ * Each value names its type: an S1 field type, `|null` when NULL is allowed, `session_state` a
+ * SESSION_STATES value, `state_reason` a reason valid for the item's state.
+ */
+export declare const EXEC_SESSIONS_RESPONSE: Readonly<{
+    sessions: Readonly<{
+        item: Readonly<{
+            id: "uuid";
+            agent_id: "string";
+            state: "session_state";
+            state_reason: "state_reason|null";
+            lease_epoch: "integer";
+            lease_expires_at: "timestamp|null";
+            held_here: "boolean";
+            cc_session_id: "string|null";
+            cwd: "string|null";
+            spec: "object|null";
+        }>;
+    }>;
+    grant_expired: Readonly<{
+        sessions: "empty";
+        grant_expires_at: "timestamp";
+        grant_expired: true;
+    }>;
+}>;
+/** One poll item: exactly the ten keys of EXEC_SESSIONS_RESPONSE.sessions.item, each of its type. */
+export declare function execSessionsItemOk(v: unknown): boolean;
+/** True for either form of EXEC_SESSIONS_RESPONSE, closed at the top level and per item (ruling 33.28.2). */
+export declare function execSessionsResponseOk(v: unknown): boolean;
+/**
+ * The owner session read (GET /v1/agent/sessions/{cid}, durable_session_view): the one field S1
+ * freezes there. Open on purpose: every other key the view carries stays the api's, so this pins
+ * only that `cc_session_id` is present, a string or null, the value `sessions adopt` matches a live
+ * Claude Code process on. Not a closed schema of the view.
+ */
+export declare const OWNER_SESSION_VIEW_FIELDS: Readonly<{
+    cc_session_id: "string|null";
+}>;
+/** True for an owner session view object carrying every OWNER_SESSION_VIEW_FIELDS key, of its type; other keys pass. */
+export declare function ownerSessionViewOk(v: unknown): boolean;
+/** The only header that carries the executor key on an executor route; never `Authorization` (33.28 (1)). */
+export declare const EXECUTOR_KEY_HEADER = "X-Mnemom-Api-Key";
+/** POST exec_heartbeat body: exactly these keys, both required (33.28.1); entries hold HEARTBEAT_ENTRY_FIELDS. */
+export declare const HEARTBEAT_REQUEST_KEYS: readonly ["nonce", "entries"];
+/**
+ * A heartbeat body (33.28.1): exactly {nonce, entries}, a non-empty nonce, and each entry exactly
+ * HEARTBEAT_ENTRY_FIELDS (no per-entry nonce, no `session` alias).
+ */
+export declare function heartbeatRequestOk(v: unknown): boolean;
+/** POST exec_claim body keys: nonce required, tokens and new_key optional (33.28 (3)). */
+export declare const CLAIM_BODY_KEYS: readonly ["nonce", "tokens", "new_key"];
+/** A claim body: only CLAIM_BODY_KEYS, a non-empty nonce, an object tokens and a boolean new_key when present. */
+export declare function claimBodyOk(v: unknown): boolean;
+/**
+ * The needs_key retry rule (33.28 (3)): after a 409 durable_claim_needs_key the daemon sends the same
+ * claim once more with new_key: true, and never sends new_key: true otherwise. Returns the body of
+ * the one retry, or null when no retry is due (another answer, or the retry was already sent).
+ */
+export declare function claimNeedsKeyRetry(body: {
+    readonly nonce: string;
+    readonly tokens?: Record<string, unknown>;
+}, answerCode: string | null, retried: boolean): {
+    nonce: string;
+    tokens?: Record<string, unknown>;
+    new_key: true;
+} | null;
+/** The header that carries the gateway-internal service credential on an `internal` route (ruling 33.32). */
+export declare const INTERNAL_KEY_HEADER = "X-Internal-Key";
+/** POST int_charter body: exactly these keys, both required (ruling 33.32). */
+export declare const CHARTER_BY_HASH_BODY_KEYS: readonly ["session_id", "charter_hash"];
+/**
+ * A charter-by-hash body: exactly {session_id, charter_hash}, session_id the agent_sessions.id uuid
+ * in lowercase and charter_hash the charter version's 64-hex hash (charterHash). A body that fails
+ * this names no charter, so the api answers it as it answers an unknown one: 404
+ * durable_charter_not_found.
+ */
+export declare function charterByHashBodyOk(v: unknown): boolean;
+/**
+ * The 200 answer of POST int_charter (ruling 33.32): the charter version whose hash is the body's
+ * charter_hash, for the body's session, with its contract decrypted by the api. Exactly these keys:
+ *  - conversation_id: the session's own conversation id (non-empty);
+ *  - version: the charter version (integer, at least 1);
+ *  - sealed_at: the charter's original sealed_at instant, ISO 8601 in UTC as the api sends it:
+ *    `YYYY-MM-DDTHH:MM:SS[.ffffff]` then `Z` or `+00:00` (CHARTER_SEALED_AT_RE);
+ *  - contract: the decrypted envelope plaintext, exactly the four Contract keys (envelope.ts), each
+ *    list an array of strings (never null: the gateway refuses a non-array requirements).
+ * An unknown session, or a hash that is not one of that session's charter versions, answers 404
+ * durable_charter_not_found, and the gateway refuses admission (durable_admission_unavailable).
+ */
+export declare const CHARTER_BY_HASH_RESPONSE: Readonly<{
+    conversation_id: "string";
+    version: "integer>=1";
+    sealed_at: "utc_timestamp";
+    contract: Readonly<{
+        statement: "string";
+        requirements: "string[]";
+        allowed_paths: "string[]";
+        forbidden_paths: "string[]";
+    }>;
+}>;
+/** The charter answer's sealed_at: ISO 8601 with a `T`, up to six fraction digits, and `Z` or `+00:00`. */
+export declare const CHARTER_SEALED_AT_RE: RegExp;
+/** True for a CHARTER_BY_HASH_RESPONSE answer, closed at the top level and in the contract. */
+export declare function charterByHashResponseOk(v: unknown): boolean;
+/**
+ * POST int_events (GATEWAY_EVENTS_ROUTE) body: exactly these keys, all required (ruling 33.32 (2);
+ * G2 settle.ts appendGatewayEvent). refs may be null, which the api reads as `{}`.
+ */
+export declare const GATEWAY_EVENTS_BODY_KEYS: readonly ["session_id", "kind", "epoch", "idempotency_key", "refs"];
+/**
+ * A gateway events body: exactly GATEWAY_EVENTS_BODY_KEYS, session_id a lowercase uuid, kind one of
+ * GATEWAY_WRITABLE_KINDS, epoch a non-negative integer, a non-empty idempotency_key, and refs null
+ * or an object that passes the kind's S1 refs schema (null read as `{}`).
+ */
+export declare function gatewayEventsBodyOk(v: unknown): boolean;

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

@@ -0,0 +1,315 @@
+// GENERATED from shared/durable-contract/src/routes.ts by cli/scripts/sync-durable-contract.mjs; do not edit.
+/**
+ * The executor and internal route table (wave-0 fix rulings 1.02 and 3a; BACKBONE A3; C04). One
+ * table for enrollment, the executor contract and the gateway internal routes, in the shape the
+ * datasets cite: a fixed route carries `path`; a route scoped to one id carries `pre` and `post`,
+ * and its path is `${pre}${id}${post}`. Not customer facing: the executor contract is called only
+ * by Mnemom's own daemon, and enrollment only through `mnemom agent host install` / `renew`.
+ *
+ * `auth` names the credential the route takes: the owner's JWT, the enrollment poll secret, the
+ * executor key from EXECUTOR_STATE_FILE, or the gateway-internal service credential. `owner` (ruling
+ * 33.22) is the owner's JWT, or the owner's personal org API key where the S1 owner-credential rule
+ * allows it.
+ *
+ * Owner session verbs (ruling 33.22; design-v3 section 3.5, BACKBONE A2): scoped on the
+ * conversation id under /v1/agent/sessions/; the `?agent_id=` query is not part of the match. Not
+ * frozen: move, inbox, triggers and profiles (not in A2), the pre-existing GET /{cid} and POST
+ * /{cid}/contract, and create and list (their methods are not spelled in the sources).
+ *
+ * Doors amendment (ruling 34.03): exec_ready_list (the pool discovery read) and exec_oidc_exchange
+ * (the CI runner's GitHub OIDC exchange for a one-lease org-scope key). S1 picks the literal paths;
+ * neither sits under /v1/executor/sessions/, so no session id can collide with them.
+ *
+ * Charter by hash (ruling 33.32, logged as 33.29 in the W1 build log; design-v3 section 3.5
+ * Internal): int_charter is the api route the gateway's durable seal calls on a cold charter LRU.
+ * The api serves it (A2: only the api holds the charter DEK); the gateway sends
+ * CHARTER_BY_HASH_BODY_KEYS with INTERNAL_KEY_HEADER and reads CHARTER_BY_HASH_RESPONSE.
+ */
+import { ARM_ROUTE } from "./arm.js";
+import { fieldOk } from "./admission.js";
+import { HEX64_RE, UUID_RE } from "./canonical.js";
+import { HEARTBEAT_ENTRY_FIELDS } from "./codes.js";
+import { parseContract } from "./envelope.js";
+import { GATEWAY_EVENTS_ROUTE, GATEWAY_WRITABLE_KINDS, validateRefs } from "./events.js";
+import { ALL_STATE_REASONS, isSessionState, isValidStateReason } from "./states.js";
+const fixed = (method, auth, path) => Object.freeze({ method, auth, path });
+const scoped = (method, auth, pre, post) => Object.freeze({ method, auth, pre, post });
+const EXECUTORS = "/v1/executors";
+const EXEC_SESSIONS = "/v1/executor/sessions";
+const EXEC_SESSION_PRE = `${EXEC_SESSIONS}/`;
+const OWNER_SESSION_PRE = "/v1/agent/sessions/";
+export const ROUTES = Object.freeze({
+    // ---- enrollment and grant (owner side) ----
+    /** Start an enrollment (device code). */
+    exec_enroll: fixed("POST", "owner_jwt", `${EXECUTORS}/enroll`),
+    /** Poll an enrollment; errors are ENROLL_POLL_ERRORS. */
+    exec_enroll_poll: fixed("POST", "poll_secret", `${EXECUTORS}/enroll/poll`),
+    exec_list: fixed("GET", "owner_jwt", EXECUTORS),
+    exec_revoke: scoped("DELETE", "owner_jwt", `${EXECUTORS}/`, ""),
+    exec_renew: scoped("POST", "owner_jwt", `${EXECUTORS}/`, "/renew"),
+    // ---- executor contract (daemon side) ----
+    /** Polled every EXECUTOR_POLL_S. */
+    exec_sessions: fixed("GET", "executor_key", EXEC_SESSIONS),
+    exec_attest: scoped("POST", "executor_key", EXEC_SESSION_PRE, "/attest"),
+    exec_claim: scoped("POST", "executor_key", EXEC_SESSION_PRE, "/claim"),
+    exec_hello: scoped("POST", "executor_key", EXEC_SESSION_PRE, "/hello"),
+    exec_release: scoped("POST", "executor_key", EXEC_SESSION_PRE, "/release"),
+    exec_append: scoped("POST", "executor_key", EXEC_SESSION_PRE, "/events"),
+    exec_seat_exit: scoped("POST", "executor_key", EXEC_SESSION_PRE, "/seat-exit"),
+    exec_fail: scoped("POST", "executor_key", EXEC_SESSION_PRE, "/fail"),
+    /** One call per executor, batched over its sessions. */
+    exec_heartbeat: fixed("POST", "executor_key", "/v1/executor/heartbeat"),
+    // ---- Doors amendment (ruling 34.03) ----
+    /** The org-scope executor's claimable pool sessions, oldest first; `?limit=` (READY_SESSIONS_LIMIT_MIN..MAX) is not part of the match. */
+    exec_ready_list: fixed("GET", "executor_key", "/v1/executor/ready"),
+    /** Body {oidc_token}; answers a one-lease org-scope executor key or an OIDC_EXCHANGE_REFUSALS refusal. */
+    exec_oidc_exchange: fixed("POST", "github_oidc", "/v1/executor/oidc/exchange"),
+    // ---- owner session verbs (ruling 33.22) ----
+    own_lock: scoped("POST", "owner", OWNER_SESSION_PRE, "/lock"),
+    own_unlock: scoped("POST", "owner", OWNER_SESSION_PRE, "/unlock"),
+    own_pause: scoped("POST", "owner", OWNER_SESSION_PRE, "/pause"),
+    own_resume: scoped("POST", "owner", OWNER_SESSION_PRE, "/resume"),
+    own_complete: scoped("POST", "owner", OWNER_SESSION_PRE, "/complete"),
+    own_kill: scoped("POST", "owner", OWNER_SESSION_PRE, "/kill"),
+    own_amend: scoped("POST", "owner", OWNER_SESSION_PRE, "/amend"),
+    own_fail: scoped("POST", "owner", OWNER_SESSION_PRE, "/fail"),
+    own_events: scoped("GET", "owner", OWNER_SESSION_PRE, "/events"),
+    // ---- gateway internal ----
+    int_events: fixed("POST", "internal", GATEWAY_EVENTS_ROUTE),
+    int_arm: fixed("GET", "internal", ARM_ROUTE),
+    int_sweep: fixed("POST", "internal", "/internal/durable/sweep"),
+    /** Charter by hash (ruling 33.32): body CHARTER_BY_HASH_BODY_KEYS, answer CHARTER_BY_HASH_RESPONSE. */
+    int_charter: fixed("POST", "internal", "/internal/durable/charter"),
+});
+const ROUTE_ID_RE = /^[A-Za-z0-9-]{1,64}$/;
+/**
+ * The concrete path of a route: a fixed route takes no id; a scoped route takes exactly one safe id
+ * (letters, digits, '-'; at most 64), so a path never gains a segment.
+ */
+export function routePath(name, id) {
+    const r = ROUTES[name];
+    if ("path" in r) {
+        if (id !== undefined)
+            throw new RangeError(`route ${name} takes no id`);
+        return r.path;
+    }
+    if (id === undefined || !ROUTE_ID_RE.test(id))
+        throw new RangeError(`route ${name} needs a safe id`);
+    return `${r.pre}${id}${r.post}`;
+}
+/**
+ * The GET ROUTES.exec_sessions body (rulings 24.16, 33.28 (4), 33.28.2), in one of two forms:
+ *  - `sessions`: `{sessions: [item, ...]}`, each item exactly the ten keys below. id is the
+ *    agent_sessions.id uuid in lowercase, the id every scoped executor route takes; spec is the
+ *    current charter version's launch_spec (null with no charter). No item carries a secret.
+ *  - `grant_expired`: `{sessions: [], grant_expires_at, grant_expired: true}` when the executor's
+ *    grant has lapsed. The daemon reports it in host status; it is not a malformed answer.
+ * Each value names its type: an S1 field type, `|null` when NULL is allowed, `session_state` a
+ * SESSION_STATES value, `state_reason` a reason valid for the item's state.
+ */
+export const EXEC_SESSIONS_RESPONSE = Object.freeze({
+    sessions: Object.freeze({
+        item: Object.freeze({
+            id: "uuid",
+            agent_id: "string",
+            state: "session_state",
+            state_reason: "state_reason|null",
+            lease_epoch: "integer",
+            lease_expires_at: "timestamp|null",
+            held_here: "boolean",
+            cc_session_id: "string|null",
+            cwd: "string|null",
+            spec: "object|null",
+        }),
+    }),
+    grant_expired: Object.freeze({
+        sessions: "empty",
+        grant_expires_at: "timestamp",
+        grant_expired: true,
+    }),
+});
+const isObj = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
+const keysExactly = (o, keys) => Object.keys(o).length === keys.length && keys.every((k) => k in o);
+/** One poll item: exactly the ten keys of EXEC_SESSIONS_RESPONSE.sessions.item, each of its type. */
+export function execSessionsItemOk(v) {
+    if (!isObj(v) || !keysExactly(v, Object.keys(EXEC_SESSIONS_RESPONSE.sessions.item)))
+        return false;
+    if (typeof v.id !== "string" || !UUID_RE.test(v.id))
+        return false;
+    if (!isSessionState(v.state))
+        return false;
+    if (!fieldOk({ type: "enum", nullable: true, values: ALL_STATE_REASONS }, v.state_reason) ||
+        !isValidStateReason(v.state, v.state_reason))
+        return false;
+    return (fieldOk({ type: "string", nullable: false }, v.agent_id) &&
+        fieldOk({ type: "integer", nullable: false }, v.lease_epoch) &&
+        fieldOk({ type: "timestamp", nullable: true }, v.lease_expires_at) &&
+        fieldOk({ type: "boolean", nullable: false }, v.held_here) &&
+        fieldOk({ type: "string", nullable: true }, v.cc_session_id) &&
+        fieldOk({ type: "string", nullable: true }, v.cwd) &&
+        fieldOk({ type: "object", nullable: true }, v.spec));
+}
+/** True for either form of EXEC_SESSIONS_RESPONSE, closed at the top level and per item (ruling 33.28.2). */
+export function execSessionsResponseOk(v) {
+    if (!isObj(v) || !Array.isArray(v.sessions))
+        return false;
+    if ("grant_expired" in v)
+        return (keysExactly(v, Object.keys(EXEC_SESSIONS_RESPONSE.grant_expired)) &&
+            v.grant_expired === true &&
+            v.sessions.length === 0 &&
+            fieldOk({ type: "timestamp", nullable: false }, v.grant_expires_at));
+    return keysExactly(v, ["sessions"]) && v.sessions.every(execSessionsItemOk);
+}
+// ---- owner session view (mnemom-test #1085, lead ruling 2026-10-28, option A) -------------------
+/**
+ * The owner session read (GET /v1/agent/sessions/{cid}, durable_session_view): the one field S1
+ * freezes there. Open on purpose: every other key the view carries stays the api's, so this pins
+ * only that `cc_session_id` is present, a string or null, the value `sessions adopt` matches a live
+ * Claude Code process on. Not a closed schema of the view.
+ */
+export const OWNER_SESSION_VIEW_FIELDS = Object.freeze({
+    cc_session_id: "string|null",
+});
+/** True for an owner session view object carrying every OWNER_SESSION_VIEW_FIELDS key, of its type; other keys pass. */
+export function ownerSessionViewOk(v) {
+    return (isObj(v) && "cc_session_id" in v && fieldOk({ type: "string", nullable: true }, v.cc_session_id));
+}
+// ---- executor wire (ruling 33.28, 33.28.1) ----------------------------------------------------
+/** The only header that carries the executor key on an executor route; never `Authorization` (33.28 (1)). */
+export const EXECUTOR_KEY_HEADER = "X-Mnemom-Api-Key";
+/** POST exec_heartbeat body: exactly these keys, both required (33.28.1); entries hold HEARTBEAT_ENTRY_FIELDS. */
+export const HEARTBEAT_REQUEST_KEYS = ["nonce", "entries"];
+/**
+ * A heartbeat body (33.28.1): exactly {nonce, entries}, a non-empty nonce, and each entry exactly
+ * HEARTBEAT_ENTRY_FIELDS (no per-entry nonce, no `session` alias).
+ */
+export function heartbeatRequestOk(v) {
+    if (!isObj(v) || !keysExactly(v, HEARTBEAT_REQUEST_KEYS))
+        return false;
+    if (typeof v.nonce !== "string" || v.nonce.length === 0 || !Array.isArray(v.entries))
+        return false;
+    return v.entries.every((e) => isObj(e) &&
+        keysExactly(e, HEARTBEAT_ENTRY_FIELDS) &&
+        fieldOk({ type: "uuid", nullable: false }, e.session_id) &&
+        fieldOk({ type: "integer", nullable: false }, e.epoch) &&
+        fieldOk({ type: "uuid", nullable: false }, e.spawn_id));
+}
+/** POST exec_claim body keys: nonce required, tokens and new_key optional (33.28 (3)). */
+export const CLAIM_BODY_KEYS = ["nonce", "tokens", "new_key"];
+/** A claim body: only CLAIM_BODY_KEYS, a non-empty nonce, an object tokens and a boolean new_key when present. */
+export function claimBodyOk(v) {
+    if (!isObj(v))
+        return false;
+    if (Object.keys(v).some((k) => !CLAIM_BODY_KEYS.includes(k)))
+        return false;
+    if (typeof v.nonce !== "string" || v.nonce.length === 0)
+        return false;
+    if ("tokens" in v && !isObj(v.tokens))
+        return false;
+    return !("new_key" in v) || typeof v.new_key === "boolean";
+}
+/**
+ * The needs_key retry rule (33.28 (3)): after a 409 durable_claim_needs_key the daemon sends the same
+ * claim once more with new_key: true, and never sends new_key: true otherwise. Returns the body of
+ * the one retry, or null when no retry is due (another answer, or the retry was already sent).
+ */
+export function claimNeedsKeyRetry(body, answerCode, retried) {
+    if (answerCode !== "durable_claim_needs_key" || retried)
+        return null;
+    return { ...body, new_key: true };
+}
+// ---- charter by hash (ruling 33.32) -----------------------------------------------------------
+/** The header that carries the gateway-internal service credential on an `internal` route (ruling 33.32). */
+export const INTERNAL_KEY_HEADER = "X-Internal-Key";
+/** POST int_charter body: exactly these keys, both required (ruling 33.32). */
+export const CHARTER_BY_HASH_BODY_KEYS = ["session_id", "charter_hash"];
+/**
+ * A charter-by-hash body: exactly {session_id, charter_hash}, session_id the agent_sessions.id uuid
+ * in lowercase and charter_hash the charter version's 64-hex hash (charterHash). A body that fails
+ * this names no charter, so the api answers it as it answers an unknown one: 404
+ * durable_charter_not_found.
+ */
+export function charterByHashBodyOk(v) {
+    return (isObj(v) &&
+        keysExactly(v, CHARTER_BY_HASH_BODY_KEYS) &&
+        typeof v.session_id === "string" &&
+        UUID_RE.test(v.session_id) &&
+        typeof v.charter_hash === "string" &&
+        HEX64_RE.test(v.charter_hash));
+}
+/**
+ * The 200 answer of POST int_charter (ruling 33.32): the charter version whose hash is the body's
+ * charter_hash, for the body's session, with its contract decrypted by the api. Exactly these keys:
+ *  - conversation_id: the session's own conversation id (non-empty);
+ *  - version: the charter version (integer, at least 1);
+ *  - sealed_at: the charter's original sealed_at instant, ISO 8601 in UTC as the api sends it:
+ *    `YYYY-MM-DDTHH:MM:SS[.ffffff]` then `Z` or `+00:00` (CHARTER_SEALED_AT_RE);
+ *  - contract: the decrypted envelope plaintext, exactly the four Contract keys (envelope.ts), each
+ *    list an array of strings (never null: the gateway refuses a non-array requirements).
+ * An unknown session, or a hash that is not one of that session's charter versions, answers 404
+ * durable_charter_not_found, and the gateway refuses admission (durable_admission_unavailable).
+ */
+export const CHARTER_BY_HASH_RESPONSE = Object.freeze({
+    conversation_id: "string",
+    version: "integer>=1",
+    sealed_at: "utc_timestamp",
+    contract: Object.freeze({
+        statement: "string",
+        requirements: "string[]",
+        allowed_paths: "string[]",
+        forbidden_paths: "string[]",
+    }),
+});
+/** The charter answer's sealed_at: ISO 8601 with a `T`, up to six fraction digits, and `Z` or `+00:00`. */
+export const CHARTER_SEALED_AT_RE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{1,6})?(Z|\+00:00)$/;
+/** True for a CHARTER_BY_HASH_RESPONSE answer, closed at the top level and in the contract. */
+export function charterByHashResponseOk(v) {
+    if (!isObj(v) || !keysExactly(v, Object.keys(CHARTER_BY_HASH_RESPONSE)))
+        return false;
+    if (!fieldOk({ type: "string", nullable: false }, v.conversation_id))
+        return false;
+    if (!Number.isSafeInteger(v.version) || v.version < 1)
+        return false;
+    if (typeof v.sealed_at !== "string" || !CHARTER_SEALED_AT_RE.test(v.sealed_at))
+        return false;
+    if (!Number.isFinite(Date.parse(v.sealed_at)))
+        return false;
+    const c = v.contract;
+    return (isObj(c) &&
+        keysExactly(c, Object.keys(CHARTER_BY_HASH_RESPONSE.contract)) &&
+        Array.isArray(c.requirements) &&
+        Array.isArray(c.allowed_paths) &&
+        Array.isArray(c.forbidden_paths) &&
+        parseContract(c) !== null);
+}
+// ---- gateway events (ruling 33.32 (2)) --------------------------------------------------------
+/**
+ * POST int_events (GATEWAY_EVENTS_ROUTE) body: exactly these keys, all required (ruling 33.32 (2);
+ * G2 settle.ts appendGatewayEvent). refs may be null, which the api reads as `{}`.
+ */
+export const GATEWAY_EVENTS_BODY_KEYS = [
+    "session_id",
+    "kind",
+    "epoch",
+    "idempotency_key",
+    "refs",
+];
+/**
+ * A gateway events body: exactly GATEWAY_EVENTS_BODY_KEYS, session_id a lowercase uuid, kind one of
+ * GATEWAY_WRITABLE_KINDS, epoch a non-negative integer, a non-empty idempotency_key, and refs null
+ * or an object that passes the kind's S1 refs schema (null read as `{}`).
+ */
+export function gatewayEventsBodyOk(v) {
+    if (!isObj(v) || !keysExactly(v, GATEWAY_EVENTS_BODY_KEYS))
+        return false;
+    if (typeof v.session_id !== "string" || !UUID_RE.test(v.session_id))
+        return false;
+    const kind = v.kind;
+    if (!GATEWAY_WRITABLE_KINDS.includes(kind))
+        return false;
+    if (!fieldOk({ type: "integer", nullable: false }, v.epoch))
+        return false;
+    if (typeof v.idempotency_key !== "string" || v.idempotency_key.length === 0)
+        return false;
+    return validateRefs(kind, v.refs ?? {});
+}

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

@@ -0,0 +1,126 @@
+/**
+ * The M1 database catalogue S1 freezes for A1 and for the C17 catalog oracle (C17-R23..R27;
+ * BACKBONE A1; design §3.3). A1 implements exactly this; a needed difference is an S1 amendment.
+ *
+ * Column decisions beyond design §3.3 (whose lists end in "…"):
+ *  - agent_sessions.cwd: the registered worktree root (the idle builder source reads it);
+ *  - agent_sessions.spawn_id / hello_at: the current epoch's registered spawn and its accepted
+ *    hello (heartbeat revival and durable_seat_exit test them in one row read);
+ *  - durable_lease_keys.agent_id / org_id: attribution at the source (C14-R14);
+ *  - agent_executors.label: the machine label `show` and `session_homed_elsewhere` print;
+ *  - agent_session_events.principal_ref (C10-R0 (d)) and durable_event_kinds.writer (C10-R0 (e));
+ *  - durable_approvals.subject / requested_by: the owner_mutation subject kind and requester.
+ *
+ * Doors amendment columns (rulings 34.03, 34.06, 34.10), each appended to its table:
+ *  - agent_sessions.wait_ref (JSONB, NULL unless wait_reason is a PARKED_ONLY_WAIT_REASONS value);
+ *  - agent_executors.scope (TEXT NOT NULL DEFAULT 'user', EXECUTOR_SCOPES);
+ *  - durable_org_policy.dispatch_agent_id (nullable FK agents, same org).
+ *
+ * Amendment 54 (signed off by Wassim 2026-10-29; ruling B5a as amended, 1a + 2a), appended to its table:
+ *  - agent_sessions.new_session (BOOLEAN NOT NULL DEFAULT false): true only on a row that
+ *    create-and-lock inserted (`--new` under durable=always on a durable-only agent, one
+ *    transaction with the lock); a plain lock never sets it. The executor learns it only from the
+ *    claim success answer (`new_session: true`, while no seat hello was ever accepted for the
+ *    session); EXEC_SESSIONS_RESPONSE item keys are unchanged.
+ */
+export declare const M1_TABLES: readonly ["agent_sessions", "durable_lease_keys", "agent_session_charters", "agent_session_events", "durable_event_kinds", "agent_session_chains", "agent_executors", "agent_durable_profiles", "durable_cell_state", "durable_org_policy", "durable_user_policy", "durable_approvals", "durable_approval_attestations"];
+export type M1Table = (typeof M1_TABLES)[number];
+export declare const M1_COLUMNS: {
+    readonly [T in M1Table]: readonly string[];
+};
+/** Columns no anon/authenticated column-level grant may reach (C17-R27, C17-M44). */
+export declare const CIPHERTEXT_COLUMNS: readonly [readonly ["agent_session_charters", "contract_ciphertext"], readonly ["agent_session_charters", "wrapped_data_key"]];
+/** Columns that must NOT exist (dropped seams, cut items). */
+export declare const FORBIDDEN_COLUMNS: readonly [readonly ["durable_cell_state", "test_barriers_enabled"]];
+export interface Arbiter {
+    name: string;
+    table: M1Table;
+    columns: readonly string[];
+    nullsNotDistinct: boolean;
+    /** WHERE predicate as pg_get_indexdef prints it, or null for a full unique index. */
+    where: string | null;
+}
+/** Every unique index an M1 ON CONFLICT relies on (C17-R24). */
+export declare const M1_ARBITERS: readonly Arbiter[];
+/** The indexdef pg_get_indexdef prints for an arbiter (public schema, btree). */
+export declare function arbiterIndexDef(a: Arbiter): string;
+export declare const M1_FUNCTIONS: readonly ["resolve_durable_session_key", "agent_durable_only", "durable_schema_version", "durable_attest_begin", "durable_claim_lease", "durable_heartbeat", "durable_seat_hello", "durable_seat_exit", "durable_fail_session", "durable_release_lease", "durable_append_event", "durable_fence_check", "durable_guard_add", "durable_revoke_executor", "durable_sweep", "durable_kill_agent_sessions", "durable_agent_killed"];
+/** Functions keeping EXECUTE for PUBLIC/anon/authenticated: none in M1. */
+export declare const EXECUTE_EXCEPTIONS: readonly string[];
+export declare const M1_TRIGGERS: readonly [{
+    readonly name: "durable_agent_killed";
+    readonly table: "agents";
+    readonly fn: "durable_agent_killed";
+}];
+/** Not in M1: must be absent from the catalog. */
+export declare const ABSENT_FUNCTIONS_M1: readonly ["durable_assert_attach", "durable_set_org_policy", "durable_test_barrier"];
+/** Down migrations refuse while any of these has rows. */
+export declare const LEDGER_TABLES: readonly ["agent_sessions", "agent_session_events", "agent_session_charters", "durable_approvals", "durable_approval_attestations", "agent_executors"];
+export declare const MIGRATION_LOCK_TIMEOUT = "3s";
+/** The durable_cell_state seed: exactly one row per canonical cell id. */
+export declare function cellSeedRows(): {
+    cell_id: string;
+    cell_generation: number;
+    unattended_enabled: false;
+    lease_seconds: number;
+    resume_reset_seconds: number;
+}[];
+/**
+ * durable_approvals.subject (kind owner_mutation) and its target rule (ruling 32.12). An enrollment
+ * approval is a row with subject 'enrollment' and a NULL session_id, scoped by org_id and
+ * requested_by; a grant_renewal names its executor inside the subject. Every other subject names a
+ * session, question included (ruling 34.06.1.1: the question wait's approval, appended). A1
+ * mirrors both CHECKs. The journal's approval.requested refs enum does not gain
+ * 'enrollment' (events.ts): executor.enrolled is journaled into no session (C10-R0(f)).
+ */
+export declare const DURABLE_APPROVAL_SUBJECTS: readonly ["unlock", "unpause_contained", "grant_renewal", "budget_raise", "enrollment", "question"];
+export type DurableApprovalSubject = (typeof DURABLE_APPROVAL_SUBJECTS)[number];
+/** Subjects whose row may carry a NULL session_id. */
+export declare const DURABLE_APPROVAL_SESSIONLESS_SUBJECTS: readonly ["grant_renewal", "enrollment"];
+export declare const DURABLE_APPROVALS_SUBJECT_CHECK: string;
+export declare const DURABLE_APPROVALS_TARGET_CHECK: string;
+/** The target CHECK as a predicate. */
+export declare function approvalTargetOk(subject: DurableApprovalSubject, sessionId: string | null): boolean;
+/** The enrollment subject's risk_line_version: decimal text, never a number (ruling 32.30). */
+export declare const RISK_LINE_VERSION_TEXT_RE: RegExp;
+/**
+ * durable_approvals.subject_hash: lowercase hex sha256 of canonicalJson(subject) (rulings 32.12,
+ * 32.30). Subjects: {subject: 'enrollment', org_id, owner_user_id, runtime, risk_line_version},
+ * {subject: 'grant_renewal', executor_id}, {subject, session_id} for the session subjects. Rejects
+ * with RangeError on an unknown subject, an extra or missing key, or a value of the wrong form.
+ * An enrollment subject may also carry scope: 'org' and nothing else (ruling 34.03.1), so an org
+ * enrollment commits the approver to a runner that can claim any pool session in the org; without
+ * it the subject, and its hash, are M1's byte for byte.
+ */
+export declare function approvalSubjectHash(subject: Readonly<Record<string, unknown>>): Promise<string>;
+/**
+ * agent_sessions_ready_ck (ruling 34.02 (1), (2)): a ready row is locked, has no reason, no home and
+ * no holder. agent_sessions_state_reason_ck gains the arm `WHEN 'ready' THEN state_reason IS NULL`
+ * (STATE_REASONS.ready), and the state CHECK lists SESSION_STATES.
+ */
+export declare const AGENT_SESSIONS_READY_CHECK: string;
+/**
+ * agent_sessions_wait_parked_ck (ruling 34.06 (1), (2)): ci, question and budget are valid only with
+ * state 'parked', and wait_ref is set exactly when wait_reason is one of them. The wait_reason
+ * CHECK lists WAIT_REASONS.
+ */
+export declare const AGENT_SESSIONS_WAIT_PARKED_CHECK: string;
+/** agent_executors.scope CHECK (ruling 34.03 (1)). */
+export declare const AGENT_EXECUTORS_SCOPE_CHECK = "scope IN ('user','org')";
+/** The ready-row CHECK as a predicate over the columns it reads. */
+export declare function readyRowOk(row: {
+    readonly state: string;
+    readonly durable_mode: string;
+    readonly state_reason: string | null;
+    readonly home_executor_id: string | null;
+    readonly lease_executor_id: string | null;
+    readonly lease_expires_at: string | null;
+    readonly spawn_id: string | null;
+    readonly hello_at: string | null;
+}): boolean;
+/** The wait-parked CHECK as a predicate. */
+export declare function waitParkedRowOk(row: {
+    readonly state: string;
+    readonly wait_reason: string | null;
+    readonly wait_ref: unknown;
+}): boolean;