@manyoars/oars 0.1.1 → 0.3.0

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

@@ -0,0 +1,48 @@
+import { type Cell, type Grain, type Pool } from './cells.js';
+import type { Motif } from './motif.js';
+import { type Family, type ReadDraft, type ReadInterval, type ReadSlice, type ReadValue } from './read.js';
+import type { Store } from './store.js';
+export interface FamilyInput {
+    pool: Pool;
+    /** Only recovery reads this: an error's signature is not in a cell. */
+    store: Store;
+}
+/** A read as a family states it; the pool's snapshot is added to all of them in one place. */
+export type ReadBody = Omit<ReadDraft, 'asOf'>;
+export type DeriveFamily = (input: FamilyInput) => ReadBody[];
+export declare const round: (value: number) => number;
+/** A rate to four places, so a value reads alike wherever it is computed; null with nothing to divide by. */
+export declare const rate: (part: number, whole: number) => number | null;
+/** The normal quantile for a 95 percent interval, which every read's interval and the screen's scaling share. */
+export declare const Z_95 = 1.96;
+/** The Wilson interval: it stays inside 0 and 1, and it is honest about the small cells one operator's store is mostly made of. */
+export declare const wilson: (part: number, whole: number) => ReadInterval | null;
+/** Windows with a known result: a step with no result is in neither count, so it is in no rate. */
+export declare const settled: (cell: Cell) => number;
+export declare const total: (cells: readonly Cell[], count: (cell: Cell) => number) => number;
+export declare const groupBy: <K, T>(items: Iterable<T>, keyOf: (item: T) => K) => Map<K, T[]>;
+/**
+ * The pool's cells at one grain (rule 6). Weekly and day cells share a table and count the same steps, so a read that sums over both counts a step twice and a read that
+ * names a day from a week answers from the wrong grain: every read takes the grain it answers from here, and no read iterates `pool.cells` itself.
+ */
+export declare const atGrain: (pool: Pool, grain: Grain) => Cell[];
+/** The (name, `platform`, `shell`) cells, which sit beside the version cells and count the same calls: a read that summed them with the version cells would count each call twice, so only the read of these asks. */
+export declare const environmentCells: (pool: Pool) => Cell[];
+/** The cells of one-step motifs at one grain: every action, and every identity capture has named. */
+export declare const unitCells: (pool: Pool, grain: Grain) => {
+    cell: Cell;
+    motif: Motif;
+}[];
+/** Counts over every one-step `shape` cell, for shares: a named motif's share is of all steps, like its action's. */
+export declare const shapeUnits: (pool: Pool, grain: Grain) => Cell[];
+export declare const body: (family: Family, cells: readonly Cell[], fields: {
+    slice: ReadSlice;
+    value: ReadValue;
+    n: number;
+    interval: ReadInterval | null;
+}, method?: {
+    readonly name: string;
+    readonly version: string;
+}) => ReadBody;
+export declare const firstDayOf: (days: readonly string[]) => string | null;
+export declare const lastDayOf: (days: readonly string[]) => string | null;

package/dist/sessions/read-support.js

