@vibe-commit/capture 0.1.0

package/dist/policy.js

@@ -0,0 +1,244 @@
+/**
+ * The failure policy — CR-018, D58 (plan §ER22/§ER10/§ER11/§ER4).
+ *
+ * The defect this replaces, verbatim from the register: *"5xx was unclassified
+ * and fell through to advance-and-discard; 401/413 never succeed."* Every failed
+ * POST used to reach the same code, so the offset moved forward as if the bytes
+ * had been delivered. They had not.
+ *
+ * ## Three classes, and why `never` and `fatal` are not the same class
+ *
+ *   later   Hold the offset. The NEXT hook invocation retries from the same
+ *           point. Transient: 5xx, no-response, 429, and 403 — a 403 here is
+ *           org-approval-pending, which means later, not failed (D60 §D12).
+ *   never   Advance PAST the failing bytes and stamp a gap, so the record shows
+ *           an honest hole instead of pretending nothing happened. Per-PAYLOAD:
+ *           resending the identical bytes cannot work (413, structurally
+ *           malformed 4xx).
+ *   fatal   Stop attempting further sends for this session until the user
+ *           reconnects. Per-CREDENTIAL, which is the whole difference from
+ *           `never`: 401 does not describe these bytes, it describes the token.
+ *
+ * **`later` never means a synchronous retry inside one hook invocation.** D56
+ * plan §D8 is a founder override that is not to be re-argued: the hook must never
+ * block or slow a developer's turn. "Later" means the bytes stay in the
+ * transcript file — which is where they already are — and the hook that fires on
+ * the next turn picks them up from the same offset.
+ *
+ * ## The table is data on purpose
+ *
+ * The title's word "table" is load-bearing. The classification is a literal data
+ * structure, so it is auditable by reading it and testable without exercising a
+ * real network failure. The original bug was an UNCLASSIFIED status silently
+ * defaulting to lossy behaviour, so the default here is explicit and it is
+ * `later` — the safe direction. A status nobody enumerated holds its bytes; it
+ * never discards them.
+ *
+ * This module is PURE. No fs, no network, no clock — `state.ts` persists, and the
+ * caller supplies `nowMs`. That is what lets both backlog caps be tested at their
+ * boundaries without waiting a day for one of them.
+ */
+import { ERRORS } from "./copy/index.js";
+/**
+ * THE TABLE. Status codes named one by one, because a family rule that swept up
+ * a whole `4xx` would be the implicit fallthrough this task exists to remove.
+ *
+ * Adding a row is how a new structurally-invalid status becomes `never`. Until
+ * someone does, an unnamed `4xx` resolves to `DEFAULT_CLASS` and HOLDS its bytes:
+ * a status we have not reasoned about is not one we discard data for.
+ */
+export const STATUS_CLASSES = new Map([
+    // Structurally malformed request. Identical bytes will be rejected identically.
+    [400, "never"],
+    // The credential, not the payload. Terminal until the user reconnects.
+    [401, "fatal"],
+    // Org approval pending (D60 §D12). Capture has not stopped; it is waiting.
+    [403, "later"],
+    // Payload too large. Retrying the same bytes cannot work.
+    [413, "never"],
+    // Rate limited. The definition of transient.
+    [429, "later"],
+]);
+/** `5xx` — the server's problem, not the payload's. */
+export const SERVER_ERROR_CLASS = "later";
+/** No HTTP response at all: DNS, refused, TLS, timeout, abort. */
+export const NETWORK_CLASS = "later";
+/**
+ * The explicit default. **It is `later` and it must stay `later`.** An implicit
+ * fallthrough to advance-and-discard is the original defect at a smaller scale.
+ */
+export const DEFAULT_CLASS = "later";
+/** Classify one HTTP status. `2xx` is the only success. */
+export function classifyStatus(status) {
+    if (status >= 200 && status < 300)
+        return "ok";
+    const named = STATUS_CLASSES.get(status);
+    if (named !== undefined)
+        return named;
+    if (status >= 500 && status < 600)
+        return SERVER_ERROR_CLASS;
+    return DEFAULT_CLASS;
+}
+/** Classify one attempt, response or not. */
+export function classify(outcome) {
+    return outcome.kind === "unreachable" ? NETWORK_CLASS : classifyStatus(outcome.status);
+}
+/**
+ * The §13.6 copy for a class.
+ *
+ * `ERRORS` was scaffolded for this task and carries exactly these three lines, so
+ * this is the one place a class becomes a sentence. Nothing in the HOOK path
+ * calls it — a hook speaks only through `systemMessage` (§13.7) — but `CR-021`'s
+ * `status` needs a class-to-copy mapping and this is where it belongs rather than
+ * as a fourth `switch` in a verb body.
+ */
+export function failureCopy(cls) {
+    switch (cls) {
+        case "later":
+            return ERRORS.networkLater;
+        case "never":
+            return ERRORS.payloadNever;
+        case "fatal":
+            return ERRORS.authFatal;
+    }
+}
+export const EMPTY_FILE_STATE = {
+    sentOffset: 0,
+    backlog: [],
+    gapBytes: 0,
+    gapCount: 0,
+    lastSentAt: 0,
+};
+/**
+ * The caps.
+ *
+ * ⚠ **Neither the register nor `DECISIONS.md` specifies an eviction policy once a
+ * cap is hit.** What is decided is only that both caps exist. The rule below is
+ * this task's choice, stated rather than smuggled: **drop the oldest span,
+ * advance past it, stamp a gap, continue.** It is the `never` class's own shape
+ * applied to our own storage, and it is the only option that neither grows
+ * unbounded nor blocks — the two things D56 §D8 forbids outright.
+ *
+ * `entries` is not a third policy. It is the same drop-oldest rule guarding the
+ * degenerate shape where a file grows one byte at a time: the byte cap alone
+ * would permit `MAX_BACKLOG_BYTES` single-byte entries.
+ */
+export const BACKLOG_CAPS = {
+    bytes: 8 * 1024 * 1024,
+    ageMs: 24 * 60 * 60 * 1000,
+    entries: 512,
+};
+/**
+ * Read the caps from the environment.
+ *
+ * Same shape as `hookBudgetMs`: an unset or unparseable value takes the default
+ * rather than disabling the cap, because a cap that an empty string can switch
+ * off is not a cap. Present for operators with unusual transcript volumes and
+ * for the tests, which have to reach a boundary they cannot otherwise reach.
+ */
+export function resolveCaps(env) {
+    return {
+        bytes: positiveOr(env.VIBECOMMIT_BACKLOG_MAX_BYTES, BACKLOG_CAPS.bytes),
+        ageMs: positiveOr(env.VIBECOMMIT_BACKLOG_MAX_AGE_MS, BACKLOG_CAPS.ageMs),
+        entries: positiveOr(env.VIBECOMMIT_BACKLOG_MAX_ENTRIES, BACKLOG_CAPS.entries),
+    };
+}
+function positiveOr(raw, fallback) {
+    if (raw === undefined)
+        return fallback;
+    const parsed = Number(raw);
+    return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
+}
+/** Undelivered bytes currently held. */
+export function pendingBytes(state) {
+    if (state.backlog.length === 0)
+        return 0;
+    return state.backlog[state.backlog.length - 1].to - state.backlog[0].from;
+}
+/**
+ * The span the next attempt should carry: everything from the offset to `eof`.
+ *
+ * A file SHORTER than the offset means the transcript was replaced or truncated —
+ * a new file at a path we have state for. Resync from 0 rather than reading a
+ * negative-length slice; the server is idempotent on `(session, offset)`.
+ */
+export function nextSpan(state, eof) {
+    const from = state.sentOffset > eof ? 0 : state.sentOffset;
+    return eof > from ? { from, to: eof } : null;
+}
+/**
+ * Everything up to `to` arrived. The backlog clears, and the success is STAMPED.
+ *
+ * `nowMs` is a parameter rather than a `Date.now()` call because this module is
+ * pure — that is what lets both backlog caps be tested at their boundaries
+ * without waiting a day, and the same property now covers the `last sent` row.
+ */
+export function markDelivered(state, to, nowMs) {
+    return { ...state, sentOffset: to, backlog: [], lastSentAt: nowMs };
+}
+/**
+ * `never` — advance PAST the attempted span exactly once, stamping a gap.
+ *
+ * Exactly once is the point: the offset lands at `to`, so the next invocation
+ * starts on the next, unrelated chunk. It neither loops on the poisoned bytes nor
+ * swallows what comes after them.
+ */
+export function markSkipped(state, from, to) {
+    const skipped = Math.max(0, to - from);
+    return {
+        // `lastSentAt` is carried, not cleared: skipping past bytes that could never
+        // be delivered does not un-deliver what already was.
+        lastSentAt: state.lastSentAt,
+        sentOffset: to,
+        backlog: [],
+        gapBytes: state.gapBytes + skipped,
+        gapCount: state.gapCount + (skipped > 0 ? 1 : 0),
+    };
+}
+/**
+ * `later` — hold the offset and remember when this span first failed.
+ *
+ * The span is appended only when the file has actually grown past what is already
+ * held. A hook that fires twice on an unchanged file retries the same span rather
+ * than minting a second entry with a newer timestamp, which would keep resetting
+ * the age cap and make it unreachable.
+ */
+export function markHeld(state, span, nowMs, caps) {
+    const base = state.sentOffset === span.from
+        ? state
+        : // The offset moved under us (a resync). Start the backlog over from here.
+            { ...state, sentOffset: span.from, backlog: [] };
+    const last = base.backlog[base.backlog.length - 1];
+    const heldTo = last?.to ?? base.sentOffset;
+    const backlog = span.to > heldTo
+        ? [...base.backlog, { from: heldTo, to: span.to, at: nowMs }]
+        : base.backlog;
+    return enforceCaps({ ...base, backlog }, nowMs, caps);
+}
+/**
+ * Shed the oldest spans until every cap holds.
+ *
+ * Never blocks, never grows. Each shed span advances the offset past itself and
+ * stamps a gap, so what the server sees is a discontinuity in `byteOffset` — an
+ * honest hole — and not a silent renumbering.
+ */
+export function enforceCaps(state, nowMs, caps) {
+    let sentOffset = state.sentOffset;
+    let backlog = state.backlog;
+    let gapBytes = state.gapBytes;
+    let gapCount = state.gapCount;
+    while (backlog.length > 0) {
+        const oldest = backlog[0];
+        const overBytes = backlog[backlog.length - 1].to - backlog[0].from > caps.bytes;
+        const overAge = nowMs - oldest.at > caps.ageMs;
+        const overEntries = backlog.length > caps.entries;
+        if (!overBytes && !overAge && !overEntries)
+            break;
+        sentOffset = oldest.to;
+        gapBytes += oldest.to - oldest.from;
+        gapCount += 1;
+        backlog = backlog.slice(1);
+    }
+    return { sentOffset, backlog, gapBytes, gapCount, lastSentAt: state.lastSentAt };
+}
+//# sourceMappingURL=policy.js.map

