@manyoars/oars 0.2.0 → 0.3.0

package/dist/sessions/strata.d.ts

@@ -0,0 +1,26 @@
+import { type RepoSize } from './public-vocabulary.js';
+import { type LanguageShare, type RepoFilesBucket, type Strata } from './schema.js';
+import type { CanonicalAction } from './actions.js';
+/** How many of the given steps only look. */
+export declare const exploreCount: (actions: readonly CanonicalAction[]) => number;
+/**
+ * A language's share of the touched files: absent, incidental (under 10 percent), secondary (10 up to 50), primary (50 and over). The lower edge is inclusive.
+ * Integers are compared, not a quotient, so 1 of 10 files is exactly 10 percent.
+ */
+export declare const languageShareBucket: (files: number, total: number) => LanguageShare;
+export declare const repoFilesBucketOf: (size: RepoSize | null) => RepoFilesBucket | null;
+/**
+ * A package the vocabulary marks as a framework, by `<ecosystem>:<name>` as `resolveName` writes it, to the framework's name in `FRAMEWORKS`. A package
+ * is not a program or a file, so this is the one source of `framework` that names a registry entry.
+ */
+export declare const FRAMEWORK_OF_PACKAGE: ReadonlyMap<string, string>;
+/** The strata of a file's evidence but `explore`, which the caller counts for the file and for each prompt. Files are counted, not touches: a path read ten times is one. */
+export declare const strataOf: (evidence: {
+    paths: readonly string[];
+    packages: readonly string[];
+    size: RepoSize | null;
+}) => Omit<Strata, "explore">;
+/** A stored language as it pools: a member of the pinned list, else `other`. */
+export declare const projectLanguage: (stored: string) => string;
+/** A stored share bucket as it pools: itself when it is one of the four, else null (no bucket is guessed from a value this code does not know). */
+export declare const projectLanguageShare: (stored: string) => LanguageShare | null;

package/dist/sessions/strata.js

