@manyoars/oars 0.2.0 → 0.3.0

package/dist/sessions/query.js

@@ -0,0 +1,246 @@
+// The read side: recall, books, and measure. All three are pure functions of a loaded store (and, for measure, the MCP log).
+import { firstCopies } from './derive.js';
+import { errorKey } from './extract.js';
+import { makeRedactor } from './redact.js';
+import { SOURCES } from './sources.js';
+import { harnessOf } from './schema.js';
+import { signatureRecord } from './store.js';
+const DAY_MS = 86_400_000;
+const sinceCutoff = (now, days) => (days === undefined ? undefined : new Date(now - days * DAY_MS).toISOString());
+/** `Bash | text` pasted whole selects the tool too. */
+const splitTool = (query) => {
+    const found = /^([^\s|]+) \| ([\s\S]*)$/.exec(query.trim());
+    return found === null ? { tool: undefined, text: query } : { tool: found[1], text: found[2] ?? '' };
+};
+const touched = (session, path) => session.files.some((file) => file === path || file.endsWith(`/${path}`) || file.endsWith(`\\${path}`));
+/** Which error rows a query selects, and the normalized text it matched them on. A count stated for a narrowed query reads through this, so it counts what the query narrowed to. */
+export const recallRows = (store, query, now, redactDomains = []) => {
+    const redact = makeRedactor(redactDomains);
+    const cutoff = sinceCutoff(now, query.sinceDays);
+    let tool;
+    let normalized = null;
+    if (query.error !== undefined) {
+        const split = splitTool(query.error);
+        tool = split.tool;
+        normalized = errorKey(split.text, redact);
+    }
+    const path = query.path === undefined ? undefined : redact(query.path);
+    const sessions = path === undefined ? undefined : new Set(store.sessions.filter((session) => touched(session, path)).map((session) => session.session));
+    const keep = (error) => {
+        if (cutoff !== undefined && (error.ts === null || error.ts < cutoff))
+            return false;
+        if (query.cls !== undefined && error.cls !== query.cls)
+            return false;
+        if (sessions !== undefined && !sessions.has(error.session))
+            return false;
+        if (tool !== undefined && error.tool !== tool)
+            return false;
+        if (normalized === null)
+            return true;
+        return normalized !== '' && error.sig.slice(error.sig.indexOf(' | ') + 3).includes(normalized);
+    };
+    return { normalized, keep };
+};
+export const recall = (store, query, now, limit = 10, redactDomains = []) => {
+    const { normalized, keep } = recallRows(store, query, now, redactDomains);
+    const bySig = new Map();
+    for (const error of store.errors) {
+        if (keep(error))
+            bySig.set(error.sig, [...(bySig.get(error.sig) ?? []), error]);
+    }
+    const matches = [...bySig.entries()]
+        .map(([sig, list]) => signatureRecord(sig, list))
+        .sort((a, b) => b.sessions - a.sessions || b.count - a.count || a.sig.localeCompare(b.sig))
+        .slice(0, limit)
+        .map((record) => ({ ...record, followedBy: Object.entries(record.following).map(([followed, count]) => ({ tool: followed, count })).sort((a, b) => b.count - a.count || a.tool.localeCompare(b.tool)) }));
+    return { query, normalized, matches };
+};
+export const formatRecall = (result) => {
+    if (result.matches.length === 0)
+        return 'No matching signature in the store.';
+    return result.matches
+        .map((match) => {
+        const followed = match.followedBy.slice(0, 3).map((entry) => `${entry.tool} x${String(entry.count)}`).join(', ');
+        return [
+            match.sig,
+            `  ${String(match.sessions)} sessions, ${String(match.count)} errors, first ${match.firstSeen ?? 'unknown'}, last ${match.lastSeen ?? 'unknown'}`,
+            `  harness ${match.harnessVersions.join(', ') || 'unknown'}; followed by ${followed || 'nothing'}; an edit followed ${String(match.editFollowed)} times`,
+        ].join('\n');
+    })
+        .join('\n');
+};
+/** Below this many in its denominator a share is noise, so a cell has none and prints as too few. The counts stay in `--json`. */
+export const BOOKS_MIN_PROMPTS = 30;
+/** Each subagent's tokens, keyed by the parent prompt that spawned it (`<session>#<index>`). */
+const delegatedByPrompt = (store) => {
+    const promptOf = new Map();
+    for (const tool of store.tools) {
+        if (tool.toolUseId !== null && tool.prompt !== null)
+            promptOf.set(`${tool.session} ${tool.toolUseId}`, `${tool.session}#${String(tool.prompt)}`);
+    }
+    const totals = new Map();
+    for (const agent of store.subagents) {
+        const prompt = promptOf.get(`${String(agent.parent)} ${String(agent.spawnedBy)}`);
+        if (prompt === undefined)
+            continue;
+        const { input, cacheWrite, cacheRead, output } = agent.usage;
+        totals.set(prompt, (totals.get(prompt) ?? 0) + input + cacheWrite + cacheRead + output);
+    }
+    return totals;
+};
+const promptKey = (session, index) => `${session}#${String(index)}`;
+const shareOf = (count, of) => ({ count, of, share: of < BOOKS_MIN_PROMPTS ? null : Math.round((count / of) * 1000) / 1000 });
+/** Each prompt's shas and pulls, by the rule `commits` is derived under: a session's first copy of a call, off the sidechain. */
+const callsByPrompt = (store) => {
+    const bySession = new Map();
+    for (const tool of store.tools) {
+        const list = bySession.get(tool.session);
+        if (list === undefined)
+            bySession.set(tool.session, [tool]);
+        else
+            list.push(tool);
+    }
+    const calls = new Map();
+    for (const tools of bySession.values()) {
+        for (const tool of firstCopies(tools)) {
+            if (tool.prompt === null || (tool.commits === undefined && tool.pulls === undefined))
+                continue;
+            const key = promptKey(tool.session, tool.prompt);
+            const entry = calls.get(key) ?? { shas: new Set(), pulls: new Set() };
+            for (const sha of tool.commits ?? [])
+                if (sha !== null)
+                    entry.shas.add(sha);
+            for (const pull of tool.pulls ?? [])
+                entry.pulls.add(`${pull.ecosystem}:${pull.name}`);
+            calls.set(key, entry);
+        }
+    }
+    return calls;
+};
+export const books = (store, by, now, sinceDays, survival = new Map()) => {
+    const cutoff = sinceCutoff(now, sinceDays);
+    const groups = new Map();
+    const harnesses = new Map(store.sessions.map((session) => [session.session, harnessOf(session)]));
+    const calls = callsByPrompt(store);
+    const keysOf = (prompt) => {
+        if (by === 'pull')
+            return calls.get(promptKey(prompt.session, prompt.index))?.pulls ?? [];
+        return [by === 'class' ? prompt.cls : by === 'model' ? prompt.model : (harnesses.get(prompt.session) ?? 'claude-code')];
+    };
+    for (const prompt of store.prompts) {
+        if (cutoff !== undefined && (prompt.ts === null || prompt.ts < cutoff))
+            continue;
+        for (const key of keysOf(prompt)) {
+            const group = groups.get(key);
+            if (group === undefined)
+                groups.set(key, [prompt]);
+            else
+                group.push(prompt);
+        }
+    }
+    const sum = (list, pick) => list.reduce((total, prompt) => total + pick(prompt), 0);
+    const delegated = delegatedByPrompt(store);
+    return [...groups.entries()]
+        .map(([key, list]) => {
+        const verified = list.filter((prompt) => prompt.cls === 'edit-verify').length;
+        const edited = verified + list.filter((prompt) => prompt.cls === 'edit-only').length;
+        const readable = list.filter((prompt) => prompt.verify !== undefined && prompt.verify !== 'na' && prompt.verify !== 'masked');
+        const carryingStop = list.filter((prompt) => prompt.stopped !== undefined);
+        const carryingRedo = list.filter((prompt) => prompt.redo !== undefined);
+        const states = [...new Set(list.flatMap((prompt) => [...(calls.get(promptKey(prompt.session, prompt.index))?.shas ?? [])]))].map((sha) => survival.get(sha));
+        const settled = states.filter((state) => state !== undefined && state !== 'unknown').length;
+        return {
+            key,
+            prompts: list.length,
+            cacheRead: sum(list, (prompt) => prompt.usage.cacheRead),
+            cacheWrite: sum(list, (prompt) => prompt.usage.cacheWrite),
+            output: sum(list, (prompt) => prompt.usage.output),
+            thinking: sum(list, (prompt) => prompt.usage.thinking),
+            wallSec: Math.round(sum(list, (prompt) => prompt.wallSec ?? 0)),
+            turns: sum(list, (prompt) => prompt.turns),
+            errors: sum(list, (prompt) => prompt.errors),
+            verifyAfterEdit: edited === 0 ? null : Math.round((verified / edited) * 1000) / 1000,
+            delegated: sum(list, (prompt) => delegated.get(promptKey(prompt.session, prompt.index)) ?? 0),
+            verifyPassed: shareOf(readable.filter((prompt) => prompt.verify === 'passed').length, readable.length),
+            stopped: shareOf(carryingStop.filter((prompt) => prompt.stopped !== null).length, carryingStop.length),
+            redone: shareOf(carryingRedo.filter((prompt) => prompt.redo === true).length, carryingRedo.length),
+            commits: sum(list, (prompt) => prompt.commits ?? 0),
+            settled,
+            survived: shareOf(states.filter((state) => state === 'survived').length, settled),
+        };
+    })
+        .sort((a, b) => b.prompts - a.prompts || a.key.localeCompare(b.key));
+};
+/** The closing line of `books` text: what the columns can and cannot be read as. */
+export const BOOKS_CAVEAT = "These are associations in one operator's logs, not measured lift.";
+const shareCell = (cell) => (cell.share === null ? 'too few' : `${String(Math.round(cell.share * 100))}%`);
+export const formatBooks = (rows, by) => {
+    if (rows.length === 0)
+        return by === 'pull' ? 'No pulls in the store.' : 'No prompts in the store.';
+    // A pull name, unlike a class, has no length it stays under.
+    const width = Math.max(14, ...rows.map((row) => row.key.length));
+    const header = `${by.padEnd(width)} ${'prompts'.padStart(8)} ${'cache read'.padStart(14)} ${'cache write'.padStart(13)} ${'output'.padStart(11)} ${'thinking'.padStart(10)} ${'wall s'.padStart(9)} ${'turns'.padStart(7)} ${'errors'.padStart(7)} ${'verify'.padStart(7)} ${'delegated'.padStart(13)} ${'passed'.padStart(8)} ${'stop'.padStart(8)} ${'redo'.padStart(8)} ${'commits'.padStart(8)} ${'settled'.padStart(8)} ${'survived'.padStart(8)}`;
+    const lines = rows.map((row) => `${row.key.padEnd(width)} ${String(row.prompts).padStart(8)} ${String(row.cacheRead).padStart(14)} ${String(row.cacheWrite).padStart(13)} ${String(row.output).padStart(11)} ${String(row.thinking).padStart(10)} ${String(row.wallSec).padStart(9)} ${String(row.turns).padStart(7)} ${String(row.errors).padStart(7)} ${(row.verifyAfterEdit === null ? '-' : `${String(Math.round(row.verifyAfterEdit * 100))}%`).padStart(7)} ${String(row.delegated).padStart(13)} ${shareCell(row.verifyPassed).padStart(8)} ${shareCell(row.stopped).padStart(8)} ${shareCell(row.redone).padStart(8)} ${String(row.commits).padStart(8)} ${String(row.settled).padStart(8)} ${shareCell(row.survived).padStart(8)}`);
+    return [header, ...lines].join('\n');
+};
+const order = (a, b) => (a.tsFirst ?? '').localeCompare(b.tsFirst ?? '') || a.session.localeCompare(b.session);
+/**
+ * Without `since` the current window is the last `window` sessions, so it moves with every deposit. With it, the current window is the
+ * first `window` sessions that started at or after the cutoff and the prior window is the `window` before it, so a reading pinned to an
+ * install time keeps its start however many sessions come later.
+ */
+export const measure = (store, calls, hookCalls, window, since) => {
+    const sessions = [...store.sessions].sort(order);
+    const index = new Map(sessions.map((session, position) => [session.session, position]));
+    const firstSeen = new Map();
+    for (const error of store.errors) {
+        const position = index.get(error.session);
+        if (position !== undefined)
+            firstSeen.set(error.sig, Math.min(firstSeen.get(error.sig) ?? position, position));
+    }
+    const signal = (slice) => {
+        if (slice.length === 0)
+            return { sessions: 0, cursorSessions: 0, recurringPer100: null, recurringSignatures: null, cacheWritePerSession: null, recallPerSession: null, hookRecallPerSession: null, hookHitsPerSession: null, hookDepositsPerSession: null };
+        const names = new Set(slice.map((session) => session.session));
+        const recurringErrors = store.errors.filter((error) => names.has(error.session) && (index.get(error.session) ?? 0) > (firstSeen.get(error.sig) ?? 0));
+        const recurring = recurringErrors.length;
+        const from = slice.map((session) => session.tsFirst).filter((ts) => ts !== null).sort()[0];
+        const to = slice.map((session) => session.tsLast).filter((ts) => ts !== null).sort().reverse()[0];
+        const inWindow = from === undefined || to === undefined ? 0 : calls.filter((call) => call.at >= from && call.at <= to).length;
+        const round = (value) => Math.round(value * 100) / 100;
+        const lookups = hookCalls.filter((call) => call.session !== null && names.has(call.session) && (call.event === 'session-start' || call.event === 'post-tool'));
+        return {
+            sessions: slice.length,
+            cursorSessions: slice.filter((session) => harnessOf(session) === 'cursor').length,
+            otherSessions: Object.fromEntries(SOURCES.filter((source) => source.harness !== 'cursor').map((source) => [source.harness, slice.filter((session) => harnessOf(session) === source.harness).length])),
+            recurringPer100: round((recurring * 100) / slice.length),
+            recurringSignatures: new Set(recurringErrors.map((error) => error.sig)).size,
+            cacheWritePerSession: Math.round(slice.reduce((total, session) => total + session.usage.cacheWrite, 0) / slice.length),
+            recallPerSession: round(inWindow / slice.length),
+            hookRecallPerSession: round(lookups.length / slice.length),
+            hookHitsPerSession: round(lookups.filter((call) => call.hit).length / slice.length),
+            hookDepositsPerSession: round(hookCalls.filter((call) => call.session !== null && names.has(call.session) && call.event === 'stop' && call.hit).length / slice.length),
+        };
+    };
+    const start = since === undefined ? Math.max(sessions.length - window, 0) : sessions.findIndex((session) => (session.tsFirst ?? '') >= since);
+    if (start < 0)
+        return { window, since: since ?? null, last: signal([]), before: signal(sessions.slice(Math.max(sessions.length - window, 0))) };
+    return { window, since: since ?? null, last: signal(sessions.slice(start, start + window)), before: signal(sessions.slice(Math.max(start - window, 0), start)) };
+};
+export const formatMeasure = (result) => {
+    const cell = (value) => (value === null ? '-' : String(value));
+    const row = (label, pick) => `${label.padEnd(36)} ${cell(pick(result.last)).padStart(12)} ${cell(pick(result.before)).padStart(12)}`;
+    return [
+        `${(result.since === null ? `G1 signals, last ${String(result.window)} sessions and the ${String(result.window)} before` : `G1 signals, ${String(result.window)} sessions from ${result.since} and the ${String(result.window)} before`).padEnd(36)} ${(result.since === null ? 'last' : 'from').padStart(12)} ${'before'.padStart(12)}`,
+        row('sessions in the window', (signal) => signal.sessions),
+        row('  of which Cursor', (signal) => signal.cursorSessions),
+        ...SOURCES.filter((source) => source.harness !== 'cursor' && ((result.last.otherSessions?.[source.harness] ?? 0) > 0 || (result.before.otherSessions?.[source.harness] ?? 0) > 0)).map((source) => row(`  of which ${source.label}`, (signal) => signal.otherSessions?.[source.harness] ?? 0)),
+        row('recurring errors per 100 sessions', (signal) => signal.recurringPer100),
+        row('distinct recurring signatures', (signal) => signal.recurringSignatures),
+        row('cache-write tokens per session', (signal) => signal.cacheWritePerSession),
+        row('recall calls per session', (signal) => signal.recallPerSession),
+        row('hook recall calls per session', (signal) => signal.hookRecallPerSession),
+        row('hook hits per session', (signal) => signal.hookHitsPerSession),
+        row('hook deposits per session', (signal) => signal.hookDepositsPerSession),
+    ].join('\n');
+};