@@ -0,0 +1,73 @@
+// What the family modules share: their input, a read's common fields, and the arithmetic of a rate over cells.
+import { cellIdOf, isEnvironmentCell } from './cells.js';
+import { METHODS } from './read.js';
+export const round = (value) => Math.round(value * 10_000) / 10_000;
+/** A rate to four places, so a value reads alike wherever it is computed; null with nothing to divide by. */
+export const rate = (part, whole) => (whole === 0 ? null : round(part / whole));
+/** The normal quantile for a 95 percent interval, which every read's interval and the screen's scaling share. */
+export const Z_95 = 1.96;
+/** The Wilson interval: it stays inside 0 and 1, and it is honest about the small cells one operator's store is mostly made of. */
+export const wilson = (part, whole) => {
+    if (whole === 0)
+        return null;
+    const share = part / whole;
+    const z2 = Z_95 * Z_95;
+    const denominator = 1 + z2 / whole;
+    const centre = share + z2 / (2 * whole);
+    const margin = Z_95 * Math.sqrt((share * (1 - share)) / whole + z2 / (4 * whole * whole));
+    return { low: round(Math.max(0, (centre - margin) / denominator)), high: round(Math.min(1, (centre + margin) / denominator)), level: 0.95 };
+};
+/** Windows with a known result: a step with no result is in neither count, so it is in no rate. */
+export const settled = (cell) => cell.ok + cell.failed;
+export const total = (cells, count) => {
+    let sum = 0;
+    for (const cell of cells)
+        sum += count(cell);
+    return sum;
+};
+export const groupBy = (items, keyOf) => {
+    const groups = new Map();
+    for (const item of items) {
+        const key = keyOf(item);
+        const group = groups.get(key);
+        if (group === undefined)
+            groups.set(key, [item]);
+        else
+            group.push(item);
+    }
+    return groups;
+};
+/**
+ * The pool's cells at one grain (rule 6). Weekly and day cells share a table and count the same steps, so a read that sums over both counts a step twice and a read that
+ * names a day from a week answers from the wrong grain: every read takes the grain it answers from here, and no read iterates `pool.cells` itself.
+ */
+export const atGrain = (pool, grain) => pool.cells.filter((cell) => cell.grain === grain && !isEnvironmentCell(cell));
+/** The (name, `platform`, `shell`) cells, which sit beside the version cells and count the same calls: a read that summed them with the version cells would count each call twice, so only the read of these asks. */
+export const environmentCells = (pool) => pool.cells.filter(isEnvironmentCell);
+/** The cells of one-step motifs at one grain: every action, and every identity capture has named. */
+export const unitCells = (pool, grain) => {
+    const units = [];
+    for (const cell of atGrain(pool, grain)) {
+        const motif = pool.motifs.get(cell.motifId);
+        if (motif === undefined || motif.steps.length !== 1)
+            continue;
+        if (motif.level === 'named' && motif.steps[0]?.identity === null)
+            continue;
+        units.push({ cell, motif });
+    }
+    return units;
+};
+/** Counts over every one-step `shape` cell, for shares: a named motif's share is of all steps, like its action's. */
+export const shapeUnits = (pool, grain) => unitCells(pool, grain).filter(({ motif }) => motif.level === 'shape').map(({ cell }) => cell);
+export const body = (family, cells, fields, method = METHODS[family]) => ({
+    family,
+    method: method.name,
+    methodVersion: method.version,
+    inputs: cells.map(cellIdOf),
+    // Cell counts cannot give distinct accounts across cells, so this is the floor they do prove, which never overstates what a served floor may rely on.
+    clusters: cells.reduce((highest, cell) => Math.max(highest, cell.clusters), 0),
+    basis: 'all',
+    ...fields,
+});
+export const firstDayOf = (days) => days.reduce((first, day) => (first === null || day < first ? day : first), null);
+export const lastDayOf = (days) => days.reduce((last, day) => (last === null || day > last ? day : last), null);

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

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

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

@@ -0,0 +1,26 @@
+// A tool on a day, at order 1: its failure rate, which the interval is on, and its share of that day's steps. The reads above it need both on a time axis, because this store
+// has too few version boundaries to cut in time. Shape level only, so a day's steps are counted once. Confounders: the day's mix of work, effort, and rule commits.
+import { motifName } from './motif.js';
+import { body, groupBy, rate, settled, total, unitCells, wilson } from './read-support.js';
+export const deriveToolDay = ({ pool }) => {
+    const known = unitCells(pool, 'day').filter(({ motif }) => motif.level === 'shape');
+    const steps = new Map([...groupBy(known, ({ cell }) => cell.day)].map(([day, group]) => [day, total(group.map(({ cell }) => cell), settled)]));
+    return [...groupBy(known, ({ cell }) => `${cell.motifId}/${cell.day}`).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);
+        const of = steps.get(first.cell.day) ?? 0;
+        return [
+            body('tool-day', cells, {
+                slice: { motif: motifName(first.motif), level: first.motif.level, day: first.cell.day },
+                // `steps` and not `of`: this read's interval rests on the tool's own calls, and `of` would hold it to the floor by the day's.
+                value: { failureRate: rate(failed, n), failed, share: rate(n, of), steps: of },
+                n,
+                interval: wilson(failed, n),
+            }),
+        ];
+    });
+};

