@mnemom/mnemom 0.17.34 → 0.17.35

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

@@ -156,7 +156,9 @@ export const M1_EXCLUDED_KINDS = [
 ];
 /**
  * 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).
+ * 34.02, 34.06), executor.turn_continued, and inbox.acked (S1 amendment 60: M1 left it out, the
+ * inbox ack writes it; M1_EXCLUDED_KINDS stays the frozen M1 record), appended so no existing index
+ * moves. Mirrors durable_event_kinds (parity test).
  */
 export const DURABLE_EVENT_KINDS = [
     "session.registered",
@@ -243,6 +245,7 @@ export const DURABLE_EVENT_KINDS = [
     "session.waiting",
     "session.wait_cleared",
     "executor.turn_continued",
+    "inbox.acked",
 ];
 export function isDurableEventKind(v) {
     return typeof v === "string" && DURABLE_EVENT_KINDS.includes(v);
@@ -502,6 +505,57 @@ const KIND_REFS = {
     // ---- 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 }),
+    // ---- S1 amendment 60 (signed off by Wassim 2026-11-02): the inbox. Content-free: ids, shas, enums ----
+    "inbox.admitted": obj({
+        inbox_id: UUID,
+        sha: S({ pattern: HEX64_PATTERN, maxLength: 64 }),
+        sender_kind: ENUM(["owner", "agent"]),
+        sender_agent_id: S({ pattern: "^[A-Za-z0-9_-]{1,64}$" }),
+        in_reply_to: UUID,
+    }, ["inbox_id", "sha", "sender_kind"], [
+        { field: "sender_kind", equals: "agent", require: ["sender_agent_id"] },
+        { field: "sender_kind", equals: "owner", forbid: ["sender_agent_id"] },
+    ]),
+    "inbox.rejected": obj({
+        reason: ENUM([
+            "not_allowlisted",
+            "not_locked",
+            "ended",
+            "unsealed",
+            "inbox_full",
+            "body_too_large",
+            "body_invalid",
+            "unattended_off",
+        ]),
+        sender_kind: ENUM(["owner", "agent"]),
+    }),
+    "inbox.coalesced": obj({ inbox_id: UUID, sha: S({ pattern: HEX64_PATTERN, maxLength: 64 }) }),
+    "inbox.delivered": obj({
+        inbox_id: UUID,
+        sha: S({ pattern: HEX64_PATTERN, maxLength: 64 }),
+        attempt: INT(1),
+    }),
+    "inbox.acked": obj({ inbox_id: UUID, sha: S({ pattern: HEX64_PATTERN, maxLength: 64 }) }),
+    "inbox.reverted": obj({
+        inbox_id: UUID,
+        sha: S({ pattern: HEX64_PATTERN, maxLength: 64 }),
+        reason: ENUM(["unconfirmed", "refused", "undeliverable"]),
+    }),
+    "inbox.dead": obj({
+        inbox_id: UUID,
+        sha: S({ pattern: HEX64_PATTERN, maxLength: 64 }),
+        reason: ENUM(["expired", "delivery_limit", "session_ended"]),
+    }),
+    // ---- S1 amendment 61 (signed off by Wassim 2026-11-02): questions. Content-free: ids, shas, enums ----
+    "question.asked": obj({
+        approval_id: UUID,
+        question_sha: S({ pattern: HEX64_PATTERN, maxLength: 64 }),
+    }),
+    "question.answered": obj({
+        approval_id: UUID,
+        outcome: ENUM(["answered", "dismissed"]),
+        via: ENUM(["coding_agent", "slack", "webhook", "mcp", "device"]),
+    }),
 };
 /** refs_schema for every M1 kind; kinds without a specific schema take EMPTY (refs must be {}). */
 export function refsSchemaOf(kind) {

package/dist/vendor/shared/durable-contract/freeze-record.d.ts

@@ -330,6 +330,13 @@ export declare const FREEZE_STRUCTURED: Readonly<{
         exec_heartbeat: import("./routes.js").FixedRoute;
         exec_ready_list: import("./routes.js").FixedRoute;
         exec_oidc_exchange: import("./routes.js").FixedRoute;
+        exec_inbox: import("./routes.js").ScopedRoute;
+        exec_inbox_take: import("./routes.js").ScopedRoute;
+        exec_inbox_ack: import("./routes.js").ScopedRoute;
+        exec_inbox_release: import("./routes.js").ScopedRoute;
+        exec_question: import("./routes.js").ScopedRoute;
+        exec_question_poll: import("./routes.js").ScopedRoute;
+        exec_question_release: import("./routes.js").ScopedRoute;
         own_lock: import("./routes.js").ScopedRoute;
         own_unlock: import("./routes.js").ScopedRoute;
         own_pause: import("./routes.js").ScopedRoute;
@@ -339,6 +346,13 @@ export declare const FREEZE_STRUCTURED: Readonly<{
         own_amend: import("./routes.js").ScopedRoute;
         own_fail: import("./routes.js").ScopedRoute;
         own_events: import("./routes.js").ScopedRoute;
+        own_inbox_send: import("./routes.js").ScopedRoute;
+        own_inbox_list: import("./routes.js").ScopedRoute;
+        own_inbox_senders: import("./routes.js").ScopedRoute;
+        own_inbox_sender_add: import("./routes.js").ScopedRoute;
+        own_inbox_sender_remove: import("./routes.js").ScopedRoute;
+        own_questions: import("./routes.js").ScopedRoute;
+        own_answer: import("./routes.js").ScopedRoute;
         int_events: import("./routes.js").FixedRoute;
         int_arm: import("./routes.js").FixedRoute;
         int_sweep: import("./routes.js").FixedRoute;

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

@@ -0,0 +1,299 @@
+/**
+ * The durable inbox (S1 amendment 60, signed off by Wassim 2026-11-02): how work reaches a locked session
+ * without anyone typing into its seat. The owner, or an agent on the owner's allowlist for the
+ * recipient agent, sends a message to the session (ROUTES.own_inbox_send); the api stores it
+ * (encrypted, as a charter contract is) and journals inbox.admitted. The session's executor takes it
+ * (ROUTES.exec_inbox_take: the api marks it delivered at the live epoch and journals
+ * inbox.delivered), pastes the delivery text into the seat, and acks it when the turn that answered
+ * it ends (ROUTES.exec_inbox_ack: inbox.acked). Between take and ack the message's sha is in the
+ * resolver's `inbox_open`, which is what lets amendment 60 (e) admit the seat's `inbox=<sha>` turn
+ * unattended.
+ *
+ * Every inbox.* kind stays api-written (writerOf): delivered and acked are written by the api inside
+ * the take and ack routes, in the transaction that moves the inbox row, never through exec_append.
+ * So an executor cannot journal a delivery the api did not make, and the gateway can never see a
+ * turn whose sha is not yet open.
+ *
+ * This file holds the limits, the message sha and delivery text recipes, and the closed wire shapes
+ * of the inbox routes (routes.ts lists the routes). Nothing here carries message text into the
+ * journal: refs are ids, shas and enums only.
+ */
+/** A message body is 1..this many UTF-8 bytes. */
+export declare const INBOX_BODY_MAX_BYTES = 16384;
+/** An admitted or delivered message nobody acks is dead (reason expired) this long after it was sent. */
+export declare const INBOX_TTL_S: number;
+/** A message taken this many times without an ack is dead (reason delivery_limit) instead of taken again. */
+export declare const INBOX_DELIVERY_LIMIT = 5;
+/** exec_inbox_take returns at most this many messages; `limit` defaults to 1. */
+export declare const INBOX_TAKE_LIMIT_MAX = 8;
+/** own_inbox_list returns at most this many messages, newest first. */
+export declare const INBOX_LIST_LIMIT = 100;
+/** At most this many live (unrevoked) allowlisted senders per recipient agent. */
+export declare const INBOX_SENDERS_MAX = 32;
+/** The open-message cap: a send that would open more than this is refused (inbox_full). */
+export declare const INBOX_OPEN_CAP = 64;
+/**
+ * Take re-offers a message delivered at the LIVE epoch once its last delivery is this old and it was
+ * neither acked nor released (the executor lost track of it: it died between the take and its own
+ * record, or gave up on a paste). The executor takes only while it tracks nothing for the seat and
+ * the seat is idle, so a re-offer never lands inside the turn answering it. At-least-once.
+ */
+export declare const INBOX_REOFFER_S: number;
+/** idempotency_key: 1..200 of letters, digits and `_ . : -` (a Slack key is `slack:<channel>:<ts>`). */
+export declare const INBOX_IDEMPOTENCY_KEY_RE: RegExp;
+/** An agents.id as the inbox takes it: opaque text, letters, digits, `_` and `-`, at most 64. */
+export declare const INBOX_AGENT_ID_RE: RegExp;
+/** A sender label: one line of printable ASCII without `[` or `]`, 1..128 characters. */
+export declare const INBOX_SENDER_LABEL_RE: RegExp;
+/** durable_inbox.status. admitted and delivered are open; acked and dead are final. */
+export declare const INBOX_STATUSES: readonly ["admitted", "delivered", "acked", "dead"];
+export type InboxStatus = (typeof INBOX_STATUSES)[number];
+/** Who sent a message: the session's owner, or an agent on the owner's allowlist. */
+export declare const INBOX_SENDER_KINDS: readonly ["owner", "agent"];
+export type InboxSenderKind = (typeof INBOX_SENDER_KINDS)[number];
+/** inbox.rejected refs.reason: why a send by an authenticated sender that can see the session was refused. */
+export declare const INBOX_REJECT_REASONS: readonly ["not_allowlisted", "not_locked", "ended", "unsealed", "inbox_full", "body_too_large", "body_invalid", "unattended_off"];
+export type InboxRejectReason = (typeof INBOX_REJECT_REASONS)[number];
+/** inbox.dead refs.reason and durable_inbox.dead_reason. */
+export declare const INBOX_DEAD_REASONS: readonly ["expired", "delivery_limit", "session_ended"];
+export type InboxDeadReason = (typeof INBOX_DEAD_REASONS)[number];
+/**
+ * exec_inbox_release body.reason and inbox.reverted refs.reason: why the executor hands a delivered
+ * message back undone, instead of acking it.
+ *  - unconfirmed: pasted, never reached the transcript;
+ *  - refused: the turn it started ended on a gateway refusal (an API-error turn): no work was done;
+ *  - undeliverable: the executor will not paste the text.
+ */
+export declare const INBOX_RELEASE_REASONS: readonly ["unconfirmed", "refused", "undeliverable"];
+export type InboxReleaseReason = (typeof INBOX_RELEASE_REASONS)[number];
+/**
+ * The `reason` of a 422 durable_inbox_sender_invalid: `sender` / `on_behalf_of` (a send whose
+ * sender identity is inconsistent), `agent_id` / `label` (a malformed allowlist change), `self` (the
+ * recipient itself), `not_found`, `other_org`, `not_owned` (not one of the owner's agents in the
+ * session's org), `too_many` (INBOX_SENDERS_MAX live senders already).
+ */
+export declare const INBOX_SENDER_INVALID_REASONS: readonly ["sender", "on_behalf_of", "agent_id", "label", "self", "not_found", "other_org", "not_owned", "too_many"];
+export type InboxSenderInvalidReason = (typeof INBOX_SENDER_INVALID_REASONS)[number];
+/**
+ * The refusal code and HTTP status of each INBOX_REJECT_REASONS value (codes.ts DURABLE_CODES). Each
+ * refused send by a sender that may see the session journals inbox.rejected {reason, sender_kind};
+ * a caller who cannot see it is refused before anything is read or written.
+ */
+export declare const INBOX_REJECT_CODES: Readonly<{
+    readonly not_allowlisted: {
+        readonly code: "durable_inbox_not_allowlisted";
+        readonly status: 403;
+    };
+    readonly not_locked: {
+        readonly code: "durable_inbox_closed";
+        readonly status: 409;
+    };
+    readonly ended: {
+        readonly code: "durable_inbox_closed";
+        readonly status: 409;
+    };
+    readonly unsealed: {
+        readonly code: "durable_inbox_closed";
+        readonly status: 409;
+    };
+    readonly inbox_full: {
+        readonly code: "durable_inbox_full";
+        readonly status: 429;
+    };
+    readonly body_too_large: {
+        readonly code: "durable_inbox_body_invalid";
+        readonly status: 422;
+    };
+    readonly body_invalid: {
+        readonly code: "durable_inbox_body_invalid";
+        readonly status: 422;
+    };
+    readonly unattended_off: {
+        readonly code: "durable_inbox_closed";
+        readonly status: 409;
+    };
+}>;
+/** The kinds amendment 60 gives an emitter (they stay in the frozen NO_M1_EMITTER_KINDS M1 baseline). */
+export declare const A60_EMITTED_KINDS: readonly ["inbox.admitted", "inbox.rejected", "inbox.coalesced", "inbox.delivered", "inbox.acked", "inbox.reverted", "inbox.dead"];
+/** What a message's sha commits to. Nulls are explicit, so absent and null hash alike. */
+export interface InboxMessageIdentity {
+    readonly session_id: string;
+    readonly sender_kind: InboxSenderKind;
+    /** The sending agent (sender_kind agent), else null. */
+    readonly sender_agent_id: string | null;
+    /** The owner an agent sends for, from the allowlist row (never from the caller), else null. */
+    readonly on_behalf_of: string | null;
+    /** The question approval this message answers, else null. */
+    readonly in_reply_to: string | null;
+    readonly body: string;
+}
+/** The sha preimage: canonicalJson of the identity plus `v: 1`. */
+export declare function inboxShaPreimage(m: InboxMessageIdentity): string;
+/**
+ * A message's sha: sha256 of inboxShaPreimage, lowercase hex. The api computes it at send. The same
+ * sender sending the same body to the same session while an earlier copy is still open gets that
+ * copy back (coalesced); it is the value the seat stamps as `inbox=<sha>` and the resolver lists in
+ * `inbox_open`.
+ */
+export declare function inboxSha(m: InboxMessageIdentity): Promise<string>;
+/** A UTF-8 body within the limits: 1..INBOX_BODY_MAX_BYTES bytes, no control character but TAB, LF, CR. */
+export declare function inboxBodyOk(body: unknown): body is string;
+/** The first line of every delivery text: `[mnemom inbox <sha>]`, then who sent it. */
+export declare const INBOX_MARKER_RE: RegExp;
+export interface InboxDeliveryInput {
+    readonly sha: string;
+    readonly sender_kind: InboxSenderKind;
+    /** The allowlist row's label, else the agent id; ignored for the owner. */
+    readonly sender_label: string | null;
+    readonly in_reply_to: string | null;
+    readonly body: string;
+}
+/**
+ * The exact text the seat is given (the api renders it in exec_inbox_take; the daemon pastes it
+ * verbatim). Line 1 is the marker and the sender, line 2 is empty, the body follows unchanged:
+ *   `[mnemom inbox <sha>] from the owner`
+ *   `[mnemom inbox <sha>] from agent <label> on behalf of the owner`
+ * and ` (answer to question <approval_id>)` when the message answers one. The marker is read from
+ * line 1 only (inboxMarkerOf), so a body cannot pose as another message.
+ */
+export declare function inboxDeliveryText(m: InboxDeliveryInput): string;
+/**
+ * The sha a prompt carries, read from its first line only, or null. The seat proxy stamps
+ * `inbox=<sha>` on the turn entry whose text this returns non-null for. Restrict-only: a stamp only
+ * makes a turn unattended, and the gateway admits it only while the sha is in `inbox_open`.
+ */
+export declare function inboxMarkerOf(text: string): string | null;
+/** POST own_inbox_send body: exactly {text, idempotency_key}. Sender and on_behalf_of come from the credential and the allowlist, never the body. */
+export declare const INBOX_SEND_BODY_KEYS: readonly ["text", "idempotency_key"];
+/** A send body: exactly INBOX_SEND_BODY_KEYS, text passing inboxBodyOk, idempotency_key INBOX_IDEMPOTENCY_KEY_RE. */
+export declare function inboxSendBodyOk(v: unknown): boolean;
+/**
+ * The 200 answer of own_inbox_send, exactly these keys:
+ *  - inbox_id, sha: the message (a coalesced or deduped send names the earlier, still-open copy);
+ *  - status: its INBOX_STATUSES value now;
+ *  - coalesced: an open message with this sha already existed, nothing new was stored;
+ *  - deduped: this idempotency_key was sent before, this is that send's message;
+ *  - sender_kind, sender_agent_id, on_behalf_of: as stored (the owner's user id for an agent send);
+ *  - expires_at: when an unacked message goes dead.
+ * A refusal is a durable error (INBOX_REJECT_CODES), never a 200.
+ */
+export declare const INBOX_SEND_RESPONSE: Readonly<{
+    inbox_id: "uuid";
+    sha: "hex64";
+    status: "inbox_status";
+    coalesced: "boolean";
+    deduped: "boolean";
+    sender_kind: "inbox_sender_kind";
+    sender_agent_id: "agent_id|null";
+    on_behalf_of: "string|null";
+    expires_at: "timestamp";
+}>;
+export declare function inboxSendResponseOk(v: unknown): boolean;
+/**
+ * One own_inbox_list item, exactly these keys; content-free (no body). GET own_inbox_list answers
+ * `{messages: [item, ...]}`, newest first, at most INBOX_LIST_LIMIT.
+ */
+export declare const INBOX_LIST_ITEM: Readonly<{
+    inbox_id: "uuid";
+    sha: "hex64";
+    status: "inbox_status";
+    sender_kind: "inbox_sender_kind";
+    sender_agent_id: "agent_id|null";
+    on_behalf_of: "string|null";
+    in_reply_to: "uuid|null";
+    body_bytes: "integer>=1";
+    delivery_count: "integer";
+    dead_reason: "inbox_dead_reason|null";
+    created_at: "timestamp";
+    delivered_at: "timestamp|null";
+    acked_at: "timestamp|null";
+    expires_at: "timestamp";
+}>;
+export declare function inboxListItemOk(v: unknown): boolean;
+export declare function inboxListResponseOk(v: unknown): boolean;
+/** POST own_inbox_sender_add body: agent_id required, label optional. */
+export declare const INBOX_SENDER_ADD_BODY_KEYS: readonly ["agent_id", "label"];
+export declare function inboxSenderAddBodyOk(v: unknown): boolean;
+/** DELETE own_inbox_sender_remove body: exactly {agent_id}. */
+export declare const INBOX_SENDER_REMOVE_BODY_KEYS: readonly ["agent_id"];
+export declare function inboxSenderRemoveBodyOk(v: unknown): boolean;
+/**
+ * One allowlisted sender, exactly these keys. The allowlist belongs to the recipient AGENT (it
+ * outlives any one session); the routes reach it through a session the owner owns. added_by is the
+ * owner's user id (null only after a DSR erase).
+ */
+export declare const INBOX_SENDER_ITEM: Readonly<{
+    sender_agent_id: "agent_id";
+    label: "label|null";
+    added_by: "string|null";
+    created_at: "timestamp";
+}>;
+export declare function inboxSenderItemOk(v: unknown): boolean;
+/** GET own_inbox_senders: exactly {recipient_agent_id, senders}, the live (unrevoked) rows. */
+export declare function inboxSendersResponseOk(v: unknown): boolean;
+/**
+ * POST own_inbox_sender_add / DELETE own_inbox_sender_remove answer: exactly
+ * {recipient_agent_id, sender_agent_id, changed}; changed false when the row was already live
+ * (add) or already absent or revoked (remove).
+ */
+export declare function inboxSenderChangeResponseOk(v: unknown): boolean;
+/**
+ * GET exec_inbox: a content-free summary for a session the executor is home to or holds, exactly
+ * {admitted, delivered, oldest_admitted_at}. The daemon reads it to decide whether a parked homed
+ * session has work to claim; it marks nothing delivered.
+ */
+export declare function inboxSummaryResponseOk(v: unknown): boolean;
+/** POST exec_inbox_take body: epoch and nonce (the live lease's) required, limit optional. */
+export declare const INBOX_TAKE_BODY_KEYS: readonly ["epoch", "nonce", "limit"];
+export declare function inboxTakeBodyOk(v: unknown): boolean;
+/**
+ * One taken message, exactly these keys. `text` is inboxDeliveryText of the message, rendered by
+ * the api; the daemon pastes it verbatim. attempt is the message's delivery_count after this take.
+ */
+export declare const INBOX_TAKE_ITEM: Readonly<{
+    inbox_id: "uuid";
+    sha: "hex64";
+    text: "string";
+    attempt: "integer>=1";
+    sender_kind: "inbox_sender_kind";
+    sender_agent_id: "agent_id|null";
+    on_behalf_of: "string|null";
+    in_reply_to: "uuid|null";
+    created_at: "timestamp";
+}>;
+export declare function inboxTakeItemOk(v: unknown): boolean;
+/** POST exec_inbox_take answer: exactly {messages}, oldest first, at most the body's limit. */
+export declare function inboxTakeResponseOk(v: unknown): boolean;
+/** POST exec_inbox_ack body: exactly {epoch, nonce, inbox_id, sha}. */
+export declare const INBOX_ACK_BODY_KEYS: readonly ["epoch", "nonce", "inbox_id", "sha"];
+export declare function inboxAckBodyOk(v: unknown): boolean;
+/**
+ * POST exec_inbox_ack answer: exactly {inbox_id, sha, status: "acked", deduped}. A message that is
+ * not delivered to this session at this epoch with this sha is 409 durable_inbox_not_open.
+ */
+export declare function inboxAckResponseOk(v: unknown): boolean;
+/** POST exec_inbox_release body: exactly {epoch, nonce, inbox_id, sha, reason}. */
+export declare const INBOX_RELEASE_BODY_KEYS: readonly ["epoch", "nonce", "inbox_id", "sha", "reason"];
+export declare function inboxReleaseBodyOk(v: unknown): boolean;
+/**
+ * POST exec_inbox_release answer: exactly {inbox_id, sha, status}. The api moves a message delivered
+ * to this session at this epoch back to `admitted` and journals inbox.reverted {inbox_id, sha,
+ * reason}, so the next take offers it again; when its delivery_count already reached
+ * INBOX_DELIVERY_LIMIT it goes `dead` instead (inbox.dead delivery_limit). Either way its sha leaves
+ * `inbox_open` in the same transaction. Anything else is 409 durable_inbox_not_open.
+ */
+export declare function inboxReleaseResponseOk(v: unknown): boolean;
+/** The journal idempotency keys the api uses for inbox events (one event per fact). */
+export declare const inboxIdempotencyKeys: {
+    readonly admitted: (inboxId: string) => string;
+    readonly coalesced: (inboxId: string, idempotencyKey: string) => string;
+    /**
+     * A refused send: keyed on the caller's idempotency_key when it is well-formed, else on the api's
+     * own request id (a body_invalid refusal may carry no usable key).
+     */
+    readonly rejected: (sessionId: string, idempotencyKey: unknown, requestId: string) => string;
+    readonly delivered: (inboxId: string, epoch: number, attempt: number) => string;
+    readonly acked: (inboxId: string) => string;
+    readonly reverted: (inboxId: string, epoch: number, attempt: number) => string;
+    readonly dead: (inboxId: string) => string;
+};