@manyoars/oars 0.2.0 → 0.4.0

package/dist/sessions/pool-send-lock.d.ts

@@ -0,0 +1,20 @@
+import { type FileHandle } from 'node:fs/promises';
+export interface LockTimes {
+    /** A lock file untouched for longer than this was left by a run that died; its holder touches it every quarter of this. */
+    staleMs: number;
+    /** How long a run waits for the lock before it gives up. */
+    waitMs: number;
+    pollMs: number;
+}
+/** What a test replaces: `stat` to read a lock as stale at the moment a waiter looks, `open` to make the create fail the way Windows does, `platform` to pick the platform's rules. */
+export interface LockFs {
+    stat: (path: string) => Promise<{
+        mtimeMs: number;
+    }>;
+    open?: (path: string, flags: 'wx') => Promise<FileHandle>;
+    platform?: NodeJS.Platform;
+}
+export declare class SendLockBusy extends Error {
+    constructor();
+}
+export declare const withSendLock: <T>(outbox: string, run: () => Promise<T>, times?: Partial<LockTimes>, fs?: LockFs) => Promise<T>;

package/dist/sessions/pool-send-lock.js

@@ -0,0 +1,87 @@
+// One sender at a time per outbox (t884): the nightly task and `deposit --send` both take this lock, so a batch is never posted twice by two runs that overlap. The lock is a file created
+// with `wx` beside `sent.log`, so it holds across processes as well as inside one. A run that finds it held waits; a lock older than `staleMs` belongs to a run that died, and is taken over by one waiter only, under a guard file. The holder touches the file while it runs, so a long send (a first night of raw parts) is never mistaken for a dead run, and it removes the file only if the file still names its own run.
+import { randomUUID } from 'node:crypto';
+import { mkdir, open, readFile, rm, stat, utimes } from 'node:fs/promises';
+import { join } from 'node:path';
+import { setTimeout as sleep } from 'node:timers/promises';
+const DEFAULT_TIMES = { staleMs: 10 * 60 * 1000, waitMs: 2 * 60 * 1000, pollMs: 50 };
+export class SendLockBusy extends Error {
+    constructor() {
+        super('Another oars run is sending from this outbox.');
+    }
+}
+// EEXIST means another run holds the file. On Windows an open of a file whose delete is still pending (the holder just released it) answers EPERM or EACCES instead: the same contention, so retry within waitMs.
+const contended = (error, platform) => {
+    if (!(error instanceof Error))
+        return false;
+    const code = Reflect.get(error, 'code');
+    return code === 'EEXIST' || (platform === 'win32' && (code === 'EPERM' || code === 'EACCES'));
+};
+/**
+ * A stale lock is removed under a takeover guard (`send.lock.takeover`, created with `wx`), so one waiter at a time reads the lock again and removes it only if it is still stale. A live lock is never moved
+ * or removed: a waiter that read a lock as stale, but meets a lock another run took over and refreshed in the meantime, finds it fresh under the guard and leaves it. A guard left by a taker that died is
+ * removed once it is older than `staleMs`.
+ */
+const takeOver = async (file, staleMs, fs) => {
+    const guard = `${file}.takeover`;
+    try {
+        await (await open(guard, 'wx')).close();
+    }
+    catch {
+        const left = await stat(guard).catch(() => undefined);
+        if (left !== undefined && Date.now() - left.mtimeMs > staleMs)
+            await rm(guard, { force: true });
+        return false;
+    }
+    try {
+        const held = await fs.stat(file).catch(() => undefined);
+        if (held === undefined || Date.now() - held.mtimeMs <= staleMs)
+            return false;
+        await rm(file, { force: true });
+        return true;
+    }
+    finally {
+        await rm(guard, { force: true });
+    }
+};
+export const withSendLock = async (outbox, run, times = {}, fs = { stat }) => {
+    const { staleMs, waitMs, pollMs } = { ...DEFAULT_TIMES, ...times };
+    const file = join(outbox, 'send.lock');
+    const runId = randomUUID();
+    const create = fs.open ?? open;
+    const platform = fs.platform ?? process.platform;
+    await mkdir(outbox, { recursive: true });
+    const giveUp = Date.now() + waitMs;
+    for (;;) {
+        try {
+            const handle = await create(file, 'wx');
+            await handle.writeFile(runId);
+            await handle.close();
+            break;
+        }
+        catch (error) {
+            if (!contended(error, platform))
+                throw error;
+        }
+        const held = await fs.stat(file).catch(() => undefined);
+        // A takeover that cleared the lock goes straight back to taking it; any other outcome waits, and gives up once waitMs has passed.
+        if (held !== undefined && Date.now() - held.mtimeMs > staleMs && (await takeOver(file, staleMs, fs)))
+            continue;
+        if (Date.now() >= giveUp)
+            throw new SendLockBusy();
+        await sleep(pollMs);
+    }
+    const beat = setInterval(() => {
+        const now = new Date();
+        utimes(file, now, now).catch(() => undefined);
+    }, Math.max(1, Math.floor(staleMs / 4)));
+    try {
+        return await run();
+    }
+    finally {
+        clearInterval(beat);
+        // The file is ours only while it still names this run; a lock another run took over is theirs.
+        if ((await readFile(file, 'utf8').catch(() => undefined)) === runId)
+            await rm(file, { force: true });
+    }
+};