package/dist/sessions/read-adoption.d.ts

@@ -0,0 +1,2 @@
+import { type DeriveFamily } from './read-support.js';
+export declare const deriveAdoption: DeriveFamily;

package/dist/sessions/read-adoption.js

@@ -0,0 +1,27 @@
+// Adoption (rank 6): when a tool was first and last seen (as the Monday of its UTC week, the grain of an index cell, rule 6), in how many weeks, and its share of all steps. Confounders: the operator's own rules move these, and
+// a program name can be noise.
+import { UNKNOWN, weekStartOf } from './cells.js';
+import { motifName } from './motif.js';
+import { body, firstDayOf, groupBy, lastDayOf, rate, settled, shapeUnits, total, unitCells, wilson } from './read-support.js';
+const WEEK_MS = 7 * 86_400_000;
+const weeksBetween = (from, to) => (from === null || to === null ? null : Math.floor((Date.parse(weekStartOf(to)) - Date.parse(from)) / WEEK_MS));
+export const deriveAdoption = ({ pool }) => {
+    const of = total(shapeUnits(pool, 'week'), settled);
+    return [...groupBy(unitCells(pool, 'week'), ({ cell }) => cell.motifId).values()].flatMap((group) => {
+        const [first] = group;
+        const cells = group.map(({ cell }) => cell);
+        const n = total(cells, settled);
+        if (first === undefined || n === 0)
+            return [];
+        const weeks = cells.map((cell) => cell.day).filter((week) => week !== UNKNOWN);
+        const lastWeek = lastDayOf(weeks);
+        return [
+            body('adoption', cells, {
+                slice: { motif: motifName(first.motif), level: first.motif.level },
+                value: { share: rate(n, of), of, firstWeek: firstDayOf(weeks), lastWeek, weeks: new Set(weeks).size, weeksSinceLast: weeksBetween(lastWeek, pool.lastDay) },
+                n,
+                interval: wilson(n, of),
+            }),
+        ];
+    });
+};

