@manyoars/oars 0.2.0 → 0.3.0

package/dist/sessions/baseline.d.ts

@@ -0,0 +1,62 @@
+import { type Harness, type PromptObservation, type SessionObservation, type ToolObservation } from './schema.js';
+/** A week needs this many tool calls to be a unit or a baseline week (spec 5.4 item 1). */
+export declare const BASELINE_MIN_CALLS = 1000;
+/** A baseline needs this many other qualifying weeks (spec 5.4 item 1). */
+export declare const BASELINE_MIN_WEEKS = 4;
+/** F's bounds: a median distance at or under the low is F 1, at or over the high is F 0. */
+export declare const FIT_LOW: Fraction;
+export declare const FIT_HIGH: Fraction;
+/**
+ * The fixed bin edges of the numeric dimensions: a value goes in the first bin whose edge it is under, else the last, so a value exactly on an edge
+ * lands in the upper bin. The cache-read share's edges are tenths (k / 10) and compare as integers: `cacheRead * 10 < k * input`.
+ */
+export declare const DURATION_EDGES_MS: readonly number[];
+export declare const WALL_EDGES_SEC: readonly number[];
+export declare const CACHE_SHARE_TENTHS: readonly number[];
+export declare const OUTPUT_PER_TURN_EDGES: readonly number[];
+export declare const DIMENSIONS: readonly ["tool mix", "status", "durationMs", "wallSec", "cache-read share", "output per turn", "prompt class"];
+export type Dimension = (typeof DIMENSIONS)[number];
+/** The fields each record needs, so a caller passes the store's records and a test passes small ones. */
+export type BaselineSession = Pick<SessionObservation, 'session' | 'tsFirst' | 'tools' | 'harness'>;
+export type BaselineTool = Pick<ToolObservation, 'session' | 'status' | 'durationMs'>;
+export type BaselinePrompt = Pick<PromptObservation, 'session' | 'wallSec' | 'cls' | 'turns' | 'usage'>;
+export interface DimensionDistance {
+    dimension: Dimension;
+    distance: number;
+}
+/** One session's layer-2 result: `scored` with `m` and `f`, or `not run` with the reason and nothing scored. */
+export interface SelfBaselineResult {
+    session: string;
+    harness: Harness;
+    /** The UTC Monday of the session's `tsFirst` (YYYY-MM-DD); null when `tsFirst` is null. */
+    week: string | null;
+    status: 'scored' | 'not run';
+    reason: string | null;
+    /** Tool calls in the session's week on its harness. */
+    calls: number;
+    /** The other qualifying weeks the baseline pools. */
+    baselineWeeks: number;
+    distances: DimensionDistance[];
+    m: number | null;
+    f: number | null;
+}
+/** An exact rational with a positive denominator: the distances, `m`, and `F` stay in this form until the one rounding at the end (spec 2.2, no float). */
+export interface Fraction {
+    n: bigint;
+    d: bigint;
+}
+/** The UTC Monday 00:00 (epoch ms) of the week holding `ts`; null for a null or unparsable timestamp. */
+export declare const weekOf: (ts: string | null) => number | null;
+/** The median; the mean of the middle two for an even count. Never called with an empty list. */
+export declare const medianOf: (values: readonly Fraction[]) => Fraction;
+/** F = 1 - clamp((m - 1/10) / (2/5 - 1/10)), exact, rounded half-even to 4 places. */
+export declare const fitOf: (m: Fraction) => number;
+/**
+ * Every session's result. A session belongs wholly to the UTC week of its `tsFirst` and takes the F of its harness and week. A week qualifies at
+ * {@link BASELINE_MIN_CALLS} tool calls with its last UTC day no later than `asOf`; the baseline is a harness's other qualifying weeks, their counts
+ * added per bin so each week weighs what its calls weigh. A dimension with no counts on one side or both is dropped; `m` is the median of the
+ * rest. Mechanics only: no signature, no record content.
+ */
+export declare const selfBaseline: (sessions: readonly BaselineSession[], tools: readonly BaselineTool[], prompts: readonly BaselinePrompt[], asOf: number) => SelfBaselineResult[];
+/** A count line for the scored sessions, then one per reason a session was not run. Counts only. */
+export declare const formatSelfBaseline: (results: readonly SelfBaselineResult[]) => string;

