@manyoars/oars 0.2.0 → 0.4.0

package/dist/sessions/read-lead-lag.js

@@ -0,0 +1,81 @@
+// Lead-lag (spec Section 6, order 3), the labeled experiment: does a tool's failure rate moving come before its share moving? Chosen over a model release moving tool choice
+// because each model has one version here with no release date (ruling mrd5591-08), and two version boundaries are too few to cut in time, while consecutive days over many tools
+// can be cut. A search over pairs of tools was rejected: it manufactures the false patterns Section 6 warns about, and this is one question asked once.
+//
+// A pair shares no day between its sides. A failure move ending on day d is paired with the share move from d+1 to d+2, not d to d+1: a burst of failing calls on d lifts both the
+// day's failure rate and its share, so a pair that read d twice would show a negative slope with no lead in it, and that slope would hold on later days and pass the check.
+//
+// Fit on earlier days and scored on later ones, with a pair dated by the day its outcome is known. It exists or not by its floor and states its score either way, labeled in
+// every output. No path serves it to an agent: Section 6 requires this check before one, and this read is the check's first run, not a licensed read.
+//
+// What the check does not remove: shares sum to one, so tools on one day are not independent; steps cluster in sessions, so intervals run narrow; a failure move measured with
+// error flattens the slope; and one operator's changes of habit move many tools at once.
+import { UNKNOWN } from './cells.js';
+import { estimateOf, relate } from './read-order.js';
+import { nextDay } from './read-day-move.js';
+import { rate, round, wilson, Z_95 } from './read-support.js';
+/** The fewest pairs on each side of the cut. */
+export const PAIRS_FLOOR = 30;
+const FIT_SHARE = 0.7;
+const SIGMA_FLOOR = 0.0001;
+const CHANCE = 0.5;
+const keyOf = (motif, metric, from) => `${motif ?? UNKNOWN}\n${metric}\n${from ?? UNKNOWN}`;
+export const leadLagPairs = (reads) => {
+    const moves = reads.filter((read) => read.family === 'day-move');
+    const byStart = new Map(moves.map((read) => [keyOf(read.slice.motif, read.slice.metric ?? UNKNOWN, read.slice.from), read]));
+    return moves.flatMap((lead) => {
+        if (lead.slice.metric !== 'failureRate')
+            return [];
+        const lag = byStart.get(keyOf(lead.slice.motif, 'share', nextDay(lead.slice.to ?? UNKNOWN)));
+        const x = estimateOf(lead, 'move');
+        const y = lag === undefined ? undefined : estimateOf(lag, 'move');
+        if (lag === undefined || x === undefined || y === undefined)
+            return [];
+        return [{ x, y, day: lag.slice.to ?? UNKNOWN, reads: [lead, lag] }];
+    });
+};
+/** A share move's weight: a thin day's move says less. The floor keeps one pair with no measured spread from outweighing the rest. */
+const weightOf = ({ y }) => {
+    const sigma = Math.max((y.interval.high - y.interval.low) / (2 * Z_95), SIGMA_FLOOR);
+    return 1 / (sigma * sigma);
+};
+const weightedSum = (pairs, term) => pairs.reduce((sum, pair) => sum + weightOf(pair) * term(pair), 0);
+/** The later days' weighted error against predicting no move at all: above zero means the slope from earlier days beat that. With nothing to explain there is no skill. */
+const skillOf = (pairs, slope) => {
+    const zero = weightedSum(pairs, ({ y }) => y.value * y.value);
+    if (zero === 0)
+        return 0;
+    return 1 - weightedSum(pairs, ({ x, y }) => (y.value - slope * x.value) ** 2) / zero;
+};
+/** How often a later day's share moved the way the slope said, among pairs where both moved. */
+const signsOf = (pairs, slope) => {
+    const moved = pairs.filter(({ x, y }) => x.value !== 0 && y.value !== 0);
+    const agreed = moved.filter(({ x, y }) => Math.sign(slope * x.value) === Math.sign(y.value)).length;
+    return { agreement: rate(agreed, moved.length), low: wilson(agreed, moved.length)?.low ?? 0 };
+};
+export const deriveLeadLag = (reads) => {
+    const pairs = leadLagPairs(reads);
+    const days = [...new Set(pairs.map(({ day }) => day))].sort();
+    const cut = Math.floor(days.length * FIT_SHARE);
+    const fitThrough = days[cut - 1];
+    const scoredFrom = days[cut];
+    if (fitThrough === undefined || scoredFrom === undefined)
+        return [];
+    const fit = pairs.filter(({ day }) => day <= fitThrough);
+    const scored = pairs.filter(({ day }) => day >= scoredFrom);
+    const leverage = weightedSum(fit, ({ x }) => x.value * x.value);
+    if (fit.length < PAIRS_FLOOR || scored.length < PAIRS_FLOOR || leverage === 0)
+        return [];
+    const slope = weightedSum(fit, ({ x, y }) => x.value * y.value) / leverage;
+    const margin = Z_95 * Math.sqrt(1 / leverage);
+    const skill = skillOf(scored, slope);
+    const signs = signsOf(scored, slope);
+    const passed = Math.abs(slope) > margin && skill > 0 && signs.low > CHANCE;
+    const read = relate('lead-lag', pairs.flatMap((pair) => pair.reads), {
+        slice: { lead: 'failureRate', lag: 'share', level: 'shape' },
+        value: { label: 'experimental', check: passed ? 'passed' : 'failed', slope: round(slope), skill: round(skill), signAgreement: signs.agreement, fitPairs: fit.length, scorePairs: scored.length, fitThrough, scoredFrom },
+        interval: { low: round(slope - margin), high: round(slope + margin), level: 0.95 },
+        n: pairs.length,
+    });
+    return read === undefined ? [] : [read];
+};

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

