@manyoars/oars 0.4.0 → 0.5.1

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

@@ -1,17 +1,33 @@
 import { VOCAB_VERSION, type RepoSize } from './public-vocabulary.js';
-import { type ArgClass, type TargetClass } from './call-shape.js';
+import { type ArgClass, type ArgFeature, type ArgName, type ArgValue, type ChangeKind, type DiffShape, type DirectoryKind, type ExtensionClass, type NameKind, type PathDepth, type PatternFeature, type TargetClass, type ValueSize } from './call-shape.js';
 import type { Cell } from './cells.js';
 import type { Redactor } from './redact.js';
 import type { Motif } from './motif.js';
+import type { Recall } from './recall-object.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;
+import { type EditDigest, 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 = 7;
+/** The formats the parser reads, oldest first: the client builds only the last. */
+export declare const READ_FORMATS: readonly [3, 4, 5, 6, 7];
+export type SkeletonFormat = (typeof READ_FORMATS)[number];
+/** The tool fields format 4 added: a format 3 batch that holds one is holding a field it does not define. */
+export declare const FORMAT_4_TOOL_FIELDS: readonly ["argFeatures", "argValues", "changeKind"];
+/** The tool fields format 5 added: a batch of format 4 or 3 that holds one is holding a field it does not define. */
+export declare const FORMAT_5_TOOL_FIELDS: readonly ["names", "namesDropped", "templates", "templatesDropped", "diffShape"];
+/** The batch fields format 6 added: a batch of an older format that holds one is holding a field it does not define. */
+export declare const FORMAT_6_BATCH_FIELDS: readonly ["recommendations"];
+/** The format that added exposure. A batch of an older format holds no `recommendations`, and its failed calls are checked with the rule they were built under. */
+export declare const EXPOSURE_FORMAT = 6;
+/** The format that added edit digests. */
+export declare const DIGEST_FORMAT = 7;
+/** The tool fields format 7 added: a batch of format 6 or older that holds one is holding a field it does not define. */
+export declare const FORMAT_7_TOOL_FIELDS: readonly ["digests"];
 /**
  * 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 FIELD_LIST_VERSION = 14;
 export declare const BUNDLE_FORMAT = 1;
 /** One constant: the pool serves only the vocabulary version the client holds. */
 export { VOCAB_VERSION };
@@ -84,8 +100,50 @@ export interface SkeletonTool {
     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>;
+    /** Each sent key's value features (layer 1), sorted by key: closed-list members only, never the value. Only a key in `keys` has one. Absent when none is sent. */
+    argFeatures?: SkeletonArgFeature[];
+    /** Each sent key's closed value (layer 1): a boolean as `true` or `false`, or a member of its tool's list in `CLOSED_ARG_VALUES`. Only a key in `keys` has one. Absent when none is sent. */
+    argValues?: SkeletonArgValue[];
+    /** What changed from the previous call of the same tool in the same prompt (layer 1), a sorted set of `CHANGE_KINDS` members. Absent on the first such call and on a call captured before it. */
+    changeKind?: Array<ChangeKind | typeof OTHER>;
+    /** The name tokens of the call's values (layer 2), sorted by kind and name: file, directory, and variable names, flag values that are names, a custom agent's name. Each passed the one gate (`wireName`); never a value. Absent when none is sent. */
+    names?: SkeletonArgName[];
+    /** A `count` bucket of the name tokens the call held that were not sent: one the redactor changes, an exclusion term matches, or that has no name shape. Absent when none was dropped; never the names. */
+    namesDropped?: number;
+    /** The old and new text of an Edit (one pair), a MultiEdit (one pair per edit, in order), or a Write (a new digest only), each a digest of the exact text, plain so the same text matches across sessions. Never the text. Absent on any other call. */
+    digests?: SkeletonDigest[];
+    /** One template per shell command of the call (layer 3), in the order the commands run: its program, subcommand, and flags, and every literal argument as a slot of `TEMPLATE_SLOTS`. Each kept word passed the one gate (`wireName`, `wireFlag`); never an argument. Absent when none is sent. */
+    templates?: string[];
+    /** A `count` bucket of the templates the call held that were not sent: one with a kept word the redactor changes, an exclusion term matches, or that has no name shape. Absent when none was dropped; never the templates. */
+    templatesDropped?: number;
+    /** What an edit did (layer 3), a sorted set of `DIFF_SHAPES` members: the shape of the change and never its text. Absent for a call that is no edit and for one that changed nothing. */
+    diffShape?: Array<DiffShape | typeof OTHER>;
     steps: SkeletonStep[];
 }
+/** One edit's digests: the first 32 hex digits of the SHA-256 of the exact UTF-8 text. A Write has `new` alone, never the digest of an empty string for `old`. */
+export interface SkeletonDigest {
+    old?: string;
+    new: string;
+}
+/** One sent key's value features as the wire holds them: each a closed-list member, or `other` for one this reader does not know. */
+export interface SkeletonArgFeature {
+    key: string;
+    valueSize: ValueSize | typeof OTHER;
+    pathDepth?: PathDepth | typeof OTHER;
+    extension?: ExtensionClass | typeof OTHER;
+    dirKind?: DirectoryKind | typeof OTHER;
+    patternFeatures?: Array<PatternFeature | typeof OTHER>;
+}
+/** One name token as the wire holds it: its kind from the closed list (`other` for one this reader does not know) and the name as sent, which has the shape of a name (`other` when it has none). */
+export interface SkeletonArgName {
+    kind: NameKind | typeof OTHER;
+    name: string;
+}
+/** One sent key's closed value as the wire holds it, or `other` for one off the list this reader holds. */
+export interface SkeletonArgValue {
+    key: string;
+    enumValue: string;
+}
 /**
  * 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.
@@ -117,6 +175,17 @@ 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];
+/** Where a session ran, as a trusted machine states it for a batch it admitted: the five host classes an enrollment knows (`HOST_CLASSES` in `machine.ts`, not imported: the pool bundles this file). */
+export declare const CLAIMED_HOST_CLASSES: readonly ["local", "vps", "cloud", "ci", "hosted"];
+export type ClaimedHostClass = (typeof CLAIMED_HOST_CLASSES)[number];
+/** What started the session, as an enrollment declares it. */
+export declare const CLAIMED_LAUNCHERS: readonly ["interactive", "orchestrated", "scheduled", "ci", "hosted-run", "unknown"];
+export type ClaimedLauncher = (typeof CLAIMED_LAUNCHERS)[number];
+/** The host class and launcher the trusted machine states for a batch a cloud VM held: a claim of the depositor's own machine, never a fact the pool stamped. `other` is a value this reader does not know. */
+export interface Claimed {
+    hostClass: ClaimedHostClass | typeof OTHER;
+    launcher: ClaimedLauncher | typeof OTHER;
+}
 /** 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;
@@ -188,8 +257,22 @@ export interface DeltaEntry {
     metric: DeltaMetric | typeof OTHER;
     change: number;
 }
+/** Whether a recommendation reached the asker (`shown`) or was withheld by the holdback (`held`). The local row's arm, as the closed list holds it. */
+export declare const RECOMMENDATION_ARMS: readonly ["shown", "held"];
+export type RecommendationArm = (typeof RECOMMENDATION_ARMS)[number];
+/**
+ * One recommendation of the session as the local row holds it: its `id`, the `arm` it was drawn into, the `poolVersion` it answered from, and the window of calls it covers, `from` up to but not including `to`, as positions in the
+ * main run's calls that are not sidechain (the line the local consequence window reads). It holds no text, query, or evidence. `other` is an arm this reader does not know.
+ */
+export interface SkeletonRecommendation {
+    id: string;
+    arm: RecommendationArm | typeof OTHER;
+    poolVersion: string;
+    from: number;
+    to: number;
+}
 export interface SessionSkeleton {
-    format: typeof SKELETON_FORMAT;
+    format: SkeletonFormat;
     /** 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. */
@@ -200,8 +283,12 @@ export interface SessionSkeleton {
     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;
+    /** Only on a batch a trusted machine admitted from a held branch: the machine writes it from its own enrollment record, never the client that built the batch. */
+    claimed?: Claimed;
     /** 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[];
+    /** The recommendations the main session was shown or held back from (format 6), in window order. Absent when it had none, and a pool reads absent as unknown exposure, never as unexposed. */
+    recommendations?: SkeletonRecommendation[];
 }
 /** One main session and the subagents it spawned, as the local store holds them. */
 export interface SessionRecords {
@@ -223,12 +310,14 @@ export interface TranscriptRoot {
 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;
+/** No session leaves this machine sooner than this after it ends, whatever `session_idle_hours` is: time for `oars sessions deposit --deny` or a delete to act on it first. Today the longer idle window governs; this is the floor under it. */
+export declare const HOLD_WINDOW_MS: number;
 /**
  * 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;
+export declare const hasEnded: (records: SessionRecords, now: number, written: number, idleMs?: number) => boolean;
 /** Every main session of a store, with its records. */
 export declare const sessionsOf: (store: {
     sessions: readonly SessionObservation[];
@@ -262,18 +351,64 @@ export declare const OPEN_GATE: WireGate;
  * `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 call's key names as the wire holds them (t870): names only, never a value. A public tool (one with a pinned input list) sends the names on its list and counts the rest; any other tool sends a name only when it passes the
+ * name gate, and a tool that went as `private` sends none, so a private tool's keys name no private work. `dropped` counts the distinct names not sent.
+ */
+export declare const wireKeys: (stored: readonly string[], native: string | undefined, gate: WireGate) => {
+    keys: string[];
+    dropped: number;
+};
+/** Whether a closed value is one the wire may carry for a tool's key: a boolean's two words, or a member of the tool's list. */
+export declare const isClosedValue: (native: string | undefined, key: string, value: string) => boolean;
+/**
+ * A call's value features as the wire sends them (layer 1): only a sent key's, and only closed-list members, so a hand-edited record never puts a value on the wire. An entry whose size is off its list is dropped whole, a
+ * path or pattern field off its list is left out, and a pattern holding no listed feature sends none.
+ */
+export declare const wireFeatures: (stored: readonly ArgFeature[] | undefined, sent: ReadonlySet<string>) => ArgFeature[];
+/** A call's closed values as the wire sends them (layer 1): only a sent key's, and only a value `isClosedValue` admits. */
+export declare const wireValues: (stored: readonly ArgValue[] | undefined, sent: ReadonlySet<string>, native: string | undefined) => ArgValue[];
+/** A call's change kinds as the wire sends them: the closed-list members, in the list's order. */
+export declare const wireChange: (stored: readonly ChangeKind[] | undefined) => ChangeKind[];
+/** A call's diff shapes as the wire sends them: the closed-list members, in the list's order. */
+export declare const wireDiffShape: (stored: readonly DiffShape[] | undefined) => DiffShape[];
+/**
+ * A call's name tokens as the wire sends them (layer 2): every stored token whose kind is on the closed list, through the one gate (`wireName`): a token the operator's exclusion terms or the redactor's secret shapes match, or that has no name shape,
+ * is dropped and counted in `dropped`. No floor, no threshold: a name is sent as it is.
+ */
+export declare const wireNames: (stored: readonly ArgName[] | undefined, gate: WireGate) => {
+    names: ArgName[];
+    dropped: number;
+};
+/** A call's edit digests as the wire sends them: a pair whose digest is not that shape is dropped whole, so a corrupt store row costs the pair and never the deposit. */
+export declare const wireDigests: (stored: readonly EditDigest[] | undefined) => SkeletonDigest[];
+/** Whether a received template has the shape the wire sends: the pool's check, which holds no operator terms and no redactor. */
+export declare const isWireTemplate: (template: string) => boolean;
+/**
+ * A call's command templates as the wire sends them (layer 3): every stored template whose kept words (program, subcommand, flags) all clear the one gate, as a name or a flag does. A template with a word the redactor changes, an exclusion term matches, or that
+ * has no name shape is dropped whole and counted in `dropped`. No floor, no threshold: a template is sent as it is, and a literal is only ever a slot.
+ */
+export declare const wireTemplates: (stored: readonly string[] | undefined, gate: WireGate) => {
+    templates: string[];
+    dropped: number;
+};
 /**
  * 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 recommendations of one session, from the local rows after `deriveConsequences` has given each its window. Only a row that showed or withheld something is carried: a miss recommended nothing, so it is neither shown nor held, and
+ * a row with no window has no calls to place. They go in window order, then by id, so one store builds one batch.
+ */
+export declare const recommendationsOf: (recalls: readonly Recall[], session: string) => SkeletonRecommendation[];
 /** 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;
+export declare const skeletonOf: (records: SessionRecords, id: string, read: ShellReader, print: Print, deltas?: readonly DeltaEntry[], gate?: WireGate, coverage?: Coverage, recommendations?: readonly SkeletonRecommendation[]) => 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.
@@ -304,23 +439,27 @@ export interface Extension {
 /** 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
+ * The fields that may be absent at formats 3, 4, and 5 (a format 4 batch reads `OPTIONAL.tool` less `FORMAT_5_TOOL_FIELDS`, and a format 3 batch also less `FORMAT_4_TOOL_FIELDS`), 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 batch: readonly ["timingPrint", "deltas", "claimed", "recommendations"];
     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 tool: readonly ["prompt", "durationMs", "errorCode", "recoveryCalls", "keys", "keysDropped", "targetClass", "argClass", "argFeatures", "argValues", "changeKind", "names", "namesDropped", "templates", "templatesDropped", "diffShape", "digests"];
     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"];
+export declare const PLATFORMS: ReadonlySet<string>;
+export declare const SHELLS: ReadonlySet<string>;
 /** 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"];
+/** Whether the harness's table names this native, so it can cross as itself; anything else (including the literal) crosses as `private`. */
+export declare const admittedNative: (harness: WireHarness, native: string) => boolean;
 /** 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;
@@ -347,6 +486,8 @@ export interface StrataCell {
 export interface BundleFloors {
     public: number;
     disclosure: number;
+    /** The floor a cell of closed public vocabulary is served at, at most `public`. Absent in a bundle signed before the pool split its floor by cell class. */
+    clear?: 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. */
@@ -401,7 +542,7 @@ export interface Bundle {
     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`. */
+    /** 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`. A clear cell is held to `floors.clear`, so a read on clear cells alone states that floor, the lowest among the cells it cites. */
     floor: number;
     asOf: ReadAsOf;
     cells: Cell[];
@@ -415,18 +556,37 @@ export interface Bundle {
 }
 /** The signature covers these exact bytes, so nothing has to be canonicalized on either side. */
 export interface SignedBundle {
+    /** Names the signing key (S17). A bundle with no `kid` is read as `LEGACY_KEY_ID`, the name a pre-key-id sign-in pins its one key under. */
+    kid?: string;
     payload: string;
     /** Ed25519 over the payload's UTF-8 bytes, in base64. */
     signature: string;
 }
+/** The key id of a bundle that names none, and of a sign-in file written before key ids: the pool's default `BUNDLE_KEY_ID`. */
+export declare const LEGACY_KEY_ID = "k1";
+/** Key ids this release no longer trusts: the way a leaked signing key is rotated out (docs/pool.md, "Rotating the bundle signing key"). A bundle signed under one is refused even when its key is pinned. */
+export declare const RETIRED_KEY_IDS: ReadonlySet<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 keys pinned for one server, by key id. One entry until the pool rotates its key. */
+export interface PinnedKeys {
+    [kid: string]: PinnedKey;
+}
+/**
+ * Public keys this release of oars ships, by key id: the only way a key id the login did not pin becomes trusted, because a server at a pool's URL must not be able to introduce a key by naming a new id (S17). Empty until the pool's first rotation
+ * (docs/pool.md, "Rotating the bundle signing key"); a bundle is checked against the keys pinned at login and these, a shipped key winning under a shared id, so a server cannot shadow it with a key of its own.
+ */
+export declare const RELEASE_KEYS: Readonly<PinnedKeys>;
+/** The first key id a login offers that the server's entry does not hold and no release ships, or none: such an id could only have come from the server. */
+export declare const unpinnedKid: (held: PinnedKeys, offered: PinnedKeys, released?: PinnedKeys) => string | undefined;
+/** A key id as the pool sends them: letters, digits, dot, dash, and underscore, 1 to 32 characters. */
+export declare const isKeyId: (kid: string) => boolean;
 /** 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<{
+export declare const verifyBundle: (signed: unknown, keys: PinnedKeys, harness: Harness, harnessVersion: string, retired?: ReadonlySet<string>, released?: PinnedKeys) => Promise<{
     ok: true;
     bundle: Bundle;
 } | {