@code-yeongyu/senpi 2026.11.6-3 → 2026.11.9

package/dist/core/egress/device-proxy.js

@@ -0,0 +1,214 @@
+import { createAssistantMessageEventStream, } from "@earendil-works/pi-ai";
+import { followCall } from "./device-proxy-call.js";
+import { lostCallPacer } from "./device-proxy-lost-calls.js";
+import { ABORT_TEXT, admittedRequestJson, failureMessage, parseStoredRequest, planDispatch, } from "./device-proxy-request.js";
+import { createAbortion, nextKeyBackoffMs, stepWaits } from "./device-proxy-waits.js";
+/** The `done` reason of a finished, successful stop; `undefined` (never replayed) for error, aborted or pending. */
+const doneReason = (stopReason) => stopReason === "error" || stopReason === "aborted" || stopReason === "pending" ? undefined : stopReason;
+export function createDeviceProxyEgress(deps) {
+    const { ledger, route, host } = deps;
+    const abortion = createAbortion();
+    const waitsOf = (run) => stepWaits(run.out, host, run.step, run.signal, abortion);
+    const callContext = (run, deviceId) => ({
+        out: run.out,
+        model: run.model,
+        ledger,
+        channel: deps.hands.channel(deviceId),
+        offlineFor: deps.hands.offlineFor,
+        waits: waitsOf(run),
+        conditions: deps.conditions,
+        clock: deps.clock,
+        bounds: deps.bounds,
+        signal: run.signal,
+        abortion,
+        claim: deps.claims.current,
+        live: run.live,
+    });
+    const servedDecision = async (run) => {
+        for (;;) {
+            const decision = route.decide(run.model.provider, await ledger.variants(run.model.provider));
+            const { deviceId } = decision;
+            if (decision.servedNow && decision.route === "device" && deviceId !== undefined)
+                return { ...decision, deviceId };
+            if (decision.servedNow)
+                throw new Error(`the device route cannot serve a ${decision.route} decision`);
+            const waitFor = decision.waitFor ?? [];
+            const wait = { reason: decision.reason, steer: decision.steer ?? "", waitFor };
+            await waitsOf(run).hold(wait, deps.conditions.until(waitFor, run.signal));
+        }
+    };
+    /** 4.6: renew an expired or superseded claim, back off on an unknown registry key, and restart the same call. */
+    const startWithClaim = async (run, dispatched, decision, plan) => {
+        let row = dispatched;
+        const deviceId = row.deviceId ?? "";
+        const expectedSourceDigest = decision.serveOwnDefinition ? undefined : route.headDigest(row.providerId);
+        const maxOutputTokens = run.options?.maxTokens;
+        let backoff;
+        for (;;) {
+            const start = {
+                t: "provider.call.start",
+                callId: row.callId,
+                sessionId: deps.sessionId,
+                call: row.call,
+                claim: await deps.claims.current(),
+                providerId: row.providerId,
+                modelId: row.modelId,
+                ...(expectedSourceDigest === undefined ? {} : { expectedSourceDigest }),
+                hooks: plan.hooks,
+                ...(deps.cwd === undefined ? {} : { cwd: deps.cwd }),
+                request: parseStoredRequest(plan.requestJson),
+                budget: {
+                    deadlineMs: deps.bounds.deadlineMs,
+                    ...(maxOutputTokens === undefined ? {} : { maxOutputTokens }),
+                },
+            };
+            const outcome = await followCall(callContext(run, deviceId), row, { start });
+            if (outcome.kind !== "refused")
+                return outcome;
+            await deps.hands.channel(deviceId).ack({ t: "provider.call.ack", callId: row.callId });
+            const waitFor = [{ kind: "claim-renewed" }];
+            const code = outcome.code;
+            if (code === "registry_key_unknown") {
+                backoff = nextKeyBackoffMs(backoff);
+                const pause = deps.clock.sleep(backoff, run.signal);
+                await waitsOf(run).hold({ reason: "claim-expired", steer: outcome.message, waitFor }, pause);
+            }
+            else {
+                const steer = "renewing this session's placement claim";
+                await waitsOf(run).hold({ reason: "claim-expired", steer, waitFor }, deps.claims.renew(code));
+            }
+            row = await ledger.replaceRefused(outcome.row, crypto.randomUUID());
+        }
+    };
+    /** A lost (`unknown`) or mismatched call is superseded; a mismatch records the device variant in the same write. */
+    const retire = async (run, outcome) => {
+        const { row } = outcome;
+        const deviceId = row.deviceId ?? "";
+        if (outcome.kind === "unknown")
+            await deps.hands
+                .channel(deviceId)
+                .cancel({ t: "provider.call.cancel", callId: row.callId, reason: "superseded" });
+        const headDigest = route.headDigest(row.providerId);
+        const variant = outcome.kind === "mismatch" && headDigest !== undefined
+            ? {
+                providerId: row.providerId,
+                deviceId,
+                stepId: run.step.stepId,
+                headDigest,
+                liveAtMismatch: route.liveDigest(deviceId, row.providerId),
+            }
+            : undefined;
+        const superseded = await ledger.supersede(row, variant);
+        run.live.row = superseded;
+        deps.notify({ t: "step.reset", sessionId: deps.sessionId, stepId: run.step.stepId, cause: "superseded" });
+        return superseded;
+    };
+    const serve = async (run, pacer, firstRequest, firstPrevious) => {
+        let stored = firstRequest;
+        let previous = firstPrevious;
+        let attempt = previous && previous.call.kind === "step" ? previous.call.attempt + 1 : run.step.attempt;
+        const providerId = run.model.provider;
+        for (;;) {
+            if (previous !== undefined && route.capability(providerId) === "callback-stream") {
+                const waitFor = [{ kind: "user-choice", choiceId: `${run.step.stepId}:${attempt}` }];
+                const steer = "re-run this step (tools may run again) or select another device";
+                await waitsOf(run).hold({ reason: "capability:callback-stream", steer, waitFor }, deps.conditions.until(waitFor, run.signal));
+            }
+            const decision = await servedDecision(run);
+            const plan = await planDispatch(decision, stored, deps.requestHooks);
+            const next = {
+                callId: crypto.randomUUID(),
+                sessionId: deps.sessionId,
+                call: { kind: "step", stepId: run.step.stepId, attempt },
+                route: "device",
+                deviceId: decision.deviceId,
+                providerId,
+                modelId: run.model.id,
+                epoch: run.step.fence.epoch,
+                capability: route.capability(providerId),
+                hooksApplied: plan.hooksApplied,
+            };
+            const row = await ledger.dispatch(next, plan.requestJson, previous);
+            const outcome = await startWithClaim(run, row, decision, plan);
+            if (outcome.kind === "ended")
+                return;
+            previous = await retire(run, outcome);
+            stored = { requestJson: await ledger.readRequest(previous), hooksApplied: previous.hooksApplied };
+            attempt += 1;
+            if (outcome.kind === "unknown")
+                await pacer.beforeReissue(decision.deviceId, attempt);
+        }
+    };
+    /** The 4.5 replay rules for a step that already has a row, applied before any route decision or request hook. */
+    const runStep = async (run, context) => {
+        const { stepId } = run.step;
+        if (await host.historyHasStep(stepId))
+            throw new Error(`step ${stepId} is already committed; resume from history`);
+        if (await ledger.isCancelled(stepId)) {
+            run.out.push({ type: "error", reason: "aborted", error: failureMessage(run.model, "aborted", ABORT_TEXT) });
+            return;
+        }
+        const latest = (await ledger.rowsForStep(stepId)).at(-1);
+        const reason = latest?.result?.kind === "message" ? doneReason(latest.result.stopReason) : undefined;
+        if (latest?.state === "ended" && reason !== undefined) {
+            const message = await ledger.readMessage(latest);
+            run.out.push({ type: "start", partial: { ...message } });
+            run.out.push({ type: "done", reason, message });
+            return;
+        }
+        const askUser = route.capability(run.model.provider) !== "callback-stream";
+        const pacer = lostCallPacer({ ...deps, stepId, waits: waitsOf(run), signal: run.signal, askUser });
+        const resumable = latest?.state === "dispatched" || latest?.state === "ended" || latest?.state === "superseded";
+        if (!latest || !resumable) {
+            const admitted = { requestJson: admittedRequestJson(context, run.options), hooksApplied: false };
+            return serve(run, pacer, admitted, undefined);
+        }
+        let previous = latest;
+        // The resumed row is live until the next W4 retires it: an abort in the waits before that must delete its chunks.
+        run.live.row = latest;
+        if (latest.state === "dispatched") {
+            const deviceId = latest.deviceId ?? "";
+            if (deps.hands.offlineFor(deviceId) >= deps.bounds.resumeWindowMs) {
+                const waitFor = [{ kind: "device-online", deviceId }];
+                const pinned = deps.conditions.until(waitFor, run.signal);
+                await waitsOf(run).hold({ reason: "device-offline", steer: `open omo on ${deviceId}`, waitFor }, pinned);
+            }
+            const outcome = await followCall(callContext(run, deviceId), latest, { resume: true });
+            if (outcome.kind === "ended")
+                return;
+            if (outcome.kind === "refused")
+                throw new Error(`device ${deviceId} refused the placement claim: ${outcome.message}`);
+            previous = await retire(run, outcome);
+            if (outcome.kind === "unknown" && latest.call.kind === "step")
+                await pacer.beforeReissue(deviceId, latest.call.attempt + 1);
+        }
+        const stored = { requestJson: await ledger.readRequest(previous), hooksApplied: previous.hooksApplied };
+        return serve(run, pacer, stored, previous);
+    };
+    const abortFailure = async (run) => {
+        const row = run.live.row;
+        let cause;
+        await ledger.cancelStep(run.step.stepId, row).catch((error) => {
+            cause = error;
+        });
+        if (row?.deviceId !== undefined && row.state === "dispatched")
+            await deps.hands
+                .channel(row.deviceId)
+                .cancel({ t: "provider.call.cancel", callId: row.callId, reason: "user" });
+        return new Error(ABORT_TEXT, cause === undefined ? undefined : { cause });
+    };
+    return {
+        stream: (model, context, options) => {
+            const out = createAssistantMessageEventStream();
+            const signal = options?.signal ?? new AbortController().signal;
+            const run = { out, model, options, step: host.currentStep(), signal, live: { row: undefined } };
+            out.trackLocalWork(runStep(run, context)).catch(async (error) => {
+                if (!signal.aborted)
+                    return out.fail(error);
+                out.fail(await abortFailure(run).catch((cause) => new Error(ABORT_TEXT, { cause })));
+            });
+            return out;
+        },
+    };
+}
+//# sourceMappingURL=device-proxy.js.map