@@ -0,0 +1,6 @@
+import { type DeriveFamily } from './read-support.js';
+/** The baseline: the seven days before the day read. */
+export declare const LIVE_BASELINE_DAYS = 7;
+/** The days a read of `day` takes its baseline from, so a pool that serves the baseline separately names the same cells. */
+export declare const baselineDaysOf: (day: string) => string[];
+export declare const deriveLive: DeriveFamily;

package/dist/sessions/read-live.js

@@ -0,0 +1,38 @@
+import { motifName } from './motif.js';
+import { body, groupBy, rate, settled, total, unitCells, wilson } from './read-support.js';
+/** The baseline: the seven days before the day read. */
+export const LIVE_BASELINE_DAYS = 7;
+const DAY_MS = 86_400_000;
+const dayBefore = (day, back) => new Date(Date.parse(day) - back * DAY_MS).toISOString().slice(0, 10);
+/** The days a read of `day` takes its baseline from, so a pool that serves the baseline separately names the same cells. */
+export const baselineDaysOf = (day) => Array.from({ length: LIVE_BASELINE_DAYS }, (_, index) => dayBefore(day, index + 1));
+export const deriveLive = ({ pool }) => {
+    const units = unitCells(pool, 'day').filter(({ motif }) => motif.level === 'shape');
+    const stepsOn = new Map([...groupBy(units, ({ cell }) => cell.day)].map(([day, group]) => [day, total(group.map(({ cell }) => cell), settled)]));
+    return [...groupBy(units, ({ cell }) => cell.motifId).values()].flatMap((group) => {
+        const motif = group[0]?.motif;
+        if (motif === undefined)
+            return [];
+        const byDay = groupBy(group.map(({ cell }) => cell), (cell) => cell.day);
+        return [...byDay].flatMap(([day, cells]) => {
+            const n = total(cells, settled);
+            if (n === 0)
+                return [];
+            const of = stepsOn.get(day) ?? 0;
+            const trailing = baselineDaysOf(day);
+            const baselineCells = trailing.flatMap((earlier) => byDay.get(earlier) ?? []);
+            const baselineOf = trailing.reduce((sum, earlier) => sum + (stepsOn.get(earlier) ?? 0), 0);
+            const share = rate(n, of);
+            const baseline = rate(total(baselineCells, settled), baselineOf);
+            return [
+                // The read cites the day's cells only: a pool counts accounts over a read's inputs, and the baseline must not lift the floor of a day it does not hold (Section 4 rule 1).
+                body('live', cells, {
+                    slice: { motif: motifName(motif), day },
+                    value: { share, baseline, of, ratio: share === null || baseline === null || baseline === 0 ? null : rate(share, baseline) },
+                    n,
+                    interval: wilson(n, of),
+                }),
+            ];
+        });
+    });
+};

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

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

package/dist/sessions/read-method.js

@@ -0,0 +1,29 @@
+// Method (rank 7): a shape's share of all windows of its length, per model. The family would also read this by class; a cell holds no class, because a step has none, so
+// the class axis waits for a field on the cell. Confounders: task assignment by tier, effort, and no outcome label, so nothing here says a method is better.
+import { bucketFields } from './cells.js';
+import { motifName } from './motif.js';
+import { body, atGrain, groupBy, rate, settled, total, wilson } from './read-support.js';
+export const deriveMethod = ({ pool }) => {
+    const windows = atGrain(pool, 'week').flatMap((cell) => {
+        const motif = pool.motifs.get(cell.motifId);
+        return motif?.level === 'shape' && motif.steps.length >= 2 ? [{ cell, motif, model: bucketFields(cell.frameBucket).model }] : [];
+    });
+    const scopeTotals = new Map([...groupBy(windows, ({ motif, model }) => `${String(motif.steps.length)}/${model}`)].map(([scope, group]) => [scope, total(group.map(({ cell }) => cell), settled)]));
+    return [...groupBy(windows, ({ cell, model }) => `${cell.motifId}/${model}`).values()].flatMap((group) => {
+        const [first] = group;
+        const cells = group.map(({ cell }) => cell);
+        const n = total(cells, settled);
+        if (first === undefined || n === 0)
+            return [];
+        const length = first.motif.steps.length;
+        const of = scopeTotals.get(`${String(length)}/${first.model}`) ?? 0;
+        return [
+            body('method', cells, {
+                slice: { motif: motifName(first.motif), model: first.model, length: String(length) },
+                value: { share: rate(n, of), of, failureRate: rate(total(cells, (cell) => cell.failed), n) },
+                n,
+                interval: wilson(n, of),
+            }),
+        ];
+    });
+};

