@noopolis/daimon 0.1.2 → 0.2.1

package/dist/runtime/engineBrokerProtocol.d.ts

@@ -0,0 +1,167 @@
+import { type BrokerClockObservation } from "./grokBrokerTaskClock.js";
+import { type EngineBrokerInferenceRequest, type EngineBrokerInferenceResponse } from "./engineBrokerInferenceProtocol.js";
+import { type EngineBrokerMcpCallObservation } from "./engineBrokerMcpCallLog.js";
+import { type EngineBrokerTurnAccounting, type EngineBrokerTurnLimitOverrides } from "./engineBrokerTurnAccounting.js";
+/**
+ * Control protocol v4 adds slot routing and reset. Both ends ship in the same
+ * package; v1/v2/v3 frames are refused on the wire. Durable terminal adapters
+ * retain those record formats. A missing slot is allowed only for a unique
+ * agent registration (unclocked production compatibility).
+ */
+declare const VERSION: "noopolis.daimon.engine-broker.v4";
+export declare const ENGINE_BROKER_VERSION: "noopolis.daimon.engine-broker.v4";
+declare const V1: "noopolis.daimon.engine-broker.v1";
+export declare const ENGINE_BROKER_MAX_FRAME_BYTES = 1048576;
+/** Version refusal is independent of the incompatible operation's schema. */
+export type EngineBrokerProtocolDiagnostic = Readonly<{
+    kind: "protocol_mismatch";
+    receivedVersion: string;
+    expectedVersion: string;
+}>;
+export declare class EngineBrokerProtocolMismatch extends TypeError {
+    readonly diagnostic: EngineBrokerProtocolDiagnostic;
+    constructor(received: unknown, expected?: unknown);
+}
+export type EngineBrokerRequest = Readonly<{
+    version: typeof VERSION;
+    kind: "health";
+    requestId: string;
+}> | Readonly<{
+    version: typeof VERSION;
+    kind: "start_turn";
+    requestId: string;
+    turnId: string;
+    slot?: number;
+    agentId: string;
+    wakeId: string;
+    prompt: string;
+    mcpEndpoint: string;
+    limits?: EngineBrokerTurnLimitOverrides;
+    processClock?: string;
+}> | Readonly<{
+    version: typeof VERSION;
+    kind: "cancel_turn";
+    requestId: string;
+    turnId: string;
+}> | Readonly<{
+    version: typeof VERSION;
+    kind: "reset_slot";
+    requestId: string;
+    slot: number;
+}> | EngineBrokerInferenceRequest;
+/**
+ * `reason` is the worker's own last words (`engineBrokerNativeClient.ts`),
+ * already redacted and flattened to one bounded line by the broker. It is the
+ * only field a failed turn carries that the worker itself wrote, so it is
+ * optional, bounded, control-character free, and admitted only for the
+ * statuses where a worker actually ran and spoke.
+ */
+export interface EngineBrokerFailureDiagnostic {
+    status: string;
+    stage: string;
+    failureClass: string;
+    profileApplied: boolean;
+    reason?: string;
+    exitCode: number;
+    termSignal: number;
+    workerPid: number;
+    workerUid: number;
+    startTicks: string;
+}
+export declare const ENGINE_BROKER_MAX_DIAGNOSTIC_REASON_BYTES = 768;
+/** Operational state after sealing; never raw filesystem errors or worker text. */
+export declare const ENGINE_BROKER_TASK_CLOCK_RESET_FAILED = "task clock reset failed; slot fenced until restart";
+export type EngineBrokerCleanupObservation = Readonly<{
+    cleanupDiagnostic?: typeof ENGINE_BROKER_TASK_CLOCK_RESET_FAILED;
+}>;
+export type EngineBrokerResponse = Readonly<{
+    version: typeof VERSION;
+    kind: "ready";
+    requestId: string;
+    brokerUid: 2100;
+    providerProxyPort: 43123;
+    mcpFacadePort: 43124;
+    registrations: number;
+    credentialStale: false;
+    realmLease: true;
+    workerIsolation: true;
+}> | Readonly<{
+    version: typeof VERSION;
+    kind: "accepted";
+    requestId: string;
+    turnId: string;
+}> | (Readonly<{
+    version: typeof VERSION;
+    kind: "completed";
+    requestId: string;
+    turnId: string;
+    text: string;
+    workerPid: number;
+    workerUid: number;
+    workerStartTime: string;
+}> & EngineBrokerTurnAccounting & BrokerClockObservation & EngineBrokerCleanupObservation) | (Readonly<{
+    version: typeof VERSION;
+    kind: "failed";
+    requestId: string;
+    turnId: string;
+    code: EngineBrokerFailureCode;
+    diagnostic?: EngineBrokerFailureDiagnostic;
+    mcpCalls?: EngineBrokerMcpCallObservation;
+}> & EngineBrokerTurnAccounting & BrokerClockObservation & EngineBrokerCleanupObservation) | Readonly<{
+    version: typeof VERSION;
+    kind: "slot_reset";
+    requestId: string;
+    slot: number;
+}> | EngineBrokerInferenceResponse;
+/**
+ * The one name for a fenced credential realm. The turn's failure code, the
+ * proxy's refusal reason on a worker request, and the grant path's 401 body
+ * (`GROK_INFERENCE_AUTH_STALE_BODY`) all say this same word, so an operator
+ * greps one string across every surface instead of three spellings of it.
+ */
+export declare const ENGINE_BROKER_AUTH_STALE: "auth_stale";
+export declare const ENGINE_BROKER_FAILURE_CODES: readonly ["auth_stale", "cancelled", "engine_failed", "invalid_request", "limit_exceeded", "turn_conflict", "unavailable"];
+export type EngineBrokerFailureCode = (typeof ENGINE_BROKER_FAILURE_CODES)[number];
+export type EngineBrokerTerminalResponse = Extract<EngineBrokerResponse, {
+    kind: "completed" | "failed";
+}>;
+type V1Completed = Readonly<{
+    version: typeof V1;
+    kind: "completed";
+    requestId: string;
+    turnId: string;
+    text: string;
+    workerPid: number;
+    workerUid: number;
+    workerStartTime: string;
+}>;
+type V1Failed = Readonly<{
+    version: typeof V1;
+    kind: "failed";
+    requestId: string;
+    turnId: string;
+    code: Exclude<EngineBrokerFailureCode, "limit_exceeded">;
+    diagnostic?: EngineBrokerFailureDiagnostic;
+}>;
+export type EngineBrokerV1TerminalResponse = V1Completed | V1Failed;
+export declare function parseEngineBrokerRequest(value: unknown): EngineBrokerRequest;
+export declare function parseEngineBrokerResponse(value: unknown): EngineBrokerResponse;
+/**
+ * A terminal response persisted by a pre-v2 broker: the v1 field sets exactly,
+ * with no accounting. Accepted only from the durable turn registry, never from
+ * the wire.
+ */
+export declare function parseEngineBrokerV1TerminalResponse(value: unknown): EngineBrokerV1TerminalResponse;
+export declare function parseEngineBrokerSlot(value: unknown): number;
+/** v3 survives only in durable records. */
+export declare function parseEngineBrokerV3TerminalResponse(value: unknown): EngineBrokerTerminalResponse;
+/** v2 survives only in durable records. The wire always refuses it. */
+export declare function parseEngineBrokerV2TerminalResponse(value: unknown): EngineBrokerTerminalResponse;
+export declare function encodeEngineBrokerFrame(value: EngineBrokerRequest | EngineBrokerResponse | EngineBrokerProtocolDiagnostic): Buffer;
+export declare class EngineBrokerFrameDecoder {
+    private buffered;
+    push(chunk: Uint8Array): unknown[];
+    finish(): void;
+}
+export {};
+//# sourceMappingURL=engineBrokerProtocol.d.ts.map