package/dist/sessions/read-version-boundary.d.ts

@@ -0,0 +1,31 @@
+import { type Candidate, type DeriveRelation, type Estimate } from './read-order.js';
+import type { Read } from './read.js';
+/** One version bucket of one harness, from its change reads. */
+export interface Bucket {
+    name: string;
+    /** Settled steps in the bucket. */
+    of: number;
+    firstWeek: string | null;
+    lastWeek: string | null;
+    reads: ReadonlyMap<string, Read>;
+    /** A read that states `of`, cited when the tool being compared has no read here. */
+    witness: Read;
+}
+export interface Boundary {
+    harness: string;
+    from: Bucket;
+    to: Bucket;
+}
+export declare const toolKey: (read: Read) => string;
+/** Each harness's neighboring version buckets, in version order: `2.1.9x` comes before `2.1.10x`. An unknown version has no place in that order. */
+export declare const boundariesOf: (reads: readonly Read[]) => Boundary[];
+/** A tool's share in a bucket, and what to cite for it. With no read of the tool there, its share is zero of the bucket's steps, and that is a measurement, not a gap. */
+export declare const shareIn: (bucket: Bucket, key: string) => {
+    read: Read;
+    share: Estimate;
+} | undefined;
+/** Every tool on either side of a boundary. */
+export declare const toolsAt: ({ from, to }: Boundary) => string[];
+/** The comparisons a store's change reads allow, above the floor, whether or not any of them moved. */
+export declare const versionBoundaryCandidates: (reads: readonly Read[]) => Candidate[];
+export declare const deriveVersionBoundary: DeriveRelation;

package/dist/sessions/read-version-boundary.js