package/dist/sessions/read-next-step.d.ts

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

package/dist/sessions/read-next-step.js

@@ -0,0 +1,35 @@
+// Next step (rank 8): from a prefix of one to three actions, which action came next, by count. Confounders: no outcome label, so the most common next step is
+// not the right one; a scoring found this barely above repeating the last tool. Remaining cost is not read here, because a window's cost stops at the window.
+import {} from './cells.js';
+import { motifName, shapeMotif } from './motif.js';
+import { body, atGrain, groupBy, rate, settled, total, wilson } from './read-support.js';
+const countsOf = (group) => {
+    const counts = {};
+    for (const { cell, next } of group)
+        counts[next] = (counts[next] ?? 0) + settled(cell);
+    return counts;
+};
+export const deriveNextStep = ({ pool }) => {
+    const extensions = atGrain(pool, 'week').flatMap((cell) => {
+        const motif = pool.motifs.get(cell.motifId);
+        const last = motif?.steps.at(-1);
+        return motif?.level === 'shape' && motif.steps.length >= 2 && last !== undefined ? [{ cell, prefix: motif.steps.slice(0, -1), next: last.action }] : [];
+    });
+    return [...groupBy(extensions, ({ prefix }) => shapeMotif(prefix).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 next = countsOf(group);
+        const [top, topCount] = Object.entries(next).sort(([a, one], [b, two]) => two - one || (a < b ? -1 : 1))[0] ?? ['', 0];
+        return [
+            body('next-step', cells, {
+                slice: { prefix: motifName(shapeMotif(first.prefix)), length: String(first.prefix.length) },
+                value: { next, top, topShare: rate(topCount, n) },
+                n,
+                interval: wilson(topCount, n),
+            }),
+        ];
+    });
+};

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

@@ -0,0 +1,54 @@
+import { type Family, type Read, type ReadInterval, type ReadSlice, type ReadValue } from './read.js';
+import { type ReadBody } from './read-support.js';
+/** A family over reads: it reads every read of the stages before it. */
+export type DeriveRelation = (reads: readonly Read[]) => ReadBody[];
+/** The fewest trials a rate may rest on and still be compared. */
+export declare const TRIALS_FLOOR = 30;
+/** The smallest move worth stating. Large samples clear zero on moves no one would act on, so a move has to be large as well as unlikely. */
+export declare const MIN_MOVE = 0.01;
+/** A number and its interval, as an input states them. */
+export interface Estimate {
+    value: number;
+    interval: ReadInterval;
+}
+/**
+ * `later - earlier`, by MOVER (Newcombe 1998, Zou and Donner 2008): each side of the result takes the sides of the inputs that could push it there, so a skewed Wilson
+ * interval stays skewed. It holds at any order, because it asks only for a value and an interval. It treats the two inputs as independent, which two periods nearly are.
+ */
+export declare const differenceOf: (later: Estimate, earlier: Estimate) => Estimate;
+/** One named number of a read with the read's interval, or nothing to propagate. */
+export declare const estimateOf: (read: Read, metric: string) => Estimate | undefined;
+/** What a read's interval rests on: a share's denominator, or else its own count. A rare tool's share of many steps is well measured, so its count would be the wrong floor. */
+export declare const trialsOf: (read: Read) => number;
+/**
+ * Whether an estimate's interval clears zero once `tested` comparisons were made, the Bonferroni way: the half-width toward zero scales from 95 percent to the family's z.
+ * `sqrt(2 ln(2m / alpha))` is the Chernoff bound on that z. It runs a little wide and needs no quantile table, and a wide screen suits inputs that count a step as independent.
+ */
+export declare const clearsZero: (estimate: Estimate, tested: number) => boolean;
+/** A move a reader should hear about: past the screen for `tested` comparisons, and large enough to matter. */
+export declare const moved: (estimate: Estimate, tested: number) => boolean;
+export interface Relation {
+    slice: ReadSlice;
+    value: ReadValue;
+    interval: ReadInterval;
+    /** The observations behind the value, when they are not the inputs' trials: a slope over pairs counts pairs. */
+    n?: number;
+    /** Reads this one cites but does not measure on: a witness for a total. They are not held to the floor. */
+    cites?: readonly Read[];
+    /** What the floor holds an input to, when the value rests on something other than `trialsOf`: a share read from a read whose interval is on another rate. */
+    trials?: (read: Read) => number;
+}
+/**
+ * A read over reads, or nothing when any measured input sits below the floor or has no interval. `n` and `clusters` state the weakest side: a relation knows no more than its
+ * thinnest input, and summing trials up a chain would count one step many times.
+ */
+export declare const relate: (family: Family, inputs: readonly Read[], relation: Relation) => ReadBody | undefined;
+/** A comparison made, before the screen: the read it would be, and every estimate that has to move for it to exist. */
+export interface Candidate {
+    gates: readonly Estimate[];
+    body: ReadBody;
+}
+/** A comparison above the floor, which therefore counts toward what the screen allows for. */
+export declare const candidateOf: (family: Family, inputs: readonly Read[], gates: readonly Estimate[], relation: Relation) => Candidate | undefined;
+/** The reads that survive the screen over everything compared, each stating how many comparisons that was: `tested * 0.05` is what chance alone would offer an unscreened reader. */
+export declare const screen: (candidates: readonly Candidate[], claims?: (candidate: Candidate) => boolean) => ReadBody[];