package/dist/runtime/engineBrokerProtocol.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engineBrokerProtocol.d.ts","sourceRoot":"","sources":["../../src/runtime/engineBrokerProtocol.ts"],"names":[],"mappings":"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"}

package/dist/runtime/engineBrokerProtocol.js

@@ -0,0 +1,357 @@
+import { parseBrokerProcessClock } from "./grokBrokerTaskClock.js";
+import { parseGrokBrokerProviderClockObservation } from "./grokBrokerProviderClock.js";
+import { isEngineBrokerInferenceRequestKind, isEngineBrokerInferenceResponseKind, parseEngineBrokerInferenceRequest, parseEngineBrokerInferenceResponse } from "./engineBrokerInferenceProtocol.js";
+import { ENGINE_BROKER_MCP_CALL_NAME, ENGINE_BROKER_MCP_OUTSTANDING_MAX, ENGINE_BROKER_MCP_REFUSAL_REASONS, ENGINE_BROKER_MCP_TUNNEL_MAX } from "./engineBrokerMcpCallLog.js";
+import { parseEngineBrokerTurnAccounting, parseEngineBrokerTurnLimitOverrides } from "./engineBrokerTurnAccounting.js";
+/**
+ * Control protocol v4 adds slot routing and reset. Both ends ship in the same
+ * package; v1/v2/v3 frames are refused on the wire. Durable terminal adapters
+ * retain those record formats. A missing slot is allowed only for a unique
+ * agent registration (unclocked production compatibility).
+ */
+const VERSION = "noopolis.daimon.engine-broker.v4";
+export const ENGINE_BROKER_VERSION = VERSION;
+const V1 = "noopolis.daimon.engine-broker.v1";
+export const ENGINE_BROKER_MAX_FRAME_BYTES = 1_048_576;
+const PROTOCOL_NAME = /^noopolis\.daimon\.engine-broker\.v[0-9]{1,6}$/u;
+const boundedProtocol = (value) => typeof value === "string" && PROTOCOL_NAME.test(value) ? value : "<invalid>";
+export class EngineBrokerProtocolMismatch extends TypeError {
+    diagnostic;
+    constructor(received, expected = VERSION) {
+        const receivedVersion = boundedProtocol(received);
+        const expectedVersion = boundedProtocol(expected);
+        super(`invalid broker frame: protocol version mismatch (received ${receivedVersion}; expected ${expectedVersion})`);
+        this.diagnostic = { kind: "protocol_mismatch", receivedVersion, expectedVersion };
+    }
+}
+const ID = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/u;
+export const ENGINE_BROKER_MAX_DIAGNOSTIC_REASON_BYTES = 768;
+/** Operational state after sealing; never raw filesystem errors or worker text. */
+export const ENGINE_BROKER_TASK_CLOCK_RESET_FAILED = "task clock reset failed; slot fenced until restart";
+/**
+ * The one name for a fenced credential realm. The turn's failure code, the
+ * proxy's refusal reason on a worker request, and the grant path's 401 body
+ * (`GROK_INFERENCE_AUTH_STALE_BODY`) all say this same word, so an operator
+ * greps one string across every surface instead of three spellings of it.
+ */
+export const ENGINE_BROKER_AUTH_STALE = "auth_stale";
+export const ENGINE_BROKER_FAILURE_CODES = [ENGINE_BROKER_AUTH_STALE, "cancelled", "engine_failed", "invalid_request", "limit_exceeded", "turn_conflict", "unavailable"];
+const ACCOUNTING = ["outcome", "usage", "model", "requests", "limitReason"];
+const record = (value) => {
+    if (value === null || typeof value !== "object" || Array.isArray(value) || (Object.getPrototypeOf(value) !== Object.prototype && Object.getPrototypeOf(value) !== null))
+        throw new TypeError("invalid broker frame");
+    return value;
+};
+const exact = (value, fields) => {
+    if (Object.keys(value).length !== fields.length || fields.some((field) => !Object.hasOwn(value, field)))
+        throw new TypeError("invalid broker frame");
+};
+const text = (value, maxBytes) => {
+    if (typeof value !== "string" || value.length === 0 || Buffer.byteLength(value, "utf8") > maxBytes)
+        throw new TypeError("invalid broker frame");
+    return value;
+};
+const id = (value) => { const result = text(value, 128); if (!ID.test(result))
+    throw new TypeError("invalid broker frame"); return result; };
+const version = (value) => {
+    if (value !== VERSION)
+        throw new EngineBrokerProtocolMismatch(value);
+    return VERSION;
+};
+export function parseEngineBrokerRequest(value) {
+    const input = record(value);
+    version(input.version);
+    if (input.kind === "health") {
+        exact(input, ["version", "kind", "requestId"]);
+        return { version: VERSION, kind: "health", requestId: id(input.requestId) };
+    }
+    if (input.kind === "start_turn") {
+        const fields = ["version", "kind", "requestId", "turnId", "agentId", "wakeId", "prompt", "mcpEndpoint"];
+        exact(input, [...fields, ...(input.slot === undefined ? [] : ["slot"]), ...(input.limits === undefined ? [] : ["limits"]), ...(input.processClock === undefined ? [] : ["processClock"])]);
+        let processClock;
+        if (input.processClock !== undefined) {
+            try {
+                processClock = parseBrokerProcessClock(input.processClock);
+            }
+            catch {
+                throw new TypeError("invalid broker frame");
+            }
+        }
+        const mcpEndpoint = text(input.mcpEndpoint, 2048);
+        const url = new URL(mcpEndpoint);
+        if (url.protocol !== "http:" || url.hostname !== "127.0.0.1" || url.pathname !== "/mcp")
+            throw new TypeError("invalid broker frame");
+        let limits;
+        if (input.limits !== undefined) {
+            try {
+                limits = parseEngineBrokerTurnLimitOverrides(input.limits);
+            }
+            catch {
+                throw new TypeError("invalid broker frame");
+            }
+        }
+        return { version: VERSION, kind: "start_turn", ...(input.slot === undefined ? {} : { slot: parseEngineBrokerSlot(input.slot) }), requestId: id(input.requestId), turnId: id(input.turnId), agentId: id(input.agentId), wakeId: id(input.wakeId), prompt: text(input.prompt, 65_536), mcpEndpoint, ...(limits === undefined ? {} : { limits }), ...(processClock === undefined ? {} : { processClock }) };
+    }
+    if (input.kind === "reset_slot") {
+        exact(input, ["version", "kind", "requestId", "slot"]);
+        return { version: VERSION, kind: "reset_slot", requestId: id(input.requestId), slot: parseEngineBrokerSlot(input.slot) };
+    }
+    if (input.kind === "cancel_turn") {
+        exact(input, ["version", "kind", "requestId", "turnId"]);
+        return { version: VERSION, kind: "cancel_turn", requestId: id(input.requestId), turnId: id(input.turnId) };
+    }
+    if (isEngineBrokerInferenceRequestKind(input.kind))
+        return parseEngineBrokerInferenceRequest(input, id(input.requestId), VERSION);
+    throw new TypeError("invalid broker frame");
+}
+export function parseEngineBrokerResponse(value) {
+    const input = record(value);
+    if (input.kind === "protocol_mismatch") {
+        exact(input, ["kind", "receivedVersion", "expectedVersion"]);
+        for (const field of [input.receivedVersion, input.expectedVersion]) {
+            if (field !== "<invalid>" && boundedProtocol(field) !== field)
+                throw new TypeError("invalid broker frame");
+        }
+        throw new EngineBrokerProtocolMismatch(input.receivedVersion, input.expectedVersion);
+    }
+    version(input.version);
+    if (input.kind === "ready") {
+        exact(input, ["version", "kind", "requestId", "brokerUid", "providerProxyPort", "mcpFacadePort", "registrations", "credentialStale", "realmLease", "workerIsolation"]);
+        if (input.brokerUid !== 2100 || input.providerProxyPort !== 43123 || input.mcpFacadePort !== 43124 || !Number.isSafeInteger(input.registrations) || input.registrations < 1 || input.credentialStale !== false || input.realmLease !== true || input.workerIsolation !== true)
+            throw new TypeError("invalid broker frame");
+        return { version: VERSION, kind: "ready", requestId: id(input.requestId), brokerUid: 2100, providerProxyPort: 43123, mcpFacadePort: 43124, registrations: input.registrations, credentialStale: false, realmLease: true, workerIsolation: true };
+    }
+    if (input.kind === "slot_reset") {
+        exact(input, ["version", "kind", "requestId", "slot"]);
+        return { version: VERSION, kind: "slot_reset", requestId: id(input.requestId), slot: parseEngineBrokerSlot(input.slot) };
+    }
+    if (input.kind === "accepted") {
+        exact(input, ["version", "kind", "requestId", "turnId"]);
+        return { version: VERSION, kind: "accepted", requestId: id(input.requestId), turnId: id(input.turnId) };
+    }
+    if (input.kind === "completed" || input.kind === "failed")
+        return parseTerminal(input, VERSION);
+    if (isEngineBrokerInferenceResponseKind(input.kind))
+        return parseEngineBrokerInferenceResponse(input, id(input.requestId), VERSION);
+    throw new TypeError("invalid broker frame");
+}
+/**
+ * A terminal response persisted by a pre-v2 broker: the v1 field sets exactly,
+ * with no accounting. Accepted only from the durable turn registry, never from
+ * the wire.
+ */
+export function parseEngineBrokerV1TerminalResponse(value) {
+    const input = record(value);
+    if (input.version !== V1 || (input.kind !== "completed" && input.kind !== "failed"))
+        throw new TypeError("invalid broker frame");
+    return parseTerminal(input, V1);
+}
+export function parseEngineBrokerSlot(value) {
+    if (!Number.isSafeInteger(value) || value < 0)
+        throw new TypeError("invalid broker slot");
+    return value;
+}
+/** v3 survives only in durable records. */
+export function parseEngineBrokerV3TerminalResponse(value) {
+    const input = record(value);
+    if (input.version !== "noopolis.daimon.engine-broker.v3" || (input.kind !== "completed" && input.kind !== "failed"))
+        throw new TypeError("invalid broker frame");
+    return parseTerminal({ ...input, version: VERSION }, VERSION);
+}
+/** v2 survives only in durable records. The wire always refuses it. */
+export function parseEngineBrokerV2TerminalResponse(value) {
+    const input = record(value);
+    if (input.version !== "noopolis.daimon.engine-broker.v2" ||
+        (input.kind !== "completed" && input.kind !== "failed") ||
+        Object.hasOwn(input, "shellClock") || Object.hasOwn(input, "providerClock") ||
+        Object.hasOwn(input, "cleanupDiagnostic")) {
+        throw new TypeError("invalid broker frame");
+    }
+    return parseTerminal({ ...input, version: VERSION }, VERSION);
+}
+function parseTerminal(input, expected) {
+    const accounting = expected === VERSION ? ACCOUNTING : [];
+    const shellClock = input.shellClock;
+    if (shellClock !== undefined && (expected !== VERSION || !["task", "real", "gap"].includes(shellClock)))
+        throw new TypeError("invalid broker frame");
+    if (input.providerClock !== undefined && expected !== VERSION)
+        throw new TypeError("invalid broker frame");
+    const cleanupDiagnostic = input.cleanupDiagnostic;
+    if (cleanupDiagnostic !== undefined &&
+        (expected !== VERSION || cleanupDiagnostic !== ENGINE_BROKER_TASK_CLOCK_RESET_FAILED)) {
+        throw new TypeError("invalid broker frame");
+    }
+    const observation = {
+        ...(cleanupDiagnostic === undefined ? {} : { cleanupDiagnostic }),
+        ...(shellClock === undefined ? {} : { shellClock: shellClock }),
+        ...(input.providerClock === undefined ? {} : {
+            providerClock: parseGrokBrokerProviderClockObservation(input.providerClock)
+        })
+    };
+    const clockFields = Object.keys(observation);
+    if (input.kind === "completed") {
+        exact(input, ["version", "kind", "requestId", "turnId", "text", "workerPid", "workerUid", "workerStartTime", ...accounting, ...clockFields]);
+        if (!Number.isSafeInteger(input.workerPid) || input.workerPid < 1 || !Number.isSafeInteger(input.workerUid) || input.workerUid < 1)
+            throw new TypeError("invalid broker frame");
+        const base = { kind: "completed", requestId: id(input.requestId), turnId: id(input.turnId), text: text(input.text, 262_144), workerPid: input.workerPid, workerUid: input.workerUid, workerStartTime: id(input.workerStartTime) };
+        return expected === VERSION ? { version: VERSION, ...base, ...observation, ...parseEngineBrokerTurnAccounting(input, "completed") } : { version: V1, ...base };
+    }
+    // `mcpCalls` is the broker's own observation of the worker's tool calls
+    // (`engineBrokerMcpCallLog.ts`), additive in v2 and never part of a v1
+    // record, which predates the instrument entirely.
+    if (expected === V1 && input.mcpCalls !== undefined)
+        throw new TypeError("invalid broker frame");
+    const fields = ["version", "kind", "requestId", "turnId", "code", ...accounting, ...clockFields, ...(input.diagnostic === undefined ? [] : ["diagnostic"]), ...(input.mcpCalls === undefined ? [] : ["mcpCalls"])];
+    exact(input, fields);
+    const codes = expected === VERSION ? ENGINE_BROKER_FAILURE_CODES : ENGINE_BROKER_FAILURE_CODES.filter((code) => code !== "limit_exceeded");
+    if (!codes.includes(input.code))
+        throw new TypeError("invalid broker frame");
+    let diagnostic;
+    if (input.diagnostic !== undefined) {
+        const value = record(input.diagnostic);
+        const fields = ["status", "stage", "failureClass", "profileApplied", "exitCode", "termSignal", "workerPid", "workerUid", "startTicks"];
+        exact(value, value.reason === undefined ? fields : [...fields, "reason"]);
+        if (value.reason !== undefined && (typeof value.reason !== "string" || value.reason.length === 0 || Buffer.byteLength(value.reason, "utf8") > ENGINE_BROKER_MAX_DIAGNOSTIC_REASON_BYTES || /[\u0000-\u001f\u007f]/u.test(value.reason)))
+            throw new TypeError("invalid broker frame");
+        const status = ["prelaunch_failed", "worker_failed", "output_failed", "cancelled"], stage = ["peer", "request", "registration", "executable", "exec", "wait", "output", "attestation"], failureClass = ["peer", "protocol", "registration", "executable", "exec", "wait", "output_limit", "cancelled", "profile_missing", "profile_invalid"];
+        if (!status.includes(value.status) || !stage.includes(value.stage) || !failureClass.includes(value.failureClass) || typeof value.profileApplied !== "boolean" || ![value.exitCode, value.termSignal, value.workerPid, value.workerUid].every(Number.isSafeInteger) || typeof value.startTicks !== "string" || !/^(0|[1-9][0-9]*)$/u.test(value.startTicks) || !closedDiagnostic(value))
+            throw new TypeError("invalid broker frame");
+        diagnostic = value;
+    }
+    const base = { kind: "failed", requestId: id(input.requestId), turnId: id(input.turnId), code: input.code, ...(diagnostic ? { diagnostic } : {}) };
+    if (expected === V1)
+        return { version: V1, ...base };
+    const accountingValue = parseEngineBrokerTurnAccounting(input, "failed");
+    if ((input.code === "limit_exceeded") !== (accountingValue.limitReason !== "none"))
+        throw new TypeError("invalid broker frame");
+    const mcpCalls = input.mcpCalls === undefined ? undefined : parseMcpCallObservation(input.mcpCalls);
+    return { version: VERSION, ...base, ...observation, ...(mcpCalls === undefined ? {} : { mcpCalls }), ...accountingValue };
+}
+/**
+ * Names and timings, bounded, and internally consistent: a report can never
+ * claim more answered calls than started ones, nor more outstanding ones than
+ * started minus answered. Every count is its own measurement, so a missing
+ * field is refused rather than defaulted — a zero the broker did not measure
+ * would read exactly like one it did.
+ */
+function parseMcpCallObservation(value) {
+    const input = record(value);
+    // `tunnels` is optional for one reason only: a turn sealed before the GET
+    // tunnel was observed carries no such member, and its record must still
+    // replay. Absence there means "the instrument did not exist", never zero.
+    exact(input, ["started", "answered", "undecoded", "outstanding", ...(input.tunnels === undefined ? [] : ["tunnels"]), ...(input.refusals === undefined ? [] : ["refusals"])]);
+    const started = input.started, answered = input.answered, undecoded = input.undecoded;
+    if (![started, answered, undecoded].every((count) => Number.isSafeInteger(count) && count >= 0))
+        throw new TypeError("invalid broker frame");
+    if (!Array.isArray(input.outstanding) || input.outstanding.length > ENGINE_BROKER_MCP_OUTSTANDING_MAX)
+        throw new TypeError("invalid broker frame");
+    const outstanding = input.outstanding.map((entry) => {
+        const call = record(entry);
+        exact(call, ["name", "outstandingMs"]);
+        if (typeof call.name !== "string" || !ENGINE_BROKER_MCP_CALL_NAME.test(call.name))
+            throw new TypeError("invalid broker frame");
+        if (!Number.isSafeInteger(call.outstandingMs) || call.outstandingMs < 0)
+            throw new TypeError("invalid broker frame");
+        return { name: call.name, outstandingMs: call.outstandingMs };
+    });
+    if (answered > started || outstanding.length > started - answered)
+        throw new TypeError("invalid broker frame");
+    const tunnels = input.tunnels === undefined ? undefined : parseMcpTunnelObservation(input.tunnels);
+    const refusals = input.refusals === undefined ? undefined : parseMcpRefusalObservation(input.refusals);
+    return { started: started, answered: answered, undecoded: undecoded, outstanding, ...(tunnels === undefined ? {} : { tunnels }), ...(refusals === undefined ? {} : { refusals }) };
+}
+/**
+ * The refused requests, by reason class: one count per closed reason, all of
+ * them required once the member is present. Optional for the same single
+ * reason `tunnels` is — a turn sealed before the facade counted its refusals
+ * must still replay — so its absence means "not measured" and never zero, and
+ * a partial member is refused rather than zero-filled.
+ */
+function parseMcpRefusalObservation(value) {
+    const input = record(value);
+    exact(input, ENGINE_BROKER_MCP_REFUSAL_REASONS);
+    for (const reason of ENGINE_BROKER_MCP_REFUSAL_REASONS) {
+        if (!Number.isSafeInteger(input[reason]) || input[reason] < 0)
+            throw new TypeError("invalid broker frame");
+    }
+    return Object.fromEntries(ENGINE_BROKER_MCP_REFUSAL_REASONS.map((reason) => [reason, input[reason]]));
+}
+/**
+ * The GET SSE tunnels, under the call observation's rules: counts and elapsed
+ * milliseconds, bounded, and internally consistent. A tunnel cannot close
+ * before it opened, cannot deliver without having opened, and no more can be
+ * reported open than `opened - closed` — a report claiming otherwise is a
+ * frame, not a measurement.
+ */
+function parseMcpTunnelObservation(value) {
+    const input = record(value);
+    exact(input, ["opened", "closed", "delivered", "open"]);
+    const opened = input.opened, closed = input.closed, delivered = input.delivered;
+    if (![opened, closed, delivered].every((count) => Number.isSafeInteger(count) && count >= 0))
+        throw new TypeError("invalid broker frame");
+    if (closed > opened || delivered > opened)
+        throw new TypeError("invalid broker frame");
+    if (!Array.isArray(input.open) || input.open.length > ENGINE_BROKER_MCP_TUNNEL_MAX || input.open.length > opened - closed)
+        throw new TypeError("invalid broker frame");
+    const open = input.open.map((entry) => {
+        const tunnel = record(entry);
+        exact(tunnel, ["openMs", "delivered"]);
+        if (!Number.isSafeInteger(tunnel.openMs) || tunnel.openMs < 0 || typeof tunnel.delivered !== "boolean")
+            throw new TypeError("invalid broker frame");
+        return { openMs: tunnel.openMs, delivered: tunnel.delivered };
+    });
+    return { opened: opened, closed: closed, delivered: delivered, open };
+}
+function closedDiagnostic(value) {
+    if (value.profileApplied !== false || value.workerPid < 0 || value.workerUid < 0)
+        return false;
+    // Only a worker that ran and wrote something can have said why it failed:
+    // no prelaunch failure and no attestation refusal carries worker words.
+    if (value.reason !== undefined && !((value.status === "worker_failed" && value.stage === "wait") || value.status === "output_failed" || value.status === "cancelled"))
+        return false;
+    const noWorker = value.workerPid === 0 && value.workerUid === 0 && value.startTicks === "0";
+    const worker = value.workerPid > 0 && value.workerUid >= 2200 && value.startTicks !== "0";
+    if (value.status === "prelaunch_failed")
+        return noWorker && { peer: "peer", request: "protocol", registration: "registration", executable: "executable", exec: "exec" }[value.stage] === value.failureClass;
+    if (value.status === "worker_failed" && value.stage === "attestation")
+        return worker && (value.failureClass === "profile_missing" || value.failureClass === "profile_invalid");
+    if (value.status === "worker_failed")
+        return worker && value.stage === "wait" && (value.failureClass === "exec" || value.failureClass === "wait");
+    if (value.status === "output_failed")
+        return worker && value.stage === "output" && value.failureClass === "output_limit";
+    return value.status === "cancelled" && worker && value.stage === "wait" && value.failureClass === "cancelled";
+}
+export function encodeEngineBrokerFrame(value) {
+    const body = Buffer.from(JSON.stringify(value), "utf8");
+    if (body.length > ENGINE_BROKER_MAX_FRAME_BYTES)
+        throw new TypeError("invalid broker frame");
+    const frame = Buffer.allocUnsafe(body.length + 4);
+    frame.writeUInt32BE(body.length);
+    body.copy(frame, 4);
+    return frame;
+}
+export class EngineBrokerFrameDecoder {
+    buffered = Buffer.alloc(0);
+    push(chunk) {
+        this.buffered = Buffer.concat([this.buffered, chunk]);
+        const values = [];
+        while (this.buffered.length >= 4) {
+            const length = this.buffered.readUInt32BE(0);
+            if (length === 0 || length > ENGINE_BROKER_MAX_FRAME_BYTES)
+                throw new TypeError("invalid broker frame");
+            if (this.buffered.length < length + 4)
+                break;
+            const body = this.buffered.subarray(4, length + 4);
+            this.buffered = this.buffered.subarray(length + 4);
+            try {
+                values.push(JSON.parse(body.toString("utf8")));
+            }
+            catch {
+                throw new TypeError("invalid broker frame");
+            }
+        }
+        return values;
+    }
+    finish() { if (this.buffered.length !== 0)
+        throw new TypeError("incomplete broker frame"); }
+}