package/dist/sessions/read-call-shape.d.ts

@@ -0,0 +1,2 @@
+import { type DeriveFamily } from './read-support.js';
+export declare const deriveCallShape: DeriveFamily;

package/dist/sessions/read-call-shape.js

@@ -0,0 +1,25 @@
+// Call shape (the fit family's other method): one tool and its input key names, over the floors a shape needs before a hook may push it. A shape is what a pre-tool hook can
+// compute from the call it is about to run, so this read is what a push cites. A failure is not in a cell by shape, so its evidence is the failed one-step cells of the
+// tool's action on the days the shape failed. Same confounders as `read-fit.ts`: a failure is not a misfit, and prompt class is not adjusted for.
+import { shapeMotif } from './motif.js';
+import { CALL_SHAPE_METHOD } from './read.js';
+import { actionOfShape, fitReads, toolShapeId } from './recall-reads.js';
+import { body, atGrain, rate, wilson } from './read-support.js';
+export const deriveCallShape = ({ pool, store }) => fitReads(store).flatMap((read) => {
+    const action = actionOfShape(read.tool, read.harnesses);
+    const motifId = shapeMotif([{ action, identity: null }]).motifId;
+    const within = (day) => read.firstDay !== null && read.lastDay !== null && day >= read.firstDay && day <= read.lastDay;
+    const cells = atGrain(pool, 'day').filter((cell) => cell.motifId === motifId && cell.failed > 0 && within(cell.day));
+    // A shape whose failures are in no cell has nothing to cite, so it is not a read: its answers keep their stand-in.
+    if (cells.length === 0)
+        return [];
+    const calls = read.calls ?? read.count;
+    return [
+        body('fit', cells, {
+            slice: { shape: toolShapeId(read.tool, read.keys), action },
+            value: { failureRate: rate(read.count, calls), failed: read.count, calls },
+            n: read.count,
+            interval: wilson(read.count, calls),
+        }, CALL_SHAPE_METHOD),
+    ];
+});