package/dist/sessions/read-order.js

@@ -0,0 +1,62 @@
+// Reads over reads (spec Section 6): noise compounds, so an interval comes from the inputs and a read below its floor does not exist. Every family above order 1 builds its
+// read here, which is how the floor stays a property of the read and not a filter on a listing. Order 1 has no floor, because a cell is the operator's own; a relation
+// between rates has one, because two thin rates differ by chance and read as news.
+import { METHODS } from './read.js';
+import { round, Z_95 } from './read-support.js';
+/** The fewest trials a rate may rest on and still be compared. */
+export const TRIALS_FLOOR = 30;
+/** The smallest move worth stating. Large samples clear zero on moves no one would act on, so a move has to be large as well as unlikely. */
+export const MIN_MOVE = 0.01;
+const FAMILYWISE_ERROR = 0.05;
+/**
+ * `later - earlier`, by MOVER (Newcombe 1998, Zou and Donner 2008): each side of the result takes the sides of the inputs that could push it there, so a skewed Wilson
+ * interval stays skewed. It holds at any order, because it asks only for a value and an interval. It treats the two inputs as independent, which two periods nearly are.
+ */
+export const differenceOf = (later, earlier) => {
+    const value = later.value - earlier.value;
+    const down = Math.hypot(later.value - later.interval.low, earlier.interval.high - earlier.value);
+    const up = Math.hypot(later.interval.high - later.value, earlier.value - earlier.interval.low);
+    return { value: round(value), interval: { low: round(value - down), high: round(value + up), level: later.interval.level } };
+};
+/** One named number of a read with the read's interval, or nothing to propagate. */
+export const estimateOf = (read, metric) => {
+    const value = read.value[metric];
+    return typeof value === 'number' && read.interval !== null ? { value, interval: read.interval } : undefined;
+};
+/** What a read's interval rests on: a share's denominator, or else its own count. A rare tool's share of many steps is well measured, so its count would be the wrong floor. */
+export const trialsOf = (read) => {
+    const { of } = read.value;
+    return typeof of === 'number' ? of : read.n;
+};
+/**
+ * Whether an estimate's interval clears zero once `tested` comparisons were made, the Bonferroni way: the half-width toward zero scales from 95 percent to the family's z.
+ * `sqrt(2 ln(2m / alpha))` is the Chernoff bound on that z. It runs a little wide and needs no quantile table, and a wide screen suits inputs that count a step as independent.
+ */
+export const clearsZero = (estimate, tested) => {
+    const { value, interval } = estimate;
+    const toZero = value > 0 ? value - interval.low : interval.high - value;
+    return value !== 0 && Math.abs(value) > toZero * (Math.sqrt(2 * Math.log((2 * tested) / FAMILYWISE_ERROR)) / Z_95);
+};
+/** A move a reader should hear about: past the screen for `tested` comparisons, and large enough to matter. */
+export const moved = (estimate, tested) => Math.abs(estimate.value) >= MIN_MOVE && clearsZero(estimate, tested);
+/**
+ * A read over reads, or nothing when any measured input sits below the floor or has no interval. `n` and `clusters` state the weakest side: a relation knows no more than its
+ * thinnest input, and summing trials up a chain would count one step many times.
+ */
+export const relate = (family, inputs, relation) => {
+    const { cites = [], trials = trialsOf, n = Math.min(...inputs.map(trials)), ...fields } = relation;
+    if (inputs.some((read) => read.interval === null || trials(read) < TRIALS_FLOOR))
+        return undefined;
+    const all = [...inputs, ...cites];
+    return { family, method: METHODS[family].name, methodVersion: METHODS[family].version, inputs: all.map((read) => read.readId), clusters: Math.min(...all.map((read) => read.clusters)), basis: 'all', n, ...fields };
+};
+/** A comparison above the floor, which therefore counts toward what the screen allows for. */
+export const candidateOf = (family, inputs, gates, relation) => {
+    const body = relate(family, inputs, relation);
+    return body === undefined ? undefined : { gates, body };
+};
+/** The reads that survive the screen over everything compared, each stating how many comparisons that was: `tested * 0.05` is what chance alone would offer an unscreened reader. */
+export const screen = (candidates, claims = () => true) => {
+    const tested = candidates.length;
+    return candidates.filter((candidate) => claims(candidate) && candidate.gates.every((gate) => moved(gate, tested))).map(({ body }) => ({ ...body, value: { ...body.value, tested } }));
+};

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