package/dist/sessions/baseline.js

@@ -0,0 +1,188 @@
+// Layer 2's self-baseline (spec 2.2): a session's week against the operator's own other weeks on the same harness. Local only: no pooled field,
+// no network, no account step. The peer baseline waits for T2.
+import { harnessOf } from './schema.js';
+/** A week needs this many tool calls to be a unit or a baseline week (spec 5.4 item 1). */
+export const BASELINE_MIN_CALLS = 1000;
+/** A baseline needs this many other qualifying weeks (spec 5.4 item 1). */
+export const BASELINE_MIN_WEEKS = 4;
+/** F's bounds: a median distance at or under the low is F 1, at or over the high is F 0. */
+export const FIT_LOW = { n: 1n, d: 10n };
+export const FIT_HIGH = { n: 2n, d: 5n };
+/**
+ * The fixed bin edges of the numeric dimensions: a value goes in the first bin whose edge it is under, else the last, so a value exactly on an edge
+ * lands in the upper bin. The cache-read share's edges are tenths (k / 10) and compare as integers: `cacheRead * 10 < k * input`.
+ */
+export const DURATION_EDGES_MS = [100, 1000, 10_000, 60_000];
+export const WALL_EDGES_SEC = [5, 30, 120, 600];
+export const CACHE_SHARE_TENTHS = [1, 2, 3, 4, 5, 6, 7, 8, 9];
+export const OUTPUT_PER_TURN_EDGES = [50, 200, 500, 1000, 2000];
+const DAY_MS = 86_400_000;
+const WEEK_MS = 7 * DAY_MS;
+export const DIMENSIONS = ['tool mix', 'status', 'durationMs', 'wallSec', 'cache-read share', 'output per turn', 'prompt class'];
+/** The UTC Monday 00:00 (epoch ms) of the week holding `ts`; null for a null or unparsable timestamp. */
+export const weekOf = (ts) => {
+    const at = ts === null ? Number.NaN : Date.parse(ts);
+    if (Number.isNaN(at))
+        return null;
+    const day = Math.floor(at / DAY_MS) * DAY_MS;
+    // 1970-01-01 was a Thursday: three days after the Monday of its week.
+    return day - ((((day / DAY_MS) + 3) % 7) * DAY_MS);
+};
+const compare = (a, b) => {
+    const diff = a.n * b.d - b.n * a.d;
+    return diff < 0n ? -1 : diff > 0n ? 1 : 0;
+};
+const minus = (a, b) => ({ n: a.n * b.d - b.n * a.d, d: a.d * b.d });
+/** Rounds half-even to 4 places, once, at the end (spec 3.2). A value is never negative here. */
+const roundTo4 = (value) => {
+    const scaled = value.n * 10000n;
+    const quotient = scaled / value.d;
+    const twiceRest = 2n * (scaled - quotient * value.d);
+    const up = twiceRest > value.d || (twiceRest === value.d && quotient % 2n === 1n);
+    return Number(up ? quotient + 1n : quotient) / 10_000;
+};
+/** The median; the mean of the middle two for an even count. Never called with an empty list. */
+export const medianOf = (values) => {
+    const sorted = [...values].sort(compare);
+    const mid = sorted.length >> 1;
+    const upper = sorted[mid] ?? { n: 0n, d: 1n };
+    if (sorted.length % 2 === 1)
+        return upper;
+    const lower = sorted[mid - 1] ?? { n: 0n, d: 1n };
+    return { n: lower.n * upper.d + upper.n * lower.d, d: 2n * lower.d * upper.d };
+};
+/** F = 1 - clamp((m - 1/10) / (2/5 - 1/10)), exact, rounded half-even to 4 places. */
+export const fitOf = (m) => {
+    const span = minus(FIT_HIGH, FIT_LOW);
+    if (compare(m, FIT_LOW) <= 0)
+        return 1;
+    if (compare(m, FIT_HIGH) >= 0)
+        return 0;
+    const over = minus(m, FIT_LOW);
+    // 1 - (over.n / over.d) / (span.n / span.d) = (over.d * span.n - over.n * span.d) / (over.d * span.n)
+    return roundTo4({ n: over.d * span.n - over.n * span.d, d: over.d * span.n });
+};
+/** The first bin whose edge the value is under, else the last: `value < edge * scale` with integers, so the comparison is exact. */
+const binOf = (value, edges, scale = 1) => {
+    const index = edges.findIndex((edge) => value < edge * scale);
+    return String(index === -1 ? edges.length : index);
+};
+const add = (histogram, key, count = 1) => {
+    histogram.set(key, (histogram.get(key) ?? 0) + count);
+};
+const emptyHistograms = () => new Map(DIMENSIONS.map((dimension) => [dimension, new Map()]));
+const histogramOf = (histograms, dimension) => histograms.get(dimension) ?? new Map();
+const callsOf = (session) => Object.values(session.tools).reduce((total, count) => total + count, 0);
+const addInto = (into, from) => {
+    for (const dimension of DIMENSIONS)
+        for (const [key, count] of histogramOf(from, dimension))
+            add(histogramOf(into, dimension), key, count);
+};
+const total = (histogram) => [...histogram.values()].reduce((sum, count) => sum + count, 0);
+/** Half the sum of absolute differences of the two normalized histograms, over integer counts: sum |a * sumB - b * sumA| / (2 * sumA * sumB). */
+const distanceBetween = (a, b) => {
+    const sumA = BigInt(total(a));
+    const sumB = BigInt(total(b));
+    let sum = 0n;
+    for (const key of new Set([...a.keys(), ...b.keys()])) {
+        const diff = BigInt(a.get(key) ?? 0) * sumB - BigInt(b.get(key) ?? 0) * sumA;
+        sum += diff < 0n ? -diff : diff;
+    }
+    return { n: sum, d: 2n * sumA * sumB };
+};
+/** One pass, pushing into each session's list: a copy per row is quadratic in a session's rows. */
+const bySession = (records) => {
+    const grouped = new Map();
+    for (const record of records) {
+        const list = grouped.get(record.session);
+        if (list === undefined)
+            grouped.set(record.session, [record]);
+        else
+            list.push(record);
+    }
+    return grouped;
+};
+const isoDay = (ms) => new Date(ms).toISOString().slice(0, 10);
+/**
+ * Every session's result. A session belongs wholly to the UTC week of its `tsFirst` and takes the F of its harness and week. A week qualifies at
+ * {@link BASELINE_MIN_CALLS} tool calls with its last UTC day no later than `asOf`; the baseline is a harness's other qualifying weeks, their counts
+ * added per bin so each week weighs what its calls weigh. A dimension with no counts on one side or both is dropped; `m` is the median of the
+ * rest. Mechanics only: no signature, no record content.
+ */
+export const selfBaseline = (sessions, tools, prompts, asOf) => {
+    const toolsOf = bySession(tools);
+    const promptsOf = bySession(prompts);
+    const groups = new Map();
+    const keyOf = new Map();
+    for (const session of sessions) {
+        const start = weekOf(session.tsFirst);
+        if (start === null) {
+            keyOf.set(session.session, null);
+            continue;
+        }
+        const harness = harnessOf(session);
+        const key = `${harness}:${String(start)}`;
+        keyOf.set(session.session, key);
+        const group = groups.get(key) ?? { harness, start, calls: 0, histograms: emptyHistograms() };
+        groups.set(key, group);
+        group.calls += callsOf(session);
+        for (const [tool, count] of Object.entries(session.tools))
+            add(histogramOf(group.histograms, 'tool mix'), tool, count);
+        for (const tool of toolsOf.get(session.session) ?? []) {
+            add(histogramOf(group.histograms, 'status'), tool.status);
+            if (tool.durationMs !== null)
+                add(histogramOf(group.histograms, 'durationMs'), binOf(tool.durationMs, DURATION_EDGES_MS));
+        }
+        for (const prompt of promptsOf.get(session.session) ?? []) {
+            add(histogramOf(group.histograms, 'prompt class'), prompt.cls);
+            if (prompt.wallSec !== null)
+                add(histogramOf(group.histograms, 'wallSec'), binOf(prompt.wallSec, WALL_EDGES_SEC));
+            const input = prompt.usage.input + prompt.usage.cacheWrite + prompt.usage.cacheRead;
+            if (input > 0)
+                add(histogramOf(group.histograms, 'cache-read share'), binOf(prompt.usage.cacheRead * 10, CACHE_SHARE_TENTHS, input));
+            if (prompt.turns > 0)
+                add(histogramOf(group.histograms, 'output per turn'), binOf(prompt.usage.output, OUTPUT_PER_TURN_EDGES, prompt.turns));
+        }
+    }
+    const scored = new Map();
+    for (const [key, group] of groups) {
+        const base = { calls: group.calls, baselineWeeks: 0, distances: [], m: null, f: null };
+        if (group.calls < BASELINE_MIN_CALLS) {
+            scored.set(key, { ...base, status: 'not run', reason: `week under ${String(BASELINE_MIN_CALLS)} tool calls` });
+            continue;
+        }
+        const others = [...groups.values()].filter((other) => other.harness === group.harness && other.start !== group.start && other.calls >= BASELINE_MIN_CALLS && other.start + WEEK_MS - DAY_MS <= Math.floor(asOf / DAY_MS) * DAY_MS);
+        if (others.length < BASELINE_MIN_WEEKS) {
+            scored.set(key, { ...base, baselineWeeks: others.length, status: 'not run', reason: `under ${String(BASELINE_MIN_WEEKS)} qualifying baseline weeks` });
+            continue;
+        }
+        const pooled = emptyHistograms();
+        for (const other of others)
+            addInto(pooled, other.histograms);
+        const exact = DIMENSIONS.filter((dimension) => total(histogramOf(group.histograms, dimension)) > 0 && total(histogramOf(pooled, dimension)) > 0).map((dimension) => ({ dimension, distance: distanceBetween(histogramOf(group.histograms, dimension), histogramOf(pooled, dimension)) }));
+        // The tool mix has counts on both sides whenever the week and the baseline each hold 1,000 calls, so at least one dimension always remains.
+        const m = medianOf(exact.map((entry) => entry.distance));
+        const distances = exact.map((entry) => ({ dimension: entry.dimension, distance: roundTo4(entry.distance) }));
+        scored.set(key, { ...base, baselineWeeks: others.length, distances, m: roundTo4(m), f: fitOf(m), status: 'scored', reason: null });
+    }
+    return sessions.map((session) => {
+        const key = keyOf.get(session.session) ?? null;
+        const harness = harnessOf(session);
+        const found = key === null ? undefined : scored.get(key);
+        if (key === null || found === undefined)
+            return { session: session.session, harness, week: null, status: 'not run', reason: 'no first timestamp', calls: 0, baselineWeeks: 0, distances: [], m: null, f: null };
+        return { session: session.session, harness, week: isoDay(groups.get(key)?.start ?? 0), ...found };
+    });
+};
+/** A count line for the scored sessions, then one per reason a session was not run. Counts only. */
+export const formatSelfBaseline = (results) => {
+    const reasons = new Map();
+    for (const entry of results)
+        if (entry.reason !== null)
+            add(reasons, entry.reason);
+    return [
+        `${String(results.length)} sessions against their own other weeks (layer 2, local; a low F lowers W and rejects nothing)`,
+        `      scored: ${String(results.filter((entry) => entry.status === 'scored').length)}`,
+        ...[...reasons].sort().map(([reason, count]) => `      not run, ${reason}: ${String(count)}`),
+    ].join('\n');
+};