@@ -0,0 +1,95 @@
+// Version boundary (spec Section 6, order 2): what moved between two neighboring harness version buckets, from order 1 change reads. Only moves past the screen exist, each
+// with how many comparisons it was screened among. A step counts as independent in the inputs and steps cluster in sessions, so the intervals run narrow, which is one reason
+// the screen runs wide. Confounders it does not remove: date (a later bucket is mostly later days, and `fromLastWeek` and `toFirstWeek` show any overlap), effort, role by brief,
+// rule commits, and class drift. A model version boundary is not readable here: a cell holds a model's name and no version of it (`read-readable.ts`).
+import { UNKNOWN } from './cells.js';
+import { candidateOf, differenceOf, estimateOf, screen, trialsOf, TRIALS_FLOOR } from './read-order.js';
+import { firstDayOf, groupBy, lastDayOf, wilson } from './read-support.js';
+const weekOf = (read, field) => {
+    const week = read.value[field];
+    return typeof week === 'string' ? [week] : [];
+};
+export const toolKey = (read) => `${read.slice.level ?? UNKNOWN}\n${read.slice.motif ?? UNKNOWN}`;
+const bucketOf = (name, reads) => ({
+    name,
+    of: trialsOf(reads[0]),
+    firstWeek: firstDayOf(reads.flatMap((read) => weekOf(read, 'firstWeek'))),
+    lastWeek: lastDayOf(reads.flatMap((read) => weekOf(read, 'lastWeek'))),
+    reads: new Map(reads.map((read) => [toolKey(read), read])),
+    witness: reads[0],
+});
+const isNonEmpty = (reads) => reads.length > 0;
+/** Each harness's neighboring version buckets, in version order: `2.1.9x` comes before `2.1.10x`. An unknown version has no place in that order. */
+export const boundariesOf = (reads) => {
+    const change = reads.filter((read) => read.family === 'change' && read.slice.harnessBucket !== UNKNOWN);
+    return [...groupBy(change, (read) => read.slice.harness ?? UNKNOWN)].flatMap(([harness, group]) => {
+        const buckets = [...groupBy(group, (read) => read.slice.harnessBucket ?? UNKNOWN)]
+            .flatMap(([name, inBucket]) => (isNonEmpty(inBucket) ? [bucketOf(name, inBucket)] : []))
+            .sort((a, b) => a.name.localeCompare(b.name, 'en', { numeric: true }));
+        return buckets.slice(1).flatMap((to, index) => {
+            const from = buckets[index];
+            return from === undefined ? [] : [{ harness, from, to }];
+        });
+    });
+};
+/** A tool's share in a bucket, and what to cite for it. With no read of the tool there, its share is zero of the bucket's steps, and that is a measurement, not a gap. */
+export const shareIn = (bucket, key) => {
+    const read = bucket.reads.get(key);
+    if (read !== undefined) {
+        const share = estimateOf(read, 'share');
+        return share === undefined ? undefined : { read, share };
+    }
+    const interval = wilson(0, bucket.of);
+    return interval === null ? undefined : { read: bucket.witness, share: { value: 0, interval } };
+};
+/** Every tool on either side of a boundary. */
+export const toolsAt = ({ from, to }) => [...new Set([...from.reads.keys(), ...to.reads.keys()])];
+const slicesOf = (boundary, key, metric) => {
+    const [level = UNKNOWN, motif = UNKNOWN] = key.split('\n');
+    return { motif, level, harness: boundary.harness, from: boundary.from.name, to: boundary.to.name, metric };
+};
+const movement = (boundary, move, before, after) => ({
+    before,
+    after,
+    move: move.value,
+    fromLastWeek: boundary.from.lastWeek,
+    toFirstWeek: boundary.to.firstWeek,
+});
+const shareCandidate = (boundary, key) => {
+    const earlier = shareIn(boundary.from, key);
+    const later = shareIn(boundary.to, key);
+    if (earlier === undefined || later === undefined)
+        return undefined;
+    const move = differenceOf(later.share, earlier.share);
+    return candidateOf('version-boundary', [earlier.read, later.read], [move], {
+        slice: slicesOf(boundary, key, 'share'),
+        value: movement(boundary, move, earlier.share.value, later.share.value),
+        interval: move.interval,
+    });
+};
+/** The change read's interval is on its share, so a failure rate's comes from the same read's count and rate. */
+const failureOf = (read) => {
+    const value = read?.value.failureRate;
+    if (read === undefined || typeof value !== 'number' || read.n < TRIALS_FLOOR)
+        return undefined;
+    const interval = wilson(value * read.n, read.n);
+    return interval === null ? undefined : { value, interval };
+};
+const failureCandidate = (boundary, key) => {
+    const earlierRead = boundary.from.reads.get(key);
+    const laterRead = boundary.to.reads.get(key);
+    const earlier = failureOf(earlierRead);
+    const later = failureOf(laterRead);
+    if (earlierRead === undefined || laterRead === undefined || earlier === undefined || later === undefined)
+        return undefined;
+    const move = differenceOf(later, earlier);
+    return candidateOf('version-boundary', [earlierRead, laterRead], [move], {
+        slice: slicesOf(boundary, key, 'failureRate'),
+        value: movement(boundary, move, earlier.value, later.value),
+        interval: move.interval,
+        n: Math.min(earlierRead.n, laterRead.n),
+    });
+};
+/** The comparisons a store's change reads allow, above the floor, whether or not any of them moved. */
+export const versionBoundaryCandidates = (reads) => boundariesOf(reads).flatMap((boundary) => toolsAt(boundary).flatMap((key) => [shareCandidate(boundary, key), failureCandidate(boundary, key)].filter((candidate) => candidate !== undefined)));
+export const deriveVersionBoundary = (reads) => screen(versionBoundaryCandidates(reads));

package/dist/sessions/read.d.ts

