@manyoars/oars 0.1.1 → 0.3.0

package/dist/sessions/pool.js

@@ -0,0 +1,164 @@
+// The derive pass over cells: motifs and cells from the store, each family's reads from those, and the files they are kept in. `cells.jsonl` and `motifs.jsonl` are
+// rewritten from the log and can be dropped at any time. Each pool version's reads go in a file of their own that is written once and never rewritten, so a read cited by
+// its ID stays what it was.
+import { readdir, readFile, stat } from 'node:fs/promises';
+import { basename, dirname, join } from 'node:path';
+import { CliError, ExitCode } from '../errors.js';
+import { cellsOf, projectedStore } from './cell-increments.js';
+import { poolOf, serializeCells, UNKNOWN } from './cells.js';
+import { shellReader } from './projection.js';
+import { contentHash, FIRST_ORDER_FAMILIES, frozenRead, makeRead, orderResolver } from './read.js';
+import { deriveConsequences, recallGraphOf } from './recall-consequence.js';
+import { readRecalls } from './recall-object.js';
+import { deriveAdoption } from './read-adoption.js';
+import { deriveCallShape } from './read-call-shape.js';
+import { deriveChange } from './read-change.js';
+import { deriveCost } from './read-cost.js';
+import { deriveFit } from './read-fit.js';
+import { deriveLive } from './read-live.js';
+import { deriveMethod } from './read-method.js';
+import { deriveNextStep } from './read-next-step.js';
+import { deriveRecovery } from './read-recovery.js';
+import { deriveToolDay } from './read-tool-day.js';
+import { vocabulary } from './vocab-load.js';
+import { deriveDayMove } from './read-day-move.js';
+import { deriveInteraction } from './read-interaction.js';
+import { deriveLeadLag } from './read-lead-lag.js';
+import { deriveSubstitution } from './read-substitution.js';
+import { deriveVersionBoundary } from './read-version-boundary.js';
+import { writeAtomic } from './store.js';
+// Built on call.
+const derivers = () => ({
+    recovery: deriveRecovery,
+    fit: (input) => [...deriveFit(input), ...deriveCallShape(input)],
+    cost: deriveCost,
+    change: deriveChange,
+    live: deriveLive,
+    adoption: deriveAdoption,
+    method: deriveMethod,
+    'next-step': deriveNextStep,
+    'tool-day': deriveToolDay,
+});
+/** Families over reads, one stage per order: a stage reads what the stages before it wrote. Built on call. */
+const relations = () => [[deriveVersionBoundary, deriveSubstitution, deriveInteraction, deriveDayMove], [deriveLeadLag]];
+export const poolFiles = (storeDir) => ({
+    cells: join(storeDir, 'cells.jsonl'),
+    consequences: join(storeDir, 'consequences.jsonl'),
+    motifs: join(storeDir, 'motifs.jsonl'),
+    reads: (version) => join(storeDir, 'reads', `${version}.jsonl`),
+});
+const made = (bodies, asOf, orderOf) => bodies
+    .map((body) => makeRead({ ...body, asOf }, orderOf))
+    .map((read) => ({ read, key: contentHash(read.slice) }))
+    .sort((a, b) => (a.key < b.key ? -1 : 1))
+    .map(({ read }) => read);
+/** Every family's order 1 reads of one pool, in family order and then by slice, so a rerun writes the same bytes. */
+export const deriveFirstOrder = (pool, store) => {
+    const asOf = { pool: pool.version, day: pool.lastDay };
+    const orderOf = orderResolver([]);
+    const byFamily = derivers();
+    return FIRST_ORDER_FAMILIES.flatMap((family) => made(byFamily[family]({ pool, store }), asOf, orderOf));
+};
+/** Order 1, then each stage of `relations` over everything before it. */
+export const deriveReads = (pool, store) => {
+    const asOf = { pool: pool.version, day: pool.lastDay };
+    return relations().reduce((known, stage) => {
+        const orderOf = orderResolver(known);
+        return [...known, ...stage.flatMap((derive) => made(derive(known), asOf, orderOf))];
+    }, deriveFirstOrder(pool, store));
+};
+export const serializeReads = (reads) => reads.map((read) => `${JSON.stringify(read)}\n`).join('');
+const isRead = (value) => typeof value === 'object' && value !== null && 'readId' in value && 'family' in value;
+const isCell = (value) => typeof value === 'object' && value !== null && 'motifId' in value && 'frameBucket' in value && 'grain' in value;
+const isMotif = (value) => typeof value === 'object' && value !== null && 'motifId' in value && 'level' in value;
+const parsedLine = (file, line) => {
+    try {
+        return JSON.parse(line);
+    }
+    catch {
+        throw new CliError(`${file} holds a line that is not JSON. Delete that file and run this again: its reads are derived from the store.`, ExitCode.UNEXPECTED, 'read');
+    }
+};
+/** A file that is missing, or whose lines are JSON but not all of the kind asked for, is no record of this pool: it is derived and written again. A line that is not JSON is damage, so it stops here and asks the operator to delete the file. */
+const storedRows = async (file, isRow) => {
+    try {
+        const text = await readFile(file, 'utf8');
+        const parsed = text.split('\n').flatMap((line) => (line === '' ? [] : [parsedLine(file, line)]));
+        return parsed.every(isRow) ? parsed : undefined;
+    }
+    catch (error) {
+        if (error instanceof Error && 'code' in error && error.code === 'ENOENT')
+            return undefined;
+        throw error;
+    }
+};
+const readStored = async (file) => (await storedRows(file, isRead))?.map(frozenRead);
+/** The current pool's reads: already written when this pool has been read before, else derived and written once. */
+export const refreshPool = async (storeDir, store) => {
+    const recalls = deriveConsequences(store, await readRecalls(storeDir));
+    const set = cellsOf(projectedStore(store, shellReader(vocabulary())), recallGraphOf(store, recalls));
+    const pool = poolOf(set, store.errors);
+    const files = poolFiles(storeDir);
+    await writeAtomic(files.consequences, recalls.flatMap(({ id, n, consequence }) => (consequence === undefined ? [] : [`${JSON.stringify({ id, n, consequence })}\n`])).join(''));
+    await writeAtomic(files.cells, serializeCells(set.cells));
+    await writeAtomic(files.motifs, set.motifs.map((motif) => `${JSON.stringify(motif)}\n`).join(''));
+    const file = files.reads(pool.version);
+    const stored = await readStored(file);
+    if (stored !== undefined)
+        return { pool, reads: stored };
+    const reads = deriveReads(pool, store);
+    await writeAtomic(file, serializeReads(reads));
+    return { pool, reads };
+};
+const POOL_FAILED = 'oars: the read pool was not built, and answers keep their stand-ins: ';
+const unbuilt = (error) => {
+    process.stderr.write(`${POOL_FAILED}${error instanceof Error ? error.message : String(error)}\n`);
+};
+/** The pool a deposit's index step reads. It answers without one (spec 2.7): a pool that cannot be read or written costs only the stored read IDs, whose answers keep their stand-ins, and one line on stderr says so. */
+export const currentPool = async (storeDir, store) => {
+    try {
+        return await refreshPool(storeDir, store);
+    }
+    catch (error) {
+        unbuilt(error);
+        return undefined;
+    }
+};
+/** The reads file written last: a deposit writes one per new pool version and nothing prunes them, so the newest by time is the pool the last deposit left. */
+const newestReadsFile = async (dir) => {
+    try {
+        const names = (await readdir(dir)).filter((name) => name.endsWith('.jsonl'));
+        const stamped = await Promise.all(names.map(async (name) => ({ file: join(dir, name), at: (await stat(join(dir, name))).mtimeMs })));
+        return stamped.sort((a, b) => b.at - a.at || (a.file < b.file ? -1 : 1))[0]?.file;
+    }
+    catch (error) {
+        if (error instanceof Error && 'code' in error && error.code === 'ENOENT')
+            return undefined;
+        throw error;
+    }
+};
+/** The newest stored pool as the files hold it, or undefined when a file of it is missing. A damaged file throws. */
+const storedPool = async (storeDir) => {
+    const files = poolFiles(storeDir);
+    const file = await newestReadsFile(dirname(files.reads('any')));
+    const reads = file === undefined ? undefined : await readStored(file);
+    const cells = await storedRows(files.cells, isCell);
+    const motifs = await storedRows(files.motifs, isMotif);
+    if (file === undefined || reads === undefined || cells === undefined || motifs === undefined)
+        return undefined;
+    const lastDay = cells.reduce((last, cell) => (cell.day !== UNKNOWN && (last === null || cell.day > last) ? cell.day : last), null);
+    return { pool: { cells, motifs: new Map(motifs.map((motif) => [motif.motifId, motif])), version: basename(file, '.jsonl'), lastDay }, reads };
+};
+/**
+ * The pool a pull answers from: the newest one already stored, with nothing derived or written. A pull used to refresh the pool, and a deposit that moved it left the next pull to
+ * derive every read again (12 to 17 s on a real store) and write a file nothing prunes. Only a store with no stored pool derives one, once, and a stored one is read after that.
+ */
+export const servedPool = async (storeDir, store) => {
+    try {
+        return (await storedPool(storeDir)) ?? (await refreshPool(storeDir, store));
+    }
+    catch (error) {
+        unbuilt(error);
+        return undefined;
+    }
+};