@@ -0,0 +1,8 @@
+import type { Family, Read } from './read.js';
+export interface NotReadable {
+    family: Family;
+    what: string;
+    why: string;
+}
+export declare const notReadable: (reads: readonly Read[]) => NotReadable[];
+export declare const formatNotReadable: (rows: readonly NotReadable[]) => string[];

package/dist/sessions/read-readable.js

@@ -0,0 +1,24 @@
+// What this store cannot read, stated rather than forced (ruling mrd5591-08). A family that finds nothing has made no claim about why, so a reader of an empty family could take
+// "no reads" for "nothing moved". These rows separate the two: a question the store cannot ask from one it asked and got no answer to.
+import { interactionCandidates } from './read-interaction.js';
+import { leadLagPairs, PAIRS_FLOOR } from './read-lead-lag.js';
+import { substitutionCandidates } from './read-substitution.js';
+import { boundariesOf, versionBoundaryCandidates } from './read-version-boundary.js';
+export const notReadable = (reads) => {
+    const rows = [{ family: 'version-boundary', what: 'a model version boundary', why: 'a cell holds a model name and no version of it' }];
+    const noBoundary = boundariesOf(reads).length === 0;
+    const whyNot = (candidates) => (noBoundary ? 'no harness has two version buckets' : candidates.length === 0 ? 'no comparison clears the floor' : undefined);
+    const boundaryWhy = whyNot(versionBoundaryCandidates(reads));
+    if (boundaryWhy !== undefined)
+        rows.push({ family: 'version-boundary', what: 'a harness version boundary', why: boundaryWhy });
+    const substitutionWhy = whyNot(substitutionCandidates(reads));
+    if (substitutionWhy !== undefined)
+        rows.push({ family: 'substitution', what: 'one tool replacing another at a boundary', why: substitutionWhy });
+    if (interactionCandidates(reads).length === 0)
+        rows.push({ family: 'interaction', what: 'a tool across the tiers assigned', why: 'no tool clears the floor on two tiers in one frame' });
+    if (!reads.some((read) => read.family === 'lead-lag')) {
+        rows.push({ family: 'lead-lag', what: 'a failure move leading a share move (experimental)', why: `${String(leadLagPairs(reads).length)} pairs, and it needs ${String(PAIRS_FLOOR)} on each side of the cut` });
+    }
+    return rows;
+};
+export const formatNotReadable = (rows) => (rows.length === 0 ? [] : ['Not readable on this store:', ...rows.map(({ family, what, why }) => `  ${family}: ${what}: ${why}`)]);

package/dist/sessions/read-recovery-edge.d.ts

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

package/dist/sessions/read-recovery-edge.js

@@ -0,0 +1,26 @@
+// Recovery from cells (rank 1, t868): what others did next after a failed call, by (failed action, `errorCode`, next action). One read for each edge, citing its own week cell only, so a count under the floor in
+// another edge is not lifted by this one. It states counts, never a fix: there is no fix field, `none` means nothing followed in that prompt, and an edit that followed is not that the failure was resolved.
+// Confounders: the work the failure interrupted, the user's refusals and policy denials (their own codes), and that a call's next action is one of many a prompt may take.
+import { parseRecoveryClass } from './cells.js';
+import { RECOVERY_EDGE_METHOD } from './read.js';
+import { atGrain, body, groupBy, rate, total, wilson } from './read-support.js';
+export const deriveRecoveryEdges = ({ pool }) => {
+    const edges = atGrain(pool, 'week').flatMap((cell) => {
+        const cls = pool.motifs.get(cell.motifId)?.cls;
+        const parts = cls === undefined || cls === null ? null : parseRecoveryClass(cls);
+        return parts === null ? [] : [{ cell, ...parts }];
+    });
+    // The denominator is the failures of the same action and code in the same frame bucket and week, over the cells this pool holds. A bundle's pool holds served cells only (`bundleOf`), so no `of` sums a cell under the floor and subtraction reveals none; the local read has no floor and sums what it holds.
+    const keyOf = ({ cell, code, failed }) => `${cell.frameBucket}/${cell.day}/${code}/${failed}`;
+    const failures = new Map([...groupBy(edges, keyOf)].map(([key, group]) => [key, total(group.map(({ cell }) => cell), (cell) => cell.failed)]));
+    return edges.flatMap((edge) => {
+        const { cell, code, failed, next } = edge;
+        const followed = cell.failed;
+        const of = failures.get(keyOf(edge)) ?? 0;
+        return followed === 0
+            ? []
+            : [
+                body('recovery', [cell], { slice: { action: failed, errorCode: code, next, week: cell.day }, value: { followed, of, share: rate(followed, of) }, n: followed, interval: wilson(followed, of) }, RECOVERY_EDGE_METHOD),
+            ];
+    });
+};

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