@@ -0,0 +1,79 @@
+/** SHA-256 of canonical JSON, 16 hex characters, unsalted: one content reads alike on any account (D1's `hP`). */
+export declare const contentHash: (value: unknown) => string;
+/** The eight families, in rank order, recovery first: the only one that changes a next call today. Then `tool-day`, which the reads above order 1 stand on. */
+export declare const FIRST_ORDER_FAMILIES: readonly ["recovery", "fit", "cost", "change", "live", "adoption", "method", "next-step", "tool-day"];
+export type FirstOrderFamily = (typeof FIRST_ORDER_FAMILIES)[number];
+/** Families that read other reads, lowest order first. `lead-lag` is the labeled experiment (spec Section 6). */
+export declare const FAMILIES: readonly ["recovery", "fit", "cost", "change", "live", "adoption", "method", "next-step", "tool-day", "version-boundary", "substitution", "interaction", "day-move", "lead-lag"];
+export type Family = (typeof FAMILIES)[number];
+/**
+ * Each family's method and its version. A rule change bumps its version here, and the pool's version hashes this table, so a stored file of the old rule is not served.
+ * It lives here and not beside each family because the pool hash needs it, and a family module imports the cells the hash is in.
+ */
+export declare const METHODS: {
+    readonly [family in Family]: {
+        readonly name: string;
+        readonly version: string;
+    };
+};
+/** The fit family's other method (`read-call-shape.ts`). The pool's version hashes it beside the table, for the same reason. */
+export declare const CALL_SHAPE_METHOD: {
+    readonly name: "call-shape";
+    readonly version: "2";
+};
+/** `all`, or `unexposed`: only steps outside any recall's consequence window, so a read cannot mistake the pool's influence for the world. */
+export type ReadBasis = 'all' | 'unexposed';
+/** The coordinates a read covers, as public names. */
+export interface ReadSlice {
+    [axis: string]: string;
+}
+/** What a read says. Closed vocabulary and numbers only: a read never holds a path, a prompt, or an error's text. */
+export interface ReadValue {
+    [metric: string]: number | string | null | {
+        [name: string]: number;
+    };
+}
+/** A 95 percent interval on a read's headline number: a rate at order 1, propagated from the inputs above it (`read-order.ts`), so it can run below zero. Null when the value is not a rate. */
+export interface ReadInterval {
+    low: number;
+    high: number;
+    level: number;
+}
+/** The pool a read was computed from: a later version is a new read, even when the value comes out the same. */
+export interface ReadAsOf {
+    pool: string;
+    /** The newest day in that pool; null when no cell has a known day. */
+    day: string | null;
+}
+export interface Read {
+    /** `read:<contentHash>` of every other field. */
+    readId: string;
+    family: Family;
+    method: string;
+    methodVersion: string;
+    /** The IDs this read cites, sorted, each `cell:<hash>` or `read:<hash>`. Never empty. A rate's denominator is a total of the pool `asOf` pins, so it is not listed. */
+    inputs: string[];
+    /** 1 + the highest order among `inputs`. */
+    order: number;
+    slice: ReadSlice;
+    value: ReadValue;
+    /** The observations behind the value. At order 1 its own count; above order 1 the trials of its weakest input, or the observations a relation names, such as pairs. */
+    n: number;
+    /** The accounts behind the value, as its inputs state it. One operator's store says 1. */
+    clusters: number;
+    interval: ReadInterval | null;
+    asOf: ReadAsOf;
+    basis: ReadBasis;
+}
+/** A read before its inputs are checked and its ID and order are computed. */
+export type ReadDraft = Omit<Read, 'readId' | 'order'>;
+export declare const cellRef: (hash: string) => string;
+/** Looks up an input's order; undefined when this input is not a cell ID and no read known here has it. */
+export type OrderResolver = (input: string) => number | undefined;
+/** Orders from the IDs themselves for cells, and from these reads for a read. */
+export declare const orderResolver: (reads: readonly Read[]) => OrderResolver;
+export declare const readIdOf: (read: Omit<Read, "readId">) => string;
+/** A read's ID pins every field down to the last count, so none of them may change below the top either. */
+export declare const frozenRead: (read: Read) => Read;
+/** The one way a read comes to exist. It refuses a read that cites nothing or cites what it cannot place, since either would have no lineage. */
+export declare const makeRead: (draft: ReadDraft, orderOf: OrderResolver) => Read;