package/dist/sessions/read-change.d.ts

@@ -0,0 +1,2 @@
+import { type DeriveFamily } from './read-support.js';
+export declare const deriveChange: DeriveFamily;

package/dist/sessions/read-change.js

@@ -0,0 +1,30 @@
+// Change (rank 4), at order 1: each tool's share and failure rate inside one harness version bucket. What moved between two buckets is a relation between
+// these reads, so it is order 2 (spec Section 6) and composes on them. Confounders: effort, role by brief, rule commits, class drift, and date.
+import { bucketFields, UNKNOWN } from './cells.js';
+import { motifName } from './motif.js';
+import { body, firstDayOf, groupBy, lastDayOf, rate, settled, shapeUnits, total, unitCells, wilson } from './read-support.js';
+const scopeOf = (cell) => {
+    const { harness, harnessBucket } = bucketFields(cell.frameBucket);
+    return `${harness}/${harnessBucket}`;
+};
+export const deriveChange = ({ pool }) => {
+    const steps = new Map([...groupBy(shapeUnits(pool, 'week'), scopeOf)].map(([scope, cells]) => [scope, total(cells, settled)]));
+    return [...groupBy(unitCells(pool, 'week'), ({ cell }) => `${cell.motifId}/${scopeOf(cell)}`).values()].flatMap((group) => {
+        const [first] = group;
+        const cells = group.map(({ cell }) => cell);
+        const n = total(cells, settled);
+        if (first === undefined || n === 0)
+            return [];
+        const of = steps.get(scopeOf(first.cell)) ?? 0;
+        const { harness, harnessBucket } = bucketFields(first.cell.frameBucket);
+        const weeks = cells.map((cell) => cell.day).filter((week) => week !== UNKNOWN);
+        return [
+            body('change', cells, {
+                slice: { motif: motifName(first.motif), level: first.motif.level, harness, harnessBucket },
+                value: { share: rate(n, of), of, failureRate: rate(total(cells, (cell) => cell.failed), n), firstWeek: firstDayOf(weeks), lastWeek: lastDayOf(weeks) },
+                n,
+                interval: wilson(n, of),
+            }),
+        ];
+    });
+};

