@manyoars/oars 0.2.0 → 0.4.0

package/dist/sessions/cell-increments.js

@@ -0,0 +1,243 @@
+// The cell computation a deposit and a local read share (pool vocabulary spec Section 2, "the deposit form", and Section 4, rules 1 to 6). The pool's ingest turns a batch's skeleton into
+// increments with `incrementsOf`, and a local read derives its cells with `cellsOf` over the store it holds, projected the way a deposit projects it (`projectedStore`). Both end in the
+// one `cellsOf`, so a session gives the same cells at the pool and on the machine. This file reads no file system: the pool's Worker bundles it.
+import { ARG_CLASSES } from './call-shape.js';
+import { bucketFields, deriveCells, ENVIRONMENT_BUCKET, isEnvironmentCell } from './cells.js';
+import { bucketOf, floorOf, OTHER, projectedSteps } from './pool-wire.js';
+import { NO_RECALLS } from './recall-consequence.js';
+import { USAGE_FIELDS, harnessOf } from './schema.js';
+const floorTokens = (value) => floorOf('tokens', bucketOf('tokens', value));
+const floorUsage = ({ input, cacheWrite, cacheRead, output, thinking }) => ({
+    input: floorTokens(input),
+    cacheWrite: floorTokens(cacheWrite),
+    cacheRead: floorTokens(cacheRead),
+    output: floorTokens(output),
+    thinking: floorTokens(thinking),
+});
+const floorPrompt = (prompt) => ({
+    ...prompt,
+    errors: floorOf('count', bucketOf('count', prompt.errors)),
+    wallSec: prompt.wallSec === null ? null : floorOf('seconds', bucketOf('seconds', prompt.wallSec)),
+    usage: floorUsage(prompt.usage),
+});
+const floorTool = (tool) => ({
+    ...tool,
+    durationMs: tool.durationMs === null ? null : floorOf('ms', bucketOf('ms', tool.durationMs)),
+    steps: tool.steps?.map((step) => ({
+        ...step,
+        cost: { tokens: step.cost.tokens === null ? null : floorTokens(step.cost.tokens), durationMs: step.cost.durationMs === null ? null : floorOf('ms', bucketOf('ms', step.cost.durationMs)) },
+    })),
+});
+const flooredStore = (store) => ({ ...store, prompts: store.prompts.map(floorPrompt), tools: store.tools.map(floorTool) });
+/** A step's shell identity without the two lists it carries: a named motif keys on the program and its subcommand, and each flag and each pull is a cell of its own (rule 1). */
+const withoutLists = (step) => (step.identity !== null && 'program' in step.identity ? { ...step, identity: { program: step.identity.program, sub: step.identity.sub, flags: [] } } : step);
+/** One step per flag and one per pull of each shell step, each holding that one name and nothing else (rule 2: no cell has two set-valued dimensions). */
+const marginalSteps = (step) => {
+    if (step.identity === null || !('program' in step.identity))
+        return [];
+    const { program, sub, flags, pulls } = step.identity;
+    return [...flags.map((flag) => ({ ...step, identity: { program, sub, flags: [flag] } })), ...(pulls ?? []).map((pull) => ({ ...step, identity: { program, sub, flags: [], pulls: [pull] } }))];
+};
+/** The tools of a store as one-step calls, one per flag and per pull: read at window length 1, each is one marginal cell. */
+const marginalStore = (store) => ({ ...store, tools: store.tools.flatMap((tool) => (tool.steps ?? []).flatMap(marginalSteps).map((marginal) => ({ ...tool, steps: [marginal] }))) });
+/**
+ * Rule 5: exact tokens and durations never reach `index`. A cell counts a bucketed value as the bucket's lowest value, so a derivation reads only what a deposit carries, and a
+ * summed window is a sum of those. A value already at a bucket's floor stays there, which is why a skeleton's store and a local store of the same session derive the same cells.
+ * Rules 1 and 2: a window names a shell step by its program and subcommand alone, and each flag and each pull of it adds a one-step cell of its own.
+ */
+export const cellsOf = (store, graph = NO_RECALLS) => {
+    const floored = flooredStore(store);
+    const whole = deriveCells({ ...floored, tools: floored.tools.map((tool) => (tool.steps === undefined ? tool : { ...tool, steps: tool.steps.map(withoutLists) })) }, graph);
+    // Only the one-step named motifs of the marginal pass that hold a shell identity (a recall step the graph places there has none, and `whole` already counts it): its prompts, its shape motifs, and its longer windows repeat or splice what `whole` holds.
+    const marginal = deriveCells(marginalStore(floored), graph);
+    const named = new Set(marginal.motifs.filter(({ level, steps }) => level === 'named' && steps.length === 1 && steps[0]?.identity !== null).map(({ motifId }) => motifId));
+    const motifs = new Map([...whole.motifs, ...marginal.motifs.filter(({ motifId }) => named.has(motifId))].map((motif) => [motif.motifId, motif]));
+    const order = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
+    const cells = [...whole.cells, ...marginal.cells.filter(({ motifId }) => named.has(motifId))].sort((a, b) => order(a.motifId, b.motifId) || order(a.frameBucket, b.frameBucket) || order(a.grain, b.grain) || order(a.day, b.day) || Number(a.exposed) - Number(b.exposed));
+    return { cells, motifs: [...motifs.values()].sort((a, b) => order(a.motifId, b.motifId)) };
+};
+/** A local store with each shell step read as a deposit reads it (`projectedSteps`), so its named motifs are the ones the pool holds. It uses the open gate, which keeps the name shape and length but applies no redactor or exclusion term: a local read sends nothing. */
+export const projectedStore = (store, read) => {
+    const harnesses = new Map([...store.sessions, ...store.subagents].map((session) => [session.session, harnessOf(session)]));
+    return { ...store, tools: store.tools.map((tool) => (tool.steps === undefined ? tool : { ...tool, steps: projectedSteps(tool, read, harnesses.get(tool.session) ?? 'claude-code') })) };
+};
+const NO_USAGE = { input: 0, cacheWrite: 0, cacheRead: 0, output: 0, thinking: 0 };
+const isKnown = (transcript) => transcript.harness !== OTHER;
+/** A frame whose own harness is `other` takes its transcript's: the two are the same harness, and a frame cannot name one the transcript does not. A repo size this reader does not know is a size the frame does not name. */
+const frameOf = (frame, harness) => ({
+    ...frame,
+    harness: frame.harness === OTHER ? harness : frame.harness,
+    stack: { ...frame.stack, size: frame.stack.size === OTHER ? null : frame.stack.size },
+});
+/** A class this reader does not know counts in `mixed`, the class a prompt that fits no other takes. */
+const classOf = (cls) => (cls === OTHER ? 'mixed' : cls);
+/** A status this reader does not know is a segment the call did not report. */
+const statusOf = (status) => (status === OTHER ? 'none' : status);
+/** A skeleton's transcript as the record `deriveCells` reads. Everything a skeleton leaves out stays empty, so no derivation here can come to depend on it unnoticed. */
+const sessionRecord = (id, parent, spawnedIn, { harness, frame }) => ({
+    kind: 'session',
+    cv: '',
+    sid: '',
+    session: id,
+    project: '',
+    parent,
+    agentType: null,
+    spawnedBy: null,
+    spawnedIn,
+    rev: 1,
+    at: '',
+    bytes: 0,
+    lines: 0,
+    badLines: 0,
+    userTurns: 0,
+    assistantTurns: 0,
+    tsFirst: null,
+    tsLast: null,
+    versions: [],
+    models: {},
+    branches: [],
+    tools: {},
+    files: [],
+    fileHashes: [],
+    // The store's salted key, so a read that groups by repo works on pooled data from one store (one machine). It joins no cell.
+    repo: frame.repoKey ?? null,
+    urls: [],
+    searches: [],
+    bashCmds: 0,
+    tldrs: [],
+    confidences: [],
+    compactSummaries: 0,
+    promptFingerprint: null,
+    env: { harness: frame.harnessVersion ?? '', oars: '', node: '', os: frame.platform },
+    costUsd: null,
+    usage: NO_USAGE,
+    harness,
+    frame: frameOf(frame, harness),
+});
+const promptRecords = (id, { harness, prompts }) => prompts.map(({ cls, errors, wallSec, usage, usageResponses, explore, frame }, index) => ({
+    kind: 'prompt',
+    v: '',
+    session: id,
+    rev: 1,
+    index,
+    ts: null,
+    wallSec: wallSec === null ? null : floorOf('seconds', wallSec),
+    head: '',
+    cls: classOf(cls),
+    tools: [],
+    shape: '',
+    errors: floorOf('count', errors),
+    thinking: 0,
+    sideTools: 0,
+    turns: 0,
+    model: frame.model ?? '',
+    efforts: frame.effort === null ? [] : [frame.effort],
+    skills: [],
+    // A category the wire sent as null was never recorded: it reads as a placeholder zero here and is left out of `usageObserved`.
+    usage: {
+        input: floorOf('tokens', usage.input ?? 0),
+        cacheWrite: floorOf('tokens', usage.cacheWrite ?? 0),
+        cacheRead: floorOf('tokens', usage.cacheRead ?? 0),
+        output: floorOf('tokens', usage.output ?? 0),
+        thinking: floorOf('tokens', usage.thinking ?? 0),
+    },
+    usageObserved: USAGE_FIELDS.filter((field) => usage[field] !== null),
+    ...(usageResponses === undefined ? {} : { usageResponses: floorOf('count', usageResponses) }),
+    recovery: [],
+    // The lowest value of the bucket, as every other bucketed value counts; a prompt that sent none counts none.
+    explore: explore === null ? 0 : floorOf('calls', explore),
+    act: 0,
+    bigrams: {},
+    contextFingerprint: null,
+    frame: frameOf(frame, harness),
+}));
+/** A step's place as the store names it: its call's position and its segment. A transcript's steps are numbered across its calls in order, which is what an edge's target counts. */
+const stepPlaces = ({ tools }) => tools.flatMap(({ steps }, n) => steps.map((_, seg) => ({ n, seg })));
+const toolRecords = (id, main, transcript, spawner) => {
+    const own = stepPlaces(transcript);
+    const spawning = spawner === null ? [] : stepPlaces(spawner);
+    return transcript.tools.map(({ side, prompt, status, durationMs, errorCode, keys, targetClass, argClass, steps }, n) => ({
+        kind: 'tool',
+        cv: '',
+        sid: '',
+        session: id,
+        rev: 1,
+        parent: main,
+        agentType: null,
+        n,
+        ts: null,
+        tool: steps[0]?.native ?? '',
+        status: statusOf(status),
+        target: null,
+        targetBase: null,
+        // The names the wire carried, which are the only ones a skeleton-derived store ever holds; `keysDropped` is a count of names not sent and has no stored form.
+        keys: keys ?? [],
+        ...(targetClass === undefined ? {} : { targetClass }),
+        ...(argClass === undefined ? {} : { argClass: ARG_CLASSES.filter((kind) => argClass.includes(kind)).sort() }),
+        durationMs,
+        toolUseId: '',
+        harnessVersion: null,
+        side,
+        prompt,
+        ...(errorCode === null ? {} : { errorCode }),
+        steps: steps.map(({ action, native, identity, status: reported, parent, tokens, ms, edges }, seg) => ({
+            action,
+            native,
+            identity,
+            status: statusOf(reported),
+            parent,
+            seg,
+            // A target is read back as the call position and segment it names, in this transcript or, for a `spawned` edge, in the spawning one. A target the transcript does not hold names nothing and is left out, and so does a kind this reader does not know (`other`).
+            edges: (edges ?? []).flatMap(({ kind, target }) => {
+                const place = (kind === 'spawned' ? spawning : own)[target];
+                return place === undefined || kind === OTHER ? [] : [{ kind, n: place.n, seg: place.seg }];
+            }),
+            cost: { tokens: tokens === null ? null : floorOf('tokens', tokens), durationMs: ms === null ? null : floorOf('ms', ms) },
+            n,
+            frameId: '',
+        })),
+    }));
+};
+/** One account's deposits as a store. A session's id is its skeleton's, which the client hashes per account, so it joins nothing across accounts. */
+export const storeOf = (skeletons) => {
+    const store = { sessions: [], prompts: [], errors: [], subagents: [], tools: [], newerCaptures: 0 };
+    for (const { id, transcripts } of skeletons) {
+        const nameOf = (index) => `${id}#${String(index)}`;
+        const main = nameOf(0);
+        transcripts.forEach((transcript, index) => {
+            if (!isKnown(transcript))
+                return;
+            const session = nameOf(index);
+            const spawner = transcript.spawnedIn === null ? null : (transcripts[transcript.spawnedIn] ?? null);
+            (index === 0 ? store.sessions : store.subagents).push(sessionRecord(session, index === 0 ? null : main, transcript.spawnedIn === null ? null : nameOf(transcript.spawnedIn), transcript));
+            store.prompts.push(...promptRecords(session, transcript));
+            store.tools.push(...toolRecords(session, main, transcript, spawner));
+        });
+    }
+    return store;
+};
+/** Whole cells and strata, summed over a batch's own sessions: the same cells a store of that batch alone derives. */
+export const incrementsOf = (skeleton) => {
+    const derived = cellsOf(storeOf([skeleton]));
+    const cells = new Map();
+    for (const cell of derived.cells) {
+        const exposed = cell.exposed ? 1 : 0;
+        const key = `${cell.motifId}/${cell.frameBucket}/${cell.grain}/${cell.day}/${String(exposed)}`;
+        // The served column is a running sum, so a cell no session of this batch recorded tokens for adds nothing to it; the sum itself holds only what was observed, and `tokenSessions` and `tokenPrompts` say how much of the cell it covers.
+        cells.set(key, { key, harnessBucket: isEnvironmentCell(cell) ? ENVIRONMENT_BUCKET : bucketFields(cell.frameBucket).harnessBucket, motifId: cell.motifId, frameBucket: cell.frameBucket, grain: cell.grain, day: cell.day, exposed, sessions: cell.sessions, ok: cell.ok, failed: cell.failed, tokens: cell.tokens ?? 0, tokenSessions: cell.tokenSessions ?? 0, tokenPrompts: cell.tokenPrompts ?? 0, durationMs: cell.durationMs });
+    }
+    // A session counts once per value, so each value is one session of this batch.
+    const strata = new Map();
+    const frames = skeleton.transcripts.flatMap(({ frame, prompts }) => [frame, ...prompts.map((prompt) => prompt.frame)]);
+    const named = [
+        ...frames.flatMap(({ stack }) => stack.languages.map((value) => ['language', value])),
+        ...frames.flatMap(({ stack }) => stack.frameworks.map((value) => ['framework', value])),
+        ...frames.flatMap(({ stack }) => (stack.size === null ? [] : [['repoFiles', stack.size]])),
+        // The two pairs (rule 3): each is a stratum of its own, never a cell and never keyed by the stack's other values. A language with no share, and a prompt with no count, make none.
+        ...frames.flatMap(({ stack }) => stack.languageShares.map(({ language, languageShare }) => ['languageShare', `${language}/${languageShare}`])),
+        ...skeleton.transcripts.flatMap(({ prompts }) => prompts.flatMap(({ explore, frame }) => (explore === null || frame.stack.size === null ? [] : [['repoFilesExplore', `${frame.stack.size}/${String(explore)}`]]))),
+    ];
+    for (const [dimension, value] of named)
+        strata.set(`${dimension}/${value}`, { key: `${dimension}/${value}`, dimension, value, sessions: 1 });
+    return { cells, motifs: derived.motifs, strata };
+};

