@manyoars/oars 0.3.0 → 0.4.1

package/dist/sessions/call-shape.js

@@ -0,0 +1,85 @@
+/** Where a path target sits in the project, as a closed list. `none` is a call with no path target (a shell call, a search, a fetch). */
+export const TARGET_CLASSES = ['source', 'test', 'config', 'doc', 'lockfile', 'generated', 'data', 'none', 'other'];
+/** What an argument holds, as a closed list: a call's arguments are the sorted set of these. `none` is a call with no arguments. */
+export const ARG_CLASSES = ['path', 'url', 'pattern', 'command', 'number', 'flag', 'text', 'none'];
+const words = (list) => new Set(list.split(/\s+/).filter((word) => word !== ''));
+const LOCKFILES = words('package-lock.json npm-shrinkwrap.json yarn.lock pnpm-lock.yaml bun.lockb bun.lock cargo.lock poetry.lock pipfile.lock uv.lock gemfile.lock composer.lock go.sum gradle.lockfile packages.lock.json podfile.lock pubspec.lock mix.lock flake.lock');
+const GENERATED_DIRS = words('dist build out node_modules .next .nuxt .astro .svelte-kit coverage target __generated__ generated .turbo .cache __pycache__ vendor');
+const TEST_DIRS = words('test tests __tests__ spec specs e2e __mocks__ fixtures testdata cypress');
+const DOC_DIRS = words('docs doc documentation');
+const SOURCE_EXTENSIONS = words('ts tsx mts cts js jsx mjs cjs py pyi java kt kts go rs rb php cs c h cc cpp hpp swift scala sh bash zsh ps1 psm1 sql astro vue svelte css scss sass less html htm lua dart ex exs erl clj hs ml r jl pl zig groovy gradle');
+const DOC_EXTENSIONS = words('md mdx rst txt adoc org tex');
+const CONFIG_EXTENSIONS = words('json jsonc json5 yaml yml toml ini cfg conf properties env plist editorconfig xml');
+const DATA_EXTENSIONS = words('csv tsv ndjson jsonl parquet avro arrow db sqlite sqlite3 log xlsx xls dat bin pkl');
+const CONFIG_BASENAMES = words('dockerfile makefile justfile procfile gemfile rakefile pom.xml build.gradle settings.gradle .gitignore .gitattributes .npmrc .nvmrc .prettierrc .eslintrc .dockerignore .editorconfig');
+const DOC_BASENAMES = words('readme license licence changelog contributing notice authors codeowners');
+const TEST_NAME = /(?:^|[._-])(?:test|tests|spec)(?:[._-]|$)|(?:_test|_spec|Test|Tests|Spec)\.[a-z]+$/;
+const GENERATED_NAME = /\.(?:min\.(?:js|css)|d\.ts|map|generated\.[a-z]+|pb\.go|g\.dart)$/;
+/**
+ * The class of a path target, from the base that hashed it and the path's own suffix. A call with no path target (`base` null) is `none`; the order below is the order a path is asked,
+ * so a lockfile is never `config` and a `tests/data.json` is `test`. The mapping is pinned in `call-shape.test.ts`. `path` is the key the target is hashed on (relative to the repository or the cwd, never the absolute path), so the folders above a repository do not decide the class; it is read here and goes no further.
+ */
+export const targetClassOf = (path, base) => {
+    if (base === null || path === undefined || path === '')
+        return 'none';
+    const parts = path.replace(/\\/g, '/').split('/').filter((part) => part !== '' && part !== '.');
+    const name = parts.at(-1) ?? '';
+    const lower = name.toLowerCase();
+    const dirs = parts.slice(0, -1).map((part) => part.toLowerCase());
+    const dot = lower.lastIndexOf('.');
+    const extension = dot > 0 ? lower.slice(dot + 1) : lower.startsWith('.') ? lower.slice(1) : '';
+    if (LOCKFILES.has(lower))
+        return 'lockfile';
+    if (dirs.some((dir) => GENERATED_DIRS.has(dir)) || GENERATED_NAME.test(lower))
+        return 'generated';
+    if (dirs.some((dir) => TEST_DIRS.has(dir)) || TEST_NAME.test(name))
+        return 'test';
+    const stem = dot > 0 ? lower.slice(0, dot) : lower;
+    if (DOC_EXTENSIONS.has(extension) || DOC_BASENAMES.has(stem) || dirs.some((dir) => DOC_DIRS.has(dir)))
+        return 'doc';
+    if (CONFIG_BASENAMES.has(lower) || /^\.[a-z0-9_.-]*(?:rc|ignore)(?:\.[a-z]+)?$/.test(lower) || /\.config\.[a-z]+$/.test(lower) || /^tsconfig[a-z0-9.-]*\.json$/.test(lower) || /^\.env(?:\.|$)/.test(lower))
+        return 'config';
+    if (SOURCE_EXTENSIONS.has(extension))
+        return 'source';
+    if (DATA_EXTENSIONS.has(extension))
+        return 'data';
+    if (CONFIG_EXTENSIONS.has(extension))
+        return 'config';
+    return 'other';
+};
+const PATH_ARGS = words('file_path notebook_path path cwd workdir directory dir filepath filename file');
+const URL_ARGS = words('url uri href');
+const PATTERN_ARGS = words('pattern regex regexp glob include exclude');
+const COMMAND_ARGS = words('command cmd script');
+const URL_VALUE = /^[a-z][a-z0-9+.-]*:\/\/\S+$/i;
+const argClassOfEntry = (key, value) => {
+    if (value === null || value === undefined)
+        return null;
+    if (typeof value === 'number')
+        return 'number';
+    if (typeof value === 'boolean')
+        return 'flag';
+    const lower = key.toLowerCase();
+    if (PATH_ARGS.has(lower))
+        return 'path';
+    if (URL_ARGS.has(lower) || (typeof value === 'string' && URL_VALUE.test(value)))
+        return 'url';
+    if (PATTERN_ARGS.has(lower))
+        return 'pattern';
+    if (COMMAND_ARGS.has(lower))
+        return 'command';
+    return 'text';
+};
+/**
+ * The classes of a call's arguments, as a sorted set: which of path, URL, pattern, command, number, flag, and text its input holds, or just `none` when it holds no value. A key name
+ * gives the class of a string (`file_path` is a path, `pattern` a pattern, `command` a command), a number or a boolean gives its own, and any other value is text. The values are read here and go no further.
+ */
+export const argClassOf = (input) => {
+    const held = new Set();
+    for (const [key, value] of Object.entries(input)) {
+        const kind = argClassOfEntry(key, value);
+        if (kind !== null)
+            held.add(kind);
+    }
+    return held.size === 0 ? ['none'] : ARG_CLASSES.filter((kind) => held.has(kind)).sort();
+};