package/dist/runtime/engineBrokerSealLedger.d.ts

@@ -0,0 +1,70 @@
+import type { EngineBrokerTerminalResponse } from "./engineBrokerProtocol.js";
+/**
+ * The operator-visible half of a sealed terminal turn, as a durable row.
+ *
+ * The seal itself already carries everything an operator needs to read a turn
+ * that stopped acting — the failure code, the worker's own redacted last words,
+ * and `engineBrokerMcpCallLog.ts`'s observation of the tool call the worker was
+ * blocked on. All of it travels in the control-protocol terminal response, and
+ * that response is the one artifact a *hung* turn never produces: the client is
+ * gone before the broker answers, the turn registry record lives in the
+ * broker's own `0700` turn store, and a training slot's control root is tmpfs
+ * that dies with the container. Six live runs reproduced the same signature and
+ * none of them could read the instrument built for it.
+ *
+ * What does survive a slot is the broker's ledger directory: Paideia already
+ * recovers `usage.jsonl` and `requests.jsonl` from it on the failure path. So
+ * this is a third stream beside those two, written by the broker — still the
+ * single sealed usage writer — from the sealed response and nothing else, at
+ * the moment that response is sealed.
+ *
+ * Its rules are the two ledgers' rules:
+ *
+ * - **Numbers, names, timings and closed vocabularies only.** The failure code,
+ *   the accounting, the diagnostic's closed `status`/`stage`/`failure_class`
+ *   and its already-redacted, already-bounded, control-character-free `reason`
+ *   (`engineBrokerNativeClient.ts` produced it; nothing here re-derives it),
+ *   plus tool-call names, GET-tunnel counts and elapsed milliseconds. Never a
+ *   prompt, a body, a
+ *   reply, a bearer, a capability or a session id — none of which the terminal
+ *   response carries in the first place.
+ * - **Absence stays absence.** `mcp` is written only when the facade actually
+ *   observed the turn, `diagnostic` only when the sealed response carried one,
+ *   and `code` only for a failure. A turn that called no tool publishes
+ *   `started: 0`, which is a measurement; a turn the facade never registered
+ *   publishes no `mcp` member at all, which is not.
+ * - **It can never fail a turn.** The row is rendered from an
+ *   already-validated frame and appended through `recordLedgerLines`, which
+ *   swallows every I/O fault.
+ *
+ * A separate stream and a separate `v`, for `turnRequestLedger.ts`'s reason:
+ * Spawnfile's reader pins `noopolis.daimon.turn-usage.v1` and drops any other
+ * `v` outright, and Paideia's request reader refuses a row it cannot type. A
+ * row in a new file is invisible to both.
+ */
+export declare const TURN_SEAL_LEDGER_VERSION: "noopolis.daimon.turn-seal.v1";
+/** Default location: beside `usage.jsonl` and `requests.jsonl`, no new mount. */
+export declare const TURN_SEAL_LEDGER: {
+    readonly version: "noopolis.daimon.turn-seal.v1";
+    readonly directoryPath: "/var/lib/spawnfile/daimon/usage";
+    readonly filePath: "/var/lib/spawnfile/daimon/usage/turns.jsonl";
+    readonly rotatedFilePath: "/var/lib/spawnfile/daimon/usage/turns.jsonl.1";
+    readonly fileMode: 416;
+};
+/** A rendered seal line is bounded by its own contents: a 768-byte reason, 16 bounded names and 8 tunnel timings. */
+export declare const TURN_SEAL_MAX_LINE_BYTES = 8192;
+export type BrokerTurnSealEntry = Readonly<{
+    agent: string;
+    wake: string;
+    at: string;
+}>;
+/**
+ * One newline-terminated row for one sealed terminal turn.
+ *
+ * Every member is copied from the terminal response the protocol already
+ * validated, so this projection cannot widen what the response admits; it is an
+ * allow-list rather than a spread, so a future additive member of the response
+ * does not silently become a ledger field.
+ */
+export declare const renderBrokerTurnSealLine: (terminal: EngineBrokerTerminalResponse, entry: BrokerTurnSealEntry) => string;
+//# sourceMappingURL=engineBrokerSealLedger.d.ts.map

package/dist/runtime/engineBrokerSealLedger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engineBrokerSealLedger.d.ts","sourceRoot":"","sources":["../../src/runtime/engineBrokerSealLedger.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,2BAA2B,CAAC;AAG9E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,eAAO,MAAM,wBAAwB,EAAG,8BAAuC,CAAC;AAEhF,iFAAiF;AACjF,eAAO,MAAM,gBAAgB;;;;;;CAMnB,CAAC;AAEX,qHAAqH;AACrH,eAAO,MAAM,wBAAwB,OAAQ,CAAC;AAE9C,MAAM,MAAM,mBAAmB,GAAG,QAAQ,CAAC;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC;AAIxF;;;;;;;GAOG;AACH,eAAO,MAAM,wBAAwB,GAAI,UAAU,4BAA4B,EAAE,OAAO,mBAAmB,KAAG,MAkExG,CAAC"}