package/dist/sessions/read.js

@@ -0,0 +1,84 @@
+// A live read's baseline is not traceable through lineage: the read cites only the sliced day's cells, and `value.baseline` comes from cells it does not cite.
+// The read (recall spec Section 2.6): any derived value, citing its inputs. A read's ID is the hash of its content and a read never changes, so
+// a recall can cite one and lineage can walk back from it. Its order is computed from its inputs and has no ceiling: a cell is 0 and a read is one more
+// than the highest order it cites, so a read over reads needs nothing here that a read over cells does not.
+import { createHash } from 'node:crypto';
+/** A value, read by content: object keys are sorted, so two writers of one value hash alike. */
+const canonical = (value) => {
+    if (Array.isArray(value))
+        return value.map(canonical);
+    if (typeof value !== 'object' || value === null)
+        return value;
+    return Object.fromEntries(Object.entries(value)
+        .sort(([a], [b]) => (a < b ? -1 : 1))
+        .map(([key, entry]) => [key, canonical(entry)]));
+};
+/** SHA-256 of canonical JSON, 16 hex characters, unsalted: one content reads alike on any account (D1's `hP`). */
+export const contentHash = (value) => createHash('sha256').update(JSON.stringify(canonical(value))).digest('hex').slice(0, 16);
+/** The eight families, in rank order, recovery first: the only one that changes a next call today. Then `tool-day`, which the reads above order 1 stand on. */
+export const FIRST_ORDER_FAMILIES = ['recovery', 'fit', 'cost', 'change', 'live', 'adoption', 'method', 'next-step', 'tool-day'];
+/** Families that read other reads, lowest order first. `lead-lag` is the labeled experiment (spec Section 6). */
+export const FAMILIES = [...FIRST_ORDER_FAMILIES, 'version-boundary', 'substitution', 'interaction', 'day-move', 'lead-lag'];
+/**
+ * Each family's method and its version. A rule change bumps its version here, and the pool's version hashes this table, so a stored file of the old rule is not served.
+ * It lives here and not beside each family because the pool hash needs it, and a family module imports the cells the hash is in.
+ */
+export const METHODS = {
+    recovery: { name: 'signature-record', version: '2' },
+    fit: { name: 'failure-rate', version: '2' },
+    cost: { name: 'per-prompt-by-class', version: '1' },
+    change: { name: 'share-in-version-bucket', version: '2' },
+    live: { name: 'day-against-trailing-week', version: '2' },
+    adoption: { name: 'share-and-span', version: '2' },
+    method: { name: 'shape-share-by-model', version: '1' },
+    'next-step': { name: 'next-action-counts', version: '1' },
+    'tool-day': { name: 'rates-on-day', version: '1' },
+    'version-boundary': { name: 'move-between-buckets', version: '2' },
+    substitution: { name: 'rise-against-fall', version: '1' },
+    interaction: { name: 'failure-gap-across-tier-assigned', version: '3' },
+    'day-move': { name: 'move-to-next-day', version: '2' },
+    'lead-lag': { name: 'failure-move-leads-share-move', version: '1' },
+};
+/** The fit family's other method (`read-call-shape.ts`). The pool's version hashes it beside the table, for the same reason. */
+export const CALL_SHAPE_METHOD = { name: 'call-shape', version: '2' };
+const ORDER_OF_CELL = 0;
+const CELL_PREFIX = 'cell:';
+const READ_PREFIX = 'read:';
+export const cellRef = (hash) => `${CELL_PREFIX}${hash}`;
+/** Orders from the IDs themselves for cells, and from these reads for a read. */
+export const orderResolver = (reads) => {
+    const orders = new Map(reads.map((read) => [read.readId, read.order]));
+    return (input) => (input.startsWith(CELL_PREFIX) ? ORDER_OF_CELL : orders.get(input));
+};
+export const readIdOf = (read) => {
+    const { family, method, methodVersion, inputs, order, slice, value, n, clusters, interval, asOf, basis } = read;
+    return `${READ_PREFIX}${contentHash({ family, method, methodVersion, inputs, order, slice, value, n, clusters, interval, asOf, basis })}`;
+};
+const deepFreeze = (value) => {
+    if (typeof value !== 'object' || value === null)
+        return;
+    Object.values(value).forEach((entry) => {
+        deepFreeze(entry);
+    });
+    Object.freeze(value);
+};
+/** A read's ID pins every field down to the last count, so none of them may change below the top either. */
+export const frozenRead = (read) => {
+    deepFreeze(read);
+    return read;
+};
+/** The one way a read comes to exist. It refuses a read that cites nothing or cites what it cannot place, since either would have no lineage. */
+export const makeRead = (draft, orderOf) => {
+    const inputs = [...new Set(draft.inputs)].sort();
+    if (inputs.length === 0)
+        throw new Error(`A ${draft.family} read cites no input.`);
+    let highest = -1;
+    for (const input of inputs) {
+        const order = orderOf(input);
+        if (order === undefined)
+            throw new Error(`A ${draft.family} read cites ${input}, whose order is not known.`);
+        highest = Math.max(highest, order);
+    }
+    const body = { ...draft, inputs, order: 1 + highest };
+    return frozenRead({ readId: readIdOf(body), ...body });
+};