package/dist/sessions/projection.d.ts

@@ -0,0 +1,75 @@
+import { type WordOfCommand } from './identity.js';
+import type { ShellReader } from './pool-wire.js';
+import type { Redactor } from './redact.js';
+import { type RepoFilesBucket, type ToolObservation, type ToolPackage } from './schema.js';
+import type { Vocabulary } from './vocab-load.js';
+/** One program of a shell call, as `index` carries it. */
+export interface ProjectedProgram {
+    program: string;
+    subcommand: string | null;
+    flags: string[];
+}
+/** A shell call: its commands in order, and the ordered `program` list a compound command pools as, capped at `pipe_max`. */
+export interface ProjectedShell {
+    commands: ProjectedProgram[];
+    programs: string[];
+}
+/** What `agentType` pools as when the agent is not a built-in. */
+export declare const CUSTOM = "custom";
+export declare const PRIVATE_PROGRAM: ProjectedProgram;
+export declare const isAdmittedProgram: (vocab: Vocabulary, program: string) => boolean;
+/** One simple command to `program`, `subcommand`, and `flags`. An unlisted subcommand or flag is dropped and not counted: its program already pools. */
+export declare const projectProgram: (vocab: Vocabulary, program: string, args: readonly WordOfCommand[]) => ProjectedProgram;
+/**
+ * A shell call to its projection. Quoting, env prefixes, `sudo`-style wrappers, pipes, `&&` chains, and `bash -c` are read by the capture parser;
+ * a command it cannot read (no program found in a non-empty text) is one `private` program, never its text.
+ */
+export declare const projectShell: (vocab: Vocabulary, command: string, redact: Redactor) => ProjectedShell;
+/**
+ * The shell call of a stored tool record, from what the account store holds (migration, spec Section 2): every command of the call, in order, from the
+ * record's `steps` (CAPTURE 9 and later), which carry the public program, subcommand, and flag names of each; so a pipeline, an `&&` chain, a `cd` hop,
+ * a `bash -c` body, and `git -C repo status` project as the raw command reads. A program the curated list does not name reads `<literal>` in its step and
+ * is read from the call's `segments` (`projectLiteralStep`): it stays admitted when only the snapshot lists it, and loses its flags (Q5). A record with no
+ * steps (captured before CAPTURE 9) projects its `target` reading alone: one program and its first plain word, no flags (Q5). A target that cannot be
+ * read back, a hashed path target, or a record that is not a shell call (a tool other than `Bash` or `PowerShell` holding no `shell.exec` step) projects `private`.
+ */
+export declare const projectStoredShell: (vocab: Vocabulary, tool: Pick<ToolObservation, "tool" | "target" | "steps" | "segments">) => ProjectedShell;
+/** The reader a deposit and a local read share: a stored shell call's commands under the pinned vocabulary, one per step, in order. */
+export declare const shellReader: (vocab: Vocabulary) => ShellReader;
+/** A `tool` name: an admitted built-in, `mcp:<server>:<tool>` admitted on both parts, `mcp:private`, or `private`. */
+export declare const projectTool: (tool: string) => string;
+/** A field whose non-admitted members pool only as a count (spec Section 1.3): `privateCount` is exact here, and Section 1.2 buckets it at deposit. */
+export interface ProjectedNames {
+    names: string[];
+    privateCount: number;
+}
+/** `skills`: the published skills among the names, the rest only counted. */
+export declare const projectSkills: (skills: readonly string[]) => ProjectedNames;
+/** `agentType`: a built-in subagent type of a harness, else `custom`; null stays null (a main transcript). */
+export declare const projectAgentType: (agentType: string | null) => string | null;
+/** `keys` of a call to `tool`: only names its published input schema lists, the rest only counted. An MCP tool lists none. */
+export declare const projectKeys: (tool: string, keys: readonly string[]) => ProjectedNames;
+export interface ProjectedPackage {
+    /** `<ecosystem>:<name>` for a seeded name, else `private`. */
+    package: string;
+    /** Null when no version was stated or the package is private; `private` for a version the snapshot does not list. */
+    packageVersion: string | null;
+}
+/**
+ * A package is admitted only when it is in its ecosystem's `seed_top` (before the admitted-list service exists, nothing else is admitted): a name
+ * that merely resolves, further down the registry, projects to `private`. A version is admitted only when the snapshot lists it for that name.
+ */
+export declare const projectPackage: (vocab: Vocabulary, ecosystem: string, name: string, version: string | null) => ProjectedPackage;
+/** A stored package (`<ecosystem>:<name>`, from `packages` on a tool record) as it pools: the name when it is in its ecosystem's `seed_top`, else `private`. */
+export declare const projectStoredPackage: (vocab: Vocabulary, stored: Pick<ToolPackage, "package" | "packageVersion">) => ProjectedPackage;
+/** A model id, lowercased the way the snapshot stores it. */
+export declare const projectModel: (vocab: Vocabulary, model: string) => string;
+/** A harness release up to the snapshot; one published after it pools as `private` until the next VOCAB_VERSION (spec R3). */
+export declare const projectHarnessVersion: (vocab: Vocabulary, harness: string, version: string) => string;
+/** An `errorCode` as it pools: a stored class that is still a member of the closed list, else `other`. A record captured before CAPTURE 14 holds none and projects `other`. */
+export declare const projectErrorCode: (stored: string | undefined) => string;
+export { projectLanguage, projectLanguageShare } from './strata.js';
+/** A stored `repoFiles` bucket as it pools: itself when it is one of the five, else null. */
+export declare const projectRepoFiles: (stored: string | null) => RepoFilesBucket | null;
+/** A stored framework as it pools: a name the vocabulary marks as a framework, else `private`. */
+export declare const projectFramework: (stored: string) => string;