package/dist/sessions/cells.d.ts

@@ -0,0 +1,109 @@
+import { type Motif } from './motif.js';
+import { type RecallGraph } from './recall-consequence.js';
+import { type ErrorObservation, type Frame } from './schema.js';
+import type { Store } from './store.js';
+/** Rule 6: an `index` cell is weekly, except a live cell, which stays at the UTC day. */
+export type Grain = 'day' | 'week';
+export interface Cell {
+    motifId: string;
+    /** `harness/versionBucket/model`, public names (`frameBucketOf`), or `env:<platform>:<shell>` for a (name, `platform`, `shell`) cell, which names no harness, version, or model (`ENVIRONMENT_BUCKET`). Effort is not in it (rule 3). */
+    frameBucket: string;
+    /** What `day` names: a UTC day, or a UTC week. A read takes the grain it answers from and never the other. */
+    grain: Grain;
+    /** The UTC day of the step's frame for a day cell, the Monday of its UTC week for a week cell, or `unknown`. */
+    day: string;
+    /** Distinct main sessions: a subagent's steps count under the session that spawned it. */
+    sessions: number;
+    /** Distinct accounts. One store is one operator, so 1 here (spec Section 6: one operator stays labeled). */
+    clusters: number;
+    /** Windows whose last step came back clean; a `class` cell: prompts with no error. */
+    ok: number;
+    /** Windows whose last step failed; a `class` cell: prompts with an error. A step with no result is in neither. */
+    failed: number;
+    /**
+     * Summed over each window's steps; a `class` cell: the whole usage of the prompts that recorded input, counting only the categories each recorded (a placeholder zero beside
+     * `usageObserved` is not a measurement). Null when no session recorded any: absent, never a measured 0.
+     */
+    tokens: number | null;
+    /** How many of `sessions` recorded the cost `tokens` sums (a class cell: input; a step cell: a step cost), which is the coverage the `tokens` figure has (a session that recorded input but not every category still counts as covered, so the figure can be partial by category); less than `sessions` makes it a partial sum. Absent on a cell read back from a stored sum written before the pool held coverage. */
+    tokenSessions?: number;
+    /** How many of the cell's prompts the `tokens` figure covers (a step cell counts steps): the divisor of a per-prompt mean, since `tokens` holds only prompts that recorded input. Absent like `tokenSessions`. */
+    tokenPrompts?: number;
+    durationMs: number;
+    /** Whether these counts sit inside a shown recall's consequence window, wholly or in part. It is part of the cell's key, so a motif's exposed and unexposed counts stay apart. */
+    exposed: boolean;
+}
+export declare const UNKNOWN = "unknown";
+/** The class name an effort cell carries: a class motif with no prompt class in it, so a read of prompt classes skips it by this prefix. */
+export declare const EFFORT_CLASS = "effort:";
+/**
+ * Rule 3: effort is not in a cell's key. The one cell that holds it pairs it with the bucket of the prompt's thinking tokens, which is the fact an effort level explains, and it
+ * carries `week` and `exposure` but no frame axis: rule 3 bars joining `effort` to `model` or `harnessVersion`, and the pair would be four dimensions over `q_dims`.
+ */
+export declare const effortClass: (effort: string, thinking: number) => string;
+/**
+ * The two day-cell families of a failed call by its `errorCode` (t868): `error:<code>/<name>` keeps the model and no version beside the code, and `error-version:<code>/<name>` keeps the harness version bucket and no model
+ * (`versionBucketOf`). Each joins three dimensions: name, code, and either model or version. A class motif with no prompt class in it, so a read of prompt classes skips both by prefix (`isPromptClass`).
+ */
+export declare const ERROR_CLASS = "error:";
+export declare const ERROR_VERSION_CLASS = "error-version:";
+/**
+ * The week cell of what followed a failed call (t868): `recovery:<code>/<failed action>><next action>`, where the next action is that of the call right after it in the same prompt, or `none` when nothing
+ * followed. It keeps the harness version bucket and no model, so it joins three dimensions: the failed-to-next edge, code, and version. A class motif with no prompt class in it, like the others.
+ */
+export declare const RECOVERY_CLASS = "recovery:";
+export declare const NO_NEXT = "none";
+export declare const recoveryClass: (code: string, failed: string, next: string) => string;
+/** The three parts of a recovery class name, or null for a name that is not one. An action name holds no `>` or `/`, and a code holds no `/`. */
+export declare const parseRecoveryClass: (cls: string) => {
+    code: string;
+    failed: string;
+    next: string;
+} | null;
+/** Whether a class motif names a prompt class, as opposed to one of the side cells (effort, or a failed call's code or what followed it). */
+export declare const isPromptClass: (cls: string | null) => boolean;
+/** The frame bucket of a cell that joins no axis. */
+export declare const NO_AXES = "-";
+/**
+ * A harness version's bucket: its patch by tens. 70.5 percent of one operator's later prompts ran a version not yet seen, so an
+ * exact-version cell goes stale in days; a reader compares buckets by distance instead. A version with no patch stands for itself.
+ */
+export declare const harnessBucket: (version: string | null) => string;
+/** Only what most comparisons cross: platform, shell, and stack are on the frame and in the records, so a later extractor can add them without new capture. */
+export declare const frameBucketOf: (frame: Frame) => string;
+/** The frame bucket of a cell that keeps the version and drops the model: `harness/versionBucket/-`. */
+export declare const versionBucketOf: (frame: Frame) => string;
+export declare const bucketFields: (bucket: string) => {
+    harness: string;
+    harnessBucket: string;
+    model: string;
+};
+/** The frame bucket of a (name, `platform`, `shell`) cell: fit's third pool form. Rule 3 lets the two join each other and a name within `q_dims`, but not a version or a model beside them, so the cell is version-free and model-free. */
+export declare const ENVIRONMENT_BUCKET = "env:";
+export declare const environmentBucketOf: (frame: Frame) => string;
+export declare const isEnvironmentCell: (cell: Pick<Cell, "frameBucket">) => boolean;
+export declare const environmentFieldsOf: (bucket: string) => {
+    platform: string;
+    shell: string;
+};
+/** The Monday of the UTC week a UTC day falls in, as a day: the week's name in a cell. An unknown day is an unknown week. */
+export declare const weekStartOf: (day: string) => string;
+/** The last UTC day a cell can hold: its day, or the Sunday that closes its week. A check that evidence predates a day reads this, since a week's cell may hold any of its seven days. */
+export declare const lastDayOfCell: (cell: Cell) => string;
+/** `cell:<contentHash>`: a cell that counts differently is a different cell, so a read's inputs pin what it read. */
+export declare const cellIdOf: (cell: Cell) => string;
+export interface CellSet {
+    cells: Cell[];
+    motifs: Motif[];
+}
+export declare const deriveCells: (store: Store, graph?: RecallGraph) => CellSet;
+export declare const serializeCells: (cells: readonly Cell[]) => string;
+/** What every read of one derive pass reads, and the snapshot it answers from. */
+export interface Pool {
+    cells: readonly Cell[];
+    motifs: ReadonlyMap<string, Motif>;
+    /** The hash of the extractor version, the family methods, every cell, and the error rows recovery reads: new data or a new rule is a new pool, and every read of it a new read. */
+    version: string;
+    lastDay: string | null;
+}
+export declare const poolOf: (set: CellSet, errors: readonly ErrorObservation[]) => Pool;