package/dist/policy.js.map

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

package/dist/post.d.ts

@@ -0,0 +1,302 @@
+/**
+ * The ingest request — the ONE place the credential's plaintext is used.
+ *
+ * `send()` still makes exactly one attempt and decides nothing; `deliver()`, at
+ * the bottom of this file, is `CR-018`'s application of the failure policy around
+ * it. The classification itself is data in `policy.ts` and the ledger is in
+ * `state.ts`, so what lives here is only the wiring between them and the wire.
+ *
+ * `X-Repo-Slug` is derived in `git.ts` (`CR-019d`) and arrives here already
+ * resolved. It is REQUIRED on the wire: the merged server 400s a request without
+ * it, deliberately, because a NULL `repository_id` is fail-closed-INVISIBLE
+ * rather than merely wrong (D57 §OV1).
+ *
+ * Wire shape retyped from the plan and from reading the closed-source server. No
+ * code is imported or copied from `vibecommit-mcp` (D60 §D1a): this package is
+ * MIT, and lifting closed code into it relicenses that code by accident.
+ *
+ * @provenance vibecommit-mcp src/conversation/ingest_session.ts — wire shape, retyped
+ */
+import { type SelectedAgentId } from "./agents/types.js";
+import type { IngestCredential } from "./credential.js";
+import { type Disposition } from "./policy.js";
+import { type Observed } from "./spool.js";
+/** Production data plane. Overridable for tests and for a self-hosted server. */
+export declare const DEFAULT_INGEST_URL = "https://api.vibecommit.ai/ingest/v1/session";
+/**
+ * `/cso` finding 2 (2026-08-09), MEDIUM. The override used to be passed to
+ * `fetch` unexamined, so `http://` put `Authorization: Bearer vcik_…` on the
+ * wire in cleartext — and the ingest credential is long-lived with no rotation
+ * by design, so one interception is a durable compromise rather than a
+ * 15-minute one.
+ */
+export declare function isAllowedIngestUrl(raw: string): boolean;
+/** The ingest URL, or null when the override is one we refuse to send to. */
+export declare function ingestUrl(env: NodeJS.ProcessEnv): string | null;
+/** Which transcript file a delta came from: the main one, or one sub-agent's. */
+export type FileKey = "main" | `agent-${string}`;
+export interface IngestDelta {
+    readonly sessionId: string;
+    /**
+     * Monotonic per session. A gap is detected server-side and reported back
+     * on the ingest response — never stamped onto a row.
+     */
+    readonly seq: number;
+    /** Offset the delta STARTS at, so the server can detect a resync. */
+    readonly byteOffset: number;
+    readonly fileKey: FileKey;
+    /**
+     * `owner/repo`, or `local:<sha256(abspath)[0:12]>` — `git.ts`'s
+     * `resolveRepoSlug` (`CR-019d`). REQUIRED and never empty: the merged server
+     * (`CR-019b`) 400s an absent or blank header.
+     *
+     * ⚠ NOT `DeliveryContext.repoKey`. That one is a filesystem path used for
+     * `~/.vibecommit/` state filenames and never leaves the machine; this one is
+     * the tenant-resolvable identity the server looks up. See `git.ts`'s header.
+     */
+    readonly repoSlug: string;
+    /**
+     * ⛔ **WHO PRODUCED THESE BYTES — `X-Agent` (`CR-204`, D177 §7).**
+     *
+     * The server binds the session's `agent` from this header and picks the
+     * extractor from it. It had **no client writer at all** until `CR-204`: nine
+     * headers went out and this was not among them, so every capture ever taken
+     * bound `unknown`, and `DIALECTS.unknown` is the Claude extractor. Measured
+     * cost on a non-Claude transcript: **32 of 32 records discarded**, against a
+     * correct extraction of 7 turns, with an empty tail — so the offset advances
+     * and the bytes are never read again (D177 §11).
+     *
+     * ⛔ **DERIVED FROM THE CONTAINING REGISTRY ROOT, never from `--agent=`**, and
+     * typed as `SelectedAgentId` rather than `string` so the flag's value is not
+     * even assignable here. `deliver()` below is the one place it is computed.
+     *
+     * ⛔ **`unknown` IS NOT SENT — it OMITS the header.** See `buildIngestHeaders`.
+     *
+     * ⚠ **This changes the digest's VALUE, not its FORMULA.** `agent` is already
+     * in `ingestContentDigest`'s preimage server-side, so there is nothing to
+     * migrate and nothing to backfill — and every stream pinned `unknown` rewinds
+     * exactly once when this lands, which is mismatch-as-rewind working as
+     * designed (D164 §4) and free at zero production rows.
+     */
+    readonly agent: SelectedAgentId;
+    /**
+     * Where `HEAD` is right now — the REF MOVE (`CR-170`, D154).
+     *
+     * ⚠ **This is not a commit.** A `pull`, a `checkout` or a `reset --hard` moves
+     * a ref without creating one, so no commit hook fires and this is the only
+     * record that it happened. Absent when git could not be read (an empty
+     * repository has no `HEAD`), which is a state rather than an error.
+     */
+    readonly head?: {
+        readonly sha: string;
+        readonly branch: string | null;
+    } | null;
+    /**
+     * Commits OBSERVED by `post-commit` since the last delivery, oldest first —
+     * ⛔ **and the rung each was attributed by, positionally aligned.**
+     *
+     * ⛔ **FULL 40-CHAR SHAs, ALWAYS.** `capture_commits.commit_sha` is 7..40
+     * because the server's `expandShortSha` can fail; an abbreviated sha makes the
+     * web join SILENTLY EMPTY, which is a wrong answer with no error (D98).
+     *
+     * ⛔ **THE WHOLE `Observed` OBJECT, not the sha list.** The two lists are only
+     * safe as a pair: `parseObservedCommits` drops the ENTIRE BATCH when their
+     * lengths differ (`D190 §1`), so a signature that let a caller supply one
+     * without the other would be a signature that lets a caller silently delete
+     * every edge in the request.
+     */
+    readonly commits?: Observed;
+    /**
+     * Rewrite pairs OBSERVED by `post-rewrite` — `ancestor:successor`, already in
+     * wire spelling (`capSuccessors`).
+     *
+     * ⚠ **NO ATTRIBUTION, and that is not an omission.** A pair asserts a relation
+     * between two SHAs and claims nothing about who did it, so there is no rung to
+     * be wrong about.
+     */
+    readonly rewrites?: readonly string[];
+}
+/**
+ * Build the request headers.
+ *
+ * `expose()` is called here and in no other module. That is the point of the
+ * opaque wrapper: the single call site is greppable, reviewable, and sits at the
+ * boundary where the secret has to be plaintext anyway.
+ *
+ * ## ⛔ SHAs ON THE WIRE, NEVER COMMIT METADATA (`CR-170` §4)
+ *
+ * No message, no author, no dates. MEASURED over the last 20 commits per repo:
+ * **9/20 schema, 8/20 web and 5/20 capture exceed 4096 bytes, largest 12,112** —
+ * so a quarter of real commits would land PERMANENTLY TRUNCATED in a header, and
+ * `capture_commits` rows cannot be retracted. Metadata is backfillable from a
+ * sha by anyone holding the repository; the observation that a commit happened
+ * at all is not. So the wire carries the irreplaceable half.
+ */
+export declare function buildIngestHeaders(credential: IngestCredential, delta: IngestDelta): Record<string, string>;
+/**
+ * The wire's error code for org-approval-pending — `CR-128`, D81.
+ *
+ * ⚠ A CROSS-REPO CONTRACT, not a local string. The server emits it as
+ * `403 { error: "capture_not_approved", owners_notified }` and pins the body
+ * shape in its own suite. **`repository_forbidden` is ALSO a 403** and carries
+ * no `owners_notified` at all — deliberately, because it is a different
+ * condition where no owner was or could have been notified. That is why every
+ * consumer here branches on THIS CODE and never on the status.
+ */
+export declare const CAPTURE_NOT_APPROVED = "capture_not_approved";
+/**
+ * The non-secret detail parsed out of an error response body.
+ *
+ * Deliberately narrow: a code and one number. The body carries no org id, no
+ * repo id, no user id and no owner list — the server discloses nothing — so
+ * there is nothing else here to lift, and widening this type later is a
+ * decision rather than a drift.
+ */
+export interface ErrorDetail {
+    /** The `error` field. The ONLY thing any caller may branch on. */
+    readonly code: string;
+    /**
+     * `owners_notified` — **`null` = NOT DETERMINABLE, `0` = determinable and
+     * nobody was told, `> 0` = N notified** (D81). `undefined` when the key was
+     * absent from the body, which is what `repository_forbidden` looks like.
+     *
+     * ⚠ `null` and `undefined` are NOT interchangeable for the caller's copy, but
+     * they resolve to the same branch: never assert delivery on either.
+     */
+    readonly ownersNotified?: number | null;
+}
+export type SendOutcome = {
+    readonly kind: "response";
+    readonly status: number;
+    /**
+     * The parsed error body, or `null` when there was not one to parse.
+     *
+     * ⚠ **The hook path ignores this for free.** It is only ever populated on
+     * a non-2xx (see `readErrorDetail`), so a healthy hook never pays for the
+     * body read at all, and `deliver()`'s classification does not consult it.
+     */
+    readonly detail: ErrorDetail | null;
+}
+/** No response at all — DNS, refused, TLS, timeout. Not an HTTP status. */
+ | {
+    readonly kind: "unreachable";
+};
+/**
+ * One attempt. No retry, no backoff, no classification — `CR-018` owns all three.
+ *
+ * The timeout is mandatory rather than optional: a hook has a wall-clock budget
+ * it must not exceed (DESIGN.md §13.7), and `fetch` without a signal waits on the
+ * platform default, which is far longer than any hook timeout.
+ *
+ * Never throws. A hook that takes an exception from the network has already
+ * broken the contract; returning `unreachable` keeps the decision with the
+ * caller.
+ */
+export declare function send(url: string, headers: Record<string, string>, body: Uint8Array, timeoutMs: number): Promise<SendOutcome>;
+/**
+ * A one-way digest of the credential, for the `fatal` stop's key.
+ *
+ * The second and last call to `expose()` in the package, kept in this module for
+ * the same reason as the first: the plaintext's exits are greppable in one file.
+ * What is stored is 16 hex characters of a SHA-256 over a high-entropy opaque
+ * token — enough to tell one credential from another, and not a preimage of
+ * anything. No copy path and no header ever carries it.
+ */
+export declare function credentialFingerprint(credential: IngestCredential): string;
+export type Delivery = 
+/** The offset is already at EOF. No request was made and none was needed. */
+{
+    readonly kind: "nothing-to-send";
+}
+/** A `fatal` class fired earlier for this credential. No request was made. */
+ | {
+    readonly kind: "stopped";
+}
+/** No repo identity, so no binding key. `CR-017d` — refuse, never guess. */
+ | {
+    readonly kind: "no-repo";
+} | {
+    readonly kind: "attempted";
+    readonly disposition: Disposition;
+    /**
+     * The parsed error body, when there was one — `CR-110`.
+     *
+     * ⚠ **This does NOT reintroduce branching on `later` / `never`.** The
+     * disposition still decides what happens to the offset, and nothing here
+     * changes it. What this carries is the ONE outcome `connect` renders a
+     * beat for, identified by its ERROR CODE, and a caller that ignores it
+     * behaves exactly as before — which is what the hook path does.
+     */
+    readonly detail: ErrorDetail | null;
+};
+export interface DeliveryContext {
+    readonly home: string;
+    readonly env: NodeJS.ProcessEnv;
+    readonly url: string;
+    readonly credential: IngestCredential;
+    /**
+     * `resolveProjectKey()`'s git toplevel — half the binding key (`CR-017d`),
+     * ahead of `sessionId` as `repository_id` sits ahead of `session_id` in
+     * `CR-017a`'s PK. Required: the caller resolves it or does not call.
+     *
+     * LOCAL ONLY. Pairs with `repoSlug` below, which is the wire half; the two
+     * describe the same repository in two different vocabularies and are not
+     * interchangeable.
+     */
+    readonly repoKey: string;
+    /** The wire identity — `X-Repo-Slug` (`CR-019d`). See `IngestDelta`. */
+    readonly repoSlug: string;
+    readonly sessionId: string;
+    readonly fileKey: FileKey;
+    /**
+     * The file these bytes come from — ⛔ **the input `X-Agent` is derived from,
+     * and the ONLY reason this module is told a path** (`CR-204`, D177 §7).
+     *
+     * ⚠ **A path, not an agent id, and that is the point.** Taking a resolved
+     * `agent` from callers would let one hand over `ctx.agentId` — the `--agent=`
+     * flag — which is the false-provenance defect this task exists to close.
+     * Taking the PATH means the derivation happens here, once, through
+     * `agentForTranscript`, and no caller can express the wrong thing.
+     *
+     * The same path the caller's `readBody` reads, and it is already confined:
+     * `readBody` is supplied precisely because the CALLER is the one that ran
+     * `isInsideAny(transcriptRoots(...))` over it (`/cso` finding 1). This module
+     * still never opens a file.
+     */
+    readonly transcriptPath: string;
+    readonly timeoutMs: number;
+    /** Epoch ms. Passed in so the backlog's age cap is reachable from a test. */
+    readonly nowMs: number;
+    /**
+     * ⛔ ATTACHED TO EXACTLY ONE DELIVERY PER HOOK — the MAIN transcript's.
+     *
+     * One hook fire delivers the main file plus up to `MAX_SUBAGENT_FILES` (8)
+     * sub-agent files, **each its own `capture_id`**. `capture_commits`' PK is
+     * `(org_id, capture_id, commit_sha)`, so attaching these to every delivery
+     * would admit NINE LEGAL, PERMANENT ROWS for one commit — the exact objection
+     * that killed the polling design (D154). Sub-agent deliveries leave both unset.
+     */
+    readonly head?: {
+        readonly sha: string;
+        readonly branch: string | null;
+    } | null;
+    readonly commits?: Observed;
+    /** Rewrite pairs, wire-spelled. Main delivery only, for the same reason. */
+    readonly rewrites?: readonly string[];
+}
+/**
+ * Send the undelivered span of one transcript file and apply the failure policy.
+ *
+ * **Exactly one attempt, ever.** `later` does not retry here; it leaves the
+ * offset where it is so the hook that fires on the NEXT turn picks the same
+ * bytes up. A loop in this function would reopen D56 plan §D8, the founder
+ * override that says a hook must never block or slow a developer's turn.
+ *
+ * Never throws: the caller is a hook, and an exception on this path is the
+ * contract breaking. Every failure resolves to a `Delivery`.
+ *
+ * `readBody` is supplied by the caller rather than read here, because the caller
+ * is the one that has confined `transcript_path` to the Claude Code root
+ * (`/cso` finding 1). This module never opens a file.
+ */
+export declare function deliver(ctx: DeliveryContext, eof: number, readBody: (from: number, to: number) => Uint8Array | null): Promise<Delivery>;