@@ -0,0 +1,20 @@
+import { type DeriveFamily, type FamilyInput, type ReadBody } from './read-support.js';
+/** Why a signature record has no read. Each is a record with nothing to cite, and a read that cites nothing is refused. */
+export type RecoveryDrop = 
+/** No call of this action in any cell, such as one a version-2 deposit left with no tool record. */
+'no-cell-of-action'
+/** Calls of this action in cells, none of them failed: the error line's call did not settle as an error. */
+ | 'no-failed-cell-of-action'
+/** Failed calls of this action in cells, none on a day this signature occurred. */
+ | 'no-failed-cell-on-day'
+/** Every day the signature's errors and their frames can name is unknown. A day cell exists for a known day only (rule 6), so there is no cell to cite however many failed calls the action has. */
+ | 'frame-has-no-day';
+export interface RecoveryOutcome {
+    reads: ReadBody[];
+    /** Every signature record is a read or is counted here, so none leaves without a reason. */
+    dropped: {
+        [reason in RecoveryDrop]: number;
+    };
+}
+export declare const recoveryOf: ({ pool, store }: FamilyInput) => RecoveryOutcome;
+export declare const deriveRecovery: DeriveFamily;

package/dist/sessions/read-recovery.js

@@ -0,0 +1,97 @@
+// Recovery (rank 1; spec Section 7): each signature record, as a read. A signature's text is class A, so the read holds its hash (the same value on any account,
+// computed by the asker's client) and public names only; `recall()` is still how an operator reads the text. Confounders: `editFollowed` is not success, and refusals and
+// hook denials are local policy. Its evidence is the cells holding the failed call and the step after it, on the days the signature occurred and the days their frames were written.
+import { ACTION_TABLES, actionOf } from './actions.js';
+import { UNKNOWN, weekStartOf } from './cells.js';
+import { utcDay } from './frame.js';
+import { shapeMotif } from './motif.js';
+import { contentHash } from './read.js';
+import { atGrain, body, groupBy } from './read-support.js';
+import { harnessOf } from './schema.js';
+import { signatureRecord } from './store.js';
+const shapeOf = (actions) => shapeMotif(actions.map((action) => ({ action, identity: null }))).motifId;
+/** Earliest first; a tie falls to what the rows say, so the copy that stands never depends on record order. */
+const standsBefore = (a, b) => {
+    if (a.ts !== b.ts)
+        return a.ts !== null && (b.ts === null || a.ts < b.ts);
+    return JSON.stringify([a.sig, a.next, a.editFollowed]) < JSON.stringify([b.sig, b.next, b.editFollowed]);
+};
+/**
+ * One row per session and tool-use id. The tool fold leaves every error line in place, so a store not yet captured again keeps a replayed result's line beside the
+ * first, and fit's folded `failed` would disagree with these counts. The earliest copy stands for the call, whatever order they came in; a row with no id is its own call.
+ */
+const oneRowPerCall = (errors) => {
+    const calls = new Map();
+    const rows = [];
+    for (const error of errors) {
+        if (error.toolUseId === undefined || error.toolUseId === null) {
+            rows.push(error);
+            continue;
+        }
+        const key = `${error.agent ?? error.session}\n${error.toolUseId}`;
+        const held = calls.get(key);
+        if (held === undefined || standsBefore(error, held))
+            calls.set(key, error);
+    }
+    return [...rows, ...calls.values()];
+};
+export const recoveryOf = ({ pool, store }) => {
+    const sessions = new Map([...store.sessions, ...store.subagents].map((session) => [session.session, session]));
+    const prompts = new Map(store.prompts.map((prompt) => [`${prompt.session}#${String(prompt.index)}`, prompt]));
+    const actionIn = (session, tool) => actionOf(ACTION_TABLES[harnessOf(sessions.get(session) ?? {})], tool).action;
+    // The failed call is a one-step shape, which has a live day cell. The step after it is a two-step window, which has a week cell only (rule 6), so it is found on the week its day falls in.
+    const cellsAt = groupBy(atGrain(pool, 'day'), (cell) => `${cell.motifId}/${cell.day}`);
+    const weeksAt = groupBy(atGrain(pool, 'week'), (cell) => `${cell.motifId}/${cell.day}`);
+    const cellsOf = groupBy(atGrain(pool, 'day'), (cell) => cell.motifId);
+    /** The day a cell files this error's call under: its frame's, which is its prompt's, or its session's for a subagent or a call before the first prompt. An error can run past that midnight. */
+    const frameDayOf = (error) => {
+        const prompt = error.agent === undefined ? prompts.get(`${error.session}#${String(error.prompt)}`) : undefined;
+        if (prompt !== undefined)
+            return prompt.frame?.day ?? utcDay(prompt.ts) ?? UNKNOWN;
+        const session = sessions.get(error.agent ?? error.session);
+        return session?.frame?.day ?? utcDay(session?.tsFirst) ?? UNKNOWN;
+    };
+    const dropped = { 'no-cell-of-action': 0, 'no-failed-cell-of-action': 0, 'no-failed-cell-on-day': 0, 'frame-has-no-day': 0 };
+    const reads = [...groupBy(oneRowPerCall(store.errors), (error) => error.sig)].flatMap(([sig, list]) => {
+        const inputs = new Set();
+        const following = {};
+        let failedAction = 'other';
+        let dated = false;
+        const session = (error) => error.agent ?? error.session;
+        for (const error of list) {
+            failedAction = actionIn(session(error), error.tool);
+            const next = error.next[0] === undefined ? undefined : actionIn(session(error), error.next[0]);
+            for (const day of new Set([utcDay(error.ts) ?? UNKNOWN, frameDayOf(error)])) {
+                dated ||= day !== UNKNOWN;
+                for (const cell of cellsAt.get(`${shapeOf([failedAction])}/${day}`) ?? [])
+                    if (cell.failed > 0)
+                        inputs.add(cell);
+                // A frame of no day names no week, though a week cell sits at the unknown week.
+                if (next !== undefined && day !== UNKNOWN)
+                    for (const cell of weeksAt.get(`${shapeOf([failedAction, next])}/${weekStartOf(day)}`) ?? [])
+                        inputs.add(cell);
+            }
+            for (const tool of error.next) {
+                const action = actionIn(session(error), tool);
+                following[action] = (following[action] ?? 0) + 1;
+            }
+        }
+        if (inputs.size === 0) {
+            const ofAction = cellsOf.get(shapeOf([failedAction])) ?? [];
+            const reason = !dated ? 'frame-has-no-day' : ofAction.length === 0 ? 'no-cell-of-action' : ofAction.some((cell) => cell.failed > 0) ? 'no-failed-cell-on-day' : 'no-failed-cell-of-action';
+            dropped[reason] += 1;
+            return [];
+        }
+        const record = signatureRecord(sig, list);
+        return [
+            body('recovery', [...inputs], {
+                slice: { sig: contentHash(sig), action: failedAction },
+                value: { sessions: record.sessions, errors: record.count, firstSeen: utcDay(record.firstSeen), lastSeen: utcDay(record.lastSeen), following, editFollowed: record.editFollowed },
+                n: record.count,
+                interval: null,
+            }),
+        ];
+    });
+    return { reads, dropped };
+};
+export const deriveRecovery = (input) => recoveryOf(input).reads;

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