package/dist/sessions/cells.js

@@ -0,0 +1,261 @@
+// The cell (recall spec Section 2.5): counts for one motif in one frame bucket in one UTC week (or, for a live cell, one UTC day), order 0. Cells are computed from the capture records, which
+// stay the primary record, so a cell file can be dropped and rebuilt and any later derivation can run over old data. Nothing here reads raw.
+import { closedFrame, utcDay } from './frame.js';
+import { classMotif, motifName, motifsOf, stepsOfCall } from './motif.js';
+import { bucketOf } from './pool-wire.js';
+import { CALL_SHAPE_METHOD, cellRef, contentHash, METHODS, RECOVERY_EDGE_METHOD } from './read.js';
+import { recoveryCallsOf } from './recovery-calls.js';
+import { NO_RECALLS } from './recall-consequence.js';
+import { ERROR_CODES, EXTRACTOR_VERSION, harnessOf, observesUsage } from './schema.js';
+export const UNKNOWN = 'unknown';
+/** The class name an effort cell carries: a class motif with no prompt class in it, so a read of prompt classes skips it by this prefix. */
+export const EFFORT_CLASS = 'effort:';
+/**
+ * Rule 3: effort is not in a cell's key. The one cell that holds it pairs it with the bucket of the prompt's thinking tokens, which is the fact an effort level explains, and it
+ * carries `week` and `exposure` but no frame axis: rule 3 bars joining `effort` to `model` or `harnessVersion`, and the pair would be four dimensions over `q_dims`.
+ */
+export const effortClass = (effort, thinking) => `${EFFORT_CLASS}${effort}/thinking:${String(bucketOf('tokens', thinking))}`;
+/**
+ * The two day-cell families of a failed call by its `errorCode` (t868): `error:<code>/<name>` keeps the model and no version beside the code, and `error-version:<code>/<name>` keeps the harness version bucket and no model
+ * (`versionBucketOf`). Each joins three dimensions: name, code, and either model or version. A class motif with no prompt class in it, so a read of prompt classes skips both by prefix (`isPromptClass`).
+ */
+export const ERROR_CLASS = 'error:';
+export const ERROR_VERSION_CLASS = 'error-version:';
+/**
+ * The week cell of what followed a failed call (t868): `recovery:<code>/<failed action>><next action>`, where the next action is that of the call right after it in the same prompt, or `none` when nothing
+ * followed. It keeps the harness version bucket and no model, so it joins three dimensions: the failed-to-next edge, code, and version. A class motif with no prompt class in it, like the others.
+ */
+export const RECOVERY_CLASS = 'recovery:';
+export const NO_NEXT = 'none';
+export const recoveryClass = (code, failed, next) => `${RECOVERY_CLASS}${code}/${failed}>${next}`;
+/** The three parts of a recovery class name, or null for a name that is not one. An action name holds no `>` or `/`, and a code holds no `/`. */
+export const parseRecoveryClass = (cls) => {
+    const found = /^recovery:([^/]+)\/([^>/]+)>([^>/]+)$/.exec(cls);
+    return found === null ? null : { code: found[1] ?? '', failed: found[2] ?? '', next: found[3] ?? '' };
+};
+/** Whether a class motif names a prompt class, as opposed to one of the side cells (effort, or a failed call's code or what followed it). */
+export const isPromptClass = (cls) => cls !== null && ![EFFORT_CLASS, ERROR_CLASS, ERROR_VERSION_CLASS, RECOVERY_CLASS].some((prefix) => cls.startsWith(prefix));
+/** The frame bucket of a cell that joins no axis. */
+export const NO_AXES = '-';
+const ONE_OPERATOR = 1;
+/**
+ * A harness version's bucket: its patch by tens. 70.5 percent of one operator's later prompts ran a version not yet seen, so an
+ * exact-version cell goes stale in days; a reader compares buckets by distance instead. A version with no patch stands for itself.
+ */
+export const harnessBucket = (version) => {
+    if (version === null)
+        return UNKNOWN;
+    const found = /^(\d+\.\d+)\.(\d+)/.exec(version);
+    return found === null ? version : `${found[1] ?? ''}.${String(Math.floor(Number(found[2]) / 10))}x`;
+};
+/** Only what most comparisons cross: platform, shell, and stack are on the frame and in the records, so a later extractor can add them without new capture. */
+export const frameBucketOf = (frame) => [frame.harness, harnessBucket(frame.harnessVersion), frame.model ?? UNKNOWN].join('/');
+/** The frame bucket of a cell that keeps the version and drops the model: `harness/versionBucket/-`. */
+export const versionBucketOf = (frame) => [frame.harness, harnessBucket(frame.harnessVersion), NO_AXES].join('/');
+export const bucketFields = (bucket) => {
+    const [harness = UNKNOWN, version = UNKNOWN, model = UNKNOWN] = bucket.split('/');
+    return { harness, harnessBucket: version, model };
+};
+/** The frame bucket of a (name, `platform`, `shell`) cell: fit's third pool form. Rule 3 lets the two join each other and a name within `q_dims`, but not a version or a model beside them, so the cell is version-free and model-free. */
+export const ENVIRONMENT_BUCKET = 'env:';
+export const environmentBucketOf = (frame) => `${ENVIRONMENT_BUCKET}${frame.platform}:${frame.shell ?? UNKNOWN}`;
+export const isEnvironmentCell = (cell) => cell.frameBucket.startsWith(ENVIRONMENT_BUCKET);
+export const environmentFieldsOf = (bucket) => {
+    const held = bucket.slice(ENVIRONMENT_BUCKET.length);
+    const at = held.indexOf(':');
+    return { platform: held.slice(0, at), shell: held.slice(at + 1) };
+};
+/** A one-step named call with no flag and no pull: the name that is one dimension. A call with no identity (a file read, an edit) is its action alone, so it counts. A flag or a pull is a second dimension of its own, so its cell would be four with the pair. */
+const isPlainCall = (motif) => {
+    const [only] = motif.steps;
+    if (motif.level !== 'named' || motif.steps.length !== 1 || only === undefined)
+        return false;
+    return only.identity === null || !('program' in only.identity) || (only.identity.flags.length === 0 && (only.identity.pulls?.length ?? 0) === 0);
+};
+const DAY_MS = 86_400_000;
+/** The Monday of the UTC week a UTC day falls in, as a day: the week's name in a cell. An unknown day is an unknown week. */
+export const weekStartOf = (day) => {
+    if (day === UNKNOWN)
+        return UNKNOWN;
+    const millis = Date.parse(day);
+    return new Date(millis - ((new Date(millis).getUTCDay() + 6) % 7) * DAY_MS).toISOString().slice(0, 10);
+};
+/** The last UTC day a cell can hold: its day, or the Sunday that closes its week. A check that evidence predates a day reads this, since a week's cell may hold any of its seven days. */
+export const lastDayOfCell = (cell) => (cell.grain === 'week' && cell.day !== UNKNOWN ? new Date(Date.parse(cell.day) + 6 * DAY_MS).toISOString().slice(0, 10) : cell.day);
+const cellIds = new WeakMap();
+/** `cell:<contentHash>`: a cell that counts differently is a different cell, so a read's inputs pin what it read. */
+export const cellIdOf = (cell) => {
+    const known = cellIds.get(cell);
+    if (known !== undefined)
+        return known;
+    const id = cellRef(contentHash(cell));
+    cellIds.set(cell, id);
+    return id;
+};
+/** The usage categories a prompt's tokens add up: thinking is part of the output already billed, so it is not summed. */
+const TOKEN_FIELDS = ['input', 'cacheWrite', 'cacheRead', 'output'];
+const newTally = (motifId, frameBucket, grain, day, exposed) => ({ motifId, frameBucket, grain, day, sessions: new Set(), ok: 0, failed: 0, tokens: 0, recorded: new Set(), recordedUnits: 0, durationMs: 0, exposed });
+const compare = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
+/** A frame for a record captured before frames existed, from the fields it does hold, held to the same public vocabulary. */
+const oldFrame = (parts) => closedFrame({
+    harness: parts.harness,
+    harnessVersion: parts.version,
+    model: parts.model === '' ? null : parts.model,
+    effort: parts.effort,
+    day: utcDay(parts.ts),
+    platform: parts.platform,
+    shell: null,
+    stack: { languages: [], frameworks: [], size: null },
+});
+const mostUsedModel = (models) => [...Object.entries(models)].sort(([a, one], [b, two]) => two - one || compare(a, b))[0]?.[0] ?? null;
+const framedPrompt = (prompt, harness, version, ts, platform) => prompt.frame ?? oldFrame({ harness, version, model: prompt.model, effort: prompt.efforts[0] ?? null, ts: prompt.ts ?? ts, platform });
+/** One line of work (spec Section 2.3): a window never crosses a prompt, a sidechain, or a transcript. */
+const linesOf = (tools) => {
+    const lines = new Map();
+    for (const tool of tools) {
+        const key = `${tool.session}\n${String(tool.side)}\n${String(tool.prompt)}`;
+        const line = lines.get(key);
+        if (line === undefined)
+            lines.set(key, [tool]);
+        else
+            line.push(tool);
+    }
+    return [...lines.values()].map((line) => line.sort((a, b) => a.n - b.n));
+};
+export const deriveCells = (store, graph = NO_RECALLS) => {
+    const tallies = new Map();
+    const motifs = new Map();
+    const tallyAt = (motif, frameBucket, grain, day, exposed) => {
+        const key = `${motif.motifId}/${frameBucket}/${grain}/${day}/${String(exposed)}`;
+        const found = tallies.get(key);
+        if (found !== undefined)
+            return found;
+        const fresh = newTally(motif.motifId, frameBucket, grain, day, exposed);
+        tallies.set(key, fresh);
+        return fresh;
+    };
+    /** The tallies one occurrence counts into: its week cell, and for a one-step shape motif with a known day its live cell too (rule 6). A window of two or more steps, a named motif, and a class motif have no day cell. */
+    const talliesOf = (motif, frame, exposed, frameBucket = frameBucketOf(frame)) => {
+        motifs.set(motif.motifId, motif);
+        const day = frame.day ?? UNKNOWN;
+        const weekly = tallyAt(motif, frameBucket, 'week', weekStartOf(day), exposed);
+        const tallies = motif.level === 'shape' && motif.steps.length === 1 && day !== UNKNOWN ? [weekly, tallyAt(motif, frameBucket, 'day', day, exposed)] : [weekly];
+        // Fit's (name, platform, shell) cell: a week cell beside the versioned one, counting the same call.
+        return isPlainCall(motif) ? [...tallies, tallyAt(motif, environmentBucketOf(frame), 'week', weekStartOf(day), exposed)] : tallies;
+    };
+    const sessions = new Map([...store.sessions, ...store.subagents].map((session) => [session.session, session]));
+    const prompts = new Map(store.prompts.map((prompt) => [`${prompt.session}#${String(prompt.index)}`, prompt]));
+    for (const line of linesOf(store.tools)) {
+        const [first] = line;
+        const session = first === undefined ? undefined : sessions.get(first.session);
+        if (first === undefined || session === undefined)
+            continue;
+        const harness = harnessOf(session);
+        const version = first.harnessVersion ?? session.env.harness;
+        const prompt = prompts.get(`${first.session}#${String(first.prompt)}`);
+        const frame = prompt === undefined
+            ? (session.frame ?? oldFrame({ harness, version, model: mostUsedModel(session.models), effort: null, ts: first.ts ?? session.tsFirst, platform: session.env.os }))
+            : framedPrompt(prompt, harness, version, first.ts, session.env.os);
+        const placed = line.flatMap((tool) => graph.place(tool, stepsOfCall(tool, harness)));
+        const steps = placed.map(({ step }) => step);
+        for (const { motif, start } of motifsOf(steps)) {
+            const window = steps.slice(start, start + motif.steps.length);
+            const status = window.at(-1)?.status;
+            for (const tally of talliesOf(motif, frame, placed.slice(start, start + motif.steps.length).some(({ exposed }) => exposed))) {
+                tally.sessions.add(first.parent);
+                if (status === 'ok')
+                    tally.ok += 1;
+                if (status === 'error')
+                    tally.failed += 1;
+                for (const step of window) {
+                    // A step with no recorded cost has no tokens to count, so it joins neither the sum nor the coverage (its duration is still counted).
+                    if (step.tokens !== null) {
+                        tally.tokens += step.tokens;
+                        tally.recorded.add(first.parent);
+                        tally.recordedUnits += 1;
+                    }
+                    tally.durationMs += step.durationMs;
+                }
+            }
+        }
+        // What followed each failed call that has a code (t868): a week cell per (code, failed action, next action).
+        // A call is read by its first step's action, as a skeleton's is; a record captured before steps has the action its native name maps to.
+        const calls = line.map((call) => ({ side: call.side, prompt: call.prompt, status: call.status, steps: stepsOfCall(call, harness) }));
+        for (const [at, tool] of line.entries()) {
+            const followed = recoveryCallsOf(calls, at);
+            if (followed === null || tool.errorCode === undefined)
+                continue;
+            const code = ERROR_CODES.has(tool.errorCode) ? tool.errorCode : 'other';
+            const motif = classMotif(recoveryClass(code, calls[at]?.steps[0]?.action ?? 'other', followed.next[0] ?? NO_NEXT));
+            motifs.set(motif.motifId, motif);
+            const tally = tallyAt(motif, versionBucketOf(frame), 'week', weekStartOf(frame.day ?? UNKNOWN), false);
+            tally.sessions.add(first.parent);
+            tally.failed += 1;
+        }
+        // The failed calls by their `errorCode` (t868). Rule 6: a day cell exists for a known day only.
+        const failedDay = frame.day ?? UNKNOWN;
+        for (const tool of failedDay === UNKNOWN ? [] : line) {
+            if (tool.status !== 'error' || tool.errorCode === undefined)
+                continue;
+            const code = ERROR_CODES.has(tool.errorCode) ? tool.errorCode : 'other';
+            for (const counted of stepsOfCall(tool, harness)) {
+                if (counted.status !== 'error')
+                    continue;
+                // The call's name at both levels: its action alone, and a named call (a flag or a pull would be a second dimension, so those steps are named by program and subcommand alone upstream).
+                for (const { motif: named } of motifsOf([counted])) {
+                    if (named.level === 'named' && counted.identity === null)
+                        continue;
+                    const name = motifName(named);
+                    for (const [prefix, bucket] of [[ERROR_CLASS, `${frame.harness}/${NO_AXES}/${frame.model ?? UNKNOWN}`], [ERROR_VERSION_CLASS, versionBucketOf(frame)]]) {
+                        const motif = classMotif(`${prefix}${code}/${name}`);
+                        motifs.set(motif.motifId, motif);
+                        const tally = tallyAt(motif, bucket, 'day', failedDay, false);
+                        tally.sessions.add(first.parent);
+                        tally.failed += 1;
+                        if (counted.tokens !== null) {
+                            tally.tokens += counted.tokens;
+                            tally.recorded.add(first.parent);
+                            tally.recordedUnits += 1;
+                        }
+                        tally.durationMs += counted.durationMs;
+                    }
+                }
+            }
+        }
+    }
+    for (const prompt of store.prompts) {
+        const session = sessions.get(prompt.session);
+        const frame = framedPrompt(prompt, harnessOf(session ?? {}), session?.env.harness ?? null, null, session?.env.os ?? UNKNOWN);
+        const exposed = graph.exposedPrompt(prompt.session, prompt.index);
+        const effort = frame.effort === null ? [] : talliesOf(classMotif(effortClass(frame.effort, prompt.usage.thinking)), frame, exposed, NO_AXES);
+        for (const tally of [...talliesOf(classMotif(prompt.cls), frame, exposed), ...effort]) {
+            tally.sessions.add(prompt.session);
+            if (prompt.errors > 0)
+                tally.failed += 1;
+            else
+                tally.ok += 1;
+            // A prompt that recorded no input has no whole usage to count, and a category it never recorded is a placeholder zero, so neither enters the sum.
+            if (observesUsage(prompt, 'input')) {
+                tally.recorded.add(prompt.session);
+                tally.recordedUnits += 1;
+                for (const field of TOKEN_FIELDS)
+                    if (observesUsage(prompt, field))
+                        tally.tokens += prompt.usage[field];
+            }
+            tally.durationMs += (prompt.wallSec ?? 0) * 1000;
+        }
+    }
+    const cells = [...tallies.values()]
+        .sort((a, b) => compare(a.motifId, b.motifId) || compare(a.frameBucket, b.frameBucket) || compare(a.grain, b.grain) || compare(a.day, b.day) || Number(a.exposed) - Number(b.exposed))
+        .map((tally) => ({ motifId: tally.motifId, frameBucket: tally.frameBucket, grain: tally.grain, day: tally.day, sessions: tally.sessions.size, clusters: ONE_OPERATOR, ok: tally.ok, failed: tally.failed, tokens: tally.recorded.size === 0 ? null : tally.tokens, tokenSessions: tally.recorded.size, tokenPrompts: tally.recordedUnits, durationMs: tally.durationMs, exposed: tally.exposed }));
+    return { cells, motifs: [...motifs.values()].sort((a, b) => compare(a.motifId, b.motifId)) };
+};
+export const serializeCells = (cells) => cells.map((cell) => `${JSON.stringify(cell)}\n`).join('');
+/** The fields of an error row a recovery read depends on, as text: only those, so a change elsewhere is not a new pool, and sorted, so record order is not one either. */
+const errorRowsRead = (errors) => errors.map(({ session, agent, toolUseId, prompt, tool, sig, ts, next, editFollowed }) => JSON.stringify([session, agent ?? null, toolUseId ?? null, prompt, tool, sig, ts, next, editFollowed])).sort();
+export const poolOf = (set, errors) => ({
+    cells: set.cells,
+    motifs: new Map(set.motifs.map((motif) => [motif.motifId, motif])),
+    version: contentHash([EXTRACTOR_VERSION, METHODS, CALL_SHAPE_METHOD, RECOVERY_EDGE_METHOD, set.cells.map(cellIdOf), errorRowsRead(errors)]),
+    lastDay: set.cells.reduce((last, cell) => (cell.day !== UNKNOWN && (last === null || cell.day > last) ? cell.day : last), null),
+});