approval-md 0.2.0 → 0.3.0

package/dist/src/codex/workspace-commit.d.ts

@@ -0,0 +1,219 @@
+/**
+ * The durable half of the Codex workspace broker (APRV-325.2).
+ *
+ * `workspace-plan.ts` decides what a change IS; this module is the only place
+ * that makes one happen. It exists because POSIX gives no atomic multi-file
+ * rename: four `rename(2)` calls are four separate instants, and a crash
+ * between the second and the third leaves a workspace that is neither the state
+ * the human approved nor the state they started from.
+ *
+ * ## The three states, and the one this module refuses to invent
+ *
+ * A committed transaction is `after`. An untouched one is `before`. Anything
+ * else is `mixed`, and mixed is reported as mixed. The classification is made
+ * by READING the filesystem back against the journal's recorded digests, never
+ * from what the applying code believes it did: a `rename` that returned zero
+ * and a `rename` whose effect a crash lost look identical from inside the
+ * process that called it, and only the bytes on disk can tell them apart. That
+ * is why {@link inspectWorkspaceState} runs after a successful apply as well as
+ * after a failed one, and why a mixed result reaches the log as
+ * `execution.indeterminate` with reason `workspace-commit-unknown` rather than
+ * as a failure (SPEC.md §8's closed reason set, extended by this task).
+ *
+ * ## Ordering, and why the journal is written before anything moves
+ *
+ * 1. Stage every new byte and every preimage into a directory on the SAME
+ *    filesystem as the workspace, and `fsync` each file and then the directory.
+ *    Nothing in the workspace has changed yet, so a crash here is `before`.
+ * 2. Write the journal — the plan's payload hash, every endpoint, and the
+ *    before/after digest of each — and `fsync` it and its directory. This is
+ *    the instant after which a crash is RECOVERABLE rather than merely
+ *    undecidable: a journal on disk names what the workspace was and what it
+ *    was becoming, so a later reader can prove which of the two it is in.
+ * 3. Apply, in a fixed order, then `fsync` every touched parent directory.
+ * 4. Read the endpoints back. Only an all-`after` reading removes the journal
+ *    as a success; an all-`before` reading removes it as an untaken
+ *    transaction; a mixed reading LEAVES IT for a person.
+ *
+ * ## Custody is claimed only as far as the platform proves it
+ *
+ * {@link acquireWorkspaceCustody} takes an `O_CREAT | O_EXCL` lock, which
+ * excludes other cooperating brokers and nothing else, and then asks POSIX
+ * ownership and mode whether any other principal can write the endpoints it is
+ * about to touch. It reports `os-exclusive` only when both hold, `advisory`
+ * otherwise, and it always reports `acl-unproven`, because ownership and mode
+ * do not speak about ACLs (the same honesty `codex/trust.ts` already keeps). A
+ * caller that needs the strong answer asks for it and is refused when the host
+ * cannot give it; nothing here silently downgrades.
+ */
+import type { PlannedWorkspaceOperation, WorkspacePlan } from "./workspace-plan.js";
+export declare const WORKSPACE_COMMIT_VERSION: "approval.codex.workspace-commit.v1";
+/**
+ * The one directory name inside a workspace root that a proposal may never
+ * name (the broker refuses an endpoint under it before the planner ever reads
+ * a preimage). Staging has to share a filesystem with the workspace for
+ * `rename` to be atomic, so it lives inside it; reserving the name is what
+ * stops a proposal from staging over its own transaction.
+ */
+export declare const WORKSPACE_TXN_DIR = ".approval-codex-txn";
+/** The lockfile, beside the staging directory and under the same reservation. */
+export declare const WORKSPACE_LOCK_FILE = ".approval-codex-lock";
+/**
+ * How much exclusion the host actually granted.
+ *
+ * `os-exclusive`: the lock is held AND POSIX says no principal other than this
+ * process's effective user can write the workspace root or any parent
+ * directory this transaction touches. `advisory`: the lock is held and that
+ * second claim failed or could not be made. Nothing returns `os-exclusive`
+ * from a claim; it is returned from an inspection.
+ */
+export type CustodyKind = "os-exclusive" | "advisory";
+export interface CustodyReport {
+    kind: CustodyKind;
+    /** Machine-readable, always includes `acl-unproven`. Never a judgment. */
+    findings: readonly string[];
+}
+export interface WorkspaceCustody {
+    report: CustodyReport;
+    root: string;
+    txnDir: string;
+    release: () => void;
+}
+export type CustodyResult = {
+    ok: true;
+    custody: WorkspaceCustody;
+} | {
+    ok: false;
+    code: "custody-contended" | "custody-unavailable";
+    message: string;
+};
+/**
+ * Take the workspace lock and report how much exclusion it bought.
+ *
+ * The lock is `O_CREAT | O_EXCL` on a reserved name, which is the strongest
+ * primitive available to a process with no privilege: it excludes every other
+ * broker that respects it and no one else. Whether anything else CAN write is a
+ * separate question, asked of POSIX afterwards, and answered conservatively.
+ */
+export declare function acquireWorkspaceCustody(root: string, touchedDirectories: readonly string[]): CustodyResult;
+/** One endpoint of one operation, with the two digests that classify it. */
+export interface JournalEndpoint {
+    /** Workspace-relative POSIX path. */
+    path: string;
+    /** SHA-256 of the bytes this path held before the transaction, or null when absent. */
+    before_sha256: string | null;
+    /** SHA-256 of the bytes it must hold after it, or null when absent. */
+    after_sha256: string | null;
+}
+export interface JournalOperation {
+    index: number;
+    kind: PlannedWorkspaceOperation["kind"];
+    endpoints: readonly JournalEndpoint[];
+    /** Staged file holding the new bytes, relative to the staging directory. */
+    staged: string | null;
+    /** Staged file holding the preimage bytes, relative to the staging directory. */
+    preimage: string | null;
+}
+export interface WorkspaceCommitJournal {
+    version: typeof WORKSPACE_COMMIT_VERSION;
+    root: string;
+    payload_hash: string;
+    custody: CustodyKind;
+    operations: readonly JournalOperation[];
+}
+/**
+ * The endpoints one planned operation owns, in the shape recovery reads.
+ *
+ * A move owns two, and the second one's `before` is deliberately `null`: the
+ * planner refuses a move whose destination exists, so "absent" is the state the
+ * transaction started from and the state a rollback must restore.
+ */
+export declare function journalEndpointsOf(operation: PlannedWorkspaceOperation): JournalEndpoint[];
+/** Every parent directory a transaction will write into, absolute and deduplicated. */
+export declare function touchedDirectories(plan: WorkspacePlan): string[];
+/** What one endpoint currently is, relative to the two states the journal names. */
+export type EndpointState = "before" | "after" | "other" | "unreadable";
+/** The whole transaction's state, proven by reading. Never inferred. */
+export type WorkspaceState = "before" | "after" | "mixed";
+export interface WorkspaceInspection {
+    state: WorkspaceState;
+    /** Per-endpoint readings, in journal order. Present for every state. */
+    endpoints: readonly {
+        path: string;
+        state: EndpointState;
+    }[];
+}
+/**
+ * Classify the workspace against a journal by reading it.
+ *
+ * `mixed` is the honest answer for anything that is not uniformly one state,
+ * INCLUDING a single unreadable endpoint: "I could not look" and "it is half
+ * done" are both "nobody knows", and collapsing the first into `before` would
+ * be the runtime deciding an effect did not happen.
+ */
+export declare function inspectWorkspaceState(journal: WorkspaceCommitJournal): WorkspaceInspection;
+export interface CommitOptions {
+    /**
+     * Called once, after the journal is durable and before the first visible
+     * mutation, and once after each applied operation with that operation's
+     * index. A TEST SEAM and nothing else: it takes a number and returns
+     * nothing, so it can supply no value and relax no check. Throwing from it
+     * simulates the crash a timing test cannot produce, and every path below
+     * treats the throw exactly as it treats a filesystem error.
+     */
+    onStep?: (step: number) => void;
+}
+export interface CommitOutcome {
+    /** What reading the workspace back established. Never what the code believed. */
+    state: WorkspaceState;
+    inspection: WorkspaceInspection;
+    journal: WorkspaceCommitJournal;
+    /** The error that stopped the apply, when one did. */
+    failure?: string;
+    /** True when the journal was deliberately left on disk for a person. */
+    journalRetained: boolean;
+}
+export type CommitResult = {
+    ok: true;
+    outcome: CommitOutcome;
+} | {
+    ok: false;
+    code: "stage-failed";
+    message: string;
+};
+/**
+ * Stage, journal, apply, read back.
+ *
+ * The caller holds custody (and therefore the staging directory) and keeps it
+ * until this returns. A `stage-failed` result is the one result that guarantees
+ * the workspace is untouched by construction rather than by inspection: nothing
+ * visible has been attempted when it fires.
+ */
+export declare function commitWorkspacePlan(plan: WorkspacePlan, custody: WorkspaceCustody, options?: CommitOptions): CommitResult;
+export type RecoverResult = {
+    ok: true;
+    state: "none";
+    message: string;
+} | {
+    ok: true;
+    state: WorkspaceState;
+    inspection: WorkspaceInspection;
+    journal: WorkspaceCommitJournal;
+} | {
+    ok: false;
+    code: "journal-unreadable";
+    message: string;
+};
+/**
+ * Read a workspace's retained journal and say which of the three states it is
+ * in. It CHANGES NOTHING in the workspace.
+ *
+ * That is the whole contract, and the restraint is the point: a recovery that
+ * rolled a mixed workspace forward would be guessing which half of it the
+ * human approved, and a recovery that rolled one back would be deleting the
+ * half that already committed. Both are the runtime inventing a fact. A proven
+ * `before` or `after` needs no repair by definition, so there is nothing left
+ * for this function to do but say so and let the operator clear the staging
+ * directory.
+ */
+export declare function recoverWorkspaceCommit(root: string): RecoverResult;