@manyoars/oars 0.4.0 → 0.5.1

package/dist/sessions/card-render.js

@@ -0,0 +1,146 @@
+// The crew card as a picture. `cardSvg` writes the SVG; `rasterize` reads back that SVG (the rects and monospace text this file writes, nothing else) into pixels, and
+// `encodePng` writes them as a PNG. No renderer dependency: the one on offer (resvg) is MPL-2.0, which `check-licenses` refuses, and the card's picture is only
+// rects and text. Both outputs are byte-stable for one card. The names on it are plain text as the session recorded them, with no vendor logo.
+import { deflateSync } from 'node:zlib';
+import { CARD_COMMAND, CARD_SITE, cardRows, cardTitle } from './card.js';
+import { GLYPH_HEIGHT, GLYPH_WIDTH, lit } from './card-font.js';
+const WIDTH = 1200;
+const MARGIN = 48;
+const TOP = 140;
+export const PITCH = 36;
+const FONT = 20;
+const TITLE_FONT = 30;
+const VALUE_X = 308;
+/** The widest value line, in characters, that fits between VALUE_X and the right margin. */
+const WRAP = 68;
+const BACKGROUND = '0b1b2b';
+const INK = 'e8eef4';
+const MUTED = '8fa6ba';
+const ACCENT = 'f2b134';
+/** A glyph cell is one column wider than the glyph, so a monospace font of size N has this advance at N / 10 pixels per font pixel: 0.6 em. */
+const advance = (font) => ((GLYPH_WIDTH + 1) * font) / 10;
+const escape = (text) => text.replaceAll('&', '&amp;').replaceAll('<', '&lt;').replaceAll('>', '&gt;').replaceAll('"', '&quot;');
+const unescape = (text) => text.replaceAll('&quot;', '"').replaceAll('&gt;', '>').replaceAll('&lt;', '<').replaceAll('&amp;', '&');
+/** A value split at its commas into lines of at most `WRAP` characters; a part longer than that stays whole. */
+const wrap = (value) => {
+    const lines = [];
+    for (const part of value.split(', ')) {
+        const last = lines.length - 1;
+        if (last >= 0 && `${lines[last] ?? ''}, ${part}`.length < WRAP)
+            lines[last] = `${lines[last] ?? ''}, ${part}`;
+        else
+            lines.push(part);
+    }
+    return lines.map((line, index) => (index < lines.length - 1 ? `${line},` : line));
+};
+const text = (x, y, font, fill, body) => `<text x="${String(x)}" y="${String(y)}" font-family="monospace" font-size="${String(font)}" fill="#${fill}">${escape(body)}</text>`;
+const rect = (x, y, width, height, fill) => `<rect x="${String(x)}" y="${String(y)}" width="${String(width)}" height="${String(height)}" fill="#${fill}"/>`;
+export const cardSvg = (card, depositor) => {
+    const body = [];
+    let y = TOP;
+    let previous = '';
+    for (const row of cardRows(card, depositor)) {
+        wrap(row.value).forEach((line, index) => {
+            // A repeated label (one `tokens` row for each model) prints once.
+            if (index === 0 && row.label !== previous)
+                body.push(text(MARGIN, y, FONT, MUTED, row.label));
+            body.push(text(VALUE_X, y, FONT, INK, line));
+            y += PITCH;
+        });
+        previous = row.label;
+    }
+    const height = y + 20 + 60;
+    const footerY = height - 30;
+    return [
+        `<svg xmlns="http://www.w3.org/2000/svg" width="${String(WIDTH)}" height="${String(height)}" viewBox="0 0 ${String(WIDTH)} ${String(height)}">`,
+        rect(0, 0, WIDTH, height, BACKGROUND),
+        text(MARGIN, 72, TITLE_FONT, INK, cardTitle(card)),
+        rect(MARGIN, 96, WIDTH - 2 * MARGIN, 2, ACCENT),
+        ...body,
+        rect(MARGIN, height - 70, WIDTH - 2 * MARGIN, 1, MUTED),
+        text(MARGIN, footerY, FONT, ACCENT, CARD_SITE),
+        text(WIDTH - MARGIN - Math.round(advance(FONT) * CARD_COMMAND.length), footerY, FONT, ACCENT, CARD_COMMAND),
+        '</svg>',
+        '',
+    ].join('\n');
+};
+const colorOf = (hex) => [Number.parseInt(hex.slice(0, 2), 16), Number.parseInt(hex.slice(2, 4), 16), Number.parseInt(hex.slice(4, 6), 16)];
+const SHAPE = /<rect x="(\d+)" y="(\d+)" width="(\d+)" height="(\d+)" fill="#([0-9a-f]{6})"\/>|<text x="(\d+)" y="(\d+)" font-family="monospace" font-size="(\d+)" fill="#([0-9a-f]{6})">([^<]*)<\/text>/g;
+/** Pixels for the SVG `cardSvg` writes: rects and monospace text in document order, a text's font size a whole multiple of ten. */
+export const rasterize = (svg) => {
+    const size = /<svg [^>]*width="(\d+)" height="(\d+)"/.exec(svg);
+    if (size === null)
+        throw new Error('The card SVG has no size.');
+    const width = Number(size[1]);
+    const height = Number(size[2]);
+    const rgb = Buffer.alloc(width * height * 3);
+    const paint = (x, y, color) => {
+        if (x < 0 || y < 0 || x >= width || y >= height)
+            return;
+        rgb.set(color, (y * width + x) * 3);
+    };
+    for (const match of svg.matchAll(SHAPE)) {
+        if (match[1] !== undefined) {
+            const [x, y, w, h] = [Number(match[1]), Number(match[2]), Number(match[3]), Number(match[4])];
+            const color = colorOf(match[5] ?? '');
+            for (let row = y; row < y + h; row += 1)
+                for (let column = x; column < x + w; column += 1)
+                    paint(column, row, color);
+            continue;
+        }
+        const [x, baseline, font] = [Number(match[6]), Number(match[7]), Number(match[8])];
+        if (font % 10 !== 0)
+            throw new Error(`The card SVG has a font size of ${String(font)}; the picture takes a multiple of 10.`);
+        const scale = font / 10;
+        const color = colorOf(match[9] ?? '');
+        Array.from(unescape(match[10] ?? '')).forEach((char, index) => {
+            for (let column = 0; column < GLYPH_WIDTH; column += 1) {
+                for (let row = 0; row < GLYPH_HEIGHT; row += 1) {
+                    if (!lit(char, column, row))
+                        continue;
+                    for (let dy = 0; dy < scale; dy += 1)
+                        for (let dx = 0; dx < scale; dx += 1)
+                            paint(x + (index * (GLYPH_WIDTH + 1) + column) * scale + dx, baseline - (GLYPH_HEIGHT - 1) * scale + row * scale + dy, color);
+                }
+            }
+        });
+    }
+    return { width, height, rgb };
+};
+const CRC_TABLE = Array.from({ length: 256 }, (_, n) => {
+    let c = n;
+    for (let bit = 0; bit < 8; bit += 1)
+        c = (c & 1) === 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+    return c >>> 0;
+});
+const crc32 = (bytes) => {
+    let c = 0xffffffff;
+    for (const byte of bytes)
+        c = (CRC_TABLE[(c ^ byte) & 0xff] ?? 0) ^ (c >>> 8);
+    return (c ^ 0xffffffff) >>> 0;
+};
+const chunk = (type, data) => {
+    const head = Buffer.alloc(8);
+    head.writeUInt32BE(data.length, 0);
+    head.write(type, 4, 'latin1');
+    const crc = Buffer.alloc(4);
+    crc.writeUInt32BE(crc32(Buffer.concat([head.subarray(4), data])), 0);
+    return Buffer.concat([head, data, crc]);
+};
+/** An 8-bit RGB PNG, unfiltered rows, zlib at level 9 (deterministic for one input). */
+export const encodePng = (width, height, rgb) => {
+    const header = Buffer.alloc(13);
+    header.writeUInt32BE(width, 0);
+    header.writeUInt32BE(height, 4);
+    header.set([8, 2, 0, 0, 0], 8);
+    const stride = width * 3;
+    const raw = Buffer.alloc((stride + 1) * height);
+    for (let row = 0; row < height; row += 1)
+        rgb.copy(raw, row * (stride + 1) + 1, row * stride, (row + 1) * stride);
+    return Buffer.concat([Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]), chunk('IHDR', header), chunk('IDAT', deflateSync(raw, { level: 9 })), chunk('IEND', Buffer.alloc(0))]);
+};
+/** The PNG for an SVG `cardSvg` wrote. */
+export const cardPng = (svg) => {
+    const { width, height, rgb } = rasterize(svg);
+    return encodePng(width, height, rgb);
+};