@@ -0,0 +1,13 @@
+import { type Family, type Read, type ReadSlice } from './read.js';
+export interface ReadFilter {
+    family: Family | undefined;
+    /** Every axis named must hold exactly this value. */
+    slice: ReadSlice;
+}
+export declare const isFamily: (value: string) => value is Family;
+/** `axis=value`, repeated; undefined when one has no axis or no value, for the caller to refuse. A value may hold `=`, as a named motif does. */
+export declare const parseSlice: (pairs: readonly string[]) => ReadSlice | undefined;
+/** In family order, then largest sample first; a read's ID settles a tie, so a rerun lists the same rows in the same order. */
+export declare const selectReads: (reads: readonly Read[], filter: ReadFilter) => Read[];
+/** Rows under a heading per family, in the order `selectReads` put them. */
+export declare const formatReads: (reads: readonly Read[]) => string;

package/dist/sessions/read-rows.js

@@ -0,0 +1,47 @@
+// What `oars sessions read` serves: reads filtered by family and slice, largest sample first, one row each. A row states its clusters. This file adds no floor: an order 1 read is
+// the operator's own cell, so a floor on it would protect no one. Reads above order 1 that fall below their floor do not exist, so there is none of them to list.
+import { FAMILIES } from './read.js';
+export const isFamily = (value) => FAMILIES.some((family) => family === value);
+/** `axis=value`, repeated; undefined when one has no axis or no value, for the caller to refuse. A value may hold `=`, as a named motif does. */
+export const parseSlice = (pairs) => {
+    const slice = {};
+    for (const pair of pairs) {
+        const at = pair.indexOf('=');
+        if (at <= 0 || at === pair.length - 1)
+            return undefined;
+        slice[pair.slice(0, at)] = pair.slice(at + 1);
+    }
+    return slice;
+};
+const compare = (a, b) => (a === b ? 0 : a < b ? -1 : 1);
+/** In family order, then largest sample first; a read's ID settles a tie, so a rerun lists the same rows in the same order. */
+export const selectReads = (reads, filter) => reads
+    .filter((read) => (filter.family === undefined || read.family === filter.family) && Object.entries(filter.slice).every(([axis, value]) => read.slice[axis] === value))
+    .sort((a, b) => FAMILIES.indexOf(a.family) - FAMILIES.indexOf(b.family) || b.n - a.n || compare(a.readId, b.readId));
+const pairsOf = (fields) => Object.entries(fields)
+    .map(([name, value]) => {
+    if (typeof value !== 'object' || value === null)
+        return `${name}=${String(value)}`;
+    return `${name}=${Object.entries(value).sort(([a, one], [b, two]) => two - one || compare(a, b)).map(([key, number]) => `${key}:${String(number)}`).join(',')}`;
+})
+    .join(' ');
+const formatRead = (read) => {
+    const interval = read.interval === null ? '' : ` ci=${String(read.interval.low)}..${String(read.interval.high)}`;
+    return `  n=${String(read.n)} clusters: ${String(read.clusters)} order=${String(read.order)} ${pairsOf(read.slice)} | ${pairsOf(read.value)}${interval}`;
+};
+const EXPERIMENT = ', experimental: fit on earlier days and scored on later ones; not served to an agent';
+/** Rows under a heading per family, in the order `selectReads` put them. */
+export const formatReads = (reads) => {
+    if (reads.length === 0)
+        return 'No reads match.';
+    const lines = [];
+    let family;
+    for (const read of reads) {
+        if (read.family !== family) {
+            family = read.family;
+            lines.push(`${family} (${String(reads.filter((one) => one.family === family).length)} reads${read.value.label === 'experimental' ? EXPERIMENT : ''})`);
+        }
+        lines.push(formatRead(read));
+    }
+    return lines.join('\n');
+};

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

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