package/dist/core/egress/endpoint.js

@@ -36,7 +36,8 @@ function isTemplatedUrlPart(raw) {
     return isCommandConfigValue(raw) || getConfigValueEnvVarNames(raw).length > 0;
 }
 function isKeyishQueryName(name) {
-    return KEYISH_QUERY_NAMES.includes(name.toLowerCase());
+    const lower = name.toLowerCase();
+    return KEYISH_QUERY_NAMES.some((keyish) => keyish === lower);
 }
 export function splitEndpoint(baseUrl, secretUrlParts = []) {
     const match = URL_SHAPE.exec(baseUrl);

package/dist/core/egress/entry-verify.d.ts

@@ -0,0 +1,13 @@
+export declare const ENTRY_SIG_DOMAIN = "omo-custody/provider-entry/v1";
+/** r11.1 C.P5: entrySig signs ASCII(domain) || 0x00 || ASCII(entryDigest), entryDigest in lowercase hex. */
+export declare function entrySigPayload(entryDigest: string): Uint8Array;
+export interface EntrySigInput {
+    readonly entryDigest: string;
+    /** Canonical base64url without padding. */
+    readonly entrySig: string;
+    /** The owner's enrolled Ed25519 public key (32 raw bytes). */
+    readonly ownerPublicKey: Uint8Array;
+}
+/** The brain-side check before dialing (custody design 3.2); a false result is a wait, never a dial. */
+export declare function verifyEntrySig(input: EntrySigInput): Promise<boolean>;
+//# sourceMappingURL=entry-verify.d.ts.map

package/dist/core/egress/entry-verify.js

@@ -0,0 +1,33 @@
+import { strictEd25519Verify } from "../../modes/rpc/ed25519-strict.js";
+export const ENTRY_SIG_DOMAIN = "omo-custody/provider-entry/v1";
+const LOWER_HEX = /^[0-9a-f]+$/u;
+const BASE64URL_NO_PAD = /^[A-Za-z0-9_-]+$/u;
+const ED25519_PUBLIC_KEY_BYTES = 32;
+const ED25519_SIGNATURE_BYTES = 64;
+/** r11.1 C.P5: entrySig signs ASCII(domain) || 0x00 || ASCII(entryDigest), entryDigest in lowercase hex. */
+export function entrySigPayload(entryDigest) {
+    if (!LOWER_HEX.test(entryDigest))
+        throw new TypeError("entryDigest must be lowercase hexadecimal");
+    const domain = Buffer.from(ENTRY_SIG_DOMAIN, "ascii");
+    return new Uint8Array(Buffer.concat([domain, Buffer.from([0]), Buffer.from(entryDigest, "ascii")]));
+}
+function decodeSignature(entrySig) {
+    if (!BASE64URL_NO_PAD.test(entrySig))
+        return undefined;
+    const bytes = Buffer.from(entrySig, "base64url");
+    if (bytes.length !== ED25519_SIGNATURE_BYTES || bytes.toString("base64url") !== entrySig)
+        return undefined;
+    return new Uint8Array(bytes);
+}
+/** The brain-side check before dialing (custody design 3.2); a false result is a wait, never a dial. */
+export async function verifyEntrySig(input) {
+    if (input.ownerPublicKey.length !== ED25519_PUBLIC_KEY_BYTES)
+        return false;
+    if (!LOWER_HEX.test(input.entryDigest))
+        return false;
+    const signature = decodeSignature(input.entrySig);
+    if (signature === undefined)
+        return false;
+    return strictEd25519Verify(input.ownerPublicKey, entrySigPayload(input.entryDigest), signature);
+}
+//# sourceMappingURL=entry-verify.js.map

package/dist/core/egress/hpke.js

@@ -46,8 +46,12 @@ function concat(...parts) {
     }
     return out;
 }