package/dist/sessions/read-cost.d.ts

@@ -0,0 +1,4 @@
+import { type DeriveFamily } from './read-support.js';
+/** The ISO 8601 week of a UTC day: the week belongs to the year of its Thursday. */
+export declare const isoWeek: (day: string) => string;
+export declare const deriveCost: DeriveFamily;

package/dist/sessions/read-cost.js

@@ -0,0 +1,37 @@
+// Cost (rank 3): tokens and wall time per prompt, by prompt class, model, and ISO week. Confounders: class drift, subagent work outside the prompt's own usage, and
+// task size, which nothing here can see. Tokens are plain counts, not priced. A prompt with no wall time adds no seconds and stays in the denominator, so seconds per prompt understates.
+import { bucketFields, EFFORT_CLASS, UNKNOWN } from './cells.js';
+import { motifName } from './motif.js';
+import { body, atGrain, groupBy, rate, settled, total } from './read-support.js';
+const DAY_MS = 86_400_000;
+/** The ISO 8601 week of a UTC day: the week belongs to the year of its Thursday. */
+export const isoWeek = (day) => {
+    const millis = Date.parse(day);
+    const weekday = (new Date(millis).getUTCDay() + 6) % 7;
+    const thursday = new Date(millis - weekday * DAY_MS + 3 * DAY_MS);
+    const year = thursday.getUTCFullYear();
+    const week = Math.floor((thursday.getTime() - Date.UTC(year, 0, 1)) / (7 * DAY_MS)) + 1;
+    return `${String(year)}-W${String(week).padStart(2, '0')}`;
+};
+const weekOf = (cell) => (cell.day === UNKNOWN ? UNKNOWN : isoWeek(cell.day));
+export const deriveCost = ({ pool }) => {
+    const classed = atGrain(pool, 'week').flatMap((cell) => {
+        const motif = pool.motifs.get(cell.motifId);
+        return motif?.level === 'class' && !motif.cls?.startsWith(EFFORT_CLASS) ? [{ cell, motif, model: bucketFields(cell.frameBucket).model }] : [];
+    });
+    return [...groupBy(classed, ({ cell, model }) => `${cell.motifId}/${model}/${weekOf(cell)}`).values()].flatMap((group) => {
+        const [first] = group;
+        if (first === undefined)
+            return [];
+        const cells = group.map(({ cell }) => cell);
+        const prompts = total(cells, settled);
+        return [
+            body('cost', cells, {
+                slice: { class: motifName(first.motif), model: first.model, week: weekOf(first.cell) },
+                value: { tokensPerPrompt: Math.round(total(cells, (cell) => cell.tokens) / prompts), secondsPerPrompt: Math.round(total(cells, (cell) => cell.durationMs) / prompts / 1000), errorShare: rate(total(cells, (cell) => cell.failed), prompts) },
+                n: prompts,
+                interval: null,
+            }),
+        ];
+    });
+};