package/dist/sessions/projection.js

@@ -0,0 +1,165 @@
+// The D11 projection (pool vocabulary spec Sections 1.3 and 2): which names in a P field may pool as themselves. A pure function of the pinned
+// `Vocabulary` and the value, computed at deposit and never written to a file. Every value that leaves here is either a member of a pinned list
+// or the word `private`: the output is built from list members, never from the input text, so a private name cannot be copied through by a
+// parsing mistake. A form the parser cannot read projects to `private`.
+import { SHELL, shellCommands } from './extract.js';
+import { isPositional } from './identity.js';
+import { BUNDLING_PROGRAMS, HARNESS_TOOLS, FRAMEWORKS, isPublicMcpTool, LITERAL, PIPE_MAX, PRIVATE, PUBLIC_FLAGS, PUBLIC_MCP_SERVERS, PUBLIC_PROGRAMS, PUBLIC_SKILLS, projectedAgentType, PUBLIC_SUBCOMMANDS, TOOL_INPUT_KEYS, } from './public-vocabulary.js';
+import { NORMALIZE } from './package-resolve.js';
+import { ERROR_CODES, REPO_FILE_BUCKETS } from './schema.js';
+/** What `agentType` pools as when the agent is not a built-in. */
+export const CUSTOM = 'custom';
+export const PRIVATE_PROGRAM = { program: PRIVATE, subcommand: null, flags: [] };
+const UNREAD_SHELL_PROJECTION = { commands: [PRIVATE_PROGRAM], programs: [PRIVATE] };
+const projectedShell = (commands) => ({ commands, programs: commands.slice(0, PIPE_MAX).map(({ program }) => program) });
+const subcommandsOf = (vocab, program) => {
+    const own = vocab.programs.get(program)?.subs;
+    const curated = PUBLIC_SUBCOMMANDS.get(program);
+    return new Set([...(own ?? []), ...(curated ?? [])]);
+};
+/** A program with a page in the snapshot lists its own flags; one the snapshot lacks (a shell keyword, say) falls back to the curated list. */
+const flagsOf = (vocab, program) => vocab.programs.get(program)?.flags ?? PUBLIC_FLAGS;
+const flagWords = (program, args) => {
+    const names = [];
+    for (const { text, quoted } of args) {
+        if (text === '--')
+            break;
+        if (quoted || !text.startsWith('-') || text.includes('$'))
+            continue;
+        // The value of `--flag=value` is never read: only the part before `=` is a candidate.
+        const name = text.split('=')[0] ?? text;
+        names.push(name);
+        if (BUNDLING_PROGRAMS.has(program) && /^-[A-Za-z]{2,}$/.test(name))
+            names.push(...Array.from(name.slice(1), (letter) => `-${letter}`));
+    }
+    return names;
+};
+export const isAdmittedProgram = (vocab, program) => vocab.programs.has(program) || PUBLIC_PROGRAMS.has(program);
+/** `shellTarget` cuts a subcommand at this many characters, and so does a `run` word (`RUN_WORD_CHARS`, extract.ts), so a stored word this long (a program too, `programOf`) may be a prefix of a longer private one. */
+const STORED_SUBCOMMAND_CUT = 30;
+/** One simple command to `program`, `subcommand`, and `flags`. An unlisted subcommand or flag is dropped and not counted: its program already pools. */
+export const projectProgram = (vocab, program, args) => {
+    // A program cut at the limit may be the front of a longer private name (`<30 characters>-acme`), so it is never a list member (register row A53).
+    if (program.length >= STORED_SUBCOMMAND_CUT || !isAdmittedProgram(vocab, program))
+        return PRIVATE_PROGRAM;
+    const subs = subcommandsOf(vocab, program);
+    const subcommand = args.filter(isPositional).find(({ text }) => subs.has(text))?.text ?? null;
+    const listed = flagsOf(vocab, program);
+    const flags = [...new Set(flagWords(program, args).filter((name) => listed.has(name)))].sort();
+    return { program, subcommand, flags };
+};
+/**
+ * A shell call to its projection. Quoting, env prefixes, `sudo`-style wrappers, pipes, `&&` chains, and `bash -c` are read by the capture parser;
+ * a command it cannot read (no program found in a non-empty text) is one `private` program, never its text.
+ */
+export const projectShell = (vocab, command, redact) => {
+    const read = shellCommands(command, redact);
+    return projectedShell(read.length === 0 ? [PRIVATE_PROGRAM] : read.map(({ program, args }) => projectProgram(vocab, program, args)));
+};
+/** The first command of a stored call as its class A `target` reads: the program and the first plain word after it. A target cut at the subcommand limit, masked by redaction, or not a program and one word projects `private`. */
+const projectTarget = (vocab, target) => {
+    if (target === null || target === '' || target.includes('<'))
+        return PRIVATE_PROGRAM;
+    const [program = '', sub, ...extra] = target.split(' ');
+    if (extra.length > 0 || (sub?.length ?? 0) >= STORED_SUBCOMMAND_CUT)
+        return PRIVATE_PROGRAM;
+    return projectProgram(vocab, program, sub === undefined ? [] : [{ text: sub, quoted: false }]);
+};
+/** One stored step: its public names, each checked against the pinned vocabulary again, so a step stamped under an older list admits nothing the current one does not. */
+const projectStep = (vocab, identity) => {
+    if (!isAdmittedProgram(vocab, identity.program))
+        return PRIVATE_PROGRAM;
+    const subs = subcommandsOf(vocab, identity.program);
+    const listed = flagsOf(vocab, identity.program);
+    return {
+        program: identity.program,
+        subcommand: identity.sub !== null && subs.has(identity.sub) ? identity.sub : null,
+        flags: [...new Set(identity.flags.filter((name) => listed.has(name)))].sort(),
+    };
+};
+/**
+ * A step that reads `<literal>` names no curated program, so its program comes from the same parse, the call's `segments`: `readShell` builds both from
+ * the same commands (extract.ts), so segment `at` is step `at`, however many words (`sudo`, `timeout 5`, `bash -c`, an assignment, a block keyword) capture
+ * skipped to reach it. `run` is the program and its plain words, so a program only the snapshot lists stays admitted, with a subcommand when a plain word
+ * is a listed one; it holds no flag, so flags are lost here (Q5). A word cut at the `run` limit is no subcommand. Segments that do not pair with the
+ * steps (none stored, or a different count) cannot say which command ran: `private`.
+ */
+const projectLiteralStep = (vocab, segments, steps, at) => {
+    const run = segments?.length === steps ? segments[at]?.run : undefined;
+    if (run === undefined)
+        return PRIVATE_PROGRAM;
+    const [program = '', ...words] = run.split(' ');
+    return projectProgram(vocab, program, words.filter((text) => text.length < STORED_SUBCOMMAND_CUT).map((text) => ({ text, quoted: false })));
+};
+const isShellStep = (identity) => identity !== null && identity !== undefined && 'program' in identity;
+/**
+ * The shell call of a stored tool record, from what the account store holds (migration, spec Section 2): every command of the call, in order, from the
+ * record's `steps` (CAPTURE 9 and later), which carry the public program, subcommand, and flag names of each; so a pipeline, an `&&` chain, a `cd` hop,
+ * a `bash -c` body, and `git -C repo status` project as the raw command reads. A program the curated list does not name reads `<literal>` in its step and
+ * is read from the call's `segments` (`projectLiteralStep`): it stays admitted when only the snapshot lists it, and loses its flags (Q5). A record with no
+ * steps (captured before CAPTURE 9) projects its `target` reading alone: one program and its first plain word, no flags (Q5). A target that cannot be
+ * read back, a hashed path target, or a record that is not a shell call (a tool other than `Bash` or `PowerShell` holding no `shell.exec` step) projects `private`.
+ */
+export const projectStoredShell = (vocab, tool) => {
+    // `SHELL` names Claude Code's two shell tools. Another harness's (`run_terminal_cmd`, `exec_command`) is told by the step capture classed `shell.exec`.
+    if (!SHELL.has(tool.tool) && tool.steps?.some(({ action }) => action === 'shell.exec') !== true)
+        return UNREAD_SHELL_PROJECTION;
+    const steps = (tool.steps ?? []).map(({ identity }) => identity);
+    if (steps.length === 0)
+        return projectedShell([projectTarget(vocab, tool.target)]);
+    return projectedShell(steps.map((identity, at) => (!isShellStep(identity) ? PRIVATE_PROGRAM : identity.program === LITERAL ? projectLiteralStep(vocab, tool.segments, steps.length, at) : projectStep(vocab, identity))));
+};
+/** The reader a deposit and a local read share: a stored shell call's commands under the pinned vocabulary, one per step, in order. */
+export const shellReader = (vocab) => (tool) => projectStoredShell(vocab, tool).commands;
+const MCP_TOOL = /^mcp__(.+?)__(.+)$/;
+/** A `tool` name: an admitted built-in, `mcp:<server>:<tool>` admitted on both parts, `mcp:private`, or `private`. */
+export const projectTool = (tool) => {
+    const mcp = MCP_TOOL.exec(tool);
+    if (mcp !== null) {
+        const [, server = '', name = ''] = mcp;
+        return PUBLIC_MCP_SERVERS.has(server) && isPublicMcpTool(server, name) ? `mcp:${server}:${name}` : 'mcp:private';
+    }
+    return [...HARNESS_TOOLS.values()].some((tools) => tools.has(tool)) ? tool : PRIVATE;
+};
+const admit = (names, admitted) => {
+    const unique = [...new Set(names)];
+    const kept = unique.filter(admitted);
+    return { names: kept.sort(), privateCount: unique.length - kept.length };
+};
+/** `skills`: the published skills among the names, the rest only counted. */
+export const projectSkills = (skills) => admit(skills, (name) => PUBLIC_SKILLS.has(name));
+/** `agentType`: a built-in subagent type of a harness, else `custom`; null stays null (a main transcript). */
+export const projectAgentType = (agentType) => (agentType === null ? null : projectedAgentType(agentType));
+/** `keys` of a call to `tool`: only names its published input schema lists, the rest only counted. An MCP tool lists none. */
+export const projectKeys = (tool, keys) => {
+    const listed = TOOL_INPUT_KEYS.get(tool);
+    return admit(keys, (name) => listed?.has(name) === true);
+};
+/**
+ * A package is admitted only when it is in its ecosystem's `seed_top` (before the admitted-list service exists, nothing else is admitted): a name
+ * that merely resolves, further down the registry, projects to `private`. A version is admitted only when the snapshot lists it for that name.
+ */
+export const projectPackage = (vocab, ecosystem, name, version) => {
+    const normalize = NORMALIZE.get(ecosystem);
+    const versions = normalize === undefined ? undefined : vocab.packages.get(ecosystem)?.seed.get(normalize(name));
+    if (normalize === undefined || versions === undefined)
+        return { package: PRIVATE, packageVersion: null };
+    return { package: `${ecosystem}:${normalize(name)}`, packageVersion: version === null ? null : versions.has(version) ? version : PRIVATE };
+};
+/** A stored package (`<ecosystem>:<name>`, from `packages` on a tool record) as it pools: the name when it is in its ecosystem's `seed_top`, else `private`. */
+export const projectStoredPackage = (vocab, stored) => {
+    const colon = stored.package.indexOf(':');
+    return projectPackage(vocab, stored.package.slice(0, colon), stored.package.slice(colon + 1), stored.packageVersion);
+};
+/** A model id, lowercased the way the snapshot stores it. */
+export const projectModel = (vocab, model) => (vocab.models.has(model.toLowerCase()) ? model.toLowerCase() : PRIVATE);
+/** A harness release up to the snapshot; one published after it pools as `private` until the next VOCAB_VERSION (spec R3). */
+export const projectHarnessVersion = (vocab, harness, version) => (vocab.harnessVersions.get(harness)?.has(version) === true ? version : PRIVATE);
+/** An `errorCode` as it pools: a stored class that is still a member of the closed list, else `other`. A record captured before CAPTURE 14 holds none and projects `other`. */
+export const projectErrorCode = (stored) => (stored !== undefined && ERROR_CODES.has(stored) ? stored : 'other');
+// The language and share projections live in `strata.ts`, which the skeleton builder imports without the extractor; they are the same functions.
+export { projectLanguage, projectLanguageShare } from './strata.js';
+/** A stored `repoFiles` bucket as it pools: itself when it is one of the five, else null. */
+export const projectRepoFiles = (stored) => REPO_FILE_BUCKETS.find((bucket) => bucket === stored) ?? null;
+/** A stored framework as it pools: a name the vocabulary marks as a framework, else `private`. */
+export const projectFramework = (stored) => (FRAMEWORKS.has(stored) ? stored : PRIVATE);