-const KEM_SUITE_ID = concat(encoder.encode("KEM"), i2osp(KEM_ID, 2));
-const HPKE_SUITE_ID = concat(encoder.encode("HPKE"), i2osp(KEM_ID, 2), i2osp(KDF_ID, 2), i2osp(AEAD_ID, 2));
+function kemSuiteId() {
+    return concat(encoder.encode("KEM"), i2osp(KEM_ID, 2));
+}
+function hpkeSuiteId() {
+    return concat(encoder.encode("HPKE"), i2osp(KEM_ID, 2), i2osp(KDF_ID, 2), i2osp(AEAD_ID, 2));
+}
 async function hmacSha256(key, data) {
     const hmacKey = await crypto.subtle.importKey("raw", key, { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);
     return new Uint8Array(await crypto.subtle.sign("HMAC", hmacKey, data));
@@ -73,8 +77,8 @@ function labeledExpand(suiteId, prk, label, info, length) {
     return hkdfExpand(prk, concat(i2osp(length, 2), encoder.encode(HPKE_V1), suiteId, encoder.encode(label), info), length);
 }
 async function extractAndExpand(dh, kemContext) {
-    const eaePrk = await labeledExtract(KEM_SUITE_ID, new Uint8Array(), "eae_prk", dh);
-    return labeledExpand(KEM_SUITE_ID, eaePrk, "shared_secret", kemContext, N_SECRET);
+    const eaePrk = await labeledExtract(kemSuiteId(), new Uint8Array(), "eae_prk", dh);
+    return labeledExpand(kemSuiteId(), eaePrk, "shared_secret", kemContext, N_SECRET);
 }
 async function importPublicKey(raw) {
     if (raw.length !== N_PK || raw[0] !== 0x04)
@@ -140,13 +144,13 @@ async function encapWith(recipientPublicKey, ephemeral, enc) {
 /** RFC 9180 KeySchedule for mode_base (no PSK). The exporter secret is not derived: the format never exports. */
 export async function hpkeKeySchedule(sharedSecret, info) {
     const empty = new Uint8Array();
-    const pskIdHash = await labeledExtract(HPKE_SUITE_ID, empty, "psk_id_hash", empty);
-    const infoHash = await labeledExtract(HPKE_SUITE_ID, empty, "info_hash", info);
+    const pskIdHash = await labeledExtract(hpkeSuiteId(), empty, "psk_id_hash", empty);
+    const infoHash = await labeledExtract(hpkeSuiteId(), empty, "info_hash", info);
     const context = concat(Uint8Array.of(MODE_BASE), pskIdHash, infoHash);
-    const secret = await labeledExtract(HPKE_SUITE_ID, sharedSecret, "secret", empty);
+    const secret = await labeledExtract(hpkeSuiteId(), sharedSecret, "secret", empty);
     return {
-        key: await labeledExpand(HPKE_SUITE_ID, secret, "key", context, N_K),
-        baseNonce: await labeledExpand(HPKE_SUITE_ID, secret, "base_nonce", context, N_N),
+        key: await labeledExpand(hpkeSuiteId(), secret, "key", context, N_K),
+        baseNonce: await labeledExpand(hpkeSuiteId(), secret, "base_nonce", context, N_N),
     };
 }
 async function aesGcmKey(key, usage) {

package/dist/core/egress/key-policy-template.d.ts

@@ -13,5 +13,11 @@ export interface KeyPolicyTemplate {
         readonly roles: CustodyRoleArns;
     }): string;
 }
-export declare const KEY_POLICY_TEMPLATE_V1: KeyPolicyTemplate;
+export declare const KEY_POLICY_TEMPLATE_V1: {
+    readonly render: ({ keyKind, roles }: {
+        readonly accountId: string;
+        readonly keyKind: KeyPolicyKind;
+        readonly roles: CustodyRoleArns;
+    }) => string;
+};
 //# sourceMappingURL=key-policy-template.d.ts.map

package/dist/core/egress/ledger-schema.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Schema of the brain's `egress_call` ledger (row CK9; custody design 4.5, 2.3, 4.2, 15.7). One row per dialed model
+ * call with its admitted request and, once `ended`, its assembled message stored beside it in 96 KiB chunks (never the
+ * event log: every streamed event carries the whole message so far), the step-cancelled marker (W14), and the
+ * per-session device variants (`session/variants`, read by the route). Every value here is written by `ledger.ts`
+ * through the host's admitted mutations; this module only names keys and converts rows to and from store values.
+ */
+import type { DeviceId, ProviderId } from "@earendil-works/pi-agent-core";
+import type { StoreValue } from "@earendil-works/pi-agent-core/conformance";
+import type { AssistantMessage, StopReason, Usage } from "@earendil-works/pi-ai";
+import { type ProviderCallErrorCode, type ProviderCallKind } from "./wire.ts";
+/** `dispatched` -> `ended` -> `closed` (by the step commit, W9); `superseded` and `cancelled` are final. */
+export type EgressCallState = "dispatched" | "ended" | "superseded" | "cancelled" | "closed";
+/** `callback-stream` providers run tools inside the stream, so every reissue of their step needs a user choice. */
+export type EgressCallCapability = "callback-stream" | "stream";
+/** `message`: the assembled message lives in `chunks` result chunks; the row keeps only its stop reason and usage. */
+export type EgressCallResult = {
+    readonly kind: "message";
+    readonly stopReason: StopReason;
+    readonly usage: Usage;
+    readonly chunks: number;
+} | {
+    readonly kind: "error";
+    readonly code: ProviderCallErrorCode;
+    readonly message: string;
+    readonly retryable: boolean;
+    readonly usage?: Usage;
+};
+/** What `ended` records: the assembled message of a finished call, or the hand's refusal or failure. */
+export type EgressCallEnd = {
+    readonly kind: "message";
+    readonly message: AssistantMessage;
+} | Extract<EgressCallResult, {
+    readonly kind: "error";
+}>;
+export interface EgressCallRow {
+    readonly callId: string;
+    readonly sessionId: string;
+    readonly call: ProviderCallKind;
+    readonly route: "sealed" | "device";
+    readonly deviceId?: DeviceId;
+    readonly providerId: ProviderId;
+    readonly modelId: string;
+    readonly epoch: number;
+    readonly capability: EgressCallCapability;
+    /** The stored request already carries this session's request hooks (4.5). */
+    readonly hooksApplied: boolean;
+    readonly state: EgressCallState;
+    readonly requestChunks: number;
+    readonly result?: EgressCallResult;
+}
+/** Durable `session/variants[P][deviceId]` (4.2); `mismatches` counts per (device, step) and restarts on a new head. */
+export interface VariantRecord {
+    readonly headDigest: string;
+    readonly liveAtMismatch: string | undefined;
+    readonly mismatches: number;
+}
+export declare const REQUEST_CHUNK_BYTES: number;
+export declare const callKey: (callId: string) => string;
+export declare const requestPrefix: (callId: string) => string;
+export declare const requestChunkKey: (callId: string, index: number) => string;
+export declare const resultPrefix: (callId: string) => string;
+export declare const resultChunkKey: (callId: string, index: number) => string;
+export declare const stepIndexPrefix: (stepId: string) => string;
+export declare const stepIndexKey: (stepId: string, attempt: number) => string;
+export declare const cancelledKey: (stepId: string) => string;
+export declare const variantPrefix: (providerId: ProviderId) => string;
+export declare const variantKey: (providerId: ProviderId, deviceId: DeviceId) => string;
+/** Splits UTF-8 text into chunks of at most `REQUEST_CHUNK_BYTES` bytes, never inside a code point. */
+export declare function splitUtf8(text: string): string[];
+/** The stored message text is the ledger's own JSON; the shape check guards against a truncated or foreign chunk set. */
+export declare function isStoredMessage(value: unknown): value is AssistantMessage;
+export declare function encodeCallRow(row: EgressCallRow): StoreValue;
+export declare function decodeCallRow(value: StoreValue | undefined): EgressCallRow | undefined;
+export interface StoredVariant extends VariantRecord {
+    readonly stepId: string;
+}
+export declare function decodeVariant(value: StoreValue | undefined): StoredVariant | undefined;
+export declare const encodeVariant: (variant: StoredVariant) => StoreValue;
+//# sourceMappingURL=ledger-schema.d.ts.map

package/dist/core/egress/ledger-schema.js

@@ -0,0 +1,117 @@
+import { PROVIDER_CALL_ERROR_CODES } from "./wire.js";
+export const REQUEST_CHUNK_BYTES = 96 * 1024;
+const pad = (index) => String(index).padStart(6, "0");
+export const callKey = (callId) => `egress_call/${encodeURIComponent(callId)}`;
+export const requestPrefix = (callId) => `egress_call_request/${encodeURIComponent(callId)}/`;
+export const requestChunkKey = (callId, index) => `${requestPrefix(callId)}${pad(index)}`;
+export const resultPrefix = (callId) => `egress_call_result/${encodeURIComponent(callId)}/`;
+export const resultChunkKey = (callId, index) => `${resultPrefix(callId)}${pad(index)}`;
+export const stepIndexPrefix = (stepId) => `egress_step/${encodeURIComponent(stepId)}/`;
+export const stepIndexKey = (stepId, attempt) => `${stepIndexPrefix(stepId)}${pad(attempt)}`;
+export const cancelledKey = (stepId) => `session/step.cancelled/${encodeURIComponent(stepId)}`;
+export const variantPrefix = (providerId) => `session/variants/${encodeURIComponent(providerId)}/`;
+export const variantKey = (providerId, deviceId) => `${variantPrefix(providerId)}${encodeURIComponent(deviceId)}`;
+/** Splits UTF-8 text into chunks of at most `REQUEST_CHUNK_BYTES` bytes, never inside a code point. */
+export function splitUtf8(text) {
+    const bytes = new TextEncoder().encode(text);
+    const decoder = new TextDecoder();
+    const chunks = [];
+    for (let start = 0; start < bytes.length;) {
+        let end = Math.min(start + REQUEST_CHUNK_BYTES, bytes.length);
+        while (end < bytes.length && ((bytes[end] ?? 0) & 0xc0) === 0x80)
+            end--;
+        chunks.push(decoder.decode(bytes.subarray(start, end)));
+        start = end;
+    }
+    return chunks.length > 0 ? chunks : [""];
+}
+const isObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const isErrorCode = (value) => PROVIDER_CALL_ERROR_CODES.some((code) => code === value);
+const isState = (value) => value === "dispatched" || value === "ended" || value === "superseded" || value === "cancelled" || value === "closed";
+function decodeCall(value) {
+    if (!isObject(value))
+        return undefined;
+    if (value.kind === "step" && typeof value.stepId === "string" && typeof value.attempt === "number")
+        return { kind: "step", stepId: value.stepId, attempt: value.attempt };
+    const { auxId, streamKind, auxKind } = value;
+    if (value.kind !== "aux" || typeof auxId !== "string" || typeof streamKind !== "string")
+        return undefined;
+    if (auxKind !== "stream" && auxKind !== "warm" && auxKind !== "compact-endpoint")
+        return undefined;
+    return { kind: "aux", auxId, streamKind, auxKind };
+}
+/** The ledger's own result JSON; the shape check guards against a truncated or foreign document. */
+function isCallResult(value) {
+    if (typeof value !== "object" || value === null || !("kind" in value))
+        return false;
+    if (value.kind === "message")
+        return "chunks" in value && typeof value.chunks === "number" && "stopReason" in value && "usage" in value;
+    return value.kind === "error" && "code" in value && isErrorCode(value.code) && "message" in value;
+}
+/** The stored message text is the ledger's own JSON; the shape check guards against a truncated or foreign chunk set. */
+export function isStoredMessage(value) {
+    if (typeof value !== "object" || value === null || !("role" in value) || value.role !== "assistant")
+        return false;
+    return "content" in value && Array.isArray(value.content) && "stopReason" in value && "usage" in value;
+}
+export function encodeCallRow(row) {
+    const { deviceId, result, ...fields } = row;
+    return {
+        ...fields,
+        ...(deviceId === undefined ? {} : { deviceId }),
+        ...(result === undefined ? {} : { result: JSON.stringify(result) }),
+    };
+}
+export function decodeCallRow(value) {
+    if (!isObject(value))
+        return undefined;
+    const { callId, sessionId, route, deviceId, providerId, modelId, epoch, capability, hooksApplied, state } = value;
+    const { requestChunks, result } = value;
+    const call = decodeCall(value.call);
+    if (typeof callId !== "string" || typeof sessionId !== "string" || !call)
+        return undefined;
+    if ((route !== "sealed" && route !== "device") || typeof providerId !== "string" || typeof modelId !== "string")
+        return undefined;
+    if (typeof epoch !== "number" || typeof hooksApplied !== "boolean" || typeof requestChunks !== "number")
+        return undefined;
+    if ((capability !== "callback-stream" && capability !== "stream") || !isState(state))
+        return undefined;
+    const parsed = typeof result === "string" ? JSON.parse(result) : undefined;
+    if (result !== undefined && !isCallResult(parsed))
+        return undefined;
+    return {
+        callId,
+        sessionId,
+        call,
+        route,
+        providerId,
+        modelId,
+        epoch,
+        capability,
+        hooksApplied,
+        state,
+        requestChunks,
+        ...(typeof deviceId === "string" ? { deviceId } : {}),
+        ...(isCallResult(parsed) ? { result: parsed } : {}),
+    };
+}
+export function decodeVariant(value) {
+    if (!isObject(value))
+        return undefined;
+    const { headDigest, liveAtMismatch, mismatches, stepId } = value;
+    if (typeof headDigest !== "string" || typeof mismatches !== "number" || typeof stepId !== "string")
+        return undefined;
+    return {
+        headDigest,
+        liveAtMismatch: typeof liveAtMismatch === "string" ? liveAtMismatch : undefined,
+        mismatches,
+        stepId,
+    };
+}
+export const encodeVariant = (variant) => ({
+    headDigest: variant.headDigest,
+    liveAtMismatch: variant.liveAtMismatch ?? null,
+    mismatches: variant.mismatches,
+    stepId: variant.stepId,
+});
+//# sourceMappingURL=ledger-schema.js.map

package/dist/core/egress/ledger.d.ts

@@ -0,0 +1,55 @@
+/**
+ * The brain's `egress_call` ledger (row CK9; custody design 4.5). Every write is one admitted mutation supplied by the
+ * host wrapper, which fences it (epoch, admission seq, instance generation) and commits it atomically; the ledger only
+ * builds the writes. W4 (row + request chunks) precedes any dial, W4' (`hooked`) replaces the request and sets
+ * `hooksApplied` in one mutation, `ended` (row + the assembled message in result chunks) is durable before the terminal
+ * event, and the step commit (W9) closes the row and deletes its chunks with `closeCallWrites` inside its own mutation.
+ * A cancelled step (W14) is never dialed again, so W14 deletes the live row's chunks too: nothing else would.
+ */
+import type { DeviceId, ProviderId } from "@earendil-works/pi-agent-core";
+import type { DurableStore, StoreWrite } from "@earendil-works/pi-agent-core/conformance";
+import type { AssistantMessage } from "@earendil-works/pi-ai";
+import { type EgressCallEnd, type EgressCallRow, type VariantRecord } from "./ledger-schema.ts";
+/** Runs `build` inside the host's admission slot and commits the writes it returns as one fenced, atomic mutation. */
+export type AdmittedMutation = (build: () => Promise<readonly StoreWrite[]>) => Promise<void>;
+export type NewCallRow = Omit<EgressCallRow, "state" | "requestChunks" | "result">;
+export interface VariantMismatch {
+    readonly providerId: ProviderId;
+    readonly deviceId: DeviceId;
+    readonly stepId: string;
+    readonly headDigest: string;
+    readonly liveAtMismatch: string | undefined;
+}
+export interface EgressLedger {
+    /** Every row of the step, oldest attempt first. */
+    rowsForStep(stepId: string): Promise<EgressCallRow[]>;
+    /** The stored request text, byte-identical to what was admitted (or what `hooked` replaced it with). */
+    readRequest(row: EgressCallRow): Promise<string>;
+    /** The assembled message of an `ended` row whose result is a message. */
+    readMessage(row: EgressCallRow): Promise<AssistantMessage>;
+    /** W4. With `previous`, the previous row is retired (`ended` -> `closed`) and its request chunks deleted, atomically. */
+    dispatch(next: NewCallRow, requestJson: string, previous?: EgressCallRow): Promise<EgressCallRow>;
+    /** W4': the post-hook request replaces the stored one and `hooksApplied` becomes true, in one mutation. */
+    recordHooked(row: EgressCallRow, requestJson: string): Promise<EgressCallRow>;
+    end(row: EgressCallRow, result: EgressCallEnd): Promise<EgressCallRow>;
+    /**
+     * The hand refused `row`'s start, so nothing ran: the row and its chunks are replaced by the same call under a new
+     * `callId` (same attempt, same stored request) in one mutation. A duplicate `start{callId}` is a result query (4.3),
+     * so the refused callId can never be started again.
+     */
+    replaceRefused(row: EgressCallRow, callId: string): Promise<EgressCallRow>;
+    /** The row is superseded; a definition mismatch records the device variant in the same mutation. */
+    supersede(row: EgressCallRow, variant?: VariantMismatch): Promise<EgressCallRow>;
+    /** W14: the step is cancelled (and its live row with it); a cancelled step is never dialed again. */
+    cancelStep(stepId: string, row: EgressCallRow | undefined): Promise<void>;
+    isCancelled(stepId: string): Promise<boolean>;
+    recordVariant(variant: VariantMismatch): Promise<void>;
+    variants(providerId: ProviderId): Promise<ReadonlyMap<DeviceId, VariantRecord>>;
+}
+/** The W9 part the ledger owns: the step's row becomes `closed` and its request chunks are deleted (4.5 retention). */
+export declare function closeCallWrites(row: EgressCallRow): StoreWrite[];
+export declare function createEgressLedger(options: {
+    readonly store: Pick<DurableStore, "getDocument" | "scanDocuments">;
+    readonly mutate: AdmittedMutation;
+}): EgressLedger;
+//# sourceMappingURL=ledger.d.ts.map