package/dist/sessions/pool-sent.d.ts

@@ -0,0 +1,4 @@
+/** Each hash that was sent, with the time it was sent. A hash sent twice keeps its first time. */
+export declare const sentLog: (outbox: string) => Promise<Map<string, string>>;
+export declare const sentHashes: (outbox: string) => Promise<Set<string>>;
+export declare const markSent: (outbox: string, hash: string, at: number) => Promise<void>;

package/dist/sessions/pool-sent.js

@@ -0,0 +1,26 @@
+// What the nightly send has already sent, so a night after a failure sends only what was not taken: one line for each hash, in the outbox beside `shown.log`. A batch that is rebuilt hashes differently and so is sent again, which is what a deposit that changed should do.
+import { appendFile, mkdir, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { isMissing } from './pool-outbox.js';
+const sentFile = (outbox) => join(outbox, 'sent.log');
+/** Each hash that was sent, with the time it was sent. A hash sent twice keeps its first time. */
+export const sentLog = async (outbox) => {
+    const log = new Map();
+    try {
+        for (const line of (await readFile(sentFile(outbox), 'utf8')).split('\n')) {
+            const [hash = '', at = ''] = line.split(' ');
+            if (hash !== '' && !log.has(hash))
+                log.set(hash, at);
+        }
+    }
+    catch (error) {
+        if (!isMissing(error))
+            throw error;
+    }
+    return log;
+};
+export const sentHashes = async (outbox) => new Set((await sentLog(outbox)).keys());
+export const markSent = async (outbox, hash, at) => {
+    await mkdir(outbox, { recursive: true });
+    await appendFile(sentFile(outbox), `${hash} ${new Date(at).toISOString()}\n`, 'utf8');
+};

package/dist/sessions/pool-totals.d.ts

@@ -0,0 +1,10 @@
+export interface OutboxTotals {
+    /** Batches of the current stamp whose hash `sent.log` holds. */
+    sentBatches: number;
+    /** Raw copies of the current stamp whose hash `sent.log` holds. */
+    sentRaw: number;
+    /** Raw copies queued now, and the placeholders in their bodies: the values masked locally before anything is sent. */
+    rawCopies: number;
+    rawMasked: number;
+}
+export declare const outboxTotals: (storeDir: string) => Promise<OutboxTotals>;

package/dist/sessions/pool-totals.js

@@ -0,0 +1,21 @@
+// What the outboxes hold across every server, for `oars sessions verify`: how much of it was already sent, and how many values the raw copies masked. Counts only.
+import { readdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { heldBatches } from './pool-outbox.js';
+import { heldRaw } from './pool-raw.js';
+import { sentHashes } from './pool-sent.js';
+import { placeholders } from './redact.js';
+export const outboxTotals = async (storeDir) => {
+    const root = join(storeDir, 'pool-outbox');
+    const totals = { sentBatches: 0, sentRaw: 0, rawCopies: 0, rawMasked: 0 };
+    for (const name of await readdir(root).catch(() => [])) {
+        const outbox = join(root, name);
+        const done = await sentHashes(outbox);
+        totals.sentBatches += (await heldBatches(outbox)).batches.filter(({ hash }) => done.has(hash)).length;
+        const { copies } = await heldRaw(outbox);
+        totals.sentRaw += copies.filter(({ hash }) => done.has(hash)).length;
+        totals.rawCopies += copies.length;
+        totals.rawMasked += copies.reduce((sum, { body }) => sum + placeholders(body), 0);
+    }
+    return totals;
+};

package/dist/sessions/pool-wire.d.ts

@@ -0,0 +1,435 @@
+import { VOCAB_VERSION, type RepoSize } from './public-vocabulary.js';
+import { type ArgClass, type TargetClass } from './call-shape.js';
+import type { Cell } from './cells.js';
+import type { Redactor } from './redact.js';
+import type { Motif } from './motif.js';
+import type { Read, ReadAsOf } from './read.js';
+import { type RecoveryCalls } from './recovery-calls.js';
+import { type PromptIntervention, type Frame, type FrameStack, type Harness, type LanguageShare, type PromptClass, type PromptObservation, type SessionObservation, type StepEdge, type StepObservation, type ToolObservation, type ToolStatus, type Usage } from './schema.js';
+export declare const SKELETON_FORMAT = 3;
+/**
+ * The version of the field list: every field name a batch can hold (`BATCH_FIELDS` in `pool-outbox.ts`). It moves with any field added, so a server told the version knows which names a batch may carry,
+ * and a test pins the list to it (`pool-wire-additive.test.ts`). A field is deprecated and left on the list, never removed (conclusion section 17, rule 3).
+ */
+export declare const FIELD_LIST_VERSION = 8;
+export declare const BUNDLE_FORMAT = 1;
+/** One constant: the pool serves only the vocabulary version the client holds. */
+export { VOCAB_VERSION };
+/**
+ * Section 7's edges. A bucket is the count of edges a value reaches, so bucket 0 is under the first edge and the last is the first edge's doubling past the cap. `tokens`: under 1k, then
+ * doubling to 1.024M and over. `ms`: under 100 ms, then doubling to 6,553.6 s and over. `seconds`: under 1 s, then doubling to 65,536 s and over. `count`: 0, 1, 2, 3-4, 5-8, 9-16, 17-32, over 32.
+ */
+declare const EDGES: {
+    readonly tokens: number[];
+    readonly ms: number[];
+    readonly seconds: number[];
+    readonly count: readonly [1, 2, 3, 5, 9, 17, 33];
+    readonly calls: readonly [1, 2, 3, 5, 9, 17, 33, 65, 129, 257, 513, 1025, 2049, 4097];
+};
+export type BucketKind = keyof typeof EDGES;
+/** The bucket a value falls in. */
+export declare const bucketOf: (kind: BucketKind, value: number) => number;
+/** A stored `explore` count as it pools: its `calls` bucket, or null for a value no count holds (a record captured before the strata has none). The exact count never leaves. */
+export declare const projectExplore: (stored: number | undefined) => number | null;
+/** The lowest value of a bucket, which is what a derivation counts a bucketed value as: it never reads above what the sender held. */
+export declare const floorOf: (kind: BucketKind, bucket: number) => number;
+/** The closed list of how a step came about (`schema.ts` `StepEdge`). */
+export declare const EDGE_KINDS: readonly ["next", "spawned", "retried", "after-error"];
+/** One edge arriving at a step: its kind, and the position of the step it names, counted over the steps of one transcript in call order (the batch's own ordinal, never a call number). A `spawned` edge names a step of the spawning transcript. */
+export interface SkeletonEdge {
+    /** `other` for a kind the reader does not know (see `OTHER`); it names no step the parser can check, so only its shape is held. */
+    kind: StepEdge['kind'] | typeof OTHER;
+    target: number;
+}
+/**
+ * A step without what a server can compute: `n` is its call's position, `seg` its place in the call (the array position), and `frameId` hashes a frame the skeleton holds. Its cost is
+ * two buckets, never the exact counts. `parent` is the position of the spawning call in the `tools` of the transcript its transcript's `spawnedIn` names (Section 1.2's `parent` ordinal).
+ */
+export type SkeletonStep = Omit<StepObservation, 'n' | 'seg' | 'frameId' | 'cost' | 'edges' | 'status'> & {
+    /** The edges that arrive at this step, `retried` already decided by the client (the pool holds no raw key to compare); absent when none arrive. */
+    edges?: SkeletonEdge[];
+    /** `other` for a status the reader does not know (see `OTHER`). */
+    status: ToolStatus | typeof OTHER;
+    /** A `tokens` bucket of the step's tokens. */
+    tokens: number | null;
+    /** An `ms` bucket of the step's time. */
+    ms: number | null;
+    /** True when `tokens` was divided among the calls of one response, not measured for this step; absent otherwise. */
+    allocated?: true;
+    /** A `tokens` bucket of the tokens the run spent after this step (spec Section 1.2): the bucket of the exact sum, never a sum of buckets, summed over the later steps that reported tokens (a lower bound). Null when steps follow and none reported tokens; 0 only when nothing follows or the later steps reported zero. */
+    remainingTokens: number | null;
+    /** The projected type of the subagent whose run holds the step, a built-in or `custom`; null on a main-run step. */
+    agentType: string | null;
+    /** The step's frame: a position in its transcript's `frames`, the frame of the call that made it, with that call's own model and harness version (t867). The parser refuses a position outside the list. */
+    frame: number;
+    /** The skill whose run the step's call sits in, the name after redaction or `private`; absent outside a run. The harness marks no end to a run but stops naming the skill on the next line, and a step carries the skill its call's line named. */
+    skill?: string;
+};
+/** A call's order is its position in `tools`, and its `prompt` is a position in the same transcript's `prompts`: ordinals inside the batch, never the session's own numbers. */
+export interface SkeletonTool {
+    side: boolean;
+    prompt: number | null;
+    status: ToolStatus | typeof OTHER;
+    /** Exact, per tool: the one exact time on the wire, which W reads on `ledger` (Section 1.2, `durationMs`). A cell never reads it. */
+    durationMs: number | null;
+    /** The failed call's class, a member of `ERROR_CODES` (a user refusal, a policy denial, and a real failure are three codes); null on a call that did not fail and on one whose capture holds none. Never result text. */
+    errorCode: string | null;
+    /** For a failed call, what followed it: the actions of up to the next 5 calls of its prompt and whether an edit was among them. Absent on a call that did not fail. Never a signature, command, or text. */
+    recoveryCalls?: RecoveryCalls;
+    /** The call's input key names, sorted (t870): a public tool's from its pinned list in `TOOL_INPUT_KEYS`, any other tool's from the name gate, and none for a tool that went as `private`. Never a value. Absent when none is sent. */
+    keys?: string[];
+    /** A `count` bucket of the key names the call held that were not sent: off a public tool's pinned list, or kept `private` by the gate. Absent when none was dropped. */
+    keysDropped?: number;
+    /** The class of the call's path target, derived at capture from the target's base and suffix (`targetClassOf`): the base name itself does not go. Absent on a call captured before it. */
+    targetClass?: TargetClass | typeof OTHER;
+    /** The classes of the call's arguments as a sorted set, derived at capture (`argClassOf`); never a value. Absent on a call captured before it. */
+    argClass?: Array<ArgClass | typeof OTHER>;
+    steps: SkeletonStep[];
+}
+/**
+ * A prompt's usage as `tokens` buckets: `thinking` is a token count (the thinking tokens of the output), so it takes the same edges as the rest. A category the source
+ * never recorded is null, never the bucket of zero: a prompt with no counts at all sends five nulls, and a partial total sends a number only for the categories it observed.
+ */
+export type SkeletonUsage = {
+    [field in keyof Usage]: number | null;
+};
+/** A language of the stack with its share of the touched files (spec Section 7): one of four buckets, never a count. */
+export interface LanguageShareEntry {
+    language: string;
+    languageShare: LanguageShare | typeof OTHER;
+}
+/**
+ * The MCP servers, skills, and plugins in reach of a session, each the name after redaction or `private` (a plugin has no pinned list, so it is always `private`). `filled` says whether the harness recorded a
+ * `setup` or a `funnel` at all: an unfilled reach lists nothing and must not be read as a session with no tools.
+ */
+export interface Reach {
+    filled: boolean;
+    mcp: string[];
+    skills: string[];
+    plugins: string[];
+}
+/** How many people the operator's organization has (an operator's setting, read locally, never looked up). */
+export declare const ORG_SIZES: readonly ["solo", "2-10", "11-100", "101-1000", "over-1000", "unknown"];
+export type OrgSize = (typeof ORG_SIZES)[number];
+/** Whether the repository's local git log shows one commit author or several (distinct authors, counted and then dropped). */
+export declare const TEAMS: readonly ["solo", "team", "unknown"];
+export type Team = (typeof TEAMS)[number];
+/** Whether the repository is public or private (an operator's setting, read locally, never looked up). */
+export declare const REPO_VISIBILITIES: readonly ["public", "private", "unknown"];
+export type RepoVisibility = (typeof REPO_VISIBILITIES)[number];
+/** What the pool can state about whom a deposit covers. It is not a filter: no read uses it. Anything not read locally is `unknown`. */
+export interface Coverage {
+    orgSize: OrgSize;
+    team: Team;
+    repoVisibility: RepoVisibility;
+}
+export declare const NO_COVERAGE: Coverage;
+/** The UTC hour of day, 0 to 23, of a timestamp, whatever offset it was written in; null when there is none or it does not parse. */
+export declare const hourOf: (ts: string | null | undefined) => number | null;
+/**
+ * The frame a skeleton holds: the stored frame, with the stack's shares beside its languages. A language whose share is not known is in `languages` and has no entry here. `reach`, `repoKey`, and the coverage bands
+ * are on the transcript's frame and the frames of its list, not on a prompt's. `hour` is the UTC hour beside `day` and joins no cell. Every one is optional: an absent field was not sent.
+ */
+export type SkeletonFrame = Omit<Frame, 'stack' | 'harness'> & {
+    harness: WireHarness;
+    stack: Omit<FrameStack, 'size'> & {
+        size: RepoSize | typeof OTHER | null;
+        languageShares: LanguageShareEntry[];
+    };
+    reach?: Reach;
+    repoKey?: string;
+    orgSize?: OrgSize | typeof OTHER;
+    team?: Team | typeof OTHER;
+    repoVisibility?: RepoVisibility | typeof OTHER;
+    hour?: number;
+};
+export interface SkeletonPrompt {
+    cls: PromptClass | typeof OTHER;
+    /** A `count` bucket. */
+    errors: number;
+    /** A `seconds` bucket. */
+    wallSec: number | null;
+    usage: SkeletonUsage;
+    /** A `calls` bucket of the prompt's steps that only look (`file.read`, `file.search`, `web.search`, `web.fetch`); null when the record holds no count. */
+    explore: number | null;
+    /** A `count` bucket of the responses that reported usage: what a partial `usage` sum covers. Absent only when the record predates the coverage (capture version 20). */
+    usageResponses?: number;
+    /** Whether a human stepped in after this prompt's work and how, one of the closed list (t882; docs/sessions-store.md "Prompt intervention"). Absent when the stored prompt predates the signal: absent means not computed, `unknown` means computed and not sayable. An outcome row, never a grade. */
+    intervention?: PromptIntervention | typeof OTHER;
+    frame: SkeletonFrame;
+}
+export interface SkeletonTranscript {
+    /** The transcript's Merkle root and the count of its lines it covers (Section 2, "Subagents"): one pair for each transcript, the main's first. */
+    merkleRoot: string;
+    leaves: number;
+    harness: WireHarness;
+    frame: SkeletonFrame;
+    /** The distinct frames the transcript's steps ran in, the transcript's own first; a step's `frame` is a position in it. */
+    frames: SkeletonFrame[];
+    /** The position, in the batch's `transcripts`, of the transcript that spawned this one; null for the main run, and for a subagent whose spawner the batch does not hold or the harness does not name. */
+    spawnedIn: number | null;
+    prompts: SkeletonPrompt[];
+    tools: SkeletonTool[];
+}
+/** What a delta entry may change (spec Section 4, rule 4): `permissionMode` and `effort` by name only, a `plugin` as added or removed, and a `package` as removed. */
+export type DeltaField = 'plugin' | 'package' | 'permissionMode' | 'effort';
+export type DeltaKind = 'added' | 'removed' | 'changed';
+/** The one metric an entry's change is in: `callsPerSession` (tool calls in a session, or calls naming the package) in `count` buckets, `thinking` (thinking tokens in a prompt) in `tokens` buckets. */
+export type DeltaMetric = 'callsPerSession' | 'thinking';
+/**
+ * One change between a client's own before and after windows. It holds no `sid`, root, window date, or exact value: `name` is the public package or the word `private` (a plugin has no pinned registry, so
+ * always `private`), null when the field is named alone; `registry` is the package's registry and is null for a `private` name; `change` is the signed bucket of the metric's move, never the metric.
+ */
+export interface DeltaEntry {
+    deltaKind: DeltaKind | typeof OTHER;
+    field: DeltaField | typeof OTHER;
+    name: string | null;
+    registry: string | null;
+    metric: DeltaMetric | typeof OTHER;
+    change: number;
+}
+export interface SessionSkeleton {
+    format: typeof SKELETON_FORMAT;
+    /** The vocabulary version the client built the batch under: stored with it, so a read can tell a batch of an older list from a current one. */
+    vocabVersion: string;
+    /** `FIELD_LIST_VERSION` as the client held it: the fields a batch of this version may carry. */
+    fieldsVersion: number;
+    /** A hash the client computes per account, so a redeposit replaces and two accounts' sessions cannot be joined. Never the session's own id. */
+    id: string;
+    /** The main transcript first, then each subagent's. */
+    transcripts: SkeletonTranscript[];
+    /** One for the batch: a hash of the main transcript's non-null call durations in call order, only with `MIN_TIMED_CALLS` of them; a subagent's calls never join it. */
+    timingPrint: string | null;
+    /** The batch's client-built delta entries (Section 2, "Deltas"): changes between the client's own before and after windows, each carried once, by the batch of the session that filled the after window. */
+    deltas: DeltaEntry[];
+}
+/** One main session and the subagents it spawned, as the local store holds them. */
+export interface SessionRecords {
+    main: SessionObservation;
+    /** The main transcript first, then each subagent's, ordered by session so one store builds one batch. */
+    transcripts: {
+        session: SessionObservation;
+        prompts: PromptObservation[];
+        tools: ToolObservation[];
+        root: TranscriptRoot | null;
+    }[];
+}
+/** What a skeleton file holds of a transcript that may leave the machine: its root and the count of lines under it. */
+export interface TranscriptRoot {
+    merkleRoot: string;
+    leaves: number;
+}
+/** W's minimum for a timing print (deposit-weighting spec, layer 5): fewer timed calls than this say too little to tell sessions apart. */
+export declare const MIN_TIMED_CALLS = 50;
+/** A session has ended once no transcript of it has gained a line for this long (`session_idle_hours`, spec Section 7). */
+export declare const SESSION_IDLE_HOURS = 6;
+/**
+ * Whether a session's batch may be built at `now`: no transcript of it, main or subagent, has gained a line for `SESSION_IDLE_HOURS`. A transcript gains a line when capture sees it change, which
+ * stamps a new `rev` in epoch milliseconds, but a transcript can grow after the last capture, so `written` (the newest write to any raw file of the session, 0 when none is known) counts too: the
+ * session was last active at the later of the two. A subagent that died without an end marker holds its session back at most that long.
+ */
+export declare const hasEnded: (records: SessionRecords, now: number, written: number) => boolean;
+/** Every main session of a store, with its records. */
+export declare const sessionsOf: (store: {
+    sessions: readonly SessionObservation[];
+    subagents: readonly SessionObservation[];
+    prompts: readonly PromptObservation[];
+    tools: readonly ToolObservation[];
+}, roots: ReadonlyMap<string, TranscriptRoot>) => SessionRecords[];
+/** One command of a shell call as the projection reads it (`projectStoredShell`): a program, its subcommand, and its flags, each the name after redaction or `private`. */
+export interface ShellCommand {
+    program: string;
+    subcommand: string | null;
+    flags: readonly string[];
+}
+/** Reads a stored shell call's commands in order. The client passes the projection; this file holds no vocabulary snapshot, so the Worker can bundle it. */
+export type ShellReader = (tool: ToolObservation) => readonly ShellCommand[];
+/** The most characters a name may hold on the wire. A longer value is not a name: it counts as redacted. */
+export declare const NAME_MAX = 128;
+/** Whether a value has the shape of a name (and so can be told from a command line, a path, or an email) and is within `NAME_MAX`. */
+export declare const isWireName: (name: string) => boolean;
+/** The shape of a pull's package name: a name, or a scope or module path with `/` in it. */
+export declare const isWirePullName: (name: string) => boolean;
+/** What the client holds against a value before it leaves: the redactor, and the exclusion terms the operator keeps. This is the one gate; the pool assigns every other class. */
+export interface WireGate {
+    readonly redact: Redactor;
+    readonly terms: readonly string[];
+}
+/** No redaction and no terms: the name shape and the length limit still apply. A local read, which sends nothing, uses it. */
+export declare const OPEN_GATE: WireGate;
+/**
+ * A name as the wire holds it: the value itself, or `private` when it counts as redacted. A value counts as redacted when the redactor changes it, it holds an exclusion term, it fails the name shape, or it is over
+ * `NAME_MAX` characters, because a secret, an employer's name, or a mis-parsed command is not a name and nothing downstream can take it back. `keys` (t870) sends its names through this same function.
+ */
+export declare const wireName: (gate: WireGate, name: string, hasShape?: (name: string) => boolean) => string;
+/**
+ * A stored tool's steps as the wire holds them: each shell step's identity is replaced by the projected command, and every long-tail name (a native name, MCP server, skill, host, program, or pull name) is
+ * sent as it is after the gate, or `private` when it counts as redacted. A `private` program holds no pull. The one place a deposit and a local read take it from.
+ */
+export declare const projectedSteps: (tool: ToolObservation, read: ShellReader, harness: Harness, gate?: WireGate) => StepObservation[];
+/** The hash a batch's timing print is made with, over the durations in call order: the client's `contentHash` (D1's `hP`). */
+export type Print = (durations: readonly number[]) => string;
+/**
+ * The skeleton of a session; null when any record of it was captured before steps and frames, or a transcript of it has no root, which holds no closed reading to send. The batch holds the main
+ * transcript's run first, then each subagent's as its own run; its `id` is the main session's, and its one `timingPrint` is over the main transcript's calls alone.
+ */
+export declare const skeletonOf: (records: SessionRecords, id: string, read: ShellReader, print: Print, deltas?: readonly DeltaEntry[], gate?: WireGate, coverage?: Coverage) => SessionSkeleton | null;
+/**
+ * The version bucket of a session that recorded none: Cursor, Gemini, and Grok Build keep no harness version in their local files, and neither does a VS Code Copilot Chat session whose requests carry no `agent.extensionVersion`, so their cells are
+ * `<harness>/unknown/<model>`. It is the one non-numeric word a bundle can be asked for, so those harnesses are served the cells they have.
+ */
+export declare const UNKNOWN_VERSION = "unknown";
+/** A harness version a bundle can be asked for: public, so the request carries nothing private, or `unknown` for a harness with none on record. The admitted list replaces this shape rule when it ships. */
+export declare const isBundleVersion: (version: string) => boolean;
+/** Whether `name` is a harness the schema names. */
+export declare const isHarness: (name: string) => name is Harness;
+export interface Refusal {
+    ok: false;
+    field: string;
+    reason: string;
+}
+/** The value a reader gives an enumerated field whose value it does not know (conclusion section 17, rule 3). */
+export declare const OTHER = "other";
+/** The harness of a transcript or a frame: one the schema names, or `other` for one a newer client names. */
+export type WireHarness = Harness | typeof OTHER;
+/**
+ * What one parse sets aside: a field the reader does not know, a value it does not know, and a literal a client sent beside `other`. The bag is the stored form of these (the `extensions` column), the fields kept as sent and
+ * read by nothing that serves: no cell, read, or bundle is derived from it. `at` is the field's path, as a refusal names it.
+ */
+export interface Extension {
+    at: string;
+    kind: 'field' | 'value' | 'literal';
+    value: unknown;
+}
+/** The fields a client may send a literal beside (`<field>Literal`) when the field itself says `other`: the enumerated fields, whose values a closed list holds. */
+export declare const ENUMERATED_FIELDS: ReadonlySet<string>;
+/**
+ * The fields that may be absent at format 3, by the level of the batch that holds them. An absent one reads as null, or as empty for a list, exactly as a sent null does, so a batch with all of them left out is
+ * served from what remains. A field the cells need to be sound (a harness, a status, a bucket of tokens) is never here.
+ */
+export declare const OPTIONAL: {
+    readonly batch: readonly ["timingPrint", "deltas"];
+    readonly frame: readonly ["harnessVersion", "model", "effort", "day", "shell", "reach", "repoKey", "orgSize", "team", "repoVisibility", "hour"];
+    readonly stack: readonly ["size", "languageShares"];
+    readonly prompt: readonly ["wallSec", "explore", "usageResponses", "intervention"];
+    readonly tool: readonly ["prompt", "durationMs", "errorCode", "recoveryCalls", "keys", "keysDropped", "targetClass", "argClass"];
+    readonly step: readonly ["tokens", "ms", "allocated", "parent", "skill", "edges", "remainingTokens"];
+    readonly transcript: readonly ["spawnedIn"];
+};
+/** The most bytes (as JSON) one field this reader does not know, or one literal, may hold: an enumerated value or a literal never needs more, and a newer client's larger structure belongs in a new format version. The deposit's own cap is no part of this. */
+export declare const MAX_EXTENSION_BYTES: number;
+export declare const HARNESSES: readonly ["claude-code", "cursor", "codex", "copilot", "gemini", "grok", "opencode", "pi", "vscode-copilot", "otel"];
+/** The registries a package comes from; a pull may also come from a skill, plugin, or MCP registry. */
+export declare const PACKAGE_REGISTRIES: readonly ["npm", "pypi", "crates", "go", "rubygems", "homebrew"];
+/** A parsed batch: the skeleton every derivation reads, the bag of what this reader did not know, and the count of values it read as `other`. Only the skeleton is ever served from. */
+export interface ParsedSkeleton {
+    ok: true;
+    skeleton: SessionSkeleton;
+    extensions: Extension[];
+    others: number;
+}
+/** The skeleton in `value`, rebuilt from the fields read, with the bag of what was set aside; else the first field that is a shape error, and why. */
+export declare const parseSkeleton: (value: unknown) => ParsedSkeleton | Refusal;
+/**
+ * One count of a stack stratum (spec Section 4, rule 3), across every harness version, so it is never joined to one. The two pairs hold two values each, joined by a slash:
+ * `languageShare` is `<language>/<share bucket>` and `repoFilesExplore` is `<stack size, xs to xl>/<explore calls bucket>`.
+ */
+export interface StrataCell {
+    dimension: 'language' | 'framework' | 'repoFiles' | 'languageShare' | 'repoFilesExplore';
+    value: string;
+    sessions: number;
+    clusters: number;
+}
+/**
+ * The floors a pool served the bundle at, stated so a client can print them and holds none of its own. `public` is the clusters a cell needs to be served and a read to count it, `disclosure` the clusters that must hold a signature's hash
+ * before its text may be requested, and `families` the read families that have a public floor of their own (a family not listed is at `public`). Both are the deploy's to set, so a client reads them here and never applies one.
+ */
+export interface BundleFloors {
+    public: number;
+    disclosure: number;
+    families?: FamilyFloors;
+}
+/** A floor per read family, keyed by the family's name as the pool states it. A client applies none and prints only the families it knows, so a name this version has never heard of (a family a later pool adds) is carried as stated and not refused. */
+export interface FamilyFloors {
+    [family: string]: number;
+}
+/** A number the pool can state, or the plain statement that nothing measures it yet. `no source yet` is never a zero: a measured nothing and an unmeasured one must not read alike. */
+export type Sourced = {
+    state: 'value';
+    value: number;
+} | {
+    state: 'no source yet';
+    reason: string;
+};
+/**
+ * The set of four (direction conclusion, section 20 rule 1), as totals. Served cells and the below-floor backlog are totals over the cells this bundle derived from; the backlog is one number and names no
+ * tuple, week, or value. The panel is one account count and names no account. `demand` and `goal` hold a place each for a source a later brief adds. `floor`, the versions, and `asOf` are its lineage (section 17 rule 6).
+ */
+export interface Books {
+    floor: number;
+    format: typeof BUNDLE_FORMAT;
+    vocabVersion: string;
+    asOf: ReadAsOf;
+    served: {
+        total: number;
+        byWeek: {
+            week: string;
+            cells: number;
+        }[];
+        byTuple: {
+            tuple: string;
+            cells: number;
+        }[];
+    };
+    backlog: number;
+    panel: Sourced;
+    /** The UTC day the panel was counted: the pool reads its deposits once a day. */
+    panelDay: string | null;
+    demand: {
+        comparisonReadOwners: Sourced;
+        followOnReads: Sourced;
+    };
+    goal: {
+        readYield: Sourced;
+        costPerServedCell: Sourced;
+        yieldPerServedCell: Sourced;
+    };
+}
+/** One harness version's replica, as the server signs it. It names its harness, which the signature covers, so a bundle for one harness cannot stand in for another's. Nothing in it is keyed by stack. */
+export interface Bundle {
+    format: typeof BUNDLE_FORMAT;
+    harness: Harness;
+    harnessVersion: string;
+    vocabVersion: string;
+    /** The public floor the pool applied (`floors.public`): every cell and read is at or above it except a family on a lower floor of its own, which states its floor on each read and in `floors.families`. */
+    floor: number;
+    asOf: ReadAsOf;
+    cells: Cell[];
+    motifs: Motif[];
+    reads: Read[];
+    strata: StrataCell[];
+    /** Additive: a bundle from a pool before the floors were bindings holds none, and a client that does not know the field ignores it. */
+    floors?: BundleFloors;
+    /** Absent in a bundle signed before the set of four existed, which `oars sessions books` reads as no pool books. */
+    books?: Books;
+}
+/** The signature covers these exact bytes, so nothing has to be canonicalized on either side. */
+export interface SignedBundle {
+    payload: string;
+    /** Ed25519 over the payload's UTF-8 bytes, in base64. */
+    signature: string;
+}
+/** The public half of the pool's key, as a client pins it at login. */
+export interface PinnedKey {
+    kty: string;
+    crv: string;
+    x: string;
+}
+/** The bundle, only when the pinned key signed these bytes for the harness and version that were asked for: another harness's or version's bundle, under a good signature, is still the wrong answer. */
+export declare const verifyBundle: (signed: unknown, key: PinnedKey, harness: Harness, harnessVersion: string) => Promise<{
+    ok: true;
+    bundle: Bundle;
+} | {
+    ok: false;
+    reason: string;
+}>;