@mnemom/mnemom 0.17.31 → 0.17.32-next.0

package/dist/lib/api.d.ts

@@ -236,6 +236,12 @@ export declare function verifyBinding(agentId: string, keyHash: string): Promise
     bound: boolean;
     key_prefix: string | null;
 }>;
+/**
+ * GET /v1/agents/:id, sent with the caller's credentials. The API answers with the projection
+ * the caller may see: the org-member view (claimed_by, org_id, `caller: "org_member"`) for an
+ * agent in one of the caller's orgs, the public view otherwise. A pinned launch needs the member
+ * view, so an unauthenticated read here refuses every pin.
+ */
 export declare function getAgent(id: string): Promise<Agent>;
 export interface AgentListItem {
     id: string;
@@ -431,6 +437,19 @@ export interface MuBalance {
     effectiveMode?: string;
     enforcementPausedReason?: string | null;
 }
+/**
+ * GET /v1/orgs/{org_id}/record/totals?lineage_key= — one lineage's model cost and μ as
+ * decimal-string millimu (`mu_charged_mmu` null until billing commits a charge). Dark unless the
+ * org is in the record-accumulator cohort: a 404 then, like an unknown lineage.
+ */
+export interface RecordTotals {
+    lineage_key: string;
+    model_cost_mmu: string;
+    mu_charged_mmu: string | null;
+    as_of: string;
+    row_count: number;
+}
+export declare function getRecordTotals(orgId: string, lineageKey: string, signal?: AbortSignal): Promise<RecordTotals>;
 export declare function getMuBalance(orgId?: string): Promise<MuBalance>;
 /**
  * Mint the one-time `cards:write:protection` capability for an agent — the
@@ -1277,6 +1296,40 @@ export interface OrgUsageQuery {
  * the user "org not found" on what is most often just the flag being off.
  */
 export declare function getOrgUsage(orgId: string, opts?: OrgUsageQuery): Promise<OrgUsageResponse>;
+/** One sealed contract in the batch-seal response (mnemom-api migration 582). */
+export interface SealedContractRow {
+    seal_id: string;
+    ordinal: number;
+    contract_sha256: string;
+    /** The deterministic node identity: `contract:<org_id>:<sha256>`. */
+    node_id: string;
+    version: number;
+    job_key: string | null;
+    canon_status: "pending" | "written";
+}
+/** `POST /v1/orgs/{org_id}/contract-step/batch-seal` 200 body. */
+export interface BatchSealResponse {
+    batch_id: string;
+    replayed: boolean;
+    repo: string;
+    seals: SealedContractRow[];
+    /** Whether the sealed contracts were handed to dispatch: off, enqueued, or deferred (fail open). */
+    dispatch: "off" | "enqueued" | "deferred";
+}
+export interface BatchSealRequest {
+    repo: string;
+    source: "cli";
+    contracts: Array<{
+        contract: unknown;
+        job_key?: string;
+    }>;
+}
+/**
+ * Seal a batch of job contracts in one transaction (Doors fuel step, W3.2). The caller passes the
+ * Idempotency-Key and holds it across retries, so a retried confirmation replays the first batch
+ * instead of sealing twice.
+ */
+export declare function sealContractBatch(orgId: string, body: BatchSealRequest, idempotencyKey: string, githubToken: string): Promise<BatchSealResponse>;
 /** `GET /v1/code/entitlement` 200 body — why Mnemom Agent is enabled for the org. */
 export interface CodeEntitlement {
     org_id: string;

package/dist/lib/api.js

@@ -112,14 +112,6 @@ export async function readApiError(response, fallback) {
         specDeviation: parsed.spec_deviation,
     });
 }
