toolroll 0.9.71 → 0.9.72

package/dist/release-carry.d.ts

@@ -0,0 +1,233 @@
+import { type TreeChange, type VerifiedCommit } from "./commit-extract.js";
+import { type ReleasePolicy, type ReleaseTerms } from "./contracts/release-terms.js";
+import { type ExecResult } from "./exec.js";
+import { type ReleaseAuthority, type ReleaseCarry, type Store } from "./store.js";
+/** The journey scripts: tests, by Alex's decision (they carry). */
+export declare const JOURNEY_SCRIPTS: readonly string[];
+/** What carries (version 1). Everything else asks again — including every other `test/**` or `scripts/**` file (the
+ * harness, what it imports, helpers and fixtures), so no harness file can slip in under a class. */
+export declare const CARRY_RULES: Readonly<{
+    version: 1;
+    classes: readonly {
+        name: string;
+        matches: (path: string) => boolean;
+    }[];
+    /** Never carry, even when a class above matches them. */
+    never: readonly {
+        why: string;
+        matches: (path: string) => boolean;
+    }[];
+}>;
+/** The limits (Alex, 2026-10-25): 400 changed lines and 20 files after the approval, 800 lines of churn. */
+export declare const CARRY_LIMITS: Readonly<{
+    lines: 400;
+    files: 20;
+    churn: 800;
+}>;
+/** "Ask for every release commit": a project setting, newest choice wins (a ledger row each); off by default. */
+export declare const ASK_EVERY_COMMIT_ACTION = "release carrying changed";
+export declare function asksEveryReleaseCommit(store: Store, repo: string): boolean;
+export declare function setAskEveryReleaseCommit(store: Store, repo: string, ask: boolean, by: string, now: Date): void;
+/** The effective policy now: the runtime rules, the project's protected paths and the limits. */
+export declare function effectivePolicy(store: Store, repo: string, options?: {
+    noCarry?: boolean;
+}): ReleasePolicy;
+/** The stricter of two policies: what either protects asks again, the lower limit wins, either one's "ask" asks. Null
+ * when either is a policy this runtime doesn't know (then nothing carries). */
+export declare function stricterOf(a: ReleasePolicy | null, b: ReleasePolicy | null): ReleasePolicy | null;
+/**
+ * A path as the rules compare it: lower case (a case-insensitive file system reads docs/Plans as docs/plans), each part
+ * without the trailing dots and spaces Windows drops, and no empty or `.` parts (a verified tree never holds them, but
+ * the rules don't rely on that).
+ */
+export declare function rulePath(path: string): string;
+/** Why one changed path doesn't carry, in words, or null when it does. Every rule reads the normalized path. */
+export declare function changeRefusal(change: TreeChange, policy: ReleasePolicy): string | null;
+/**
+ * A release scope's terms, from the plane's own records: the project's repository, the approved commit and its
+ * verified tree, the effective policy, the live release check grant and the check access (only the fence), and the
+ * expiry. Null with why when the release can't carry at all (it then asks for every commit, as before).
+ */
+export declare function releaseTermsFor(store: Store, input: {
+    repo: string;
+    version: string;
+    branch: string;
+    pr: number;
+    candidate: string;
+    now: Date;
+    noCarry?: boolean;
+}): {
+    ok: true;
+    terms: ReleaseTerms;
+} | {
+    ok: false;
+    why: string;
+};
+/** One carried commit, as the summary and the merge message list it. */
+export type LandedCommit = {
+    sha: string;
+    files: {
+        path: string;
+        added: number;
+        deleted: number;
+    }[];
+};
+export type CarryRefusal = {
+    ok: false;
+    reason: "authority" | "ancestry" | "shape" | "rules" | "limits" | "build" | "artifact" | "stale";
+    message: string;
+    path?: string;
+};
+export type PreflightPlan = {
+    authority: ReleaseAuthority;
+    to: string;
+    toTree: string;
+    commits: LandedCommit[];
+    changedLines: number;
+    files: number;
+    churn: number;
+    policy: ReleasePolicy;
+    currentPolicyDigest: string;
+};
+/**
+ * Step 2, read-only: nothing from the candidate is installed, built or run here. Objects come from the project's own
+ * Git directory as Toolroll records it, hashed here; the authority is read live.
+ */
+export declare function preflightCarry(store: Store, input: {
+    authority: number;
+    to: string;
+    epoch?: number | null;
+    now: Date;
+}): {
+    ok: true;
+    plan: PreflightPlan;
+} | CarryRefusal;
+/** How a build step runs: the fenced default, or a test's stand-in. */
+export type BuildRunner = (file: string, args: readonly string[], options: {
+    cwd: string;
+    env: Record<string, string>;
+    writable: readonly string[];
+    timeoutMs: number;
+}) => Promise<ExecResult>;
+/** The default build runner: the OS fence, writes only where named, and no network — its only way out is a proxy of its
+ * own that allows no host. No fence on this machine, no build. */
+export declare function fencedBuildRunner(store: Store): BuildRunner;
+/** What the writer scan reads from the OS: injectable so each refusal shape can be shown (tests), real by default. */
+export type WriterScanIO = {
+    platform: NodeJS.Platform;
+    /** This process: its pid, and the user the build runs as (its effective uid). */
+    pid: number;
+    uid: number;
+    /** Linux: the numeric entries of /proc. Throws when /proc can't be listed. */
+    procPids(): string[];
+    /** Linux: readlink /proc/<pid>/cwd. Throws with the errno code. */
+    procCwd(pid: string): string;
+    /** Linux: a process's real and effective uid (/proc/<pid>/status, readable even when its folder isn't) and its start
+     * time in clock ticks since boot (/proc/<pid>/stat). Throws with the errno code. Never the owner of its /proc files:
+     * a process can make those root's (PR_SET_DUMPABLE 0). */
+    procIdentity(pid: string): {
+        uids: number[];
+        startTicks: number;
+    };
+    /** Linux: now, in clock ticks since boot (from /proc/uptime), and the ticks in a second; null when unreadable. */
+    nowTicks(): {
+        ticks: number;
+        hz: number;
+    } | null;
+    /** macOS: each process's pid, effective uid and whether it is a zombie (ps), or null when ps failed. */
+    processes(): {
+        pid: number;
+        uid: number;
+        zombie: boolean;
+    }[] | null;
+    /** macOS: lsof's cwd listing, its stdout and how it ended. */
+    lsof(): {
+        stdout: string;
+        status: number | null;
+        signal: string | null;
+        code: string | null;
+    };
+    /** macOS: a second look at these pids (ps): each one still there, with its uid, whether it is a zombie and when it
+     * started (ms, whole seconds); a pid missing from the map is gone. Null when ps failed. */
+    describe(pids: readonly number[]): Map<number, {
+        uid: number;
+        zombie: boolean;
+        startedMs: number | null;
+    }> | null;
+    /** Whether a pid is gone (ESRCH). */
+    gone(pid: number): boolean;
+};
+/** When the build began: wall-clock ms, and on Linux the clock ticks since boot. */
+export type BuildStart = {
+    ms: number;
+    ticks: {
+        ticks: number;
+        hz: number;
+    } | null;
+};
+/**
+ * Pids whose working folder is inside `root` (lsof on macOS, /proc on Linux), or null when that can't be shown (the
+ * caller refuses: nothing is digested unless it is shown that no writer remains). A process is passed over only when
+ * it is gone, or provably runs as another user than the build; one of the build's own user that can't be read refuses.
+ *
+ * On Linux a fenced build can't leave one at all: the sandbox runtime starts every launch in a PID namespace of its own
+ * (bwrap --unshare-pid, --die-with-parent), and when the build's process ends the kernel kills everything left in that
+ * namespace, a detached or new-session child included, before the launch returns. The scan is the check for whatever
+ * runs outside such a namespace (an unfenced runner) and the proof on macOS, where Seatbelt has no PID namespace.
+ */
+export declare function processesInside(root: string, since: BuildStart | null, io?: WriterScanIO): number[] | null;
+/** Files left out of the artifact digest and listed as doc changes instead. */
+export declare const ARTIFACT_EXCLUDED: readonly string[];
+/**
+ * The digest of one built tree's production artifacts, read as untrusted: every entry walked with lstat, opened with
+ * O_NOFOLLOW and checked again on the descriptor; only regular files inside `root` count; a symlink, a special file or a
+ * path that escapes refuses. Each entry records path, mode and sha256.
+ */
+export declare function digestTree(root: string, paths: readonly string[]): {
+    ok: true;
+    digest: string;
+    entries: number;
+} | {
+    ok: false;
+    message: string;
+};
+/**
+ * Step 3 for one commit: extract it (verified objects, regular files only) into a fresh folder, install from its
+ * lockfile with no scripts and no network (npm checks every package against the lockfile's integrity hash), build it,
+ * list what `npm pack` would ship, wait until nothing runs from the folder any more, and digest dist/ plus the packed
+ * files twice — a difference means something is still writing, and refuses.
+ */
+export declare function artifactDigest(gitDir: string, sha: string, runner: BuildRunner, options?: {
+    timeoutMs?: number;
+    npmCache?: string;
+}): Promise<{
+    ok: true;
+    digest: string;
+} | {
+    ok: false;
+    message: string;
+}>;
+/** The release task's id for a commit (release.ts gateTaskId's naming). */
+export declare const carriedTaskId: (version: string, sha: string) => string;
+export type CarryResult = {
+    ok: true;
+    taskId: string;
+    carry: ReleaseCarry;
+    retried: boolean;
+} | CarryRefusal;
+/**
+ * Carry a person's release approval to commit `to`, or say exactly why not. The lead may ask; only these rules decide.
+ * A refusal seals nothing and writes no row.
+ */
+export declare function proveCarry(store: Store, input: {
+    authority: number;
+    to: string;
+    requestId?: string;
+    epoch?: number | null;
+    now: Date;
+    runner?: BuildRunner;
+    runtime?: string;
+}): Promise<CarryResult>;
+/** The words a refused carry ends with: the commit, the path and the rule, and that a person approves it instead. */
+export declare function carryRefusalWords(refusal: CarryRefusal, to: string): string;
+export type { VerifiedCommit };