package/dist/sessions/read-substitution.js

@@ -0,0 +1,51 @@
+// Substitution (spec Section 6, order 2): at one version boundary, one tool's share rose as another's fell. Shares sum to one, so any rise pushes every other share down; a pair
+// counts only when the falling tool also fell among the steps that are not the rising tool, which arithmetic alone cannot do. Confounders it does not remove: date, class
+// drift (the work changed, not the choice of tool), and rule commits. It says two shares moved oppositely, not that one call replaced another.
+import { UNKNOWN } from './cells.js';
+import { candidateOf, differenceOf, screen, TRIALS_FLOOR } from './read-order.js';
+import { rate, wilson } from './read-support.js';
+import { boundariesOf, shareIn, toolsAt } from './read-version-boundary.js';
+const countIn = (bucket, key) => bucket.reads.get(key)?.n ?? 0;
+/** A tool's share of the steps that are not the other tool's, floored like any rate. */
+const shareOfRest = (bucket, key, without) => {
+    const trials = bucket.of - countIn(bucket, without);
+    const count = countIn(bucket, key);
+    const value = rate(count, trials);
+    const interval = wilson(count, trials);
+    return trials < TRIALS_FLOOR || value === null || interval === null ? undefined : { value, interval };
+};
+const levelOf = (key) => key.split('\n')[0] ?? UNKNOWN;
+const motifOf = (key) => key.split('\n')[1] ?? UNKNOWN;
+const pairCandidate = (boundary, rising, falling) => {
+    const { from, to } = boundary;
+    const risingBefore = shareIn(from, rising);
+    const risingAfter = shareIn(to, rising);
+    const fallingBefore = shareIn(from, falling);
+    const fallingAfter = shareIn(to, falling);
+    const restBefore = shareOfRest(from, falling, rising);
+    const restAfter = shareOfRest(to, falling, rising);
+    if (risingBefore === undefined || risingAfter === undefined || fallingBefore === undefined || fallingAfter === undefined || restBefore === undefined || restAfter === undefined)
+        return undefined;
+    const rise = differenceOf(risingAfter.share, risingBefore.share);
+    const fall = differenceOf(fallingBefore.share, fallingAfter.share);
+    const restFall = differenceOf(restBefore, restAfter);
+    // How much of the move the two share: the smaller of them, whose interval is bounded by the smaller of each side.
+    const offset = Math.min(rise.value, fall.value);
+    const interval = { low: Math.min(rise.interval.low, fall.interval.low), high: Math.min(rise.interval.high, fall.interval.high), level: rise.interval.level };
+    return candidateOf('substitution', [risingBefore.read, risingAfter.read, fallingBefore.read, fallingAfter.read], [rise, fall, restFall], {
+        slice: { rising: motifOf(rising), falling: motifOf(falling), level: levelOf(rising), harness: boundary.harness, from: from.name, to: to.name },
+        value: { rise: rise.value, fall: fall.value, restFall: restFall.value, offset },
+        interval,
+    });
+};
+/** Both moves point the way the read claims: `moved` asks only that each is large, not its sign. */
+const opposed = ({ gates }) => gates.every((gate) => gate.value > 0);
+/** The pairs a store's change reads allow, above the floor, whether or not any of them moved. */
+export const substitutionCandidates = (reads) => boundariesOf(reads).flatMap((boundary) => {
+    const keys = toolsAt(boundary);
+    return keys.flatMap((rising) => keys.filter((falling) => falling !== rising && levelOf(falling) === levelOf(rising)).flatMap((falling) => {
+        const candidate = pairCandidate(boundary, rising, falling);
+        return candidate === undefined ? [] : [candidate];
+    }));
+});
+export const deriveSubstitution = (reads) => screen(substitutionCandidates(reads), opposed);