package/dist/sessions/cell-increments.d.ts

@@ -15,6 +15,10 @@ export interface CellRow {
     ok: number;
     failed: number;
     tokens: number;
+    /** How many of the batch's sessions recorded input, the coverage of `tokens`; the served column sums it. */
+    tokenSessions: number;
+    /** How many of the batch's prompts (or steps) `tokens` covers: the divisor of a per-prompt mean. */
+    tokenPrompts: number;
     durationMs: number;
 }
 export interface StratumRow {
@@ -35,7 +39,7 @@ export interface Increments {
  * 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 declare const cellsOf: (store: Store, graph?: RecallGraph) => CellSet;
-/** A local store with each shell step read as a deposit reads it (`projectedSteps`), so its named motifs are the ones the pool holds. */
+/** 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 declare const projectedStore: (store: Store, read: ShellReader) => Store;
 /** 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 declare const storeOf: (skeletons: readonly SessionSkeleton[]) => Store;

package/dist/sessions/cell-increments.js

@@ -1,10 +1,11 @@
 // 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, projectedSteps } from './pool-wire.js';
+import { bucketOf, floorOf, OTHER, projectedSteps } from './pool-wire.js';
 import { NO_RECALLS } from './recall-consequence.js';
-import { harnessOf } from './schema.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),
@@ -55,14 +56,25 @@ export const cellsOf = (store, graph = NO_RECALLS) => {
     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. */
+/** 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, { harness, frame }) => ({
+const sessionRecord = (id, parent, spawnedIn, { harness, frame }) => ({
     kind: 'session',
     cv: '',
     sid: '',
@@ -71,7 +83,7 @@ const sessionRecord = (id, parent, { harness, frame }) => ({
     parent,
     agentType: null,
     spawnedBy: null,
-    spawnedIn: null,
+    spawnedIn,
     rev: 1,
     at: '',
     bytes: 0,
@@ -87,7 +99,8 @@ const sessionRecord = (id, parent, { harness, frame }) => ({
     tools: {},
     files: [],
     fileHashes: [],
-    repo: null,
+    // 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,
@@ -99,9 +112,9 @@ const sessionRecord = (id, parent, { harness, frame }) => ({
     costUsd: null,
     usage: NO_USAGE,
     harness,
-    frame,
+    frame: frameOf(frame, harness),
 });
-const promptRecords = (id, { prompts }) => prompts.map(({ cls, errors, wallSec, usage, explore, frame }, index) => ({
+const promptRecords = (id, { harness, prompts }) => prompts.map(({ cls, errors, wallSec, usage, usageResponses, explore, frame }, index) => ({
     kind: 'prompt',
     v: '',
     session: id,
@@ -110,7 +123,7 @@ const promptRecords = (id, { prompts }) => prompts.map(({ cls, errors, wallSec,
     ts: null,
     wallSec: wallSec === null ? null : floorOf('seconds', wallSec),
     head: '',
-    cls,
+    cls: classOf(cls),
     tools: [],
     shape: '',
     errors: floorOf('count', errors),
@@ -120,54 +133,71 @@ const promptRecords = (id, { prompts }) => prompts.map(({ cls, errors, wallSec,
     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),
-        cacheWrite: floorOf('tokens', usage.cacheWrite),
-        cacheRead: floorOf('tokens', usage.cacheRead),
-        output: floorOf('tokens', usage.output),
-        thinking: floorOf('tokens', usage.thinking),
+        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,
+    frame: frameOf(frame, harness),
 }));
-const toolRecords = (id, main, { tools }) => tools.map(({ side, prompt, status, durationMs, steps }, n) => ({
-    kind: 'tool',
-    cv: '',
-    sid: '',
-    session: id,
-    rev: 1,
-    parent: main,
-    agentType: null,
-    n,
-    ts: null,
-    tool: steps[0]?.native ?? '',
-    status,
-    target: null,
-    targetBase: null,
-    keys: [],
-    durationMs,
-    toolUseId: '',
-    harnessVersion: null,
-    side,
-    prompt,
-    steps: steps.map(({ action, native, identity, status: reported, parent, tokens, ms }, seg) => ({
-        action,
-        native,
-        identity,
-        status: reported,
-        parent,
-        seg,
-        edges: [],
-        cost: { tokens: tokens === null ? null : floorOf('tokens', tokens), durationMs: ms === null ? null : floorOf('ms', ms) },
+/** 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,
-        frameId: '',
-    })),
-}));
+        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 };
@@ -175,10 +205,13 @@ export const storeOf = (skeletons) => {
         const nameOf = (index) => `${id}#${String(index)}`;
         const main = nameOf(0);
         transcripts.forEach((transcript, index) => {
+            if (!isKnown(transcript))
+                return;
             const session = nameOf(index);
-            (index === 0 ? store.sessions : store.subagents).push(sessionRecord(session, index === 0 ? null : main, transcript));
+            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));
+            store.tools.push(...toolRecords(session, main, transcript, spawner));
         });
     }
     return store;
@@ -190,7 +223,8 @@ export const incrementsOf = (skeleton) => {
     for (const cell of derived.cells) {
         const exposed = cell.exposed ? 1 : 0;
         const key = `${cell.motifId}/${cell.frameBucket}/${cell.grain}/${cell.day}/${String(exposed)}`;
-        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, durationMs: cell.durationMs });
+        // 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();

package/dist/sessions/cells.d.ts

@@ -6,7 +6,7 @@ import type { Store } from './store.js';
 export type Grain = 'day' | 'week';
 export interface Cell {
     motifId: string;
-    /** `harness/versionBucket/model`, public names (`frameBucketOf`). Effort is not in it (rule 3). */
+    /** `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;
@@ -20,8 +20,15 @@ export interface Cell {
     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 prompts' whole usage. */
-    tokens: 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;
@@ -34,6 +41,27 @@ export declare const EFFORT_CLASS = "effort:";
  * 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 = "-";
 /**
@@ -43,6 +71,8 @@ export declare const NO_AXES = "-";
 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;

package/dist/sessions/cells.js

@@ -1,11 +1,12 @@
 // 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, motifsOf, stepsOfCall } from './motif.js';
+import { classMotif, motifName, motifsOf, stepsOfCall } from './motif.js';
 import { bucketOf } from './pool-wire.js';
-import { CALL_SHAPE_METHOD, cellRef, contentHash, METHODS } from './read.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 { EXTRACTOR_VERSION, harnessOf } from './schema.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:';
@@ -14,6 +15,26 @@ export const EFFORT_CLASS = 'effort:';
  * 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;
@@ -29,6 +50,8 @@ export const harnessBucket = (version) => {
 };
 /** 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 };
@@ -69,7 +92,9 @@ export const cellIdOf = (cell) => {
     cellIds.set(cell, id);
     return id;
 };
-const newTally = (motifId, frameBucket, grain, day, exposed) => ({ motifId, frameBucket, grain, day, sessions: new Set(), ok: 0, failed: 0, tokens: 0, durationMs: 0, exposed });
+/** 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({
@@ -143,11 +168,60 @@ export const deriveCells = (store, graph = NO_RECALLS) => {
                 if (status === 'error')
                     tally.failed += 1;
                 for (const step of window) {
-                    tally.tokens += step.tokens;
+                    // 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);
@@ -160,14 +234,20 @@ export const deriveCells = (store, graph = NO_RECALLS) => {
                 tally.failed += 1;
             else
                 tally.ok += 1;
-            const { input, cacheWrite, cacheRead, output } = prompt.usage;
-            tally.tokens += input + cacheWrite + cacheRead + output;
+            // 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.tokens, durationMs: tally.durationMs, exposed: tally.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('');
@@ -176,6 +256,6 @@ const errorRowsRead = (errors) => errors.map(({ session, agent, toolUseId, promp
 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, set.cells.map(cellIdOf), errorRowsRead(errors)]),
+    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),
 });