package/dist/sessions/read-day-move.d.ts

@@ -0,0 +1,3 @@
+import { type DeriveRelation } from './read-order.js';
+export declare const nextDay: (day: string) => string;
+export declare const deriveDayMove: DeriveRelation;

package/dist/sessions/read-day-move.js

@@ -0,0 +1,65 @@
+// Day move (spec Section 6, order 2): a tool's failure rate from one calendar day to the next, for a tool above the floor of calls on both, and its share, for a tool on either
+// of two days above the floor of steps. Unlike the other order 2 families this is not screened: it is the input lead-lag stands on, and keeping only the large moves, or only the
+// tools still called after a fall, would select that read on its outcome. So a row here is not a finding.
+import { UNKNOWN } from './cells.js';
+import { differenceOf, estimateOf, relate } from './read-order.js';
+import { groupBy, wilson } from './read-support.js';
+const DAY_MS = 86_400_000;
+const ISO_DAY_LENGTH = 10;
+export const nextDay = (day) => new Date(Date.parse(`${day}T00:00:00Z`) + DAY_MS).toISOString().slice(0, ISO_DAY_LENGTH);
+const stepsOf = (read) => {
+    const { steps } = read.value;
+    return typeof steps === 'number' ? steps : 0;
+};
+/** A tool's share on a day, measured against that day's steps. With no read of the tool there, it is zero of them, and that is a measurement, not a gap. The read's interval is on its failure rate, so a share's comes from its counts. */
+const shareOn = (tool, witness) => {
+    const interval = wilson(tool?.n ?? 0, stepsOf(witness));
+    const value = tool === undefined ? 0 : tool.value.share;
+    return typeof value !== 'number' || interval === null ? undefined : { value, interval };
+};
+const sliceOf = (tool, metric, from, to) => ({ motif: tool.slice.motif ?? UNKNOWN, level: tool.slice.level ?? UNKNOWN, metric, from, to });
+const moveOver = (before, after) => {
+    const move = differenceOf(after, before);
+    return { value: { before: before.value, after: after.value, move: move.value }, interval: move.interval };
+};
+/** Held to the tool's calls on both days: a failure rate is a rate of those calls. */
+const failureMove = (earlier, later, from, to) => {
+    const before = estimateOf(earlier, 'failureRate');
+    const after = estimateOf(later, 'failureRate');
+    if (before === undefined || after === undefined)
+        return [];
+    const read = relate('day-move', [earlier, later], { slice: sliceOf(earlier, 'failureRate', from, to), ...moveOver(before, after) });
+    return read === undefined ? [] : [read];
+};
+/** Held to each day's steps and not the tool's calls: a floor on the calls would drop a tool for falling, which is the outcome a read over these moves asks about. */
+const shareMove = (tool, sides, from, to) => {
+    const [earlier, later] = sides;
+    const before = shareOn(earlier.tool, earlier.witness);
+    const after = shareOn(later.tool, later.witness);
+    if (before === undefined || after === undefined)
+        return [];
+    const read = relate('day-move', [earlier.tool ?? earlier.witness, later.tool ?? later.witness], {
+        slice: sliceOf(tool, 'share', from, to),
+        ...moveOver(before, after),
+        trials: stepsOf,
+    });
+    return read === undefined ? [] : [read];
+};
+export const deriveDayMove = (reads) => {
+    const toolDays = reads.filter((read) => read.family === 'tool-day');
+    const witnesses = new Map([...groupBy(toolDays, (read) => read.slice.day ?? UNKNOWN)].flatMap(([day, [witness]]) => (witness === undefined ? [] : [[day, witness]])));
+    return [...groupBy(toolDays, (read) => read.slice.motif)].flatMap(([, group]) => {
+        const byDay = new Map(group.map((read) => [read.slice.day, read]));
+        return [...witnesses].flatMap(([from, earlierWitness]) => {
+            const to = nextDay(from);
+            const laterWitness = witnesses.get(to);
+            const earlier = byDay.get(from);
+            const later = byDay.get(to);
+            const tool = earlier ?? later;
+            if (laterWitness === undefined || tool === undefined)
+                return [];
+            const failure = earlier === undefined || later === undefined ? [] : failureMove(earlier, later, from, to);
+            return [...failure, ...shareMove(tool, [{ tool: earlier, witness: earlierWitness }, { tool: later, witness: laterWitness }], from, to)];
+        });
+    });
+};

