@noopolis/daimon 0.1.1 → 0.2.0

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

@@ -0,0 +1 @@
+{"version":3,"file":"turnRequestLedger.d.ts","sourceRoot":"","sources":["../../src/runtime/turnRequestLedger.ts"],"names":[],"mappings":"AAGA,OAAO,EAA4B,KAAK,iBAAiB,EAAE,MAAM,4BAA4B,CAAC;AAC9F,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAGlE;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,2BAA2B,EAAG,kCAA2C,CAAC;AAEvF;;;GAGG;AACH,eAAO,MAAM,mBAAmB;;;;;;CAMtB,CAAC;AAEX;;;;;GAKG;AACH,eAAO,MAAM,4BAA4B,EAAG,kCAA2C,CAAC;AAExF,eAAO,MAAM,4BAA4B,GAAI,cAAa,MAAM,CAAC,UAAwB,KAAG,MAG3F,CAAC;AAEF,MAAM,MAAM,gBAAgB,GAAG,QAAQ,CAAC;IACtC,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,gEAAgE;IAChE,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,SAAS,iBAAiB,EAAE,CAAC;IACvC,EAAE,CAAC,EAAE,MAAM,CAAC;CACb,CAAC,CAAC;AAIH;;;;;;;;;;GAUG;AACH,eAAO,MAAM,sBAAsB,GAAI,OAAO,gBAAgB,KAAG,MAqBhE,CAAC;AASF,0FAA0F;AAC1F;;;;GAIG;AACH;;;;GAIG;AACH,MAAM,MAAM,eAAe,GAAG,QAAQ,CAAC;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,QAAQ,GAAG,UAAU,GAAG,WAAW,CAAC;IAAC,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,CAAC,CAAC;AACvQ;;;;GAIG;AACH,MAAM,MAAM,oBAAoB,GAAG,QAAQ,CAAC;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,eAAe,CAAC;IAAC,QAAQ,EAAE,SAAS,eAAe,EAAE,CAAC;IAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAAC,EAAE,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC;AAE/M;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,eAAO,MAAM,0BAA0B,GAAI,OAAO,oBAAoB,KAAG,MAuBxE,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,GAAU,MAAM,MAAM,EAAE,OAAO,MAAM,KAAG,OAAO,CAAC,OAAO,CAGpF,CAAC;AAEF,iGAAiG;AACjG,eAAO,MAAM,sBAAsB,GAAU,MAAM,MAAM,EAAE,OAAO,oBAAoB,KAAG,OAAO,CAAC,OAAO,CAGvG,CAAC;AA4BF;;;;;;;GAOG;AACH,eAAO,MAAM,kBAAkB,GAAU,MAAM,MAAM,EAAE,OAAO,gBAAgB,KAAG,OAAO,CAAC,OAAO,CAU/F,CAAC;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,uBAAuB,GAAU,OAAO,QAAQ,CAAC;IAC5D,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,CAAC,KAAG,OAAO,CAAC,OAAO,CAiBnB,CAAC"}

package/dist/runtime/turnRequestLedger.js

