@vibe-commit/capture 0.1.0

package/dist/spool.js

@@ -0,0 +1,556 @@
+/**
+ * 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 { appendFileSync, chmodSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { repoSessionsDir, sessionStatePath } from "./paths.js";
+/**
+ * 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 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 const SESSION_LIVE_WINDOW_MS = 30 * 60 * 1000;
+/**
+ * `<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 function spoolPath(home, key) {
+    const state = sessionStatePath(home, key);
+    if (state === null)
+        return null;
+    return state.replace(/\.json$/, ".spool.jsonl");
+}
+/**
+ * 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 function appendSpool(home, key, entry) {
+    const path = spoolPath(home, key);
+    if (path === null)
+        return false;
+    try {
+        mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+        appendFileSync(path, `${JSON.stringify(entry)}\n`, { mode: 0o600 });
+        chmodSync(path, 0o600);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * 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 function readSpool(home, key) {
+    const path = spoolPath(home, key);
+    if (path === null)
+        return [];
+    let raw;
+    try {
+        raw = readFileSync(path, "utf8");
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const line of raw.split("\n")) {
+        if (line.trim() === "")
+            continue;
+        const entry = parseEntry(line);
+        if (entry !== null)
+            out.push(entry);
+    }
+    return out;
+}
+/**
+ * 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 function dropSpooled(home, key, count) {
+    const path = spoolPath(home, key);
+    if (path === null || count <= 0)
+        return false;
+    try {
+        const lines = readFileSync(path, "utf8").split("\n").filter((l) => l.trim() !== "");
+        writeFileSync(path, lines.slice(count).map((l) => `${l}\n`).join(""), { mode: 0o600 });
+        chmodSync(path, 0o600);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * 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 function activeSessionFor(home, repoKey, envSessionId, nowMs = Date.now(), windowMs = SESSION_LIVE_WINDOW_MS) {
+    const live = liveSessions(home, repoKey, nowMs, windowMs);
+    // Rung 1 — the committing process told us, and a state file agrees.
+    if (envSessionId !== null && live.some((s) => s.sessionId === envSessionId)) {
+        return { sessionId: envSessionId, attribution: "env_session_id" };
+    }
+    // No candidate at all: nothing has captured this repo inside the window, so
+    // there is no bucket to record anything in. The refusal has to be silent here
+    // and only here.
+    if (live.length === 0)
+        return null;
+    // ⛔ THE NAMED REFUSAL, AND IT COMES BEFORE BOTH WRITE RUNGS. We were TOLD who
+    // committed, and it is none of these. Falling through would attribute the
+    // commit to a session we have positive evidence did not make it.
+    if (envSessionId !== null) {
+        return { sessionId: live[0].sessionId, attribution: "env_session_unmatched" };
+    }
+    // Rung 2 — D5. One session, nothing contradicting it.
+    if (live.length === 1) {
+        return { sessionId: live[0].sessionId, attribution: "sole_live_session" };
+    }
+    // ⛔ Rung 3 — the guess, and TWO OR MORE candidates is now structurally
+    // guaranteed here: every path with an env id returned above, and one candidate
+    // returned on the line before. `commit_attributions_ambiguity_is_plural`
+    // requires exactly that, and a cardinality-one row is refused 23514.
+    return { sessionId: live[0].sessionId, attribution: "recency_heuristic" };
+}
+/** Every session state file touched inside the window, most recent first. */
+function liveSessions(home, repoKey, nowMs, windowMs) {
+    const dir = repoSessionsDir(home, repoKey);
+    if (dir === null)
+        return [];
+    let entries;
+    try {
+        entries = readdirSync(dir);
+    }
+    catch {
+        // No directory at all: nothing has ever captured this repo.
+        return [];
+    }
+    const live = [];
+    for (const entry of entries) {
+        // ⚠ State files only. `.spool.jsonl` and `.rewrites.jsonl` live here too and
+        // are not sessions — and neither ends with `.json`, which is the same
+        // load-bearing spelling `spoolPath` documents.
+        if (!entry.endsWith(".json"))
+            continue;
+        let touchedAt;
+        try {
+            touchedAt = statSync(join(dir, entry)).mtimeMs;
+        }
+        catch {
+            continue;
+        }
+        if (nowMs - touchedAt > windowMs)
+            continue;
+        live.push({ sessionId: entry.slice(0, -".json".length), at: touchedAt });
+    }
+    // ⚠ Ties broken by name so the guess is at least DETERMINISTIC. Two state files
+    // written in the same millisecond is ordinary on a coarse-grained filesystem,
+    // and a rung that picked differently on each read would be unreproducible as
+    // well as wrong.
+    live.sort((a, b) => (b.at - a.at) || a.sessionId.localeCompare(b.sessionId));
+    return live;
+}
+/**
+ * ⛔ **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 const WIRE_RUNGS = ["env_session_id", "sole_live_session"];
+/**
+ * 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 function capSpool(entries) {
+    const taken = entries.slice(0, MAX_SPOOLED_SHAS);
+    const shas = [];
+    const attributions = [];
+    for (const entry of taken) {
+        if (!WIRE_RUNGS.includes(entry.attribution))
+            continue;
+        shas.push(entry.sha);
+        attributions.push(entry.attribution);
+    }
+    return { shas, attributions, count: taken.length };
+}
+/**
+ * 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 const MAX_SPOOLED_PAIRS = 16;
+/** `<repo>/<session>.rewrites.jsonl`, beside the commit spool. */
+export function rewriteSpoolPath(home, key) {
+    const state = sessionStatePath(home, key);
+    if (state === null)
+        return null;
+    return state.replace(/\.json$/, ".rewrites.jsonl");
+}
+/**
+ * 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 function appendRewrites(home, key, pairs) {
+    const path = rewriteSpoolPath(home, key);
+    if (path === null)
+        return 0;
+    const seen = new Set(readRewrites(home, key).map(wirePair));
+    let written = 0;
+    try {
+        mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+        for (const pair of pairs) {
+            const wire = wirePair(pair);
+            if (seen.has(wire))
+                continue;
+            seen.add(wire);
+            appendFileSync(path, `${JSON.stringify(pair)}\n`, { mode: 0o600 });
+            written += 1;
+        }
+        if (written > 0)
+            chmodSync(path, 0o600);
+        return written;
+    }
+    catch {
+        return written;
+    }
+}
+/** Every well-formed pair in the rewrite spool, oldest first. */
+export function readRewrites(home, key) {
+    const path = rewriteSpoolPath(home, key);
+    if (path === null)
+        return [];
+    let raw;
+    try {
+        raw = readFileSync(path, "utf8");
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const line of raw.split("\n")) {
+        if (line.trim() === "")
+            continue;
+        const pair = parsePair(line);
+        if (pair !== null)
+            out.push(pair);
+    }
+    return out;
+}
+/** Drop the first `count` pairs — called ONLY after the server's 2xx. */
+export function dropRewrites(home, key, count) {
+    const path = rewriteSpoolPath(home, key);
+    if (path === null || count <= 0)
+        return false;
+    try {
+        const lines = readFileSync(path, "utf8").split("\n").filter((l) => l.trim() !== "");
+        writeFileSync(path, lines.slice(count).map((l) => `${l}\n`).join(""), { mode: 0o600 });
+        chmodSync(path, 0o600);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * 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 function capSuccessors(pairs) {
+    const taken = pairs.slice(0, MAX_SPOOLED_PAIRS);
+    return { pairs: taken.map(wirePair), count: taken.length };
+}
+/** The wire spelling of one pair. Also the dedup key. */
+function wirePair(pair) {
+    return `${pair.ancestor}:${pair.successor}`;
+}
+function parsePair(line) {
+    let parsed;
+    try {
+        parsed = JSON.parse(line);
+    }
+    catch {
+        return null;
+    }
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed))
+        return null;
+    const o = parsed;
+    const { ancestor, successor } = o;
+    // ⛔ Re-validated on the way OUT as well as in. A spool file is on disk and
+    // outlives the process that wrote it, so what comes back is input.
+    if (!isFullSha(ancestor) || !isFullSha(successor))
+        return null;
+    // ⚠ A self-pair is dropped by the server anyway; dropping it here keeps a
+    // no-op from occupying one of the 16 slots a real pair needs.
+    if (ancestor === successor)
+        return null;
+    return { ancestor, successor };
+}
+/** Full width, both widths git uses. ⛔ Never abbreviated. */
+export function isFullSha(value) {
+    return typeof value === "string" && /^[0-9a-f]{40}$|^[0-9a-f]{64}$/.test(value);
+}
+function parseEntry(line) {
+    let parsed;
+    try {
+        parsed = JSON.parse(line);
+    }
+    catch {
+        return null;
+    }
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed))
+        return null;
+    const o = parsed;
+    const sha = o.sha;
+    // ⛔ The width check lives here as well as at the boundary: a spool file is
+    // on disk and outlives the process that wrote it, so what comes back out is
+    // input, not something we already validated.
+    if (!isFullSha(sha))
+        return null;
+    const at = typeof o.at === "string" ? o.at : "";
+    const branch = typeof o.branch === "string" && o.branch !== "" ? o.branch : null;
+    const files = Array.isArray(o.files) ? o.files.filter((f) => typeof f === "string") : [];
+    return { sha, branch, at, files, attribution: parseRung(o.attribution) };
+}
+/**
+ * ⛔ **AN UNLABELLED LINE IS `recency_heuristic`, AND THAT IS NOT A DEFAULT — IT
+ * IS THE CORRECT NAME FOR HOW IT WAS PRODUCED.**
+ *
+ * A spool file outlives the process that wrote it and survives an upgrade, so a
+ * line written by a PRE-LADDER client is ordinary input here. That client picked
+ * its session by mtime recency, with no corroboration and no way to tell one
+ * candidate from two. Naming it anything else would upgrade a guess to an
+ * observation on the strength of a version number.
+ *
+ * ⚠ **This is `D190 §2`'s NO RUNG, NO EDGE, on the client side.** The server
+ * refuses to write an edge for a commit that arrives without a rung, for exactly
+ * this reason; here the same commit is refused a place on `x-commits` before it
+ * is ever sent. Both directions of the seam agree, independently.
+ */
+function parseRung(value) {
+    switch (value) {
+        case "env_session_id":
+        case "sole_live_session":
+        case "env_session_unmatched":
+            return value;
+        default:
+            // ⛔ INCLUDING an unlabelled line and a rung outside the vocabulary. A
+            // near-miss spelling is NOT admitted: the server skips an unknown rung
+            // silently, which is a zero with no error, so it is resolved here to the
+            // value that says *we do not know*.
+            return "recency_heuristic";
+    }
+}
+//# sourceMappingURL=spool.js.map

package/dist/spool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"spool.js","sourceRoot":"","sources":["../src/spool.ts"],"names":[],"mappings":"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"}