package/dist/sessions/read-fit.d.ts

@@ -0,0 +1,7 @@
+import { type DeriveFamily } from './read-support.js';
+export declare const deriveFit: DeriveFamily;
+/**
+ * Fit by environment: how often a name fails on a platform and shell, from the version-free cells beside the versioned ones. The two sets count the same calls and are never summed, so
+ * this read is its own, and a read of the version cells does not see these cells (`atGrain`). A shell the frame does not name reads as `unknown`, as a missing model does.
+ */
+export declare const deriveFitEnvironment: DeriveFamily;

package/dist/sessions/read-fit.js

@@ -0,0 +1,41 @@
+// Fit (rank 2): how often a tool fails on this frame, by harness version bucket and model. Effort is not in a cell (rule 3), so it is not a slice. Confounders it does not remove: a failure is not a
+// misfit, red tests can be the method, effort, and prompt class is not adjusted for.
+import { bucketFields, environmentFieldsOf } from './cells.js';
+import { motifName } from './motif.js';
+import { body, environmentCells, groupBy, rate, settled, total, unitCells, wilson } from './read-support.js';
+export const deriveFit = ({ pool }) => [...groupBy(unitCells(pool, 'week'), ({ cell }) => `${cell.motifId}/${cell.frameBucket}`).values()].flatMap((group) => {
+    const [first] = group;
+    const cells = group.map(({ cell }) => cell);
+    const n = total(cells, settled);
+    if (first === undefined || n === 0)
+        return [];
+    const failed = total(cells, (cell) => cell.failed);
+    return [
+        body('fit', cells, {
+            slice: { motif: motifName(first.motif), level: first.motif.level, ...bucketFields(first.cell.frameBucket) },
+            value: { failureRate: rate(failed, n), failed, ok: n - failed },
+            n,
+            interval: wilson(failed, n),
+        }),
+    ];
+});
+/**
+ * Fit by environment: how often a name fails on a platform and shell, from the version-free cells beside the versioned ones. The two sets count the same calls and are never summed, so
+ * this read is its own, and a read of the version cells does not see these cells (`atGrain`). A shell the frame does not name reads as `unknown`, as a missing model does.
+ */
+export const deriveFitEnvironment = ({ pool }) => [...groupBy(environmentCells(pool), (cell) => `${cell.motifId}/${cell.frameBucket}`).values()].flatMap((group) => {
+    const [first] = group;
+    const motif = first === undefined ? undefined : pool.motifs.get(first.motifId);
+    const n = total(group, settled);
+    if (first === undefined || motif === undefined || n === 0)
+        return [];
+    const failed = total(group, (cell) => cell.failed);
+    return [
+        body('fit', group, {
+            slice: { motif: motifName(motif), level: motif.level, ...environmentFieldsOf(first.frameBucket) },
+            value: { failureRate: rate(failed, n), failed, ok: n - failed },
+            n,
+            interval: wilson(failed, n),
+        }),
+    ];
+});

package/dist/sessions/read-interaction.d.ts

@@ -0,0 +1,5 @@
+import { type Candidate, type DeriveRelation } from './read-order.js';
+import type { Read } from './read.js';
+/** The comparisons a store's fit reads allow, above the floor, whether or not any of them moved. */
+export declare const interactionCandidates: (reads: readonly Read[]) => Candidate[];
+export declare const deriveInteraction: DeriveRelation;

package/dist/sessions/read-interaction.js