package/dist/sessions/recall-consequence.d.ts

@@ -0,0 +1,45 @@
+import { type CountedStep } from './motif.js';
+import type { Recall } from './recall-object.js';
+import { type ToolObservation } from './schema.js';
+import type { Store } from './store.js';
+/** A consequence window ends at the prompt's end or after this many calls (spec Section 2.7). */
+export declare const WINDOW_CALLS = 20;
+/** Fills `n` and `consequence`. A recall with no session, or from a session this store does not hold, has nothing to read and comes back as it was. */
+export declare const deriveConsequences: (store: Store, recalls: readonly Recall[]) => Recall[];
+/** A step as a cell counts it, and whether it sits inside a shown recall's window. */
+export interface PlacedStep {
+    step: CountedStep;
+    exposed: boolean;
+}
+/** What recalls add to the graph: the one seam `deriveCells` reads for `recall.*` steps and `exposed`. */
+export interface RecallGraph {
+    place: (tool: ToolObservation, steps: readonly CountedStep[]) => PlacedStep[];
+    exposedPrompt: (session: string, index: number) => boolean;
+}
+export declare const NO_RECALLS: RecallGraph;
+/**
+ * Takes recalls that have been through `deriveConsequences`. An MCP pull has no session id, so the only step it has is the one in its transcript; a pull that names its session
+ * (`--session`) has no MCP call, so its step is this one.
+ */
+export declare const recallGraphOf: (store: Store, recalls: readonly Recall[]) => RecallGraph;
+/** One row per mode, arm, and answer kind. Counts only. */
+export interface RecallCountRow {
+    mode: Recall['mode'];
+    arm: Recall['arm'];
+    kind: Recall['answer']['kind'];
+    recalls: number;
+    sessions: number;
+    /** The size of what was injected, or for a held recall would have been. */
+    tokens: number;
+    /** Recalls with a consequence window, and of those how many followed. */
+    windows: number;
+    followed: number;
+    windowCalls: number;
+    /** Null when no window in the row measured any tokens. */
+    windowTokens: number | null;
+    /** Held windows that share a call with a shown recall's window. The arm is drawn per session and shape, so one session can hold both, and such a window is a contaminated baseline. */
+    overlapped: number;
+}
+/** Takes recalls that have been through `deriveConsequences`; `day` is a UTC day, so one day of hooks reads as one set of rows. A shown window from any day can overlap a held one. */
+export declare const recallCounts: (recalls: readonly Recall[], day?: string) => RecallCountRow[];
+export declare const formatRecallCounts: (rows: readonly RecallCountRow[]) => string;