package/dist/sessions/capture-runtime.d.ts

@@ -0,0 +1,10 @@
+/** The `version` in a package.json text, or `0.0.0` when it has none. */
+export declare const versionIn: (manifestText: string) => string;
+/** This package's version: `package.json` sits two folders above both `src/sessions/` and `dist/sessions/`. */
+export declare const oarsVersion: () => string;
+export interface CaptureRuntime {
+    oars: string;
+    node: string;
+    os: string;
+}
+export declare const captureRuntime: () => CaptureRuntime;

package/dist/sessions/capture-runtime.js

@@ -0,0 +1,12 @@
+// What a capture records about the machine it ran on (`env` on the session record, class P): the oars package version, Node.js, and OS.
+// Names and versions only; a library version is recorded only when a transcript states it, and none is read here.
+import { readFileSync } from 'node:fs';
+/** The `version` in a package.json text, or `0.0.0` when it has none. */
+export const versionIn = (manifestText) => {
+    const manifest = JSON.parse(manifestText);
+    const version = typeof manifest === 'object' && manifest !== null ? Reflect.get(manifest, 'version') : undefined;
+    return typeof version === 'string' ? version : '0.0.0';
+};
+/** This package's version: `package.json` sits two folders above both `src/sessions/` and `dist/sessions/`. */
+export const oarsVersion = () => versionIn(readFileSync(new URL('../../package.json', import.meta.url), 'utf8'));
+export const captureRuntime = () => ({ oars: oarsVersion(), node: process.version, os: process.platform });

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