@@ -0,0 +1,62 @@
+// Interaction (spec Section 6, order 2): a tool fails more on one tier than another, beyond how those two tiers differ on every other tool. The difference of differences is
+// what makes it an interaction: a tier that fails more on everything has a main effect, usually the harder work it is given. The axis is the tier assigned, not a model version
+// (ruling mrd5591-08: one version per model on this store), and comparisons hold the version bucket constant. Effort is not in a cell (rule 3), so nothing here holds it. Confounders it does not remove: task assignment by
+// tier, which is the operator's own choice and the largest of them, effort, prompt class, and a failure not being a misfit.
+import { UNKNOWN } from './cells.js';
+import { candidateOf, differenceOf, estimateOf, screen, TRIALS_FLOOR } from './read-order.js';
+import { groupBy, rate, wilson } from './read-support.js';
+import { toolKey } from './read-version-boundary.js';
+const countOf = (read, metric) => {
+    const value = read.value[metric];
+    return typeof value === 'number' ? value : 0;
+};
+const tierOf = (model, reads) => ({ model, tools: new Map(reads.map((read) => [toolKey(read), read])), shapes: reads.filter((read) => read.slice.level === 'shape') });
+/** A tier's failure rate on every step but this tool's. A named tool's steps are in its action's shape read, so subtracting it works at either level. */
+const restOf = (tier, read) => {
+    const failed = tier.shapes.reduce((sum, shape) => sum + countOf(shape, 'failed'), 0) - countOf(read, 'failed');
+    const trials = tier.shapes.reduce((sum, shape) => sum + shape.n, 0) - read.n;
+    const value = rate(failed, trials);
+    const interval = wilson(failed, trials);
+    return trials < TRIALS_FLOOR || value === null || interval === null ? undefined : { value, interval, cites: tier.shapes.filter((shape) => shape.readId !== read.readId) };
+};
+const candidateFor = (a, b, key, scope) => {
+    const readA = a.tools.get(key);
+    const readB = b.tools.get(key);
+    if (readA === undefined || readB === undefined)
+        return undefined;
+    const failureA = estimateOf(readA, 'failureRate');
+    const failureB = estimateOf(readB, 'failureRate');
+    const restA = restOf(a, readA);
+    const restB = restOf(b, readB);
+    if (failureA === undefined || failureB === undefined || restA === undefined || restB === undefined)
+        return undefined;
+    const gap = differenceOf(failureA, failureB);
+    const restGap = differenceOf(restA, restB);
+    const interaction = differenceOf(gap, restGap);
+    const [level = UNKNOWN, motif = UNKNOWN] = key.split('\n');
+    return candidateOf('interaction', [readA, readB], [gap, interaction], {
+        slice: { motif, level, ...scope, tierA: a.model, tierB: b.model },
+        value: { failureA: failureA.value, failureB: failureB.value, gap: gap.value, restGap: restGap.value, interaction: interaction.value },
+        interval: interaction.interval,
+        cites: [...restA.cites, ...restB.cites],
+    });
+};
+/** The comparisons a store's fit reads allow, above the floor, whether or not any of them moved. */
+export const interactionCandidates = (reads) => {
+    const known = reads.filter((read) => read.family === 'fit' && read.slice.model !== UNKNOWN && read.slice.harnessBucket !== UNKNOWN);
+    const frames = groupBy(known, (read) => `${read.slice.harness ?? UNKNOWN}\n${read.slice.harnessBucket ?? UNKNOWN}`);
+    return [...frames].flatMap(([frame, group]) => {
+        const [harness = UNKNOWN, harnessBucket = UNKNOWN] = frame.split('\n');
+        const tiers = [...groupBy(group, (read) => read.slice.model ?? UNKNOWN)].map(([model, inTier]) => tierOf(model, inTier)).sort((a, b) => (a.model < b.model ? -1 : 1));
+        return tiers.flatMap((a, index) => tiers.slice(index + 1).flatMap((b) => [...a.tools.keys()].flatMap((key) => {
+            const candidate = candidateFor(a, b, key, { harness, harnessBucket });
+            return candidate === undefined ? [] : [candidate];
+        })));
+    });
+};
+/**
+ * The gap and the interaction point the same way, so the tool moves toward that tier whatever the other tools do: `moved` asks only that each gate is large, not its sign. A gap and an interaction
+ * of opposite signs mean the tool resists the main effect (it still fails more on that tier, only by less than the other tools do), which is not a tool that works on one tier and not the other.
+ */
+const sameSign = ({ gates }) => gates.every((gate) => gate.value > 0) || gates.every((gate) => gate.value < 0);
+export const deriveInteraction = (reads) => screen(interactionCandidates(reads), sameSign);

package/dist/sessions/read-lead-lag.d.ts

@@ -0,0 +1,15 @@
+import { type DeriveRelation, type Estimate } from './read-order.js';
+import type { Read } from './read.js';
+/** The fewest pairs on each side of the cut. */
+export declare const PAIRS_FLOOR = 30;
+export interface LeadLagPair {
+    /** The failure move. */
+    x: Estimate;
+    /** The share move that shares no day with it. */
+    y: Estimate;
+    /** The day the outcome is known: the last day of the share move. */
+    day: string;
+    reads: readonly [Read, Read];
+}
+export declare const leadLagPairs: (reads: readonly Read[]) => LeadLagPair[];
+export declare const deriveLeadLag: DeriveRelation;