@@ -0,0 +1,249 @@
+import { constants } from "node:fs";
+import { open, rename, stat } from "node:fs/promises";
+import { readCodexRolloutRequests } from "../pi/codexRolloutUsage.js";
+import { TURN_USAGE_LEDGER, TURN_USAGE_MAX_IDENTIFIER_CHARS, TURN_USAGE_ROTATE_BYTES } from "./turnUsageLedger.js";
+/**
+ * Per-model-request token accounting, written *beside* the per-wake usage
+ * ledger and never inside it.
+ *
+ * `turnUsageLedger.ts` records one aggregate row per wake. Production measured
+ * 55 wakes at 14,890,263 input tokens against 159,726 output — output is 1.06%
+ * of the spend — with context per model request flat at 23–32k regardless of
+ * how many requests a wake made. That is the signature of a fixed prefix
+ * replayed once per request rather than of a conversation that grows, but the
+ * aggregate row cannot tell the two apart, and every optimisation worth doing
+ * next depends on which one it is. This file is what tells them apart.
+ *
+ * It is a separate stream, not a wider row, for one specific reason. Spawnfile's
+ * reader (`spawnfile/src/runtime/usageLedger.ts`) rejects any line whose `v` is
+ * not `noopolis.daimon.turn-usage.v1` and returns `null` for the whole line, so
+ * a version bump on the existing ledger would make an unreleased Spawnfile drop
+ * every row it can read today. Nothing here changes the shape, version, path, or
+ * field list of that ledger; a reader that knows nothing about this file keeps
+ * working byte for byte.
+ */
+export const TURN_REQUEST_LEDGER_VERSION = "noopolis.daimon.turn-requests.v1";
+/**
+ * Default location: the directory Spawnfile already provisions for the usage
+ * ledger, under its own filename. No new mount, no new provisioning step.
+ */
+export const TURN_REQUEST_LEDGER = {
+    version: TURN_REQUEST_LEDGER_VERSION,
+    directoryPath: TURN_USAGE_LEDGER.directoryPath,
+    filePath: `${TURN_USAGE_LEDGER.directoryPath}/requests.jsonl`,
+    rotatedFilePath: `${TURN_USAGE_LEDGER.directoryPath}/requests.jsonl.1`,
+    fileMode: TURN_USAGE_LEDGER.fileMode
+};
+/**
+ * `DAIMON_TURN_REQUESTS_LEDGER_PATH` relocates the stream, exactly as
+ * `DAIMON_TURN_USAGE_LEDGER_PATH` relocates the ledger it sits beside. A
+ * relative or empty value is ignored rather than honoured: a ledger written to
+ * a process-relative path is a ledger nobody can find again.
+ */
+export const TURN_REQUEST_LEDGER_PATH_ENV = "DAIMON_TURN_REQUESTS_LEDGER_PATH";
+export const resolveTurnRequestLedgerPath = (environment = process.env) => {
+    const override = environment[TURN_REQUEST_LEDGER_PATH_ENV]?.trim();
+    return override !== undefined && override.startsWith("/") ? override : TURN_REQUEST_LEDGER.filePath;
+};
+const bounded = (value) => [...value].slice(0, TURN_USAGE_MAX_IDENTIFIER_CHARS).join("");
+/**
+ * One line per model request.
+ *
+ * `fresh_input` is `input − cached_input`, the split the whole exercise exists
+ * to see. It is derived from exactly the relationship Daimon already validates
+ * (`cached_input_tokens` is a subset of `input_tokens`, asserted by Codex's own
+ * reconciled totals and re-checked when the block is decoded). `cache_write` is
+ * emitted raw and never subtracted, because whether Codex counts a cache write
+ * inside `input_tokens` has not been verified — a reader that needs that answer
+ * has the raw number to work from instead of a guess baked into the row.
+ */
+export const renderTurnRequestLines = (entry) => {
+    const at = entry.at ?? new Date().toISOString();
+    const requests = entry.requests.length;
+    return entry.requests.map((request) => `${JSON.stringify({
+        v: TURN_REQUEST_LEDGER_VERSION,
+        agent: bounded(entry.agent),
+        wake: bounded(entry.wake),
+        engine: "codex",
+        at,
+        thread: bounded(entry.thread),
+        request: request.index,
+        requests,
+        input: request.input,
+        cached_input: request.cachedInput,
+        fresh_input: request.input - request.cachedInput,
+        cache_write: request.cacheWrite,
+        output: request.output,
+        reasoning: request.reasoning,
+        total: request.total,
+        ...requestClockFields(request)
+    })}\n`).join("");
+};
+const TIMESTAMP = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{1,9})?Z$/u;
+/** Per-request `started_at`/`ended_at`, each only when it was measured; `at` stays the append time. */
+const requestClockFields = (request) => ({
+    ...(request.startedAt !== undefined && TIMESTAMP.test(request.startedAt) ? { started_at: request.startedAt } : {}),
+    ...(request.endedAt !== undefined && TIMESTAMP.test(request.endedAt) ? { ended_at: request.endedAt } : {})
+});
+/**
+ * Grok rows share the Codex row's field meaning: `input` is the whole prompt
+ * side the request replayed (`input_tokens + cache_read`), `cached_input` the
+ * cache read, `fresh_input` the uncached remainder. Grok does not separate
+ * reasoning tokens, so `reasoning` is absent rather than zero. `turn` is the
+ * broker idempotency key and `thread` the Grok session id when the stream
+ * named one.
+ *
+ * `tool_calls` is what a turn's rows could not say before: whether the model
+ * ever *tried* to call anything. Two live turns ended with correctly mounted
+ * tools and no visible attempt, and the rows recorded timings and tokens only,
+ * so the question could not be answered after the fact. It is names only —
+ * never arguments, never message content, never a bearer — bounded, `[]` for a
+ * response that called nothing, and absent for a response that could not be
+ * decoded, because a fabricated empty list is byte-identical to a measured one.
+ *
+ * It is an additive field inside the unchanged
+ * `noopolis.daimon.turn-requests.v1` row, deliberately without a version bump:
+ * Spawnfile's usage reader (`spawnfile/src/runtime/usageLedger.ts`) drops every
+ * line whose `v` it does not recognise while ignoring fields it does not know,
+ * and Paideia only relocates this stream's path
+ * (`DAIMON_TURN_REQUESTS_LEDGER_PATH`). A bump is what would blind them; a new
+ * field is not.
+ */
+export const renderGrokTurnRequestLines = (entry) => {
+    const at = entry.at ?? new Date().toISOString();
+    return entry.requests.map((request) => `${JSON.stringify({
+        v: TURN_REQUEST_LEDGER_VERSION,
+        agent: bounded(entry.agent),
+        wake: bounded(entry.wake),
+        engine: "grok",
+        at,
+        turn: entry.turn,
+        ...(entry.session === undefined ? {} : { thread: bounded(entry.session) }),
+        model: entry.model,
+        request: request.index,
+        requests: Math.max(entry.requests.length, entry.requestCount ?? 0),
+        input: request.input + request.cacheRead,
+        cached_input: request.cacheRead,
+        fresh_input: request.input,
+        cache_write: request.cacheWrite,
+        output: request.output,
+        total: request.total,
+        ...(request.usageSource === undefined ? {} : { usage_source: request.usageSource }),
+        ...(request.toolCalls === undefined ? {} : { tool_calls: request.toolCalls }),
+        ...requestClockFields(request)
+    })}\n`).join("");
+};
+/**
+ * Append already-rendered, newline-terminated ledger lines in one write, with the
+ * same rotation and file mode as both ledgers. Advisory: never rejects. The
+ * broker uses it to append the exact bytes it sealed into a turn record.
+ */
+export const recordLedgerLines = async (file, lines) => {
+    if (lines.length === 0)
+        return false;
+    try {
+        await rotate(file);
+        await appendLines(file, lines);
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+/** Advisory and never rejects, like {@link recordTurnRequests}; an empty turn writes nothing. */
+export const recordGrokTurnRequests = async (file, entry) => {
+    if (entry.requests.length === 0)
+        return false;
+    try {
+        await rotate(file);
+        await appendLines(file, renderGrokTurnRequestLines(entry));
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+const rotate = async (file) => {
+    let size;
+    try {
+        size = (await stat(file)).size;
+    }
+    catch {
+        return;
+    }
+    if (size >= TURN_USAGE_ROTATE_BYTES)
+        await rename(file, `${file}.1`);
+};
+/**
+ * One `write(2)` for the whole wake's rows.
+ *
+ * Turns for different agents run concurrently inside the single broker process.
+ * `O_APPEND` makes a single sub-page write atomic against them, so a wake's rows
+ * are contiguous and never interleaved with another wake's — which matters more
+ * here than in the per-wake ledger, because a row only means something beside
+ * the other rows of its own thread. A wake with enough requests to exceed a page
+ * is still append-ordered per line; interleaving would cost grouping, not
+ * correctness, since every row carries its own thread id.
+ */
+const appendLines = async (file, lines) => {
+    const bytes = Buffer.from(lines, "utf8");
+    const handle = await open(file, constants.O_WRONLY | constants.O_APPEND | constants.O_CREAT | constants.O_NOFOLLOW, TURN_REQUEST_LEDGER.fileMode);
+    try {
+        const { bytesWritten } = await handle.write(bytes, 0, bytes.length);
+        if (bytesWritten !== bytes.length)
+            throw new Error("turn request ledger append was torn");
+    }
+    finally {
+        await handle.close();
+    }
+};
+/**
+ * Advisory. Never rejects, and never writes an empty wake.
+ *
+ * A wake whose rollout was absent, unreadable, or undecodable contributes no
+ * rows at all rather than a zero row — the same invariant the usage ledger
+ * holds, for the same reason: a fabricated zero is byte-identical to a measured
+ * one, and this stream exists to be believed.
+ */
+export const recordTurnRequests = async (file, entry) => {
+    if (entry.requests.length === 0)
+        return false;
+    try {
+        await rotate(file);
+        await appendLines(file, renderTurnRequestLines(entry));
+        return true;
+    }
+    catch {
+        /* advisory: instrumentation never fails a wake that published */
+        return false;
+    }
+};
+/**
+ * The whole instrumentation path for one Codex wake: find that thread's
+ * rollout, decode its per-request usage, append it. Never throws.
+ *
+ * A wake that produced no rows says so on stderr exactly once. Silence would
+ * make a permanently blind instrument indistinguishable from a working one —
+ * `--ephemeral`, a relocated `CODEX_HOME`, or a Codex version that renamed the
+ * usage frame all end here, and each is worth one line rather than a
+ * quietly-empty file nobody questions.
+ */
+export const recordCodexTurnRequests = async (input) => {
+    try {
+        const requests = await readCodexRolloutRequests(input.codexHome, input.threadId);
+        const written = await recordTurnRequests(input.file ?? resolveTurnRequestLedgerPath(), {
+            agent: input.agent,
+            wake: input.wake,
+            thread: input.threadId,
+            requests
+        });
+        if (!written) {
+            console.error(`daimon: no per-request usage recorded for codex thread ${input.threadId} (${requests.length === 0 ? "no decodable rollout usage" : "ledger append failed"})`);
+        }
+        return written;
+    }
+    catch (error) {
+        console.error(`daimon: per-request usage instrumentation failed: ${error instanceof Error ? error.message : "unknown error"}`);
+        return false;
+    }
+};

package/dist/runtime/turnUsageLedger.d.ts

@@ -0,0 +1,143 @@
+import { type EngineBrokerLimitReason } from "./engineBrokerTurnAccounting.js";
+import type { GrokBrokerModel } from "./grokBrokerModelPolicy.js";
+/**
+ * Append-only per-turn token accounting for one container.
+ *
+ * The record carries no organization: there is one ledger per container and one
+ * organization per container, so identity comes from which container was
+ * queried. Nothing engine-controlled and non-numeric is ever persisted.
+ */
+export declare const TURN_USAGE_LEDGER_VERSION: "noopolis.daimon.turn-usage.v1";
+/**
+ * Where the broker writes, and what Spawnfile provisions.
+ *
+ * Deliberately *not* folded into `RUNTIME_CONTRACT_MANIFEST`. That manifest's
+ * canonical bytes are digest-pinned by Spawnfile
+ * (`DAIMON_CONTRACT_MANIFEST_SHA256`) and attested against the runtime image
+ * selected at compile time, so any new key there makes every pinned image fail
+ * to attest and blocks all Daimon compiles until an image is rebuilt and
+ * re-pinned. Nothing about metering needs digest attestation: this is a path
+ * both sides agree on, mirrored in `spawnfile/src/runtime/daimon/`. Registering
+ * the schema in the manifest is bookkeeping that belongs with the next image
+ * rebuild.
+ */
+export declare const TURN_USAGE_LEDGER: {
+    readonly version: "noopolis.daimon.turn-usage.v1";
+    readonly directoryPath: "/var/lib/spawnfile/daimon/usage";
+    readonly filePath: "/var/lib/spawnfile/daimon/usage/usage.jsonl";
+    readonly rotatedFilePath: "/var/lib/spawnfile/daimon/usage/usage.jsonl.1";
+    readonly directoryMode: 488;
+    readonly fileMode: 416;
+};
+/**
+ * `agent` and `wake` are caller-supplied external text (`wake` is `event.id`
+ * from the wake request, schema-bounded to 4096 codepoints). They are truncated
+ * so one record cannot grow past a size where a single `write(2)` stops being
+ * atomic. JSON escaping already prevents line injection.
+ */
+export declare const TURN_USAGE_MAX_IDENTIFIER_CHARS = 128;
+/** Rotate to a single `.1` sibling. ~2.5k lines/day observed, so this is months. */
+export declare const TURN_USAGE_ROTATE_BYTES: number;
+export type TurnUsageMeasurement = Readonly<{
+    input: number;
+    output: number;
+    cacheRead: number;
+    cacheWrite: number;
+    total: number;
+    calls: number;
+    notionalUsd: number;
+    complete: boolean;
+}>;
+/**
+ * Every engine whose headless stream reports its own token accounting.
+ *
+ * Codex, AGY, and Grok all publish decoded terminal-stream accounting here.
+ * Spawnfile's reader mirrors this list and is updated separately in packet
+ * A1b; until then, a reader that rejects `codex` will drop every Codex line.
+ */
+export declare const TURN_USAGE_ENGINES: readonly ["agy", "codex", "grok"];
+/**
+ * Whether the wake that spent these tokens went on to succeed.
+ *
+ * Money is spent by a failed wake exactly as by a successful one, so a row is
+ * written whenever the engine actually reported usage — see
+ * `../pi/cliSession.ts`. Without this field every failed wake's spend was
+ * simply absent from the ledger, and an organization's cost total silently
+ * undercounted by however much its failures burned.
+ *
+ * `reason` is a closed vocabulary, never an engine- or error-supplied string:
+ * the record's rule that nothing engine-controlled and non-numeric is
+ * persisted still holds, and `renderTurnUsageLine` degrades anything outside
+ * the list to `unknown` rather than writing it through.
+ */
+export declare const TURN_USAGE_OUTCOMES: readonly ["completed", "failed"];
+/**
+ * - `token_ceiling` — the turn's own reported usage crossed the per-wake ceiling.
+ * - `request_ceiling` — the broker refused a model request past the turn's request limit.
+ * - `wake_timeout` — the wall-clock bound fired before the child finished.
+ * - `output_limit` — the retained-output bound was exceeded.
+ * - `engine_exit` — the child exited non-zero (or died) after reporting usage.
+ * - `turn_rejected` — usage was reported but the decoded turn was not publishable.
+ * - `unknown` — any other failure (verification, cleanup, spawn).
+ */
+export declare const TURN_USAGE_FAILURE_REASONS: readonly ["token_ceiling", "request_ceiling", "wake_timeout", "output_limit", "engine_exit", "turn_rejected", "unknown"];
+export type TurnUsageFailureReason = typeof TURN_USAGE_FAILURE_REASONS[number];
+export type TurnUsageOutcome = Readonly<{
+    status: typeof TURN_USAGE_OUTCOMES[number];
+    reason?: TurnUsageFailureReason;
+}>;
+export type TurnUsageEntry = Readonly<{
+    agent: string;
+    wake: string;
+    engine: typeof TURN_USAGE_ENGINES[number];
+    usage: TurnUsageMeasurement;
+    at?: string;
+    outcome?: TurnUsageOutcome;
+    /**
+     * Broker rows only. `turn` is the idempotency key readers dedupe on (the
+     * broker turn id, a sha256 hex); `limitReason` and `model` come from the
+     * closed broker vocabularies and are dropped rather than written through
+     * when they are not members.
+     */
+    turn?: string;
+    limitReason?: EngineBrokerLimitReason;
+    model?: GrokBrokerModel;
+    /** Broker rows only: how many of the turn's requests were charged an estimate because their response carried no valid usage. */
+    estimatedRequests?: number;
+}>;
+/**
+ * Where a metered turn is appended.
+ *
+ * Production is {@link TURN_USAGE_LEDGER}`.filePath`, which Spawnfile
+ * provisions as a non-run-scoped volume. `DAIMON_TURN_USAGE_LEDGER_PATH`
+ * redirects it to an absolute path elsewhere; it exists so the wiring between a
+ * live engine session and this ledger can be exercised end to end, and so an
+ * operator can relocate the ledger without a rebuild. A relative or empty value
+ * is ignored rather than honoured, because a ledger written to a
+ * process-relative path is a ledger nobody can find again.
+ */
+export declare const TURN_USAGE_LEDGER_PATH_ENV: "DAIMON_TURN_USAGE_LEDGER_PATH";
+export declare const resolveTurnUsageLedgerPath: (environment?: NodeJS.ProcessEnv) => string;
+/** One complete line, newline-terminated. `JSON.stringify` escapes any embedded newline. */
+export declare const renderTurnUsageLine: (entry: TurnUsageEntry) => string;
+/**
+ * Collapse rows that share a `turn` key to the first one, keeping rows without
+ * a key untouched. Every reader that sums the ledger applies this, because a
+ * turn key exists precisely so a re-appended turn can never be counted twice.
+ */
+export declare const dedupeTurnUsageRows: <T extends Readonly<{
+    turn?: unknown;
+}>>(rows: readonly T[]) => T[];
+/**
+ * Advisory. Never rejects.
+ *
+ * The caller runs this inside the broker's turn `try` block, after the turn has
+ * already been recorded as *completed*. That block's `catch` calls
+ * `finish(..., failed)` unconditionally, and `finish` has no terminal-state
+ * guard — it renames over an existing record. An escaping append error would
+ * therefore rewrite an already-completed turn as failed. This guard is the only
+ * thing preventing that, so it is the one place where getting "advisory" wrong
+ * corrupts turn state instead of merely dropping a line.
+ */
+export declare const recordTurnUsage: (file: string, entry: TurnUsageEntry) => Promise<void>;
+//# sourceMappingURL=turnUsageLedger.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"turnUsageLedger.d.ts","sourceRoot":"","sources":["../../src/runtime/turnUsageLedger.ts"],"names":[],"mappings":"AAIA,OAAO,EAA+B,KAAK,uBAAuB,EAAE,MAAM,iCAAiC,CAAC;AAC5G,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAElE;;;;;;GAMG;AACH,eAAO,MAAM,yBAAyB,EAAG,+BAAwC,CAAC;AAElF;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,iBAAiB;;;;;;;CAOpB,CAAC;AAEX;;;;;GAKG;AACH,eAAO,MAAM,+BAA+B,MAAM,CAAC;AAEnD,oFAAoF;AACpF,eAAO,MAAM,uBAAuB,QAAmB,CAAC;AAExD,MAAM,MAAM,oBAAoB,GAAG,QAAQ,CAAC;IAC1C,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,OAAO,CAAC;CACnB,CAAC,CAAC;AAEH;;;;;;GAMG;AACH,eAAO,MAAM,kBAAkB,mCAAoC,CAAC;AAEpE;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,mBAAmB,kCAAmC,CAAC;AAEpE;;;;;;;;GAQG;AACH,eAAO,MAAM,0BAA0B,0HAQ7B,CAAC;AAEX,MAAM,MAAM,sBAAsB,GAAG,OAAO,0BAA0B,CAAC,MAAM,CAAC,CAAC;AAE/E,MAAM,MAAM,gBAAgB,GAAG,QAAQ,CAAC;IACtC,MAAM,EAAE,OAAO,mBAAmB,CAAC,MAAM,CAAC,CAAC;IAC3C,MAAM,CAAC,EAAE,sBAAsB,CAAC;CACjC,CAAC,CAAC;AAEH,MAAM,MAAM,cAAc,GAAG,QAAQ,CAAC;IACpC,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,OAAO,kBAAkB,CAAC,MAAM,CAAC,CAAC;IAC1C,KAAK,EAAE,oBAAoB,CAAC;IAC5B,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,OAAO,CAAC,EAAE,gBAAgB,CAAC;IAC3B;;;;;OAKG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,uBAAuB,CAAC;IACtC,KAAK,CAAC,EAAE,eAAe,CAAC;IACxB,gIAAgI;IAChI,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B,CAAC,CAAC;AAEH;;;;;;;;;;GAUG;AACH,eAAO,MAAM,0BAA0B,EAAG,+BAAwC,CAAC;AAEnF,eAAO,MAAM,0BAA0B,GAAI,cAAa,MAAM,CAAC,UAAwB,KAAG,MAGzF,CAAC;AAuBF,4FAA4F;AAC5F,eAAO,MAAM,mBAAmB,GAAI,OAAO,cAAc,KAAG,MAgBtD,CAAC;AASP;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,GAAI,CAAC,SAAS,QAAQ,CAAC;IAAE,IAAI,CAAC,EAAE,OAAO,CAAA;CAAE,CAAC,EAAE,MAAM,SAAS,CAAC,EAAE,KAAG,CAAC,EAGjG,CAAC;AAuBF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,eAAe,GAAU,MAAM,MAAM,EAAE,OAAO,cAAc,KAAG,OAAO,CAAC,IAAI,CAOvF,CAAC"}

package/dist/runtime/turnUsageLedger.js

@@ -0,0 +1,203 @@
+import { constants } from "node:fs";
+import { open, rename, stat } from "node:fs/promises";
+import { GROK_BROKER_MODELS } from "../contracts/grokWorkerContract.js";
+import { ENGINE_BROKER_LIMIT_REASONS } from "./engineBrokerTurnAccounting.js";
+/**
+ * Append-only per-turn token accounting for one container.
+ *
+ * The record carries no organization: there is one ledger per container and one
+ * organization per container, so identity comes from which container was
+ * queried. Nothing engine-controlled and non-numeric is ever persisted.
+ */
+export const TURN_USAGE_LEDGER_VERSION = "noopolis.daimon.turn-usage.v1";
+/**
+ * Where the broker writes, and what Spawnfile provisions.
+ *
+ * Deliberately *not* folded into `RUNTIME_CONTRACT_MANIFEST`. That manifest's
+ * canonical bytes are digest-pinned by Spawnfile
+ * (`DAIMON_CONTRACT_MANIFEST_SHA256`) and attested against the runtime image
+ * selected at compile time, so any new key there makes every pinned image fail
+ * to attest and blocks all Daimon compiles until an image is rebuilt and
+ * re-pinned. Nothing about metering needs digest attestation: this is a path
+ * both sides agree on, mirrored in `spawnfile/src/runtime/daimon/`. Registering
+ * the schema in the manifest is bookkeeping that belongs with the next image
+ * rebuild.
+ */
+export const TURN_USAGE_LEDGER = {
+    version: TURN_USAGE_LEDGER_VERSION,
+    directoryPath: "/var/lib/spawnfile/daimon/usage",
+    filePath: "/var/lib/spawnfile/daimon/usage/usage.jsonl",
+    rotatedFilePath: "/var/lib/spawnfile/daimon/usage/usage.jsonl.1",
+    directoryMode: 0o750,
+    fileMode: 0o640
+};
+/**
+ * `agent` and `wake` are caller-supplied external text (`wake` is `event.id`
+ * from the wake request, schema-bounded to 4096 codepoints). They are truncated
+ * so one record cannot grow past a size where a single `write(2)` stops being
+ * atomic. JSON escaping already prevents line injection.
+ */
+export const TURN_USAGE_MAX_IDENTIFIER_CHARS = 128;
+/** Rotate to a single `.1` sibling. ~2.5k lines/day observed, so this is months. */
+export const TURN_USAGE_ROTATE_BYTES = 64 * 1024 * 1024;
+/**
+ * Every engine whose headless stream reports its own token accounting.
+ *
+ * Codex, AGY, and Grok all publish decoded terminal-stream accounting here.
+ * Spawnfile's reader mirrors this list and is updated separately in packet
+ * A1b; until then, a reader that rejects `codex` will drop every Codex line.
+ */
+export const TURN_USAGE_ENGINES = ["agy", "codex", "grok"];
+/**
+ * Whether the wake that spent these tokens went on to succeed.
+ *
+ * Money is spent by a failed wake exactly as by a successful one, so a row is
+ * written whenever the engine actually reported usage — see
+ * `../pi/cliSession.ts`. Without this field every failed wake's spend was
+ * simply absent from the ledger, and an organization's cost total silently
+ * undercounted by however much its failures burned.
+ *
+ * `reason` is a closed vocabulary, never an engine- or error-supplied string:
+ * the record's rule that nothing engine-controlled and non-numeric is
+ * persisted still holds, and `renderTurnUsageLine` degrades anything outside
+ * the list to `unknown` rather than writing it through.
+ */
+export const TURN_USAGE_OUTCOMES = ["completed", "failed"];
+/**
+ * - `token_ceiling` — the turn's own reported usage crossed the per-wake ceiling.
+ * - `request_ceiling` — the broker refused a model request past the turn's request limit.
+ * - `wake_timeout` — the wall-clock bound fired before the child finished.
+ * - `output_limit` — the retained-output bound was exceeded.
+ * - `engine_exit` — the child exited non-zero (or died) after reporting usage.
+ * - `turn_rejected` — usage was reported but the decoded turn was not publishable.
+ * - `unknown` — any other failure (verification, cleanup, spawn).
+ */
+export const TURN_USAGE_FAILURE_REASONS = [
+    "token_ceiling",
+    "request_ceiling",
+    "wake_timeout",
+    "output_limit",
+    "engine_exit",
+    "turn_rejected",
+    "unknown"
+];
+/**
+ * Where a metered turn is appended.
+ *
+ * Production is {@link TURN_USAGE_LEDGER}`.filePath`, which Spawnfile
+ * provisions as a non-run-scoped volume. `DAIMON_TURN_USAGE_LEDGER_PATH`
+ * redirects it to an absolute path elsewhere; it exists so the wiring between a
+ * live engine session and this ledger can be exercised end to end, and so an
+ * operator can relocate the ledger without a rebuild. A relative or empty value
+ * is ignored rather than honoured, because a ledger written to a
+ * process-relative path is a ledger nobody can find again.
+ */
+export const TURN_USAGE_LEDGER_PATH_ENV = "DAIMON_TURN_USAGE_LEDGER_PATH";
+export const resolveTurnUsageLedgerPath = (environment = process.env) => {
+    const override = environment[TURN_USAGE_LEDGER_PATH_ENV]?.trim();
+    return override !== undefined && override.startsWith("/") ? override : TURN_USAGE_LEDGER.filePath;
+};
+const bounded = (value) => [...value].slice(0, TURN_USAGE_MAX_IDENTIFIER_CHARS).join("");
+/**
+ * `outcome`/`reason` are an additive field pair inside the *unchanged* `v1`
+ * record, deliberately not a `v2`.
+ *
+ * Spawnfile's reader (`spawnfile/src/runtime/usageLedger.ts`) rejects any `v`
+ * that is not `noopolis.daimon.turn-usage.v1` and returns `null` for the whole
+ * line, while picking only the fields it knows and ignoring the rest. Bumping
+ * the version would therefore make an unreleased Spawnfile drop *every* row —
+ * strictly worse than the defect being fixed. Reading the pair is opt-in;
+ * every historical row lacks it and, since a failed wake previously recorded
+ * nothing at all, absent can be read as `completed` without ambiguity.
+ */
+const outcomeFields = (outcome) => {
+    const status = outcome?.status === "failed" ? "failed" : "completed";
+    if (status === "completed")
+        return { outcome: status };
+    const reason = outcome?.reason;
+    return { outcome: status, reason: reason !== undefined && TURN_USAGE_FAILURE_REASONS.includes(reason) ? reason : "unknown" };
+};
+/** One complete line, newline-terminated. `JSON.stringify` escapes any embedded newline. */
+export const renderTurnUsageLine = (entry) => `${JSON.stringify({
+    v: TURN_USAGE_LEDGER_VERSION,
+    agent: bounded(entry.agent),
+    wake: bounded(entry.wake),
+    engine: entry.engine,
+    at: entry.at ?? new Date().toISOString(),
+    input: entry.usage.input,
+    output: entry.usage.output,
+    cache_read: entry.usage.cacheRead,
+    cache_write: entry.usage.cacheWrite,
+    total: entry.usage.total,
+    calls: entry.usage.calls,
+    notional_usd: entry.usage.notionalUsd,
+    complete: entry.usage.complete,
+    ...outcomeFields(entry.outcome),
+    ...brokerFields(entry)
+})}\n`;
+const brokerFields = (entry) => ({
+    ...(entry.turn !== undefined && /^[a-f0-9]{64}$/u.test(entry.turn) ? { turn: entry.turn } : {}),
+    ...(entry.limitReason !== undefined && ENGINE_BROKER_LIMIT_REASONS.includes(entry.limitReason) ? { limit_reason: entry.limitReason } : {}),
+    ...(entry.model !== undefined && GROK_BROKER_MODELS.includes(entry.model) ? { model: entry.model } : {}),
+    ...(entry.estimatedRequests !== undefined && Number.isSafeInteger(entry.estimatedRequests) && entry.estimatedRequests > 0 ? { estimated_requests: entry.estimatedRequests } : {})
+});
+/**
+ * Collapse rows that share a `turn` key to the first one, keeping rows without
+ * a key untouched. Every reader that sums the ledger applies this, because a
+ * turn key exists precisely so a re-appended turn can never be counted twice.
+ */
+export const dedupeTurnUsageRows = (rows) => {
+    const seen = new Set();
+    return rows.filter((row) => { if (typeof row.turn !== "string")
+        return true; if (seen.has(row.turn))
+        return false; seen.add(row.turn); return true; });
+};
+const rotate = async (file) => {
+    let size;
+    try {
+        size = (await stat(file)).size;
+    }
+    catch {
+        return;
+    }
+    if (size >= TURN_USAGE_ROTATE_BYTES)
+        await rename(file, `${file}.1`);
+};
+/**
+ * One `write(2)` per complete line. Turns for different agents run concurrently
+ * inside the single broker process, and `O_APPEND` makes a single sub-page write
+ * atomic against them. The directory is root-provisioned, so this never creates
+ * it: a missing directory is a provisioning failure, not something to paper over.
+ */
+const appendLine = async (file, line) => {
+    const bytes = Buffer.from(line, "utf8");
+    const handle = await open(file, constants.O_WRONLY | constants.O_APPEND | constants.O_CREAT | constants.O_NOFOLLOW, TURN_USAGE_LEDGER.fileMode);
+    try {
+        const { bytesWritten } = await handle.write(bytes, 0, bytes.length);
+        if (bytesWritten !== bytes.length)
+            throw new Error("turn usage ledger append was torn");
+    }
+    finally {
+        await handle.close();
+    }
+};
+/**
+ * Advisory. Never rejects.
+ *
+ * The caller runs this inside the broker's turn `try` block, after the turn has
+ * already been recorded as *completed*. That block's `catch` calls
+ * `finish(..., failed)` unconditionally, and `finish` has no terminal-state
+ * guard — it renames over an existing record. An escaping append error would
+ * therefore rewrite an already-completed turn as failed. This guard is the only
+ * thing preventing that, so it is the one place where getting "advisory" wrong
+ * corrupts turn state instead of merely dropping a line.
+ */
+export const recordTurnUsage = async (file, entry) => {
+    try {
+        await rotate(file);
+        await appendLine(file, renderTurnUsageLine(entry));
+    }
+    catch {
+        /* advisory: a failed append never fails a turn that published */
+    }
+};

package/dist/runtime/wakeAcceptanceProcessIdentity.d.ts

@@ -0,0 +1,17 @@
+export type TransitionLock = Readonly<{
+    owner_id: string;
+    generation: string;
+    pid: number;
+    process_start: string;
+    boot_id: string;
+    pid_namespace_dev: number;
+    pid_namespace_ino: number;
+}>;
+export declare class WakeTransitionLockBlockedError extends Error {
+    readonly code: "offline_reconciliation_required";
+    constructor();
+}
+export declare function sameNamespace(left: Pick<TransitionLock, "pid_namespace_dev" | "pid_namespace_ino">, right: Pick<TransitionLock, "pid_namespace_dev" | "pid_namespace_ino">): boolean;
+export declare function currentProcessIdentity(): Promise<Omit<TransitionLock, "owner_id" | "generation">>;
+export declare function processIsAlive(lock: TransitionLock): Promise<boolean>;
+//# sourceMappingURL=wakeAcceptanceProcessIdentity.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"wakeAcceptanceProcessIdentity.d.ts","sourceRoot":"","sources":["../../src/runtime/wakeAcceptanceProcessIdentity.ts"],"names":[],"mappings":"AACA,MAAM,MAAM,cAAc,GAAG,QAAQ,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,aAAa,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,iBAAiB,EAAE,MAAM,CAAC;IAAC,iBAAiB,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC;AAC3L,qBAAa,8BAA+B,SAAQ,KAAK;IAAG,QAAQ,CAAC,IAAI,EAAG,iCAAiC,CAAU;;CAAmF;AAC1M,wBAAgB,aAAa,CAAC,IAAI,EAAE,IAAI,CAAC,cAAc,EAAE,mBAAmB,GAAG,mBAAmB,CAAC,EAAE,KAAK,EAAE,IAAI,CAAC,cAAc,EAAE,mBAAmB,GAAG,mBAAmB,CAAC,GAAG,OAAO,CAAqH;AAC1S,wBAAsB,sBAAsB,IAAI,OAAO,CAAC,IAAI,CAAC,cAAc,EAAE,UAAU,GAAG,YAAY,CAAC,CAAC,CAKvG;AACD,wBAAsB,cAAc,CAAC,IAAI,EAAE,cAAc,GAAG,OAAO,CAAC,OAAO,CAAC,CAO3E"}