@@ -0,0 +1,43 @@
+import { type CellSet, type Grain } from './cells.js';
+import type { Motif } from './motif.js';
+import { type SessionSkeleton, type ShellReader } from './pool-wire.js';
+import { type RecallGraph } from './recall-consequence.js';
+import type { Store } from './store.js';
+export interface CellRow {
+    key: string;
+    harnessBucket: string;
+    motifId: string;
+    frameBucket: string;
+    grain: Grain;
+    day: string;
+    exposed: number;
+    sessions: number;
+    ok: number;
+    failed: number;
+    tokens: number;
+    durationMs: number;
+}
+export interface StratumRow {
+    key: string;
+    dimension: string;
+    value: string;
+    sessions: number;
+}
+/** What one batch adds to the index: its cells, the motifs they name, and rule 3's strata. */
+export interface Increments {
+    cells: Map<string, CellRow>;
+    motifs: Motif[];
+    strata: Map<string, StratumRow>;
+}
+/**
+ * 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 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. */
+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;
+/** Whole cells and strata, summed over a batch's own sessions: the same cells a store of that batch alone derives. */
+export declare const incrementsOf: (skeleton: SessionSkeleton) => Increments;

package/dist/sessions/cell-increments.js

@@ -0,0 +1,209 @@
+// 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 { bucketFields, deriveCells, ENVIRONMENT_BUCKET, isEnvironmentCell } from './cells.js';
+import { bucketOf, floorOf, projectedSteps } from './pool-wire.js';
+import { NO_RECALLS } from './recall-consequence.js';
+import { 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. */
+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 };
+/** 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 }) => ({
+    kind: 'session',
+    cv: '',
+    sid: '',
+    session: id,
+    project: '',
+    parent,
+    agentType: null,
+    spawnedBy: null,
+    spawnedIn: null,
+    rev: 1,
+    at: '',
+    bytes: 0,
+    lines: 0,
+    badLines: 0,
+    userTurns: 0,
+    assistantTurns: 0,
+    tsFirst: null,
+    tsLast: null,
+    versions: [],
+    models: {},
+    branches: [],
+    tools: {},
+    files: [],
+    fileHashes: [],
+    repo: 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,
+});
+const promptRecords = (id, { prompts }) => prompts.map(({ cls, errors, wallSec, usage, explore, frame }, index) => ({
+    kind: 'prompt',
+    v: '',
+    session: id,
+    rev: 1,
+    index,
+    ts: null,
+    wallSec: wallSec === null ? null : floorOf('seconds', wallSec),
+    head: '',
+    cls,
+    tools: [],
+    shape: '',
+    errors: floorOf('count', errors),
+    thinking: 0,
+    sideTools: 0,
+    turns: 0,
+    model: frame.model ?? '',
+    efforts: frame.effort === null ? [] : [frame.effort],
+    skills: [],
+    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),
+    },
+    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,
+}));
+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) },
+        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) => {
+            const session = nameOf(index);
+            (index === 0 ? store.sessions : store.subagents).push(sessionRecord(session, index === 0 ? null : main, transcript));
+            store.prompts.push(...promptRecords(session, transcript));
+            store.tools.push(...toolRecords(session, main, transcript));
+        });
+    }
+    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)}`;
+        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 });
+    }
+    // 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,79 @@
+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`). 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 prompts' whole usage. */
+    tokens: 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 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;
+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;