package/dist/sessions/public-vocabulary.d.ts

@@ -0,0 +1,73 @@
+/** What every name outside this file becomes. */
+export declare const LITERAL = "<literal>";
+export declare const REPO_SIZES: readonly ["xs", "s", "m", "l", "xl"];
+export type RepoSize = (typeof REPO_SIZES)[number];
+/** A stored size bucket: null is a size that could not be read, and undefined is a value that is not one. */
+export declare const asRepoSize: (value: unknown) => RepoSize | null | undefined;
+/** File extension to language: the stack's language mix. */
+export declare const LANGUAGE_OF_EXTENSION: ReadonlyMap<string, string>;
+export declare const LANGUAGES: ReadonlySet<string>;
+/** A touched file's base name to the framework it shows. */
+export declare const FRAMEWORK_OF_FILE: ReadonlyArray<readonly [RegExp, string]>;
+/** A program a shell call ran to the framework it shows. */
+export declare const FRAMEWORK_OF_PROGRAM: ReadonlyMap<string, string>;
+export declare const FRAMEWORKS: ReadonlySet<string>;
+export declare const publicEffort: (value: string | null) => string | null;
+export declare const publicModel: (value: string | null) => string | null;
+export declare const publicVersion: (value: string | null) => string | null;
+/** Programs whose short flags are commonly bundled, as in `rm -rf`. Elsewhere a short lowercase run is more likely a value joined to its flag, as in `mysql -pabc`. */
+export declare const BUNDLING_PROGRAMS: ReadonlySet<string>;
+/** Programs anyone can install or a system ships. A private script or binary is not here, so it reads as the literal. */
+export declare const PUBLIC_PROGRAMS: ReadonlySet<string>;
+/** The subcommands of a public program. Only a program whose subcommands are its own public interface is here: a `just` recipe or a `make` target belongs to the repository. */
+export declare const PUBLIC_SUBCOMMANDS: ReadonlyMap<string, ReadonlySet<string>>;
+/** Flag names of common public programs. A flag name on another program can be a private script's, so an unlisted name reads as the literal. */
+export declare const PUBLIC_FLAGS: ReadonlySet<string>;
+/** Hosts that say nothing about who asked. Matched whole: `acme.github.io` names a customer even though `github.io` is public. */
+export declare const PUBLIC_HOSTS: ReadonlySet<string>;
+/** MCP servers published for anyone to install. A server someone named themselves can name their company, so it reads as the literal. */
+export declare const PUBLIC_MCP_SERVERS: ReadonlySet<string>;
+/**
+ * Tools the published server of that name serves, by server. A server name is a label the user picks, so an allowlisted server does not make
+ * its tools public: anything not listed under the server reads as the literal, and a server with no entry here has every tool read that way.
+ */
+export declare const PUBLIC_MCP_TOOLS: ReadonlyMap<string, ReadonlySet<string>>;
+/** Skills published for anyone to install. */
+export declare const PUBLIC_SKILLS: ReadonlySet<string>;
+/** Packages a public registry serves and many projects use. No registry is asked at capture, so anything else reads as the literal, including a real public package missing here. */
+export declare const PUBLIC_PACKAGES: ReadonlySet<string>;
+export declare const isRegistryVersion: (version: string) => boolean;
+export declare const isPublicMcpTool: (server: string, tool: string) => boolean;
+/**
+ * The version of every pinned snapshot and curated list below, as one number. Change a snapshot file or any curated list in vocab-pin.test.ts's
+ * `curatedDigest`, and bump it: that test fails otherwise.
+ */
+export declare const VOCAB_VERSION = "1";
+/** The day the snapshots were taken. It must equal `snapshotDate` in vocab/manifest.json, which the loader checks. */
+export declare const VOCAB_SNAPSHOT_DATE = "2026-11-04";
+/** How old a snapshot may be before `deposit` builds no batch (spec Section 7, `registry_max_age`). */
+export declare const REGISTRY_MAX_AGE_DAYS = 30;
+/** Names admitted per package ecosystem, by the registry's own download counts (spec Section 7, `seed_top`). */
+export declare const SEED_TOP = 1000;
+/** The longest ordered `program` list a compound command pools as (spec Section 7, `pipe_max`). */
+export declare const PIPE_MAX = 4;
+/** What a name that is not admitted pools as. */
+export declare const PRIVATE = "private";
+/** A client more than `registry_max_age` past its snapshot builds no batch (the exact elapsed time, not whole days): its sessions wait in `A` until it upgrades. */
+export declare const isVocabularyExpired: (now: Date) => boolean;
+/** The built-in tools of Claude Code, by the names a transcript records. Curated, since no registry publishes them (spec Section 1.3, the name seed). */
+export declare const HARNESS_TOOLS: ReadonlyMap<string, ReadonlySet<string>>;
+/**
+ * The built-in subagent types of each harness, by the names a transcript records (`agentType`). Curated, since no registry publishes them. No plugin registry
+ * is pinned yet, so an admitted plugin agent is not on this list and pools as `custom` (spec Section 2).
+ */
+export declare const HARNESS_AGENT_TYPES: ReadonlyMap<string, ReadonlySet<string>>;
+/** What a subagent type pools as when it is not a built-in: a custom agent's name is private. */
+export declare const CUSTOM_AGENT = "custom";
+/** A subagent type as it pools: a built-in of a harness as itself, anything else as `custom`. */
+export declare const projectedAgentType: (agentType: string) => string;
+/**
+ * The input keys each built-in tool's published schema lists, by the tool's name. Curated from the harness's tool reference. A key outside the tool's list, and every
+ * key of an MCP tool (no pinned registry lists their schemas), is counted and never named (spec Section 1.3).
+ */
+export declare const TOOL_INPUT_KEYS: ReadonlyMap<string, ReadonlySet<string>>;