@@ -0,0 +1,77 @@
+// The stack strata a capture stores (pool vocabulary spec Sections 1.1 and 7): language and its share of the touched files, the repository's file
+// count by order of magnitude, the framework a resolved package shows, and how many steps only looked. Every value is a member of a closed list or a count,
+// so no path, package name, or program text is kept. The language and share projections are here; the rest that gate these at deposit are in `projection.ts`.
+import { LANGUAGE_OF_EXTENSION, LANGUAGES } from './public-vocabulary.js';
+import { LANGUAGE_SHARES } from './schema.js';
+/** The steps that only look at the code or the web. `file.read`, `file.search`, `web.search`, and `web.fetch`; a shell step is not counted, because what it does is not known from its action. */
+const EXPLORE_ACTIONS = new Set(['file.read', 'file.search', 'web.search', 'web.fetch']);
+/** How many of the given steps only look. */
+export const exploreCount = (actions) => actions.filter((action) => EXPLORE_ACTIONS.has(action)).length;
+/**
+ * A language's share of the touched files: absent, incidental (under 10 percent), secondary (10 up to 50), primary (50 and over). The lower edge is inclusive.
+ * Integers are compared, not a quotient, so 1 of 10 files is exactly 10 percent.
+ */
+export const languageShareBucket = (files, total) => {
+    if (files <= 0 || total <= 0)
+        return '0';
+    if (files * 100 < total * 10)
+        return 'under-10';
+    return files * 100 < total * 50 ? '10-50' : 'over-50';
+};
+/** The repository's size bucket (`repoSizeOf`) as the pool's `repoFiles` bucket: both cut at 100, 1000, 10000, and 100000 with the lower edge inclusive. */
+const REPO_FILES_OF_SIZE = new Map([
+    ['xs', 'under-100'],
+    ['s', '100-1k'],
+    ['m', '1k-10k'],
+    ['l', '10k-100k'],
+    ['xl', 'over-100k'],
+]);
+export const repoFilesBucketOf = (size) => (size === null ? null : (REPO_FILES_OF_SIZE.get(size) ?? null));
+/**
+ * A package the vocabulary marks as a framework, by `<ecosystem>:<name>` as `resolveName` writes it, to the framework's name in `FRAMEWORKS`. A package
+ * is not a program or a file, so this is the one source of `framework` that names a registry entry.
+ */
+export const FRAMEWORK_OF_PACKAGE = new Map([
+    ['npm:vite', 'vite'],
+    ['npm:vitest', 'vitest'],
+    ['npm:astro', 'astro'],
+    ['npm:next', 'next'],
+    ['npm:nuxt', 'nuxt'],
+    ['npm:svelte', 'svelte'],
+    ['npm:@angular/core', 'angular'],
+    ['npm:tailwindcss', 'tailwind'],
+    ['npm:jest', 'jest'],
+    ['npm:playwright', 'playwright'],
+    ['npm:@playwright/test', 'playwright'],
+    ['npm:wrangler', 'cloudflare-workers'],
+    ['pypi:django', 'django'],
+    ['rubygems:rails', 'rails'],
+]);
+/** The language of one touched path: the vocabulary's name for its extension, else `other`; null for a path with no extension, which shows no language. A dotfile (`.gitignore`) has none: its only dot leads the name. */
+const languageOfPath = (path) => {
+    const base = path.replace(/\\/g, '/').split('/').pop() ?? path;
+    if (base.lastIndexOf('.') <= 0)
+        return null;
+    return LANGUAGE_OF_EXTENSION.get(base.split('.').pop()?.toLowerCase() ?? '') ?? 'other';
+};
+/** The strata of a file's evidence but `explore`, which the caller counts for the file and for each prompt. Files are counted, not touches: a path read ten times is one. */
+export const strataOf = (evidence) => {
+    const counts = new Map();
+    let total = 0;
+    for (const path of new Set(evidence.paths)) {
+        const language = languageOfPath(path);
+        if (language === null)
+            continue;
+        counts.set(language, (counts.get(language) ?? 0) + 1);
+        total += 1;
+    }
+    return {
+        languages: [...counts].sort(([a], [b]) => a.localeCompare(b)).map(([language, files]) => ({ language, share: languageShareBucket(files, total) })),
+        repoFiles: repoFilesBucketOf(evidence.size),
+        frameworks: [...new Set(evidence.packages.flatMap((name) => FRAMEWORK_OF_PACKAGE.get(name) ?? []))].sort(),
+    };
+};
+/** A stored language as it pools: a member of the pinned list, else `other`. */
+export const projectLanguage = (stored) => (LANGUAGES.has(stored) ? stored : 'other');
+/** A stored share bucket as it pools: itself when it is one of the four, else null (no bucket is guessed from a value this code does not know). */
+export const projectLanguageShare = (stored) => LANGUAGE_SHARES.find((bucket) => bucket === stored) ?? null;

package/dist/sessions/survival.d.ts

@@ -0,0 +1,25 @@
+import { type SessionsRuntime } from './store.js';
+/** A commit younger than this has not had time to be reverted or dropped, so it is not read yet. */
+export declare const SURVIVAL_DAYS = 7;
+declare const STATES: readonly ["survived", "reverted", "unreachable", "unknown"];
+export type SurvivalState = (typeof STATES)[number];
+/** One line of `commit-survival.jsonl`. `sha` as captured (usually short), and a day-resolution date. */
+export interface SurvivalObservation {
+    sha: string;
+    state: SurvivalState;
+    day: string;
+}
+export type SurvivalCounts = {
+    [state in SurvivalState]: number;
+};
+/** Runs one read-only git command in a repository and answers its stdout; rejects on any failure. */
+export type Git = (root: string, args: readonly string[], stdin?: string) => Promise<string>;
+export declare const survivalFile: (storeDir: string) => string;
+/** The latest state of each sha. The file only adds to what `books` shows, so a missing or unreadable one reads as nothing observed yet. */
+export declare const readSurvival: (storeDir: string) => Promise<Map<string, SurvivalState>>;
+/**
+ * Observes every commit older than `SURVIVAL_DAYS` in the allowlisted folders. Never rejects, since a deposit that has already succeeded
+ * must not fail on what it adds: null when the store could not be read or written, and the next run tries again.
+ */
+export declare const recordSurvival: (runtime: SessionsRuntime, allow: readonly string[], now: () => number, git?: Git) => Promise<SurvivalCounts | null>;
+export {};

