@vibe-commit/capture 0.1.0

package/dist/spool.d.ts

@@ -0,0 +1,390 @@
+/**
+ * The commit spool — where `post-commit` leaves what it OBSERVED, for the next
+ * Claude Code hook to deliver (`CR-170`, D154).
+ *
+ * ## Why a spool at all, rather than sending from `post-commit`
+ *
+ * `post-commit` runs inside `git commit`. A network call there would put our
+ * latency on the user's own commit, and a failure would surface as noise in a
+ * command that has nothing to do with us. So the commit hook does the one thing
+ * only it can do — witness the commit — and writes a line. Delivery stays on the
+ * hook path that already has a credential, a budget and a retry story.
+ *
+ * ## ⛔ APPEND, THEN TRUNCATE ON 2xx — NEVER READ-AND-DELETE
+ *
+ * A send that fails must leave the commit in the spool so the NEXT hook retries
+ * it. Deleting on read would lose a commit to a single 500, permanently, and
+ * `capture_commits` rows cannot be retracted (D105/D108). So the truncation is
+ * the LAST step and it is conditional on the server's 2xx.
+ *
+ * ## ⛔ THE SESSION GATE IS ABOUT WHICH SESSION, NOT ABOUT WHO TYPED IT
+ *
+ * ⚠ **This block used to say the gate is what keeps a HUMAN'S commits out. That
+ * has been FALSE since `CR-170` shipped** — `activeSessionFor` has never
+ * inspected authorship, and `post_commit.ts` says three lines below its own copy
+ * of the claim that the hook *"fires for every commit in this work tree,
+ * including ones no agent was involved in."* Corrected as a comment fix; no
+ * behaviour moved with it (`D5`).
+ *
+ * What the gate actually asks is whether a capture session is demonstrably live
+ * for this repo, and — since the ladder below — **WHICH ONE**. A line is written
+ * only when that question has an answer, and the answer carries the rung that
+ * produced it so the server can tell an observation from a guess.
+ *
+ * ## The line is deliberately small, and the file list stays here
+ *
+ * `{sha, branch, at, files}`. Only the SHA reaches the wire in wave 1 (`CR-170`
+ * §4): commit messages were MEASURED at 9/20, 8/20 and 5/20 commits over 4096
+ * bytes across the three repos, largest 12,112, so a quarter of real commits
+ * would land permanently truncated in a header. Metadata is backfillable from
+ * the sha; the observation is not. `files` is carried for wave 2 and never put
+ * in a header.
+ */
+import { type SessionKey } from "./paths.js";
+/**
+ * ⛔ **WHICH RUNG OF THE LADDER ANSWERED — the difference between an observation,
+ * a guess, and a refusal (`D190`).**
+ *
+ * Two of these four may reach the wire. The other two may not, and the asymmetry
+ * is the whole point:
+ *
+ *   - `env_session_id` — the committing process told us, `M1`. An OBSERVATION.
+ *   - `sole_live_session` — one session is live in this clone and nothing
+ *     contradicts it. Weaker, but unambiguous.
+ *   - ⛔ `recency_heuristic` — **two or more candidates and nothing to choose
+ *     between them.** The pre-ladder answer, and the defect this wave exists to
+ *     close: `cr071:157` makes a wrong edge PERMANENT, UPDATE and DELETE both
+ *     raise, `service_role` included. **HELD, never sent.**
+ *   - ⛔ `env_session_unmatched` — **the committing process named a session, and
+ *     no live session here is it.** A REFUSAL, and a different one from *"no
+ *     session is live at all"*. **Never sent, and never a `commit_attributions`
+ *     row either.**
+ *
+ * ## ⛔ WHY THE LAST TWO ARE NOT ONE VALUE, AND IT IS STRUCTURAL
+ *
+ * The first draft of this ladder called the unmatched-env case
+ * `recency_heuristic`, and that is **wrong by a server constraint this repository
+ * cannot see**: `commit_attributions_ambiguity_is_plural` requires
+ * `cardinality(candidate_session_ids) >= 2`, so a `recency_heuristic` row naming
+ * ONE candidate is refused **23514**.
+ *
+ * ⛔ **CITED TO `D197 §3`, WHICH IS WHERE THAT ARGUMENT LIVES IN FULL** — including
+ * the constraint's own comment, verbatim: *"ONE live candidate is the
+ * `sole_live_session` rung and writes an edge, ZERO is the refusal that writes
+ * nothing anywhere. A writer that mis-walks the ladder gets a 23514 rather than a
+ * hold nobody can resolve."*
+ *
+ * ⚠ **I have NOT read the constraint in the closed schema**, so it is cited to a
+ * decision entry anyone here can open rather than characterised from a repository
+ * this package must not depend on (`feedback_characterization_is_not_citation`).
+ *
+ * ⛔ **And citing the DECISION rather than the sibling repo is deliberate, not
+ * cosmetic.** `test/provenance.test.ts` reads a sibling-repo name in `src/` as an
+ * undeclared closed-core reference, and a new declaration is a LICENSING REVIEW
+ * EVENT (D60 §D1a) requiring a human in the PR body. Nothing here was retyped out
+ * of closed source, so a declaration would assert a reading that did not happen —
+ * and pointing at `D197 §3` removes the event instead of adding one.
+ *
+ * ⚠ Both of that guard's tripwires fired on the prose of this docblock while it
+ * was being written — the repo name, and then the marker tag's own literal name
+ * inside a sentence disclaiming it. ⛔ A grep over a repo name cannot tell a
+ * citation from a disclaimer (`feedback_gate_on_the_phrase_not_the_token`); the
+ * wording moved and the guards were left alone.
+ *
+ * ⛔ And the old ladder really could produce that row: an unmatched env id with
+ * **exactly one** live candidate fell through to `recency_heuristic`, cardinality
+ * one. ⚠ Not reachable from this client TODAY — no held commit is ever
+ * transmitted — so this is a defect in the VOCABULARY rather than a live 23514.
+ * It would have become one the moment a later wave sent held rows, which is
+ * precisely when nobody would be looking at this file.
+ *
+ * ⚠ **The two also differ in meaning, not just in cardinality.**
+ * `recency_heuristic` says *we could not tell which of several*;
+ * `env_session_unmatched` says *we were told, and the answer names nobody here*.
+ * The second is the more certain statement of the two, and collapsing it into the
+ * first records a doubt we do not have.
+ *
+ * ⚠ **The wire vocabulary is the first two** — `WIRE_RUNGS`, below, and `capSpool`
+ * is where the other two stop.
+ */
+export type AttributionRung = "env_session_id" | "sole_live_session" | "recency_heuristic" | "env_session_unmatched";
+/** One observed commit. */
+export interface SpoolEntry {
+    /** Full 40- or 64-hex. ⛔ Never abbreviated — see `capSpool`. */
+    readonly sha: string;
+    /** Null on a detached HEAD. */
+    readonly branch: string | null;
+    /** ISO-8601, from git's own `%cI`. */
+    readonly at: string;
+    /** Paths touched. Wave 2. ⛔ Never a header. */
+    readonly files: readonly string[];
+    /**
+     * ⛔ **HOW THE SESSION ON THIS LINE WAS DECIDED.** Recorded at OBSERVATION
+     * time, because the evidence is gone by the time the next hook fires: the env
+     * variable belonged to the committing process, and the mtimes have moved on.
+     */
+    readonly attribution: AttributionRung;
+}
+/**
+ * How many SHAs one hook may put on the wire.
+ *
+ * A header has a practical size bound and the server pins its own; 40 hex plus a
+ * separator is 41 bytes, so 32 is ~1.3 KB and comfortably inside any of them.
+ * ⛔ **The rest stay spooled** rather than being dropped — a burst of commits is
+ * delivered across several hooks, and hooks are frequent.
+ */
+export declare const MAX_SPOOLED_SHAS = 32;
+/**
+ * A session is "live" for this repo if its state file was touched inside this
+ * window.
+ *
+ * ⚠ **A JUDGEMENT CALL, AND IT IS THE ONE KNOB IN THIS MODULE.** The Claude Code
+ * hook writes session state on every fire, so during active work this file is
+ * touched every turn. Too short and a long turn's commit is missed; too long and
+ * a human's commit hours later is attributed to a session that is morally over.
+ *
+ * The asymmetry decides it, the same way it did in `spawn_budget.ts`: a MISSED
+ * commit is recoverable — the sha is still in git and wave 2 can backfill it —
+ * while a WRONGLY ATTRIBUTED commit is a permanent row linking work to a session
+ * that did not do it. So this is sized to the length of a plausible single turn,
+ * not to the length of a working day.
+ */
+export declare const SESSION_LIVE_WINDOW_MS: number;
+/**
+ * `<repo>/<session>.spool.jsonl`, beside the session's state file.
+ *
+ * ⚠ **`.jsonl`, NOT `.json`, and that is load-bearing.** `lastSendForRepo`
+ * scans this same directory and filters on `entry.endsWith(".json")`; a spool
+ * named `.json` would be parsed as session state, fail, and silently degrade
+ * every `vibecommit status` for the repo. Checked rather than assumed — there is
+ * a test for exactly that.
+ *
+ * Null on no repo identity, for the reason `sessionStatePath` is: there is no
+ * repo-less bucket and a placeholder key is a cross-repo bleed with an extra step.
+ */
+export declare function spoolPath(home: string, key: SessionKey): string | null;
+/**
+ * Append one observed commit. Returns false on any failure.
+ *
+ * ⛔ **NEVER THROWS.** This runs inside `git commit`: an exception here would
+ * surface as a failed hook on the user's own commit, which is exactly the noise
+ * `post-commit` must not create. A dropped line is strictly better.
+ *
+ * `appendFileSync` with `a` is a single positioned write, so two commits racing
+ * in one repo interleave whole lines rather than corrupting each other.
+ */
+export declare function appendSpool(home: string, key: SessionKey, entry: SpoolEntry): boolean;
+/**
+ * Every well-formed entry in the spool, oldest first.
+ *
+ * A malformed line is SKIPPED rather than fatal: the file is appended to by a
+ * different process than reads it, so a torn final line is a real possibility
+ * and losing one observation beats losing the whole spool.
+ */
+export declare function readSpool(home: string, key: SessionKey): SpoolEntry[];
+/**
+ * Drop the first `count` entries — called ONLY after the server's 2xx.
+ *
+ * ⚠ **RE-READS BEFORE REWRITING, and that is not defensive tidiness.**
+ * `post-commit` may have appended while the send was in flight. Slicing the
+ * array we read BEFORE the send would rewrite the file without those lines and
+ * lose them silently. Appends only ever go to the END, so the first `count`
+ * lines are still the same ones we delivered, and dropping exactly that many is
+ * correct against the current file rather than against a stale snapshot.
+ *
+ * ⚠ **A residual race remains and is accepted:** a commit landing between this
+ * re-read and the write is lost. The window is one `readFileSync` plus one
+ * `writeFileSync` on a small file, the cost is one un-delivered commit row, and
+ * closing it properly means a lock file on a path that must never block
+ * (`post-commit` runs inside the user's `git commit`). Recorded rather than
+ * hidden.
+ */
+export declare function dropSpooled(home: string, key: SessionKey, count: number): boolean;
+/** Which session answered, and which rung answered it. */
+export interface ActiveSession {
+    readonly sessionId: string;
+    readonly attribution: AttributionRung;
+}
+/**
+ * Which session, if any, is live for this repo right now — ⛔ **AND HOW WE KNOW.**
+ *
+ * ## The defect this replaces
+ *
+ * Until the ladder, this function returned *the most recently mtime'd state file
+ * within 30 minutes* and said nothing about its own confidence. Two agents in one
+ * clone: session A commits, B's state file is newer, **A's commit enters B's
+ * spool** — and `cr071:157` makes the resulting edge PERMANENT, with UPDATE and
+ * DELETE both raising for `service_role` too. A wrong edge is forever, so the
+ * guess had to stop being indistinguishable from the answer.
+ *
+ * ## The ladder
+ *
+ * ```
+ *  env id names a live session ─────────> env_session_id         WRITE
+ *  no live session at all ──────────────> null                   REFUSE (no row)
+ *  env id names NONE of them ───────────> env_session_unmatched  REFUSE (named)
+ *  exactly ONE candidate ───────────────> sole_live_session      WRITE  (D5)
+ *  TWO OR MORE candidates ──────────────> recency_heuristic      HOLD
+ * ```
+ *
+ * ⛔ **`sole_live_session` ALWAYS WRITES, and that is not a change.** It never
+ * inspected authorship and does not start now: a human's `git commit` in a clone
+ * with one live session produces a spool line today, at HEAD, and
+ * `test/post-commit-spool.test.ts` has a green arm asserting exactly that. What
+ * is new is that the server will write a PERMANENT row off this rung, so the rung
+ * has to be named on the wire (`D190`).
+ *
+ * ## ⛔ `env_session_unmatched` — THE THIRD ARM, AND IT IS A REFUSAL WITH A NAME
+ *
+ * An env id that names **none** of the live candidates is a shape the plan's
+ * ladder does not draw, and the code must answer it. It is REAL rather than
+ * hypothetical: `agents/registry.ts:11-13` rejects an environment variable as the
+ * agent selector precisely because **Codex exports `CLAUDE_PLUGIN_ROOT` itself**,
+ * so a Codex agent running under an outer Claude session carries a
+ * `CLAUDE_CODE_SESSION_ID` that corroborates nothing here.
+ *
+ *   - ⛔ `sole_live_session` there would name a session we have POSITIVE evidence
+ *     did not commit — the permanent wrong edge, arrived at from the other
+ *     direction. Never.
+ *   - ⛔ `recency_heuristic` is what this ladder used first, and it is wrong for
+ *     the reason `AttributionRung` records: cardinality one, refused **23514**,
+ *     and a doubt we do not actually have.
+ *   - ⛔ **A silent refusal is worse than either in one respect** — nobody can
+ *     afterwards ask *why did that commit vanish*. That is the failure class this
+ *     whole wave exists to close, so the refusal is RECORDED and NAMED.
+ *
+ * ⚠ **The line goes in the recency winner's spool bucket, because that is the
+ * only bucket that exists** — an uncorroborated env id deliberately does not open
+ * one of its own. The bucket is a FILE LOCATION and the rung is the attribution:
+ * the line says, in terms, *this commit is attributed to nobody, and here is
+ * why*. It never reaches `x-commits` and never becomes a `commit_attributions`
+ * row.
+ *
+ * ⚠ **So `recency_heuristic` is reachable ONLY with two or more candidates**,
+ * which is what `commit_attributions_ambiguity_is_plural` demands. That is a
+ * property of the ladder's SHAPE now rather than of a caller's care, and
+ * `test/post-commit-spool.test.ts` asserts it directly.
+ *
+ * ⚠ **A commit made before a session's FIRST hook has fired is still NOT
+ * captured**, because the state file it would key on does not exist yet. The env
+ * id could key a bucket that has no state file, and deliberately does not: the
+ * ladder's first rung requires CORROBORATION, so a stale or inherited variable
+ * cannot open a spool of its own.
+ *
+ * `envSessionId` is a PARAMETER rather than a read of `process.env` here, and it
+ * has no default: the compiler is the only thing that will notice a caller which
+ * forgot the env path, and this seam has no other check.
+ */
+export declare function activeSessionFor(home: string, repoKey: string, envSessionId: string | null, nowMs?: number, windowMs?: number): ActiveSession | null;
+/**
+ * ⛔ **THE TWO RUNGS THAT MAY GO ON `x-commit-attributions` (`D190`).**
+ *
+ * The server's vocabulary is exactly these two (`edge_derivation.ts:178`) and a
+ * rung outside it is **skipped silently** — no edge, no error, no log. So the
+ * refusal lives here, on the producing side, rather than being discovered as a
+ * zero where edges should have been.
+ *
+ * ⚠ **This constant is NOT what the wire cell asserts against.** There is no
+ * shared type across that seam and inventing one would couple an MIT client to a
+ * closed server, so the cell types the literals itself — round-tripping this
+ * constant through our own code would only prove it equals itself (`D190 §5`).
+ */
+export declare const WIRE_RUNGS: readonly AttributionRung[];
+/** What one hook may put on the wire, and how many spool LINES that consumed. */
+export interface Observed {
+    /** ⛔ Same length as `attributions`, same order. Wire rungs only. */
+    readonly shas: readonly string[];
+    /** ⛔ Same length as `shas`, same order. Wire rungs only. */
+    readonly attributions: readonly AttributionRung[];
+    /** Spool lines consumed — ⛔ **held ones INCLUDED, so they drain.** */
+    readonly count: number;
+}
+/**
+ * The SHAs this hook will carry, their rungs, and how many lines to drop after a
+ * 2xx.
+ *
+ * ⛔ **FULL WIDTH, ALWAYS.** `capture_commits.commit_sha` is 7..40 because the
+ * server's `expandShortSha` can fail, so an abbreviated sha makes the web join
+ * SILENTLY EMPTY — a wrong answer with no error, D98's class exactly. Anything
+ * that is not a full sha is dropped by `parseEntry` rather than sent.
+ *
+ * ⛔ **`shas` AND `attributions` ARE THE SAME LENGTH BY CONSTRUCTION** — one
+ * `push` each, in one iteration, or neither. That is not style.
+ * `parseObservedCommits` returns `[]` when the two lists differ in length: **the
+ * ENTIRE BATCH is dropped, not the odd entry**, with no edge, no error and no
+ * log (`D190 §1`). A `filter` and a `map` over the same array would be the same
+ * thing until someone changed one of them.
+ *
+ * ⛔ **`count` IS LINES CONSUMED, NOT `shas.length`, AND THEY DIVERGE.** A held
+ * entry is consumed and never sent. `dropSpooled` drops **the first N lines**, so
+ * a caller truncating by `shas.length` would delete a held line at the head and
+ * re-send the commit that was actually delivered — forever.
+ *
+ * ⚠ **A held entry IS dropped on the 2xx, and the observation is lost.** Stated
+ * rather than hidden: this wave gives the client no way to transmit a held
+ * commit, and leaving it in the file would make every subsequent hook re-read a
+ * line that can never be sent. The asymmetry this module already runs on decides
+ * it — a MISSED commit is recoverable, the sha is still in git, while a WRONGLY
+ * ATTRIBUTED one is a permanent row (`cr071:157`).
+ */
+export declare function capSpool(entries: readonly SpoolEntry[]): Observed;
+/** One rewrite: the sha that was destroyed, and the one that replaced it. */
+export interface RewritePair {
+    readonly ancestor: string;
+    readonly successor: string;
+}
+/**
+ * How many rewrite pairs one hook may put on the wire.
+ *
+ * ⛔ **ITS OWN CONSTANT, AND SHARING `MAX_SPOOLED_SHAS` WOULD MAKE ONE OF THE TWO
+ * WRONG.** The units differ: a sha plus a separator is 41 bytes, a pair plus a
+ * separator is **82** (40 + `:` + 40 + `,`). 16 pairs is 1,312 bytes — the same
+ * header budget `MAX_SPOOLED_SHAS = 32` was sized against, arrived at through the
+ * arithmetic of this header rather than inherited from the other one.
+ *
+ * ⛔ **The rest stay spooled**, exactly as the commit spool's remainder does.
+ */
+export declare const MAX_SPOOLED_PAIRS = 16;
+/** `<repo>/<session>.rewrites.jsonl`, beside the commit spool. */
+export declare function rewriteSpoolPath(home: string, key: SessionKey): string | null;
+/**
+ * Append rewrite pairs, skipping any already spooled. Returns how many were
+ * WRITTEN — ⛔ not how many were offered.
+ *
+ * ## ⛔ THE DEDUP IS ONE OF T4'S TWO GUARDS, AND IT IS NOT REDUNDANCY
+ *
+ * `M6` measured the squash hazard and it is **SIZE-DEPENDENT**. A 3→1 squash
+ * fires `post-rewrite` twice — `amend A→F`, then `rebase A→F; B→F` — so **the
+ * pair `A→F` arrives twice**. A 4→1 squash instead produces rows naming an
+ * INTERMEDIATE sha that never existed on any branch; that one is killed by the
+ * in-progress-rebase suppression in `hooks/post_rewrite.ts`, which cannot see the
+ * duplicate, exactly as this cannot see the intermediate. **One squash size
+ * cannot test both.**
+ *
+ * ⚠ **Dedup is against the FILE, not against the batch**, because the two fires
+ * are two processes: a batch-local check would see one pair each time and dedup
+ * nothing. ⚠ The read-then-append is not atomic — two rewrites racing in one
+ * clone could both miss — but `post-rewrite` runs inside git's own serialised
+ * rebase, and the cost of the residual race is one duplicate pair rather than a
+ * wrong one.
+ *
+ * ⛔ **NEVER THROWS.** This runs inside the user's `git rebase`.
+ */
+export declare function appendRewrites(home: string, key: SessionKey, pairs: readonly RewritePair[]): number;
+/** Every well-formed pair in the rewrite spool, oldest first. */
+export declare function readRewrites(home: string, key: SessionKey): RewritePair[];
+/** Drop the first `count` pairs — called ONLY after the server's 2xx. */
+export declare function dropRewrites(home: string, key: SessionKey, count: number): boolean;
+/**
+ * The pairs this hook will carry, and how many to drop after a 2xx.
+ *
+ * ⛔ **`ancestor:successor`, COLON-SEPARATED.** `parseRewritePairs` drops
+ * silently on a wrong separator, on a third colon-field, on a bad sha and on a
+ * self-pair — no edge, no error, no log (`D190 §1`).
+ */
+export declare function capSuccessors(pairs: readonly RewritePair[]): {
+    pairs: string[];
+    count: number;
+};
+/** Full width, both widths git uses. ⛔ Never abbreviated. */
+export declare function isFullSha(value: unknown): value is string;