package/dist/sessions/card.d.ts

@@ -0,0 +1,59 @@
+import { type BooksShare } from './query.js';
+import type { Store } from './store.js';
+import type { SurvivalState } from './survival.js';
+export type CardPeriod = 'week' | 'month' | 'year';
+export declare const OTHER = "other";
+export declare const cardWindow: (period: CardPeriod, now: number) => {
+    days: number;
+    end: string;
+};
+export interface CardModel {
+    name: string;
+    prompts: number;
+    /** Input, cache, and output tokens over the prompts that recorded them. */
+    tokens: number;
+}
+export interface Card {
+    period: CardPeriod;
+    days: number;
+    /** The UTC date the window ends on. */
+    windowEnd: string;
+    sessions: number;
+    activeDays: number;
+    harnesses: Array<{
+        name: string;
+        sessions: number;
+    }>;
+    models: CardModel[];
+    /** Main-line tool calls, each call once. */
+    strokes: number;
+    /** Tool calls that failed. */
+    crabs: number;
+    /** Crabs whose next call was a different tool, over the crabs; a share under the floor reads `too few`. */
+    movedOn: BooksShare;
+    /** Edited prompts that were followed by a command, over edited prompts. */
+    verifyAfterEdit: BooksShare;
+    commits: number;
+    /** Commits whose survival is known, and how many survived. */
+    survived: BooksShare;
+    /** The harness's own `cost-state` totals, summed over the sessions that have one. Absent under `--no-cost`, so no output form carries it. */
+    cost?: {
+        usd: number | null;
+        recorded: number;
+        of: number;
+    };
+}
+export declare const cardOf: (store: Store, survival: ReadonlyMap<string, SurvivalState>, period: CardPeriod, now: number, includeCost?: boolean) => Card;
+export interface CardRow {
+    label: string;
+    value: string;
+}
+/** The rows of the card, in order, shared by the table and the picture. `depositor` is the one line the sign-in state decides. */
+export declare const cardRows: (card: Card, depositor: string) => CardRow[];
+export declare const CARD_SITE = "manyoars.com";
+export declare const CARD_COMMAND = "npx @manyoars/oars card";
+export declare const cardTitle: (card: Card) => string;
+/** The compact table `--text` prints, sized to screenshot in a terminal. */
+export declare const cardText: (card: Card, depositor: string) => string;
+/** The one link `card` prints: X's web intent with the text only. The person adds the picture; nothing is posted from here. */
+export declare const tweetLink: (card: Card) => string;