package/dist/sessions/survival.js

@@ -0,0 +1,230 @@
+// Commit survival: what became of a commit is an observation made later, not a fact of the transcript, so it never
+// runs at derive time and never from a hook a session waits on. A manual deposit and the nightly run read the repository of each
+// allowlisted folder and append to `commit-survival.jsonl` beside the store, so the log `verify` checks stays untouched.
+import { execFile } from 'node:child_process';
+import { createReadStream } from 'node:fs';
+import { appendFile, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { createInterface } from 'node:readline';
+import { compileAllow, slugOf } from './allow.js';
+import { makeRepoRoot } from './repo-root.js';
+import { loadStore, paths } from './store.js';
+/** A commit younger than this has not had time to be reverted or dropped, so it is not read yet. */
+export const SURVIVAL_DAYS = 7;
+const DAY_MS = 86_400_000;
+const GIT_TIMEOUT_MS = 120_000;
+/** `rev-list` prints 41 bytes a commit; this holds about 6 million of them. */
+const GIT_MAX_BUFFER = 256 * 1024 * 1024;
+/** How far into a transcript to look for its working directory: the harness stamps every line, so a file without one by here has none. */
+const CWD_SCAN_LINES = 200;
+/** Tried in this order when `origin/HEAD` is not set, which `git clone` sets and `git init` plus `git remote add` does not. */
+const DEFAULT_REFS = ['refs/remotes/origin/main', 'refs/remotes/origin/master', 'refs/heads/main', 'refs/heads/master'];
+const STATES = ['survived', 'reverted', 'unreachable', 'unknown'];
+export const survivalFile = (storeDir) => join(storeDir, 'commit-survival.jsonl');
+const runGit = (root, args, stdin) => new Promise((resolve, reject) => {
+    const child = execFile('git', ['-C', root, ...args], {
+        encoding: 'utf8',
+        timeout: GIT_TIMEOUT_MS,
+        maxBuffer: GIT_MAX_BUFFER,
+        windowsHide: true,
+        // A partial clone would fetch a missing object from its remote, and this reads no network. `GIT_NO_LAZY_FETCH` needs about 2.45 or later, and a `protocol.allow` key loses to a `protocol.<name>.allow` key in the
+        // repository's own config. `GIT_ALLOW_PROTOCOL` is checked first on any git and beats every config key, and setting it here replaces one inherited from the caller. A `GIT_DIR` inherited from a caller's hook would read some other repository than the one named.
+        env: { ...process.env, GIT_ALLOW_PROTOCOL: 'none', GIT_NO_LAZY_FETCH: '1', GIT_OPTIONAL_LOCKS: '0', GIT_DIR: undefined, GIT_WORK_TREE: undefined },
+    }, (error, stdout) => {
+        if (error === null)
+            resolve(stdout);
+        else
+            reject(new Error(error.message));
+    });
+    // A git that exits before reading its stdin raises EPIPE here; its exit status already reports the failure.
+    child.stdin?.on('error', () => undefined);
+    child.stdin?.end(stdin ?? '');
+});
+const outputLines = (text) => text.split(/\r?\n/).filter((line) => line !== '');
+const defaultRef = async (git, root) => {
+    const head = (await git(root, ['symbolic-ref', '--quiet', 'refs/remotes/origin/HEAD']).catch(() => '')).trim();
+    if (head !== '')
+        return head;
+    const present = new Set(outputLines(await git(root, ['for-each-ref', '--format=%(refname)', ...DEFAULT_REFS])));
+    return DEFAULT_REFS.find((ref) => present.has(ref)) ?? null;
+};
+const REVERT_RECORD = /^([0-9a-f]{40})\n([\s\S]*)$/;
+const REVERTS = /This reverts commit ([0-9a-f]{40})/g;
+/**
+ * The commits the default branch has undone, from `git revert`'s own message. `git log --topo-order` runs children before parents, so by the
+ * time a revert is reached anything that undid it has been seen, and a reverted revert undoes nothing.
+ */
+const revertedIn = (log) => {
+    const reverted = new Set();
+    for (const record of log.split('\0')) {
+        const found = REVERT_RECORD.exec(record.trimStart());
+        if (found === null || reverted.has(found[1] ?? ''))
+            continue;
+        for (const match of (found[2] ?? '').matchAll(REVERTS))
+            reverted.add(match[1] ?? '');
+    }
+    return reverted;
+};
+/** What one repository says of each sha. A sha it does not hold reads `unknown`: the session may have committed in another repository, which a path rule cannot follow. */
+const classify = async (git, root, shas) => {
+    const states = new Map();
+    if ((await git(root, ['rev-parse', '--is-shallow-repository'])).trim() !== 'false')
+        return states;
+    const ref = await defaultRef(git, root);
+    if (ref === null)
+        return states;
+    const reachable = new Set(outputLines(await git(root, ['rev-list', ref])));
+    const reverted = revertedIn(await git(root, ['log', ref, '--topo-order', '--no-show-signature', '--grep=This reverts commit', '--format=%H%n%B%x00']));
+    const resolved = outputLines(await git(root, ['cat-file', '--batch-check=%(objectname) %(objecttype)'], `${shas.join('\n')}\n`));
+    shas.forEach((sha, index) => {
+        const [full = '', type] = (resolved[index] ?? '').split(' ');
+        if (type !== 'commit')
+            return;
+        states.set(sha, reverted.has(full) ? 'reverted' : reachable.has(full) ? 'survived' : 'unreachable');
+    });
+    return states;
+};
+/** The shas old enough to read, per allowlisted project. Main-line calls only: a subagent's commits are not attributed yet. */
+const dueByProject = (store, allows, cutoff) => {
+    const projectOf = new Map(store.sessions.map((session) => [session.session, session.project]));
+    const due = new Map();
+    for (const tool of store.tools) {
+        const project = projectOf.get(tool.session);
+        if (project === undefined || !allows(project) || tool.side || tool.ts === null || tool.ts >= cutoff)
+            continue;
+        for (const sha of tool.commits ?? []) {
+            if (sha === null)
+                continue;
+            const entry = due.get(project) ?? { sessions: new Set(), shas: new Set() };
+            entry.sessions.add(tool.session);
+            entry.shas.add(sha);
+            due.set(project, entry);
+        }
+    }
+    return due;
+};
+const topLevelCwd = (line) => {
+    try {
+        const parsed = JSON.parse(line);
+        const cwd = typeof parsed === 'object' && parsed !== null ? Reflect.get(parsed, 'cwd') : undefined;
+        return typeof cwd === 'string' ? cwd : undefined;
+    }
+    catch {
+        return undefined;
+    }
+};
+/** The transcript's first `cwd` whose slug is the project. A later `cd` moves `cwd`, and a path a transcript merely names must not choose what gets read. */
+const cwdIn = async (file, project) => {
+    const stream = createReadStream(file, { encoding: 'utf8' });
+    // An absent file errors here, not in the loop.
+    const opened = new Promise((resolve) => {
+        stream.once('error', () => {
+            resolve(false);
+        });
+        stream.once('open', () => {
+            resolve(true);
+        });
+    });
+    if (!(await opened))
+        return undefined;
+    const reader = createInterface({ input: stream, crlfDelay: Infinity });
+    let read = 0;
+    try {
+        for await (const line of reader) {
+            read += 1;
+            if (read > CWD_SCAN_LINES)
+                return undefined;
+            const cwd = topLevelCwd(line);
+            if (cwd !== undefined && slugOf(cwd) === project)
+                return cwd;
+        }
+        return undefined;
+    }
+    finally {
+        reader.close();
+        stream.destroy();
+    }
+};
+const cwdOfProject = async (runtime, project, sessions) => {
+    for (const session of sessions) {
+        for (const root of [runtime.projectsRoot, paths(runtime.storeDir).raw]) {
+            const found = await cwdIn(join(root, project, `${session}.jsonl`), project);
+            if (found !== undefined)
+                return found;
+        }
+    }
+    return undefined;
+};
+const isObservation = (value) => {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const state = Reflect.get(value, 'state');
+    return typeof Reflect.get(value, 'sha') === 'string' && STATES.some((known) => known === state);
+};
+/** The latest state of each sha. The file only adds to what `books` shows, so a missing or unreadable one reads as nothing observed yet. */
+export const readSurvival = async (storeDir) => {
+    const states = new Map();
+    const text = await readFile(survivalFile(storeDir), 'utf8').catch(() => '');
+    for (const line of text.split('\n')) {
+        if (line === '')
+            continue;
+        try {
+            const parsed = JSON.parse(line);
+            if (isObservation(parsed))
+                states.set(parsed.sha, parsed.state);
+        }
+        catch {
+            // A torn last line from a crashed run: the next run observes that sha again.
+        }
+    }
+    return states;
+};
+const observe = async (runtime, allowEntries, now, git) => {
+    const allow = compileAllow(allowEntries);
+    const due = dueByProject(await loadStore(runtime.storeDir), allow.allows, new Date(now() - SURVIVAL_DAYS * DAY_MS).toISOString());
+    const repoRoot = makeRepoRoot();
+    const byRoot = new Map();
+    const shas = new Set();
+    for (const [project, entry] of due) {
+        for (const sha of entry.shas)
+            shas.add(sha);
+        const cwd = await cwdOfProject(runtime, project, entry.sessions);
+        const root = cwd === undefined ? null : repoRoot(cwd);
+        if (root !== null)
+            byRoot.set(root, new Set([...(byRoot.get(root) ?? []), ...entry.shas]));
+    }
+    const fresh = new Map();
+    for (const [root, wanted] of byRoot) {
+        // Fail-open per repository: one that cannot be read leaves its shas unknown and the others are still read.
+        const states = await classify(git, root, [...wanted]).catch(() => new Map());
+        for (const [sha, state] of states)
+            fresh.set(sha, state);
+    }
+    const known = await readSurvival(runtime.storeDir);
+    const day = new Date(now()).toISOString().slice(0, 10);
+    const counts = { survived: 0, reverted: 0, unreachable: 0, unknown: 0 };
+    const appended = [];
+    for (const sha of shas) {
+        const before = known.get(sha);
+        // An observation is not undone by a later failure to look: only a state git answered replaces one.
+        const state = fresh.get(sha) ?? before ?? 'unknown';
+        counts[state] += 1;
+        if (state !== before)
+            appended.push({ sha, state, day });
+    }
+    if (appended.length > 0)
+        await appendFile(survivalFile(runtime.storeDir), appended.map((line) => `${JSON.stringify(line)}\n`).join(''), { mode: 0o600 });
+    return counts;
+};
+/**
+ * Observes every commit older than `SURVIVAL_DAYS` in the allowlisted folders. Never rejects, since a deposit that has already succeeded
+ * must not fail on what it adds: null when the store could not be read or written, and the next run tries again.
+ */
+export const recordSurvival = async (runtime, allow, now, git = runGit) => {
+    try {
+        return await observe(runtime, allow, now, git);
+    }
+    catch {
+        return null;
+    }
+};

package/dist/sessions/verify.d.ts

@@ -0,0 +1,53 @@
+import { type SessionObservation, type Skeleton, type SkeletonLine, type ToolObservation } from './schema.js';
+export interface InvariantResult {
+    name: string;
+    /** What was compared: lines, pairs, or tool results, as each invariant defines it. */
+    checked: number;
+    violations: number;
+    /** Checks that neither hold nor fail, each counted under the cause it was traced to (the cost-state check only). */
+    observed?: ObservedClass[];
+}
+export type CostClass = 'resume scope' | 'subagent transcripts' | 'harness side calls' | 'other';
+export interface ObservedClass {
+    cls: CostClass;
+    /** True for a check that holds only once its scope is applied; false for a total above the recorded sum. */
+    holds: boolean;
+    checks: number;
+    /** The first session seen in the class. */
+    example: string | null;
+}
+export declare const INVARIANTS: readonly ["tool_result names an earlier tool_use", "parentUuid resolves in the file", "message timestamps never step back more than 1 s", "assistant lines carry a request id; shared ids have consecutive apiBlockIndex", "thinking tokens never exceed output tokens", "cost-state totals equal summed usage since the process start, subagents included"];
+/** `delegated` holds the lines of the session's subagent transcripts, which its cost-state totals include. */
+export declare const verifySkeleton: (skeleton: Skeleton, delegated?: readonly SkeletonLine[]) => InvariantResult[];
+/** Sums each invariant over many skeletons, each main session's cost-state checked with its subagent transcripts' lines. */
+export declare const verifyAll: (skeletons: readonly Skeleton[], delegatedFrom?: readonly Skeleton[]) => InvariantResult[];
+export declare const formatVerify: (results: readonly InvariantResult[], sessions: number) => string;
+export declare const CAPTURE_INVARIANTS: readonly ["every session is captured at the current capture version (none is cv-behind)", "sessions captured at the current version share one sid", "every fileHash on a session is a path target of one of its tool calls", "a path target names its base; no other target does"];
+/**
+ * The CAPTURE 4 fields, checked over the store's capture records: cv-behind sessions (a session captured at an older readable
+ * version, not yet captured again, unless `frozen` names it: its transcript is gone from the harness and `raw/` (or, for a Cursor
+ * session, its composer is gone from Cursor), so it is counted apart, never a violation), a mixed `sid` (two salts in one store, so
+ * path joins hold only within each), `fileHashes` that no tool call explains, and `targetBase` set on, or missing from, the wrong
+ * kind of target. Skeleton invariants stay in {@link verifyAll}.
+ */
+export declare const verifyCaptured: (sessions: readonly SessionObservation[], tools: readonly ToolObservation[], frozen?: ReadonlySet<string>) => InvariantResult[];
+/** `not run` when a row had nothing to check (a session behind the current capture version for rows 8 to 10, a transcript with no stamped lines for row 3, and so on). */
+export type RowStatus = 'pass' | 'fail' | 'not run';
+/** One session's result: the ten rows of {@link INVARIANTS} then {@link CAPTURE_INVARIANTS}, each with its status (spec 5.4 item 5). */
+export interface SessionVerification {
+    session: string;
+    invariants: Array<InvariantResult & {
+        status: RowStatus;
+    }>;
+}
+/**
+ * A result for every session with a skeleton or a capture record: {@link verifySkeleton} with the session's subagent transcripts' lines as `delegated`,
+ * then {@link verifyCaptured} over the session's own capture records. A session with no skeleton gets rows 1 to 6 at `checked: 0` (`not run`) and its real
+ * rows 7 to 10. Row 8 (one `sid`) is read within the one session, so it cannot fail for a session with a non-null `sid`; a current-version session with a
+ * null `sid` fails it. The store-wide row stays in `verifyCaptured` over all sessions.
+ */
+export declare const verifySessions: (skeletons: readonly Skeleton[], sessions: readonly SessionObservation[], tools: readonly ToolObservation[], frozen?: ReadonlySet<string>) => SessionVerification[];
+/** Per-session lines the default text prints; the JSON lists them all. */
+export declare const SESSION_LINE_CAP = 20;
+/** One line per session with a failing row, naming the rows, capped at {@link SESSION_LINE_CAP} with a count of the rest; empty when none fails. Ids and row names only. */
+export declare const formatSessionResults: (results: readonly SessionVerification[]) => string;