-async function fetchApi(endpoint) {
-    const url = validateUrl(`${API_BASE}${endpoint}`);
-    const response = await mnemomFetch(url);
-    if (!response.ok) {
-        throw await readApiError(response, "API request failed");
-    }
-    return response.json();
-}
 export async function postApi(endpoint, body, opts = {}) {
     const url = validateUrl(`${API_BASE}${endpoint}`);
     const headers = {
@@ -197,8 +189,19 @@ async function fetchWithAuthRetry(url, buildInit) {
         return first;
     return mnemomFetch(url, await buildInit());
 }
+/**
+ * GET /v1/agents/:id, sent with the caller's credentials. The API answers with the projection
+ * the caller may see: the org-member view (claimed_by, org_id, `caller: "org_member"`) for an
+ * agent in one of the caller's orgs, the public view otherwise. A pinned launch needs the member
+ * view, so an unauthenticated read here refuses every pin.
+ */
 export async function getAgent(id) {
-    return fetchApi(`/v1/agents/${id}`);
+    const url = validateUrl(`${API_BASE}/v1/agents/${id}`);
+    const response = await fetchWithAuthRetry(url, async () => ({ headers: await authHeaders() }));
+    if (!response.ok) {
+        throw await readApiError(response, "API request failed");
+    }
+    return (await response.json());
 }
 /**
  * Key-compatible agent listing — `GET /v1/agents` is scoped by the caller's
@@ -405,6 +408,9 @@ export async function getMyPersonalOrg() {
 export async function getMe() {
     return gFetch("/v1/auth/me", {}, { fallback: "Could not read your identity" });
 }
+export async function getRecordTotals(orgId, lineageKey, signal) {
+    return gFetch(`/v1/orgs/${encodeURIComponent(orgId)}/record/totals?lineage_key=${encodeURIComponent(lineageKey)}`, signal ? { signal } : {}, { notFoundLabel: "Record totals", fallback: "Could not read record totals" });
+}
 export async function getMuBalance(orgId) {
     const q = orgId ? `?org_id=${encodeURIComponent(orgId)}` : "";
     return gFetch(`/v1/billing/mu${q}`, {}, { fallback: "Could not read MU balance" });
@@ -747,7 +753,7 @@ function emptyIntegrityRow(agentId) {
 export async function getTraces(id, limit = 10) {
     const data = await gFetch(`/v1/traces?agent_id=${id}&limit=${limit}`, {}, { fallback: "API request failed" });
     // Accept both the envelope shape (current API) and a bare array (defensive
-    // — staging is mid-deploy when a CLI smoke runs against an older API).
+    // — the test cell is mid-deploy when a CLI smoke runs against an older API).
     if (Array.isArray(data))
         return data;
     return data.traces ?? [];
@@ -1308,6 +1314,7 @@ async function gFetch(path, init = {}, opts = {}) {
             ...(init.headers ?? {}),
         },
         body: init.body,
+        ...(init.signal ? { signal: init.signal } : {}),
     }));
     if (!response.ok) {
         if (response.status === 401)
@@ -1569,6 +1576,20 @@ async function codeFetch(path, init = {}, fallback) {
     }
     return (await response.json());
 }
+/**
+ * Seal a batch of job contracts in one transaction (Doors fuel step, W3.2). The caller passes the
+ * Idempotency-Key and holds it across retries, so a retried confirmation replays the first batch
+ * instead of sealing twice.
+ */
+export async function sealContractBatch(orgId, body, idempotencyKey, githubToken) {
+    return codeFetch(`/v1/orgs/${encodeURIComponent(orgId)}/contract-step/batch-seal`, {
+        method: "POST",
+        body: JSON.stringify(body),
+        // The api checks with this token that the caller can write to the repo (OD-10). It reads
+        // it for that check only and never stores it.
+        headers: { "Idempotency-Key": idempotencyKey, "X-GitHub-Token": githubToken },
+    }, "Could not seal the contracts");
+}
 /** The machine-readable code on the gate's 403 when the org is not enabled. */
 export const CODE_NOT_ENABLED = "code_not_enabled";
 /**

package/dist/lib/canonical-json.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Canonical JSON: the one place the CLI serialises a contract for hashing. Kept in its own module,
+ * with no imports, so the contract hash helper and the thin runner can use it without loading
+ * agent.ts. `agent.ts` re-exports it for its existing importers.
+ */
+/**
+ * Canonical JSON — object keys sorted recursively, arrays in order, no
+ * whitespace, `undefined` keys dropped. Byte-identical to the gateway's
+ * `canonicalJson` (gateway/src/goal-contract.ts), so the base64 we send and the
+ * sha we print match what the gateway seals.
+ */
+export declare function canonicalJson(value: unknown): string;

package/dist/lib/canonical-json.js

@@ -0,0 +1,22 @@
+/**
+ * Canonical JSON: the one place the CLI serialises a contract for hashing. Kept in its own module,
+ * with no imports, so the contract hash helper and the thin runner can use it without loading
+ * agent.ts. `agent.ts` re-exports it for its existing importers.
+ */
+/**
+ * Canonical JSON — object keys sorted recursively, arrays in order, no
+ * whitespace, `undefined` keys dropped. Byte-identical to the gateway's
+ * `canonicalJson` (gateway/src/goal-contract.ts), so the base64 we send and the
+ * sha we print match what the gateway seals.
+ */
+export function canonicalJson(value) {
+    if (value === null || typeof value !== "object")
+        return JSON.stringify(value);
+    if (Array.isArray(value))
+        return `[${value.map(canonicalJson).join(",")}]`;
+    const obj = value;
+    const keys = Object.keys(obj)
+        .filter((k) => obj[k] !== undefined)
+        .sort();
+    return `{${keys.map((k) => `${JSON.stringify(k)}:${canonicalJson(obj[k])}`).join(",")}}`;
+}

package/dist/lib/conduct-receipt.d.ts

@@ -0,0 +1,81 @@
+/**
+ * The conduct receipt (experimental `record`, Doors W1.2 / W1.3): the engineer's private view of
+ * one session, printed when `mnemom agent` exits and when a durable session parks.
+ *
+ *   Conduct receipt
+ *     model cost  $0.42
+ *     μ           12.5
+ *
+ * Every figure is measured, never estimated (decision 14): model cost and μ are the session
+ * lineage's `record_accumulator` totals, read from `GET /v1/orgs/{org}/record/totals`. μ reads
+ * "μ pending" until billing has committed a charge for the lineage (the route's null), and the
+ * receipt then gives a link instead of a number.
+ *
+ * NEVER BLOCKS EXIT. The whole read, auth refresh included, races a hard deadline
+ * (RECEIPT_DEADLINE_MS): with the API or the record builder down, exit takes at most that much
+ * longer, and the receipt falls back to the link. The caller keeps its exit code; nothing here
+ * throws.
+ *
+ * The lineage key is the gateway's (x-mnemom-lineage-key, set on every response), captured by the
+ * local base-URL proxy into a state file: the CLI never derives one itself.
+ */
+/** The hard ceiling on what the receipt adds to exit (W1.3: at most 2 s). */
+export declare const RECEIPT_DEADLINE_MS = 1800;
+/** Pause between totals reads while μ is still pending. */
+export declare const RECEIPT_POLL_MS = 400;
+/** What the local proxy saw on the session's responses (base-url-proxy.mjs, record state). */
+export interface RecordState {
+    lineageKey?: string;
+    recordUrl?: string;
+}
+/** A totals read: the route's two amounts, or why there are none. */
+export type TotalsRead = {
+    kind: "ok";
+    modelCostMmu: bigint;
+    muChargedMmu: bigint | null;
+} | {
+    kind: "unavailable";
+};
+export interface ReceiptDeps {
+    /** One totals read for the lineage; may throw or hang (both are "unavailable"). */
+    readTotals: (lineageKey: string, signal: AbortSignal) => Promise<TotalsRead>;
+    /** The page the receipt links to when no record URL was captured (the agent dashboard). */
+    fallbackUrl: string;
+    now?: () => number;
+    sleep?: (ms: number) => Promise<void>;
+    deadlineMs?: number;
+    pollMs?: number;
+}
+/** Read the proxy's record-state file; a missing or malformed file is an empty state. */
+export declare function readRecordState(path: string | undefined): RecordState;
+/** Keep only a well-formed lineage key and an https record URL. */
+export declare function sanitizeRecordState(raw: Record<string, unknown>): RecordState;
+/** Parse the totals route body; anything off-contract is "unavailable", never a guessed figure. */
+export declare function parseTotals(body: unknown): TotalsRead;
+/** `$0.42`; a non-zero cost under a cent reads `< $0.01`, never `$0.00`. */
+export declare function formatUsd(mmu: bigint): string;
+/** μ to at most three decimals, trailing zeros dropped: 12500 mmu → `12.5`. */
+export declare function formatMu(mmu: bigint): string;
+/** The receipt lines for what was read (pure). */
+export declare function receiptLines(read: TotalsRead | null, link: string, trigger?: "exit" | "park"): string[];
+/**
+ * Read the lineage's totals until μ is final or the deadline passes, then return the receipt.
+ * Never throws and never waits past `deadlineMs`.
+ */
+export declare function buildConductReceipt(state: RecordState, deps: ReceiptDeps, trigger?: "exit" | "park"): Promise<string[]>;
+/** Where the receipt's launch facts come from (the launcher at exit; Durable at park). */
+export interface ReceiptLaunch {
+    orgId: string;
+    /** The served agent id: the fallback link is its dashboard page. */
+    agentId: string;
+    /** The proxy's record-state file (absent: no lineage was captured). */
+    statePath?: string;
+}
+/**
+ * The receipt for a launch, against the real API (the exit and park call sites).
+ *
+ * The deadline bounds what the caller waits for, not every network call: on a 401 the auth
+ * refresh (fetchWithAuthRetry) takes no signal and may outlive the receipt. The exit path
+ * process.exit()s right after; a long-lived caller (a durable park) may see it finish later.
+ */
+export declare function conductReceiptFor(launch: ReceiptLaunch, trigger?: "exit" | "park", deps?: Partial<ReceiptDeps>): Promise<string[]>;

package/dist/lib/conduct-receipt.js

@@ -0,0 +1,177 @@
+/**
+ * The conduct receipt (experimental `record`, Doors W1.2 / W1.3): the engineer's private view of
+ * one session, printed when `mnemom agent` exits and when a durable session parks.
+ *
+ *   Conduct receipt
+ *     model cost  $0.42
+ *     μ           12.5
+ *
+ * Every figure is measured, never estimated (decision 14): model cost and μ are the session
+ * lineage's `record_accumulator` totals, read from `GET /v1/orgs/{org}/record/totals`. μ reads
+ * "μ pending" until billing has committed a charge for the lineage (the route's null), and the
+ * receipt then gives a link instead of a number.
+ *
+ * NEVER BLOCKS EXIT. The whole read, auth refresh included, races a hard deadline
+ * (RECEIPT_DEADLINE_MS): with the API or the record builder down, exit takes at most that much
+ * longer, and the receipt falls back to the link. The caller keeps its exit code; nothing here
+ * throws.
+ *
+ * The lineage key is the gateway's (x-mnemom-lineage-key, set on every response), captured by the
+ * local base-URL proxy into a state file: the CLI never derives one itself.
+ */
+import { readFileSync } from "node:fs";
+import { getRecordTotals } from "./api.js";
+import { getWebsiteUrl } from "./config.js";
+/** The hard ceiling on what the receipt adds to exit (W1.3: at most 2 s). */
+export const RECEIPT_DEADLINE_MS = 1800;
+/** Pause between totals reads while μ is still pending. */
+export const RECEIPT_POLL_MS = 400;
+/** 1 MU = 1000 mmu; 1 USD = 100 000 mmu (mnemom-api src/billing/pricing.ts MMU_PER_USD). */
+const MMU_PER_MU = 1000n;
+const MMU_PER_USD = 100000n;
+const LINEAGE_KEY_RE = /^[A-Za-z0-9:._-]{1,256}$/;
+const MMU_RE = /^(0|[1-9][0-9]{0,18})$/;
+/** Read the proxy's record-state file; a missing or malformed file is an empty state. */
+export function readRecordState(path) {
+    if (!path)
+        return {};
+    try {
+        const raw = JSON.parse(readFileSync(path, "utf8"));
+        return sanitizeRecordState(raw);
+    }
+    catch {
+        return {};
+    }
+}
+/** Keep only a well-formed lineage key and an https record URL. */
+export function sanitizeRecordState(raw) {
+    const out = {};
+    if (typeof raw.lineage_key === "string" && LINEAGE_KEY_RE.test(raw.lineage_key)) {
+        out.lineageKey = raw.lineage_key;
+    }
+    if (typeof raw.record_url === "string" && isHttpsUrl(raw.record_url)) {
+        out.recordUrl = raw.record_url;
+    }
+    return out;
+}
+/** Printable ASCII only: the URL is printed to the user's terminal, so no escape bytes. */
+const PRINTABLE_URL_RE = /^https:\/\/[\x21-\x7e]+$/;
+function isHttpsUrl(s) {
+    if (s.length > 2048 || !PRINTABLE_URL_RE.test(s))
+        return false;
+    try {
+        return new URL(s).protocol === "https:";
+    }
+    catch {
+        return false;
+    }
+}
+/** Parse the totals route body; anything off-contract is "unavailable", never a guessed figure. */
+export function parseTotals(body) {
+    if (!body || typeof body !== "object")
+        return { kind: "unavailable" };
+    const b = body;
+    if (typeof b.model_cost_mmu !== "string" || !MMU_RE.test(b.model_cost_mmu)) {
+        return { kind: "unavailable" };
+    }
+    let mu = null;
+    if (b.mu_charged_mmu !== null) {
+        if (typeof b.mu_charged_mmu !== "string" || !MMU_RE.test(b.mu_charged_mmu)) {
+            return { kind: "unavailable" };
+        }
+        mu = BigInt(b.mu_charged_mmu);
+    }
+    return { kind: "ok", modelCostMmu: BigInt(b.model_cost_mmu), muChargedMmu: mu };
+}
+/** `$0.42`; a non-zero cost under a cent reads `< $0.01`, never `$0.00`. */
+export function formatUsd(mmu) {
+    if (mmu > 0n && mmu * 100n < MMU_PER_USD)
+        return "< $0.01";
+    const cents = (mmu * 100n + MMU_PER_USD / 2n) / MMU_PER_USD;
+    return `$${cents / 100n}.${String(cents % 100n).padStart(2, "0")}`;
+}
+/** μ to at most three decimals, trailing zeros dropped: 12500 mmu → `12.5`. */
+export function formatMu(mmu) {
+    const whole = mmu / MMU_PER_MU;
+    const frac = String(mmu % MMU_PER_MU)
+        .padStart(3, "0")
+        .replace(/0+$/, "");
+    return frac ? `${whole}.${frac}` : `${whole}`;
+}
+/** The receipt lines for what was read (pure). */
+export function receiptLines(read, link, trigger = "exit") {
+    const head = trigger === "park" ? "Conduct receipt (parked)" : "Conduct receipt";
+    if (!read || read.kind === "unavailable") {
+        return [head, `  record not available yet: ${link}`];
+    }
+    const lines = [head, `  model cost  ${formatUsd(read.modelCostMmu)}`];
+    if (read.muChargedMmu === null)
+        lines.push(`  μ pending   ${link}`);
+    else
+        lines.push(`  μ           ${formatMu(read.muChargedMmu)}`);
+    return lines;
+}
+/**
+ * Read the lineage's totals until μ is final or the deadline passes, then return the receipt.
+ * Never throws and never waits past `deadlineMs`.
+ */
+export async function buildConductReceipt(state, deps, trigger = "exit") {
+    const link = state.recordUrl ?? deps.fallbackUrl;
+    if (!state.lineageKey)
+        return receiptLines(null, link, trigger);
+    const now = deps.now ?? Date.now;
+    const sleep = deps.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+    const deadline = now() + (deps.deadlineMs ?? RECEIPT_DEADLINE_MS);
+    const pollMs = deps.pollMs ?? RECEIPT_POLL_MS;
+    const lineageKey = state.lineageKey;
+    let last = null;
+    for (;;) {
+        const left = deadline - now();
+        if (left <= 0)
+            break;
+        const read = await readWithin(deps.readTotals, lineageKey, left);
+        // A later failure never hides an earlier good read.
+        if (read.kind === "ok" || !last)
+            last = read;
+        if (read.kind === "ok" && read.muChargedMmu !== null)
+            break;
+        if (deadline - now() <= pollMs)
+            break;
+        await sleep(pollMs);
+    }
+    return receiptLines(last, link, trigger);
+}
+async function readWithin(readTotals, lineageKey, ms) {
+    const ac = new AbortController();
+    let timer;
+    const timeout = new Promise((resolve) => {
+        timer = setTimeout(() => {
+            ac.abort();
+            resolve({ kind: "unavailable" });
+        }, ms);
+    });
+    try {
+        return await Promise.race([
+            readTotals(lineageKey, ac.signal).catch(() => ({ kind: "unavailable" })),
+            timeout,
+        ]);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/**
+ * The receipt for a launch, against the real API (the exit and park call sites).
+ *
+ * The deadline bounds what the caller waits for, not every network call: on a 401 the auth
+ * refresh (fetchWithAuthRetry) takes no signal and may outlive the receipt. The exit path
+ * process.exit()s right after; a long-lived caller (a durable park) may see it finish later.
+ */
+export async function conductReceiptFor(launch, trigger = "exit", deps = {}) {
+    return buildConductReceipt(readRecordState(launch.statePath), {
+        ...deps,
+        readTotals: deps.readTotals ??
+            (async (lineageKey, signal) => parseTotals(await getRecordTotals(launch.orgId, lineageKey, signal))),
+        fallbackUrl: deps.fallbackUrl ?? `${getWebsiteUrl()}/agents/${encodeURIComponent(launch.agentId)}`,
+    }, trigger);
+}

package/dist/lib/contract-hash.d.ts

@@ -0,0 +1,61 @@
+/**
+ * The contract's full sha256 and seal-time check, as the gateway computes them (Doors W3.5).
+ *
+ * Callers that hash contracts outside the gateway (the fuel step's CLI verb and the thin runner,
+ * each in its own change) use this module. It computes a contract's hash, its committed file's
+ * bytes and its repo path; writing the file is the caller's job. It ports the gateway's
+ * `normaliseContractObject` / `checkContractObject` / `canonicalHash` (gateway/src/goal-contract.ts). The full sha256 is the digest whose first 16
+ * hex characters are the gateway's `x-mnemom-contract-hash`: sha256 of the canonical JSON of the
+ * normalised contract, with a default `"nudge"` mode dropped and `"enforce"` kept. The 8 KB
+ * limit is measured, like the gateway's, on the canonical JSON with the mode still present.
+ *
+ * `gateway/test/fixtures/contract-sha256-parity.json` pins the gateway's own outputs; the CLI's
+ * parity suite and mnemom-api's (`src/contract-step/hash.ts`) read the same cases.
+ */
+/** The gateway's `CONTRACT_JSON_MAX`: bytes of canonical JSON of the normalised contract. */
+export declare const CONTRACT_JSON_MAX = 8192;
+/** The gateway's `STATEMENT_MAX` (its `USER_CLIP`), in characters. */
+export declare const STATEMENT_MAX = 4000;
+export type ContractMode = "nudge" | "enforce";
+/** pv2 SealedContract, the shape the gateway seals from `x-mnemom-contract`. */
+export interface Contract {
+    goal_id?: string;
+    statement: string;
+    requirements: string[];
+    allowed_paths: string[];
+    forbidden_paths: string[];
+    max_turns?: number;
+    budget_usd?: number;
+    stall_turns?: number;
+    time_limit_s?: number;
+    mode?: ContractMode;
+}
+export type ContractRejectReason = "unparseable" | "statement_missing" | "statement_too_long" | "contract_too_large" | "mode_invalid";
+export type ContractCheck = {
+    ok: true;
+    contract: Contract;
+} | {
+    ok: false;
+    reason: ContractRejectReason;
+    message: string;
+};
+/** The gateway's `normaliseContractObject`: null without a non-empty statement. Mode defaults to "nudge". */
+export declare function normaliseContract(obj: Record<string, unknown>): Contract | null;
+/** The gateway's seal-time gate (`checkContractObject`), with the same reasons. */
+export declare function checkContract(value: unknown, label?: string): ContractCheck;
+/** Bytes the 8 KB limit measures: canonical JSON of the normalised contract, mode included. */
+export declare function contractSizeBytes(contract: Contract): number;
+/** The hash form: a default "nudge" mode dropped, "enforce" kept (the gateway's `canonicalHash`). */
+export declare function hashForm(contract: Contract): Contract;
+/**
+ * The committed contract file's exact bytes: canonical JSON of the hash form, no trailing newline,
+ * so sha256 of the file equals `contractSha256`.
+ */
+export declare function contractFileText(contract: Contract): string;
+/** Full lowercase-hex sha256. Its first 16 characters are the gateway's `x-mnemom-contract-hash`. */
+export declare function contractSha256(contract: Contract): string;
+/**
+ * Where a sealed contract is committed in the repo: content-addressed by its full sha256. Throws
+ * on anything but 64 lowercase hex characters, so the path can never leave `.mnemom/contracts/`.
+ */
+export declare function contractRepoPath(sha256: string): string;

package/dist/lib/contract-hash.js

@@ -0,0 +1,126 @@
+/**
+ * The contract's full sha256 and seal-time check, as the gateway computes them (Doors W3.5).
+ *
+ * Callers that hash contracts outside the gateway (the fuel step's CLI verb and the thin runner,
+ * each in its own change) use this module. It computes a contract's hash, its committed file's
+ * bytes and its repo path; writing the file is the caller's job. It ports the gateway's
+ * `normaliseContractObject` / `checkContractObject` / `canonicalHash` (gateway/src/goal-contract.ts). The full sha256 is the digest whose first 16
+ * hex characters are the gateway's `x-mnemom-contract-hash`: sha256 of the canonical JSON of the
+ * normalised contract, with a default `"nudge"` mode dropped and `"enforce"` kept. The 8 KB
+ * limit is measured, like the gateway's, on the canonical JSON with the mode still present.
+ *
+ * `gateway/test/fixtures/contract-sha256-parity.json` pins the gateway's own outputs; the CLI's
+ * parity suite and mnemom-api's (`src/contract-step/hash.ts`) read the same cases.
+ */
+import { createHash } from "node:crypto";
+import { canonicalJson } from "./canonical-json.js";
+/** The gateway's `CONTRACT_JSON_MAX`: bytes of canonical JSON of the normalised contract. */
+export const CONTRACT_JSON_MAX = 8_192;
+/** The gateway's `STATEMENT_MAX` (its `USER_CLIP`), in characters. */
+export const STATEMENT_MAX = 4_000;
+const MODES = new Set(["nudge", "enforce"]);
+function stringArray(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value.filter((v) => typeof v === "string" && v.trim().length > 0);
+}
+function positiveFinite(value) {
+    return typeof value === "number" && Number.isFinite(value) && value > 0 ? value : undefined;
+}
+/** The gateway's `normaliseContractObject`: null without a non-empty statement. Mode defaults to "nudge". */
+export function normaliseContract(obj) {
+    const statement = typeof obj.statement === "string" ? obj.statement.trim() : "";
+    if (!statement)
+        return null;
+    const contract = {
+        statement,
+        requirements: stringArray(obj.requirements),
+        allowed_paths: stringArray(obj.allowed_paths),
+        forbidden_paths: stringArray(obj.forbidden_paths),
+    };
+    if (typeof obj.goal_id === "string" && obj.goal_id.trim())
+        contract.goal_id = obj.goal_id.trim();
+    const maxTurns = positiveFinite(obj.max_turns);
+    if (maxTurns !== undefined)
+        contract.max_turns = maxTurns;
+    const budgetUsd = positiveFinite(obj.budget_usd);
+    if (budgetUsd !== undefined)
+        contract.budget_usd = budgetUsd;
+    const stallTurns = positiveFinite(obj.stall_turns);
+    if (stallTurns !== undefined)
+        contract.stall_turns = stallTurns;
+    const timeLimitS = positiveFinite(obj.time_limit_s);
+    if (timeLimitS !== undefined)
+        contract.time_limit_s = timeLimitS;
+    contract.mode = MODES.has(obj.mode) ? obj.mode : "nudge";
+    return contract;
+}
+/** The gateway's seal-time gate (`checkContractObject`), with the same reasons. */
+export function checkContract(value, label = "contract") {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        return { ok: false, reason: "unparseable", message: `${label} must be a JSON object` };
+    }
+    const obj = value;
+    const contract = normaliseContract(obj);
+    if (!contract) {
+        return {
+            ok: false,
+            reason: "statement_missing",
+            message: `${label} needs a non-empty "statement"`,
+        };
+    }
+    if (contract.statement.length > STATEMENT_MAX) {
+        return {
+            ok: false,
+            reason: "statement_too_long",
+            message: `"statement" is ${contract.statement.length} characters; the maximum is ${STATEMENT_MAX}`,
+        };
+    }
+    if (obj.mode !== undefined && !MODES.has(obj.mode)) {
+        return {
+            ok: false,
+            reason: "mode_invalid",
+            message: `"mode" must be "nudge" or "enforce" (got ${JSON.stringify(obj.mode)})`,
+        };
+    }
+    const bytes = contractSizeBytes(contract);
+    if (bytes > CONTRACT_JSON_MAX) {
+        return {
+            ok: false,
+            reason: "contract_too_large",
+            message: `the contract is ${bytes} bytes of canonical JSON; the maximum is ${CONTRACT_JSON_MAX}`,
+        };
+    }
+    return { ok: true, contract };
+}
+/** Bytes the 8 KB limit measures: canonical JSON of the normalised contract, mode included. */
+export function contractSizeBytes(contract) {
+    return Buffer.byteLength(canonicalJson(contract), "utf8");
+}
+/** The hash form: a default "nudge" mode dropped, "enforce" kept (the gateway's `canonicalHash`). */
+export function hashForm(contract) {
+    const form = { ...contract };
+    if ((contract.mode ?? "nudge") === "nudge")
+        delete form.mode;
+    return form;
+}
+/**
+ * The committed contract file's exact bytes: canonical JSON of the hash form, no trailing newline,
+ * so sha256 of the file equals `contractSha256`.
+ */
+export function contractFileText(contract) {
+    return canonicalJson(hashForm(contract));
+}
+/** Full lowercase-hex sha256. Its first 16 characters are the gateway's `x-mnemom-contract-hash`. */
+export function contractSha256(contract) {
+    return createHash("sha256").update(contractFileText(contract), "utf8").digest("hex");
+}
+/**
+ * Where a sealed contract is committed in the repo: content-addressed by its full sha256. Throws
+ * on anything but 64 lowercase hex characters, so the path can never leave `.mnemom/contracts/`.
+ */
+export function contractRepoPath(sha256) {
+    if (!/^[0-9a-f]{64}$/.test(sha256))
+        throw new Error("contract sha256 must be 64 lowercase hex characters");
+    return `.mnemom/contracts/${sha256}.json`;
+}

package/dist/lib/experimental.d.ts

@@ -12,7 +12,7 @@
  * Everything here is pure or dependency-injected; index.ts and the command
  * modules are the thin drivers.
  */
-export type ExperimentalId = "context-handoff" | "slack" | "implicit" | "measured-savings";
+export type ExperimentalId = "context-handoff" | "slack" | "implicit" | "measured-savings" | "record" | "fuel";
 /**
  * Features that used to be experimental and are now on by default for everyone. Their ids are
  * no longer in the registry, but `mnemom experimental enable|disable <id>` still accepts them
@@ -63,6 +63,15 @@ export declare function resolveExperimental(opts: {
     stored: ExperimentalPrefs | undefined;
     env: Record<string, string | undefined>;
 }): ExperimentalState;
+/**
+ * Features a prerelease (`-next.N`) build makes available without `mnemom experimental
+ * enable`: door one's T16 turns implicit goals on by default on `next` (decisions 12 and
+ * 22), so its flag, its launcher.toml value and `mnemom agent goal` are not refused there.
+ * Stable is unchanged.
+ */
+export declare const PRERELEASE_AVAILABLE: readonly ExperimentalId[];
+/** The features whose flags, keys and commands are usable: the enabled ones, plus PRERELEASE_AVAILABLE on a prerelease. */
+export declare function availableFeatures(enabled: readonly ExperimentalId[], prerelease: boolean): ExperimentalId[];
 /** The one-line stderr notice for a launch with experimental features on; null when none are. */
 export declare function experimentalNotice(enabled: readonly ExperimentalId[]): string | null;
 /** The error for using an experimental flag or command while its feature is off. */