package/dist/sessions/card.js

@@ -0,0 +1,107 @@
+// `oars card`: the person's own week, month, or year as counts, read from the local store only. It reuses `books` for the prompt-level columns (turns,
+// commits, and commit survival) so no second parser of the store exists, and prints nothing a reader of the picture could trace to a folder, a path, a prompt,
+// a repository, or a name outside the published model list.
+import { firstCopies } from './derive.js';
+import { books, BOOKS_MIN_PROMPTS } from './query.js';
+import { publicModel } from './public-vocabulary.js';
+import { harnessOf, observesUsage } from './schema.js';
+const DAY_MS = 86_400_000;
+const DAYS_IN = { week: 7, month: 30, year: 365 };
+/** How many models the card names before the rest fold into `other`. */
+const MODELS_SHOWN = 3;
+export const OTHER = 'other';
+export const cardWindow = (period, now) => ({ days: DAYS_IN[period], end: new Date(now).toISOString().slice(0, 10) });
+const shareOf = (count, of) => ({ count, of, share: of < BOOKS_MIN_PROMPTS ? null : Math.round((count / of) * 1000) / 1000 });
+const tokensOf = (prompt) => {
+    const { input, cacheWrite, cacheRead, output } = prompt.usage;
+    // A category the source never recorded is a placeholder zero, so it adds nothing either way; the check keeps the sum to what was measured.
+    return input + output + (observesUsage(prompt, 'cacheWrite') ? cacheWrite : 0) + (observesUsage(prompt, 'cacheRead') ? cacheRead : 0);
+};
+/** Models by prompts, the first few published names kept and every other name, published or not, counted under `other`. */
+const modelMix = (prompts) => {
+    const byModel = new Map();
+    for (const prompt of prompts) {
+        const entry = byModel.get(prompt.model) ?? { name: prompt.model, prompts: 0, tokens: 0 };
+        entry.prompts += 1;
+        entry.tokens += tokensOf(prompt);
+        byModel.set(prompt.model, entry);
+    }
+    const ranked = [...byModel.values()].sort((a, b) => b.prompts - a.prompts || a.name.localeCompare(b.name));
+    const named = ranked.filter((entry) => publicModel(entry.name) === entry.name).slice(0, MODELS_SHOWN);
+    const rest = ranked.filter((entry) => !named.includes(entry));
+    return rest.length === 0 ? named : [...named, { name: OTHER, prompts: rest.reduce((total, entry) => total + entry.prompts, 0), tokens: rest.reduce((total, entry) => total + entry.tokens, 0) }];
+};
+const strokesOf = (tools) => {
+    const bySession = new Map();
+    for (const tool of tools)
+        bySession.set(tool.session, [...(bySession.get(tool.session) ?? []), tool]);
+    return [...bySession.values()].reduce((total, list) => total + firstCopies(list).length, 0);
+};
+export const cardOf = (store, survival, period, now, includeCost = true) => {
+    const { days, end } = cardWindow(period, now);
+    // Whole UTC dates: the window opens at 00:00 UTC of the date days - 1 before today, so it holds exactly `days` dates.
+    const cutoff = new Date(Date.parse(`${end}T00:00:00Z`) - (days - 1) * DAY_MS).toISOString();
+    const prompts = store.prompts.filter((prompt) => prompt.ts !== null && prompt.ts >= cutoff);
+    const promptKeys = new Set(prompts.map((prompt) => `${prompt.session}#${String(prompt.index)}`));
+    const inWindow = (record) => record.prompt !== null && promptKeys.has(`${record.session}#${String(record.prompt)}`);
+    const sessionIds = new Set(prompts.map((prompt) => prompt.session));
+    const sessions = store.sessions.filter((session) => sessionIds.has(session.session) && session.supersededBy === undefined);
+    const crabs = store.errors.filter((error) => error.agent === undefined && inWindow(error));
+    // `books` over one group: with no session naming a harness, every prompt falls under the one default key.
+    const [row] = books({ ...store, sessions: [], prompts }, 'harness', now, undefined, survival);
+    const verified = prompts.filter((prompt) => prompt.cls === 'edit-verify').length;
+    const edited = verified + prompts.filter((prompt) => prompt.cls === 'edit-only').length;
+    const harnessCounts = new Map();
+    for (const session of sessions)
+        harnessCounts.set(harnessOf(session), (harnessCounts.get(harnessOf(session)) ?? 0) + 1);
+    const costed = sessions.filter((session) => session.costUsd !== null);
+    return {
+        period,
+        days,
+        windowEnd: end,
+        sessions: sessions.length,
+        activeDays: new Set(prompts.map((prompt) => (prompt.ts ?? '').slice(0, 10))).size,
+        harnesses: [...harnessCounts.entries()].map(([name, count]) => ({ name, sessions: count })).sort((a, b) => b.sessions - a.sessions || a.name.localeCompare(b.name)),
+        models: modelMix(prompts),
+        strokes: strokesOf(store.tools.filter(inWindow)),
+        crabs: crabs.length,
+        movedOn: shareOf(crabs.filter((error) => error.next[0] !== undefined && error.next[0] !== error.tool).length, crabs.length),
+        verifyAfterEdit: shareOf(verified, edited),
+        commits: row?.commits ?? 0,
+        survived: row?.survived ?? shareOf(0, 0),
+        ...(includeCost ? { cost: { usd: costed.length === 0 ? null : costed.reduce((total, session) => total + (session.costUsd ?? 0), 0), recorded: costed.length, of: sessions.length } } : {}),
+    };
+};
+/** A share as the card prints it: a percent at or over the floor, else `too few`, with the counts it rests on. */
+const shareText = (share, unit) => `${share.share === null ? 'too few' : `${String(Math.round(share.share * 100))}%`} (${String(share.count)} of ${String(share.of)} ${unit})`;
+const dollars = (usd) => `$${usd.toFixed(2)}`;
+/** The rows of the card, in order, shared by the table and the picture. `depositor` is the one line the sign-in state decides. */
+export const cardRows = (card, depositor) => [
+    { label: 'sessions', value: `${String(card.sessions)} on ${String(card.activeDays)} active ${card.activeDays === 1 ? 'day' : 'days'}` },
+    { label: 'harnesses', value: card.harnesses.map((entry) => `${entry.name} ${String(entry.sessions)}`).join(', ') },
+    { label: 'models', value: card.models.map((entry) => `${entry.name} ${String(entry.prompts)}`).join(', ') },
+    ...card.models.map((entry) => ({ label: 'tokens', value: `${entry.name} ${String(entry.tokens)}` })),
+    { label: 'strokes', value: String(card.strokes) },
+    { label: 'crabs', value: String(card.crabs) },
+    { label: 'moved on', value: shareText(card.movedOn, 'crabs') },
+    { label: 'verified after edit', value: shareText(card.verifyAfterEdit, 'edits') },
+    { label: 'commits', value: String(card.commits) },
+    { label: 'survived', value: shareText(card.survived, 'settled') },
+    ...(card.cost === undefined ? [] : [{ label: 'cost', value: card.cost.usd === null ? 'not recorded by these harnesses' : `${dollars(card.cost.usd)} (${String(card.cost.recorded)} of ${String(card.cost.of)} sessions recorded one)` }]),
+    { label: 'depositor', value: depositor },
+];
+export const CARD_SITE = 'manyoars.com';
+export const CARD_COMMAND = 'npx @manyoars/oars card';
+export const cardTitle = (card) => `oars crew card: the last ${String(card.days)} days to ${card.windowEnd}`;
+/** The compact table `--text` prints, sized to screenshot in a terminal. */
+export const cardText = (card, depositor) => {
+    const rows = cardRows(card, depositor).filter((row) => row.value !== '');
+    const width = Math.max(...rows.map((row) => row.label.length)) + 2;
+    return [cardTitle(card), '', ...rows.map((row) => `${row.label.padEnd(width)}${row.value}`), '', `${CARD_SITE}  ${CARD_COMMAND}`].join('\n');
+};
+/** The one link `card` prints: X's web intent with the text only. The person adds the picture; nothing is posted from here. */
+export const tweetLink = (card) => {
+    const stats = `${String(card.sessions)} ${card.sessions === 1 ? 'session' : 'sessions'}, ${String(card.strokes)} strokes, ${String(card.crabs)} crabs`;
+    const text = `My agents, the last ${String(card.days)} days: ${stats}. ${CARD_SITE} ${CARD_COMMAND}`;
+    return `https://x.com/intent/tweet?text=${encodeURIComponent(text)}`;
+};

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

