@manyoars/oars 0.2.0 → 0.4.0

package/dist/sessions/audit.js

@@ -0,0 +1,104 @@
+// Layer 4, T0, local (spec 2.4): does the raw file still match the root capture wrote, and do the capture records agree with each other?
+// Local only: a local match commits nobody, so no result here raises a tier. It reads `raw/` and `state.json`, and prints ids and counts, never content.
+import { readFile, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+import { merkleRootOf, MIN_ROOT_LEAVES, rawLinesOf } from './merkle.js';
+import { paths, readState, relativeOfSession } from './store.js';
+/** The T0 result table of spec 2.4, one name per row. */
+export const T0_RESULTS = ['root matches and the counts bind', 'changed since deposit', 'root mismatch', 'counts do not bind', 'not run'];
+const statOrUndefined = (file) => stat(file, { bigint: true }).catch((error) => {
+    if (error instanceof Error && 'code' in error && error.code === 'ENOENT')
+        return undefined;
+    throw error;
+});
+/** The count bindings of spec 2.4: the skeleton's leaves, the session's lines, and the skeleton's lines plus the session's bad lines must all agree. No skeleton is zero leaves and zero lines. */
+const bindingsOf = (session, skeleton) => {
+    const leaves = skeleton?.leaves ?? 0;
+    const skeletonLines = skeleton?.lines.length ?? 0;
+    return { leaves, sessionLines: session.lines, skeletonLines, badLines: session.badLines, bind: leaves === session.lines && session.lines === skeletonLines + session.badLines };
+};
+const unrun = (session, skeleton, bindings) => ({
+    session,
+    result: 'not run',
+    tier: 'skeleton',
+    mode: null,
+    leaves: skeleton?.leaves ?? 0,
+    belowMinLeaves: (skeleton?.leaves ?? 0) < MIN_ROOT_LEAVES,
+    changedSinceDeposit: false,
+    possibleTampering: false,
+    bindings,
+});
+/**
+ * One session's T0 result. The count bindings come first and need no raw file: a record set that disagrees with itself is `none` whatever `raw/`
+ * holds. `state` is `state.json`, read once by {@link auditStore}.
+ */
+export const auditSession = async (runtime, session, skeleton, state) => {
+    const bindings = bindingsOf(session, skeleton);
+    const base = { session: session.session, leaves: bindings.leaves, belowMinLeaves: bindings.leaves < MIN_ROOT_LEAVES, changedSinceDeposit: false, possibleTampering: false, bindings };
+    if (skeleton === undefined)
+        return { ...base, result: 'not run', tier: 'skeleton', mode: null };
+    if (!bindings.bind)
+        return { ...base, result: 'counts do not bind', tier: 'none', mode: null };
+    const relative = join(session.project, ...relativeOfSession(session.session));
+    const rawFile = join(paths(runtime.storeDir).raw, relative);
+    const raw = await statOrUndefined(rawFile);
+    if (raw === undefined)
+        return { ...base, result: 'not run', tier: 'skeleton', mode: null };
+    // The mode is read from the file: with the source's inode it is the link, otherwise a copy (or a link whose source is gone).
+    const source = await statOrUndefined(join(runtime.projectsRoot, relative));
+    const mode = source !== undefined && source.ino === raw.ino && source.dev === raw.dev ? 'link' : 'copy';
+    const held = (state ?? (await readState(runtime.storeDir))).files[relative.split('\\').join('/')];
+    // `state.json` holds float milliseconds from a plain `stat`; the match compares against the same reading.
+    const plain = await stat(rawFile);
+    const sizeHeld = held !== undefined && plain.size === held.size;
+    const matches = held !== undefined && sizeHeld && (mode === 'link' ? plain.mtimeMs === held.mtimeMs : plain.mtimeMs >= held.mtimeMs);
+    if (!matches)
+        return { ...base, result: 'changed since deposit', tier: 'skeleton', mode, changedSinceDeposit: true, possibleTampering: mode === 'copy' && held !== undefined && !sizeHeld };
+    const lines = rawLinesOf(await readFile(rawFile, 'utf8'));
+    const recomputed = lines.length < skeleton.leaves ? undefined : merkleRootOf(lines.slice(0, skeleton.leaves));
+    return recomputed === skeleton.merkleRoot ? { ...base, result: 'root matches and the counts bind', tier: 'skeleton', mode } : { ...base, result: 'root mismatch', tier: 'none', mode };
+};
+/**
+ * Every session's T0 result, in the order given, then one `not run` for each skeleton with no capture record (a torn or removed observations line), so
+ * the table never shrinks without a signal. A session with no skeleton, or whose raw file cannot be read, is also `not run`.
+ */
+export const auditStore = async (runtime, sessions, skeletons) => {
+    const state = await readState(runtime.storeDir);
+    const bySession = new Map(skeletons.map((skeleton) => [skeleton.session, skeleton]));
+    const audits = [];
+    for (const session of sessions) {
+        const skeleton = bySession.get(session.session);
+        // One unreadable raw file (EACCES, EBUSY, too large for a string) costs that session its result, never the others'.
+        audits.push(await auditSession(runtime, session, skeleton, state).catch(() => unrun(session.session, skeleton, bindingsOf(session, skeleton))));
+    }
+    const recorded = new Set(sessions.map((session) => session.session));
+    for (const skeleton of skeletons) {
+        if (!recorded.has(skeleton.session))
+            audits.push(unrun(skeleton.session, skeleton, { leaves: skeleton.leaves, sessionLines: 0, skeletonLines: skeleton.lines.length, badLines: 0, bind: false }));
+    }
+    return audits;
+};
+export const auditCounts = (audits) => {
+    const count = (result) => audits.filter((audit) => audit.result === result).length;
+    return {
+        'root matches and the counts bind': count('root matches and the counts bind'),
+        'changed since deposit': count('changed since deposit'),
+        'root mismatch': count('root mismatch'),
+        'counts do not bind': count('counts do not bind'),
+        'not run': count('not run'),
+    };
+};
+/** A count line for every row of the T0 table, then one FAIL line per session at tier `none` and one note per session that changed. */
+export const formatAudit = (audits) => {
+    const counts = auditCounts(audits);
+    const tampering = audits.filter((audit) => audit.possibleTampering).length;
+    const small = audits.filter((audit) => audit.belowMinLeaves).length;
+    return [
+        `${String(audits.length)} sessions audited against raw (T0, local: a local match commits nobody)`,
+        ...T0_RESULTS.map((result) => `      ${result}: ${String(counts[result])}`),
+        ...(tampering > 0 ? [`      possible tampering (a copy of a different size): ${String(tampering)}`] : []),
+        ...(small > 0 ? [`      under ${String(MIN_ROOT_LEAVES)} leaves, so joined to no cluster and counted toward no n: ${String(small)}`] : []),
+        ...audits.filter((audit) => audit.tier === 'none').map((audit) => `FAIL  ${audit.session}: ${audit.result}; weight is 0 until a new capture writes a new root`),
+        ...audits.filter((audit) => audit.changedSinceDeposit).map((audit) => `      ${audit.session}: changed since deposit (${audit.mode ?? 'no mode'}${audit.possibleTampering ? ', possible tampering' : ''})`),
+    ].join('\n');
+};

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' | 'usageObserved'>;
+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,190 @@
+// 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, observesUsage } 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));
+            // A category the source never recorded is a placeholder zero, not a measurement: the share needs input and cacheRead, and counts only the input-side categories recorded;
+            // output per turn needs output. A prompt missing what a dimension needs adds no count to it, so its denominator holds only the prompts that recorded the category.
+            const input = ['input', 'cacheWrite', 'cacheRead'].reduce((sum, field) => sum + (observesUsage(prompt, field) ? prompt.usage[field] : 0), 0);
+            if (observesUsage(prompt, 'input') && observesUsage(prompt, 'cacheRead') && input > 0)
+                add(histogramOf(group.histograms, 'cache-read share'), binOf(prompt.usage.cacheRead * 10, CACHE_SHARE_TENTHS, input));
+            if (observesUsage(prompt, 'output') && 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/call-shape.d.ts

@@ -0,0 +1,19 @@
+import type { TargetBase } from './schema.js';
+/** 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 declare const TARGET_CLASSES: readonly ["source", "test", "config", "doc", "lockfile", "generated", "data", "none", "other"];
+export type TargetClass = (typeof TARGET_CLASSES)[number];
+/** 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 declare const ARG_CLASSES: readonly ["path", "url", "pattern", "command", "number", "flag", "text", "none"];
+export type ArgClass = (typeof ARG_CLASSES)[number];
+/**
+ * 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 declare const targetClassOf: (path: string | undefined, base: TargetBase | null) => TargetClass;
+/**
+ * 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 declare const argClassOf: (input: {
+    readonly [key: string]: unknown;
+}) => ArgClass[];

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/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,47 @@
+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;
+    /** 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 {
+    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. 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;
+/** 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;