@@ -1,4 +1,4 @@
-import { type CellSet, type Grain } from './cells.js';
+import { type CellSet, type ExposureGraph, type Exposure, type Grain } from './cells.js';
 import type { Motif } from './motif.js';
 import { type SessionSkeleton, type ShellReader } from './pool-wire.js';
 import { type RecallGraph } from './recall-consequence.js';
@@ -10,7 +10,10 @@ export interface CellRow {
     frameBucket: string;
     grain: Grain;
     day: string;
+    /** 1 for a shown cell, 0 for any other: the column the cell table held before held and unknown were told apart. */
     exposed: number;
+    /** Shown, held, or unknown; its code (`EXPOSURE_CODES`) is the last field of `key`. */
+    exposure: Exposure;
     sessions: number;
     ok: number;
     failed: number;
@@ -39,9 +42,17 @@ export interface Increments {
  * Rules 1 and 2: a window names a shell step by its program and subcommand alone, and each flag and each pull of it adds a one-step cell of its own.
  */
 export declare const cellsOf: (store: Store, graph?: RecallGraph) => CellSet;
-/** A local store with each shell step read as a deposit reads it (`projectedSteps`), so its named motifs are the ones the pool holds. It uses the open gate, which keeps the name shape and length but applies no redactor or exclusion term: a local read sends nothing. */
+/**
+ * A local store with each shell step read as a deposit reads it (`projectedSteps`), so its named motifs are the ones the pool holds, and each call's key names as the wire sends them (`wireKeys`), so its shape cells are too.
+ * It uses the open gate, which keeps the name shape and length but applies no redactor or exclusion term: a local read sends nothing.
+ */
 export declare const projectedStore: (store: Store, read: ShellReader) => Store;
 /** One account's deposits as a store. A session's id is its skeleton's, which the client hashes per account, so it joins nothing across accounts. */
 export declare const storeOf: (skeletons: readonly SessionSkeleton[]) => Store;
-/** Whole cells and strata, summed over a batch's own sessions: the same cells a store of that batch alone derives. */
+/**
+ * The graph a deposit derives its cells under: the recommendations the skeleton carries, placed on the main run's calls that are not sidechain (the line the windows were counted on). A call in a shown window is shown, in a held
+ * one held, and one the batch has no row for is unknown: the graph adds no step and never reads a call as unexposed, since no row cannot be told from a client that did not look. An arm this reader does not know places nothing.
+ */
+export declare const exposureGraphOf: (store: Store, skeleton: SessionSkeleton) => ExposureGraph;
+/** Whole cells and strata, summed over a batch's own sessions: the same cells a store of that batch alone derives, under the exposure the batch carries. */
 export declare const incrementsOf: (skeleton: SessionSkeleton) => Increments;

package/dist/sessions/cell-increments.js

@@ -1,9 +1,9 @@
 // The cell computation a deposit and a local read share (pool vocabulary spec Section 2, "the deposit form", and Section 4, rules 1 to 6). The pool's ingest turns a batch's skeleton into
 // increments with `incrementsOf`, and a local read derives its cells with `cellsOf` over the store it holds, projected the way a deposit projects it (`projectedStore`). Both end in the
 // one `cellsOf`, so a session gives the same cells at the pool and on the machine. This file reads no file system: the pool's Worker bundles it.
-import { ARG_CLASSES } from './call-shape.js';
-import { bucketFields, deriveCells, ENVIRONMENT_BUCKET, isEnvironmentCell } from './cells.js';
-import { bucketOf, floorOf, OTHER, projectedSteps } from './pool-wire.js';
+import { ARG_CLASSES, CHANGE_KINDS } from './call-shape.js';
+import { bucketFields, deriveCells, ENVIRONMENT_BUCKET, EXPOSURE_CODES, exposureOfCell, isEnvironmentCell } from './cells.js';
+import { bucketOf, floorOf, OTHER, OPEN_GATE, projectedSteps, wireChange, wireFeatures, wireKeys, wireValues } from './pool-wire.js';
 import { NO_RECALLS } from './recall-consequence.js';
 import { USAGE_FIELDS, harnessOf } from './schema.js';
 const floorTokens = (value) => floorOf('tokens', bucketOf('tokens', value));
@@ -53,13 +53,34 @@ export const cellsOf = (store, graph = NO_RECALLS) => {
     const named = new Set(marginal.motifs.filter(({ level, steps }) => level === 'named' && steps.length === 1 && steps[0]?.identity !== null).map(({ motifId }) => motifId));
     const motifs = new Map([...whole.motifs, ...marginal.motifs.filter(({ motifId }) => named.has(motifId))].map((motif) => [motif.motifId, motif]));
     const order = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
-    const cells = [...whole.cells, ...marginal.cells.filter(({ motifId }) => named.has(motifId))].sort((a, b) => order(a.motifId, b.motifId) || order(a.frameBucket, b.frameBucket) || order(a.grain, b.grain) || order(a.day, b.day) || Number(a.exposed) - Number(b.exposed));
+    const cells = [...whole.cells, ...marginal.cells.filter(({ motifId }) => named.has(motifId))].sort((a, b) => order(a.motifId, b.motifId) || order(a.frameBucket, b.frameBucket) || order(a.grain, b.grain) || order(a.day, b.day) || EXPOSURE_CODES[exposureOfCell(a)] - EXPOSURE_CODES[exposureOfCell(b)]);
     return { cells, motifs: [...motifs.values()].sort((a, b) => order(a.motifId, b.motifId)) };
 };
-/** A local store with each shell step read as a deposit reads it (`projectedSteps`), so its named motifs are the ones the pool holds. It uses the open gate, which keeps the name shape and length but applies no redactor or exclusion term: a local read sends nothing. */
+/**
+ * A local store with each shell step read as a deposit reads it (`projectedSteps`), so its named motifs are the ones the pool holds, and each call's key names as the wire sends them (`wireKeys`), so its shape cells are too.
+ * It uses the open gate, which keeps the name shape and length but applies no redactor or exclusion term: a local read sends nothing.
+ */
 export const projectedStore = (store, read) => {
     const harnesses = new Map([...store.sessions, ...store.subagents].map((session) => [session.session, harnessOf(session)]));
-    return { ...store, tools: store.tools.map((tool) => (tool.steps === undefined ? tool : { ...tool, steps: projectedSteps(tool, read, harnesses.get(tool.session) ?? 'claude-code') })) };
+    return {
+        ...store,
+        tools: store.tools.map((tool) => {
+            if (tool.steps === undefined)
+                return tool;
+            const steps = projectedSteps(tool, read, harnesses.get(tool.session) ?? 'claude-code');
+            const { keys, dropped } = wireKeys(tool.keys, steps[0]?.native, OPEN_GATE);
+            const sent = new Set(keys);
+            const argFeatures = wireFeatures(tool.argFeatures, sent);
+            const argValues = wireValues(tool.argValues, sent, steps[0]?.native);
+            const changeKind = wireChange(tool.changeKind);
+            // Only what the wire would carry, so the shape cells here are the pool's.
+            const projected = { ...tool, steps, keys };
+            delete projected.argFeatures;
+            delete projected.argValues;
+            delete projected.changeKind;
+            return { ...projected, ...(dropped === 0 ? {} : { keysDropped: dropped }), ...(argFeatures.length === 0 ? {} : { argFeatures }), ...(argValues.length === 0 ? {} : { argValues }), ...(changeKind.length === 0 ? {} : { changeKind }) };
+        }),
+    };
 };
 const NO_USAGE = { input: 0, cacheWrite: 0, cacheRead: 0, output: 0, thinking: 0 };
 const isKnown = (transcript) => transcript.harness !== OTHER;
@@ -71,6 +92,20 @@ const frameOf = (frame, harness) => ({
 });
 /** A class this reader does not know counts in `mixed`, the class a prompt that fits no other takes. */
 const classOf = (cls) => (cls === OTHER ? 'mixed' : cls);
+/** A feature whose key or size this reader does not know names nothing it can count, and a field it does not know is a field the call did not send. */
+const knownFeatures = (features) => (features ?? []).flatMap(({ key, valueSize, pathDepth, extension, dirKind, patternFeatures }) => key === OTHER || valueSize === OTHER
+    ? []
+    : [
+        {
+            key,
+            valueSize,
+            ...(pathDepth === undefined || pathDepth === OTHER ? {} : { pathDepth }),
+            ...(extension === undefined || extension === OTHER ? {} : { extension }),
+            ...(dirKind === undefined || dirKind === OTHER ? {} : { dirKind }),
+            ...(patternFeatures === undefined ? {} : { patternFeatures: patternFeatures.flatMap((feature) => (feature === OTHER ? [] : [feature])) }),
+        },
+    ]);
+const knownValues = (values) => (values ?? []).filter(({ key, enumValue }) => key !== OTHER && enumValue !== OTHER);
 /** A status this reader does not know is a segment the call did not report. */
 const statusOf = (status) => (status === OTHER ? 'none' : status);
 /** A skeleton's transcript as the record `deriveCells` reads. Everything a skeleton leaves out stays empty, so no derivation here can come to depend on it unnoticed. */
@@ -156,7 +191,7 @@ const stepPlaces = ({ tools }) => tools.flatMap(({ steps }, n) => steps.map((_,
 const toolRecords = (id, main, transcript, spawner) => {
     const own = stepPlaces(transcript);
     const spawning = spawner === null ? [] : stepPlaces(spawner);
-    return transcript.tools.map(({ side, prompt, status, durationMs, errorCode, keys, targetClass, argClass, steps }, n) => ({
+    return transcript.tools.map(({ side, prompt, status, durationMs, errorCode, keys, keysDropped, targetClass, argClass, argFeatures, argValues, changeKind, steps }, n) => ({
         kind: 'tool',
         cv: '',
         sid: '',
@@ -170,10 +205,14 @@ const toolRecords = (id, main, transcript, spawner) => {
         status: statusOf(status),
         target: null,
         targetBase: null,
-        // The names the wire carried, which are the only ones a skeleton-derived store ever holds; `keysDropped` is a count of names not sent and has no stored form.
+        // The names the wire carried, which are the only ones a skeleton-derived store ever holds, and the count of those it did not, at its bucket's lowest value.
         keys: keys ?? [],
+        ...(keysDropped === undefined ? {} : { keysDropped: floorOf('count', keysDropped) }),
         ...(targetClass === undefined ? {} : { targetClass }),
         ...(argClass === undefined ? {} : { argClass: ARG_CLASSES.filter((kind) => argClass.includes(kind)).sort() }),
+        ...(argFeatures === undefined ? {} : { argFeatures: knownFeatures(argFeatures) }),
+        ...(argValues === undefined ? {} : { argValues: knownValues(argValues) }),
+        ...(changeKind === undefined ? {} : { changeKind: CHANGE_KINDS.filter((kind) => changeKind.includes(kind)) }),
         durationMs,
         toolUseId: '',
         harnessVersion: null,
@@ -216,15 +255,43 @@ export const storeOf = (skeletons) => {
     }
     return store;
 };
-/** Whole cells and strata, summed over a batch's own sessions: the same cells a store of that batch alone derives. */
+const callKey = (tool) => `${tool.session}#${String(tool.n)}`;
+const promptKey = (session, index) => `${session}#${String(index)}`;
+/**
+ * The graph a deposit derives its cells under: the recommendations the skeleton carries, placed on the main run's calls that are not sidechain (the line the windows were counted on). A call in a shown window is shown, in a held
+ * one held, and one the batch has no row for is unknown: the graph adds no step and never reads a call as unexposed, since no row cannot be told from a client that did not look. An arm this reader does not know places nothing.
+ */
+export const exposureGraphOf = (store, skeleton) => {
+    const main = `${skeleton.id}#0`;
+    const line = store.tools.filter((tool) => tool.session === main && !tool.side).sort((a, b) => a.n - b.n);
+    const shown = { calls: new Set(), prompts: new Set() };
+    const held = { calls: new Set(), prompts: new Set() };
+    for (const { arm, from, to } of skeleton.recommendations ?? []) {
+        if (arm === OTHER)
+            continue;
+        const into = arm === 'shown' ? shown : held;
+        for (const tool of line.slice(from, to)) {
+            into.calls.add(callKey(tool));
+            into.prompts.add(promptKey(tool.session, tool.prompt));
+        }
+    }
+    return {
+        place: (tool, steps) => steps.map((step) => ({ step, exposed: shown.calls.has(callKey(tool)), held: held.calls.has(callKey(tool)) })),
+        exposedPrompt: (session, index) => shown.prompts.has(promptKey(session, index)),
+        heldPrompt: (session, index) => held.prompts.has(promptKey(session, index)),
+    };
+};
+/** Whole cells and strata, summed over a batch's own sessions: the same cells a store of that batch alone derives, under the exposure the batch carries. */
 export const incrementsOf = (skeleton) => {
-    const derived = cellsOf(storeOf([skeleton]));
+    const store = storeOf([skeleton]);
+    const derived = cellsOf(store, exposureGraphOf(store, skeleton));
     const cells = new Map();
     for (const cell of derived.cells) {
+        const exposure = exposureOfCell(cell);
         const exposed = cell.exposed ? 1 : 0;
-        const key = `${cell.motifId}/${cell.frameBucket}/${cell.grain}/${cell.day}/${String(exposed)}`;
+        const key = `${cell.motifId}/${cell.frameBucket}/${cell.grain}/${cell.day}/${String(EXPOSURE_CODES[exposure])}`;
         // The served column is a running sum, so a cell no session of this batch recorded tokens for adds nothing to it; the sum itself holds only what was observed, and `tokenSessions` and `tokenPrompts` say how much of the cell it covers.
-        cells.set(key, { key, harnessBucket: isEnvironmentCell(cell) ? ENVIRONMENT_BUCKET : bucketFields(cell.frameBucket).harnessBucket, motifId: cell.motifId, frameBucket: cell.frameBucket, grain: cell.grain, day: cell.day, exposed, sessions: cell.sessions, ok: cell.ok, failed: cell.failed, tokens: cell.tokens ?? 0, tokenSessions: cell.tokenSessions ?? 0, tokenPrompts: cell.tokenPrompts ?? 0, durationMs: cell.durationMs });
+        cells.set(key, { key, harnessBucket: isEnvironmentCell(cell) ? ENVIRONMENT_BUCKET : bucketFields(cell.frameBucket).harnessBucket, motifId: cell.motifId, frameBucket: cell.frameBucket, grain: cell.grain, day: cell.day, exposed, exposure, sessions: cell.sessions, ok: cell.ok, failed: cell.failed, tokens: cell.tokens ?? 0, tokenSessions: cell.tokenSessions ?? 0, tokenPrompts: cell.tokenPrompts ?? 0, durationMs: cell.durationMs });
     }
     // A session counts once per value, so each value is one session of this batch.
     const strata = new Map();

package/dist/sessions/cells.d.ts

@@ -1,6 +1,6 @@
-import { type Motif } from './motif.js';
-import { type RecallGraph } from './recall-consequence.js';
-import { type ErrorObservation, type Frame } from './schema.js';
+import { type CountedStep, type Motif } from './motif.js';
+import { type PlacedStep, type RecallGraph } from './recall-consequence.js';
+import { type ErrorObservation, type Frame, type ToolObservation } from './schema.js';
 import type { Store } from './store.js';
 /** Rule 6: an `index` cell is weekly, except a live cell, which stays at the UTC day. */
 export type Grain = 'day' | 'week';
@@ -32,7 +32,27 @@ export interface Cell {
     durationMs: number;
     /** Whether these counts sit inside a shown recall's consequence window, wholly or in part. It is part of the cell's key, so a motif's exposed and unexposed counts stay apart. */
     exposed: boolean;
+    /**
+     * What a deposit's evidence says of the counts: `shown` (inside a shown window), `held` (inside a held one), or `unknown` (no recommendation covers them, which a pool cannot tell from a client that never looked).
+     * Present only on a cell derived with an `ExposureGraph`; a local cell leaves it out and reads `exposed` alone. Its code is the last field of a stored key (`EXPOSURE_CODES`).
+     */
+    exposure?: Exposure;
+}
+/** The three readings of a recommendation's exposure. There is no `unexposed`: absent evidence is `unknown`. */
+export type Exposure = 'shown' | 'held' | 'unknown';
+/** The last field of a stored cell key. `unknown` is 0 so every key written before held existed keeps its meaning. */
+export declare const EXPOSURE_CODES: Readonly<Record<Exposure, number>>;
+/** A step placed by a graph that also knows the recommendations a session was held back from. */
+export interface HeldStep extends PlacedStep {
+    held: boolean;
+}
+/** A recall graph that states exposure in three readings. `deriveCells` reads `heldPrompt` and `held` beside the shown reading, and a cell it derives carries `exposure`. */
+export interface ExposureGraph extends RecallGraph {
+    place: (tool: ToolObservation, steps: readonly CountedStep[]) => HeldStep[];
+    heldPrompt: (session: string, index: number) => boolean;
 }
+/** A cell's reading: its own `exposure`, or for a local cell the two readings it can tell apart. */
+export declare const exposureOfCell: (cell: Pick<Cell, "exposed" | "exposure">) => Exposure;
 export declare const UNKNOWN = "unknown";
 /** The class name an effort cell carries: a class motif with no prompt class in it, so a read of prompt classes skips it by this prefix. */
 export declare const EFFORT_CLASS = "effort:";
@@ -60,7 +80,25 @@ export declare const parseRecoveryClass: (cls: string) => {
     failed: string;
     next: string;
 } | null;
-/** Whether a class motif names a prompt class, as opposed to one of the side cells (effort, or a failed call's code or what followed it). */
+/**
+ * The week cell of a call's shape: `shape:<action>/<facet>/<value>`, one facet of what the call held and never a value. It keeps the harness version bucket and no model, so it joins three dimensions: the call's action, the
+ * facet's value, and version. `target` is the class of the path target, `arg` one member of the argument classes (a set is one cell per member, rule 2), `dropped` the `count` bucket of key names not sent, and `keys` the
+ * sorted key names joined by commas, the call-shape method's key (a long tail, so the pool holds it to the thresholded floor). Layer 1 adds one cell per sent key's value feature (`size`, `depth`, `extension`, `dir`, and each
+ * `pattern` feature, its value `<key>=<member>`), per closed value (`enum`, `<key>=<value>`), and per change kind (`change`). A class motif with no prompt class in it, like the others.
+ */
+export declare const SHAPE_CLASS = "shape:";
+export declare const SHAPE_FACETS: readonly ["target", "arg", "dropped", "keys", "size", "depth", "extension", "dir", "pattern", "enum", "change"];
+export type ShapeFacet = (typeof SHAPE_FACETS)[number];
+export declare const shapeClass: (action: string, facet: ShapeFacet, value: string) => string;
+/** The three parts of a shape class name, or null for a name that is not one. An action name and a facet hold no `/`; the value is the rest. */
+export declare const parseShapeClass: (cls: string) => {
+    action: string;
+    facet: ShapeFacet;
+    value: string;
+} | null;
+/** The facets one call counts in: each that the record holds. A record captured before a facet existed has none of it, so it adds no cell of that facet. */
+export declare const shapeFacetsOf: (tool: ToolObservation) => [ShapeFacet, string][];
+/** Whether a class motif names a prompt class, as opposed to one of the side cells (effort, a failed call's code or what followed it, or a call's shape). */
 export declare const isPromptClass: (cls: string | null) => boolean;
 /** The frame bucket of a cell that joins no axis. */
 export declare const NO_AXES = "-";