@vibe-commit/capture 0.6.1 → 0.8.0

package/dist/policy.d.ts

@@ -62,7 +62,22 @@ export declare const NETWORK_CLASS: FailureClass;
 export declare const DEFAULT_CLASS: FailureClass;
 /** Classify one HTTP status. `2xx` is the only success. */
 export declare function classifyStatus(status: number): Disposition;
-/** Classify one attempt, response or not. */
+/**
+ * The wire code for "the user turned this repository off, on their account" (slice 2, `CR-259`). A cross-repo contract, like
+ * `CAPTURE_NOT_APPROVED`: the server answers `403 { error: "repository_excluded" }` to a credential that has synced its
+ * grants. Its sibling `repository_not_granted` is ALSO a 403 and is `later` — nothing here names it, because the 403 row
+ * above already says so and a code we did not need to name is one fewer that can drift.
+ */
+export declare const REPOSITORY_EXCLUDED = "repository_excluded";
+/**
+ * Classify one attempt, response or not.
+ *
+ * ⛔ **ONE 403 IS `never`, AND IT IS IDENTIFIED BY THE ERROR CODE ALONE** (`ErrorDetail.code` is the only thing a caller may
+ * branch on, `post.ts`) — and only on a 403. `never` drops bytes, so every doubt is `later`: a 403 with no body, a body that
+ * did not parse or was cut off, a code this client does not know, and the same code on any other status all fall through
+ * to the 403 row. Excluded means the user said not to capture this repo, so its bytes are not held for a "later" that the
+ * user has already refused.
+ */
 export declare function classify(outcome: SendOutcome): Disposition;
 /**
  * The §13.6 copy for a class.
@@ -161,6 +176,60 @@ export interface BacklogCaps {
  * for the tests, which have to reach a boundary they cannot otherwise reach.
  */
 export declare function resolveCaps(env: NodeJS.ProcessEnv): BacklogCaps;
+/**
+ * The most RAW transcript bytes one delta carries. The server's own ceiling is 16 MiB decompressed
+ * (`MAX_DELTA_BYTES`, `ingest_session.ts:146`); half of it leaves room for redaction markers and for a record that
+ * straddles the cut.
+ */
+export declare const MAX_DELTA_RAW_BYTES: number;
+/**
+ * The most COMPRESSED bytes one delta's frame may be. The server refuses a request body over 1 MiB (`MAX_BODY_BYTES`,
+ * `src/transport/server.ts:115`, a 413); 960 KiB leaves the rest for the framing the body does not include.
+ */
+export declare const MAX_DELTA_FRAME_BYTES: number;
+/**
+ * Where a transcript's records end. A boundary is an offset `b` where byte `b - 1` is `\n`.
+ *
+ * ⛔ A delta must END ON ONE. The server drops a delta's trailing partial line: it counts as `malformed` and is not
+ * carried into the next POST (`ingest_session.ts`, `parseNdjsonRecords`' "KNOWN GAP"), so a cut mid-line loses that
+ * record for good.
+ *
+ * Implemented by the caller (`hooks/entry.ts`'s `recordCutter`), because this module is pure and reads no file. An
+ * implementation reads bytes only to find a newline; none of them leaves the process.
+ */
+export interface RecordCutter {
+    /** The largest boundary `b` with `from < b <= limit`, or `null` when there is no newline in `[from, limit)`. */
+    readonly lastBoundary: (from: number, limit: number) => number | null;
+    /** The first boundary after `from` (the end of the record that starts there), or `null` when none before EOF. */
+    readonly firstBoundary: (from: number) => number | null;
+}
+/** What the next delta at `from` should be. `to` is exclusive. */
+export type ChunkPlan = {
+    readonly kind: "span";
+    readonly to: number;
+}
+/** The record at `from` alone is longer than `maxRaw`: skip `[from, to)` and count it. */
+ | {
+    readonly kind: "oversize";
+    readonly to: number;
+}
+/** The record at `from` is longer than `maxRaw` AND unterminated at EOF. It may still be growing: leave it. */
+ | {
+    readonly kind: "wait";
+};
+/**
+ * Cut the next delta from `from`: everything to `eof` when it fits, else up to the last record boundary inside `maxRaw`.
+ *
+ * Pure; the cutter is the only thing that touches a file.
+ */
+export declare function planChunk(cutter: RecordCutter, from: number, eof: number, maxRaw?: number): ChunkPlan;
+/**
+ * Where to cut `[from, to)` in two, at a record boundary, or `null` when the span is a single record and cannot be.
+ *
+ * Halves by bytes, snapping back to the last boundary at or before the middle. When the first record is longer than
+ * half, the cut is that record's end, so the oversize record goes out alone and a second 413 on it is final.
+ */
+export declare function splitPoint(cutter: RecordCutter, from: number, to: number): number | null;
 /** Undelivered bytes currently held. */
 export declare function pendingBytes(state: FileState): number;
 /**

package/dist/policy.js

@@ -55,6 +55,11 @@ export const STATUS_CLASSES = new Map([
     // Org approval pending (D60 §D12). Capture has not stopped; it is waiting.
     [403, "later"],
     // Payload too large. Retrying the same bytes cannot work.
+    //
+    // ⚠ PR 4a: this row is now the verdict on a span that CANNOT BE SPLIT — a single record that alone exceeds a limit.
+    // `deliver()` halves a splittable span at a record boundary and sends the two halves, which are different bytes, so the
+    // reason above still holds for what reaches this table. Only a `deliver()` given no `RecordCutter` (a caller that
+    // cannot align) classifies a 413 here directly, and it is `never` there exactly as before.
     [413, "never"],
     // Rate limited. The definition of transient.
     [429, "later"],
@@ -79,9 +84,28 @@ export function classifyStatus(status) {
         return SERVER_ERROR_CLASS;
     return DEFAULT_CLASS;
 }
-/** Classify one attempt, response or not. */
+/**
+ * The wire code for "the user turned this repository off, on their account" (slice 2, `CR-259`). A cross-repo contract, like
+ * `CAPTURE_NOT_APPROVED`: the server answers `403 { error: "repository_excluded" }` to a credential that has synced its
+ * grants. Its sibling `repository_not_granted` is ALSO a 403 and is `later` — nothing here names it, because the 403 row
+ * above already says so and a code we did not need to name is one fewer that can drift.
+ */
+export const REPOSITORY_EXCLUDED = "repository_excluded";
+/**
+ * Classify one attempt, response or not.
+ *
+ * ⛔ **ONE 403 IS `never`, AND IT IS IDENTIFIED BY THE ERROR CODE ALONE** (`ErrorDetail.code` is the only thing a caller may
+ * branch on, `post.ts`) — and only on a 403. `never` drops bytes, so every doubt is `later`: a 403 with no body, a body that
+ * did not parse or was cut off, a code this client does not know, and the same code on any other status all fall through
+ * to the 403 row. Excluded means the user said not to capture this repo, so its bytes are not held for a "later" that the
+ * user has already refused.
+ */
 export function classify(outcome) {
-    return outcome.kind === "unreachable" ? NETWORK_CLASS : classifyStatus(outcome.status);
+    if (outcome.kind === "unreachable")
+        return NETWORK_CLASS;
+    if (outcome.status === 403 && outcome.detail?.code === REPOSITORY_EXCLUDED)
+        return "never";
+    return classifyStatus(outcome.status);
 }
 /**
  * The §13.6 copy for a class.
@@ -150,6 +174,48 @@ function positiveOr(raw, fallback) {
     const parsed = Number(raw);
     return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
 }
+// ---------------------------------------------------------------------------
+// Delta sizing — PR 4a. One request carries one DELTA, never the whole span to EOF.
+// ---------------------------------------------------------------------------
+/**
+ * The most RAW transcript bytes one delta carries. The server's own ceiling is 16 MiB decompressed
+ * (`MAX_DELTA_BYTES`, `ingest_session.ts:146`); half of it leaves room for redaction markers and for a record that
+ * straddles the cut.
+ */
+export const MAX_DELTA_RAW_BYTES = 8 * 1024 * 1024;
+/**
+ * The most COMPRESSED bytes one delta's frame may be. The server refuses a request body over 1 MiB (`MAX_BODY_BYTES`,
+ * `src/transport/server.ts:115`, a 413); 960 KiB leaves the rest for the framing the body does not include.
+ */
+export const MAX_DELTA_FRAME_BYTES = 960 * 1024;
+/**
+ * Cut the next delta from `from`: everything to `eof` when it fits, else up to the last record boundary inside `maxRaw`.
+ *
+ * Pure; the cutter is the only thing that touches a file.
+ */
+export function planChunk(cutter, from, eof, maxRaw = MAX_DELTA_RAW_BYTES) {
+    if (eof - from <= maxRaw)
+        return { kind: "span", to: eof };
+    const boundary = cutter.lastBoundary(from, from + maxRaw);
+    if (boundary !== null)
+        return { kind: "span", to: boundary };
+    const end = cutter.firstBoundary(from);
+    return end === null ? { kind: "wait" } : { kind: "oversize", to: end };
+}
+/**
+ * Where to cut `[from, to)` in two, at a record boundary, or `null` when the span is a single record and cannot be.
+ *
+ * Halves by bytes, snapping back to the last boundary at or before the middle. When the first record is longer than
+ * half, the cut is that record's end, so the oversize record goes out alone and a second 413 on it is final.
+ */
+export function splitPoint(cutter, from, to) {
+    const middle = from + Math.floor((to - from) / 2);
+    const boundary = cutter.lastBoundary(from, middle);
+    if (boundary !== null)
+        return boundary;
+    const end = cutter.firstBoundary(from);
+    return end !== null && end < to ? end : null;
+}
 /** Undelivered bytes currently held. */
 export function pendingBytes(state) {
     if (state.backlog.length === 0)

package/dist/policy.js.map

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

package/dist/post.d.ts

@@ -19,7 +19,7 @@
  */
 import { type SelectedAgentId } from "./agents/types.js";
 import type { IngestCredential } from "./credential.js";
-import { type Disposition } from "./policy.js";
+import { type Disposition, type RecordCutter } from "./policy.js";
 import { type InferredGroupId, 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";
@@ -230,8 +230,10 @@ export type SendOutcome = {
      * ⚠ Read from the HEADER, never the body: `readErrorDetail` states that a
      * 2xx body is not read, not awaited and not parsed ON THE HOOK PATH, and
      * that property is why the hook's hot path cannot throw on a response. A
-     * header costs a map lookup. (`connect` alone opts in to a 2xx body read,
-     * for `conversation_id` — see `readConversationId`.)
+     * header costs a map lookup. (`connect` alone opts in to a 2xx body read of an
+     * INGEST reply, for `conversation_id` — see `readConversationId`. The only other 2xx
+     * body a hook reads is SessionStart's one bounded `GET /ingest/v1/grants`, which is
+     * not an ingest reply and does not go through `send` — see `hooks/session_grants.ts`.)
      */
     readonly captureId: string | null;
     /**
@@ -277,11 +279,48 @@ export type SendOutcome = {
      * credential-meta sidecar so state 5 can warn before the 365-day cap; it changes no disposition.
      */
     readonly credentialExpires?: string | null;
+    /**
+     * `X-Grant-Epoch` (slice 2, `CR-259`): the version of the user's account grants, on every credential-lane ingest 2xx and on a
+     * grants refusal. `null` when absent (a server that predates it) or not a non-negative integer.
+     *
+     * Read from the HEADER, like the others. It changes no disposition: `deliver` hands it to `noteGrantEpoch`, which marks
+     * `grants-account.json` stale when it is not the epoch this machine last recorded, and SessionStart's one bounded GET
+     * (`hooks/session_grants.ts`) is what answers that.
+     */
+    readonly grantEpoch?: number | null;
 }
 /** No response at all — DNS, refused, TLS, timeout. Not an HTTP status. */
  | {
     readonly kind: "unreachable";
 };
+/**
+ * An error body is a handful of bytes by contract. Anything larger is not one
+ * this client parses — a cap so a misconfigured or hostile endpoint cannot make
+ * a hook buffer an arbitrary response into memory.
+ */
+export declare const MAX_ERROR_BODY_BYTES: number;
+/**
+ * ⛔ THE ONE CAPPED, TIMED BODY READER — `readErrorDetail` (non-2xx), `readConversationId` (`connect`'s opt-in
+ * 2xx) and `grants_sync.ts`'s two grants reads all read through it, so no bound can drift from another.
+ *
+ * Returns the parsed JSON (which may legitimately be `null`, an array or a scalar — the caller shapes it), or
+ * `undefined` for EVERY failure: no body, a declared length over the cap, a streamed body that crosses the cap,
+ * an abort, a stalled or reset stream, invalid JSON. **NEVER THROWS, on any input.**
+ *
+ *   - BYTES: the declared `content-length` is checked first, and the stream is then counted chunk by chunk and
+ *     CANCELLED the moment it crosses `maxBytes` (`MAX_ERROR_BODY_BYTES`, 64 KiB, unless a CLI verb asks for more) — so a chunked body with no length cannot be
+ *     buffered whole before a post-hoc check (the old `await res.text()` did exactly that, contradicting
+ *     `readErrorDetail`'s own comment that a hostile endpoint cannot make a hook buffer an arbitrary response).
+ *   - TIME: every read is RACED against the request's abort signal rather than trusting the abort to reach the
+ *     stream. Aborting is supposed to reject a pending `reader.read()` (it does, in a direct probe), but the
+ *     bound is then a property of this function and not of the HTTP client's internals.
+ */
+export declare function readCappedJson(res: Response, signal: AbortSignal, maxBytes?: number): Promise<unknown>;
+/**
+ * `X-Grant-Epoch`: a non-negative integer, or null. Digits only (and a sane length), so a header that is not one reads as
+ * "the server did not say" and never as `NaN`, a negative, or a float that could equal nothing.
+ */
+export declare function parseGrantEpoch(raw: string | null): number | null;
 /**
  * `X-Credential-Expires`: an ISO 8601 instant, or null. Only a string that parses as a date is believed —
  * the value is printed (as a date) to a person and compared against the clock, so a header that is not one
@@ -360,8 +399,29 @@ export type Delivery =
     readonly inferredSetAsidePairs: number;
     /** `X-Credential-Expires` from the 2xx that delivered this, or `null`/absent. See `SendOutcome`. */
     readonly credentialExpires?: string | null;
-    /** `conversation_id` from that 2xx, ONLY when the caller opted in and `disposition === "ok"`. See `SendOutcome`. */
+    /**
+     * `conversation_id` from a 2xx, ONLY when the caller opted in. See `SendOutcome`.
+     *
+     * PR 4a (DX D8): a delivery of several deltas carries the id from whichever delta was acknowledged with it, even when
+     * a LATER delta came back `later`, so `connect`'s session link does not fall back to `/app/commits` on a partial run.
+     */
     readonly conversationId?: string;
+    /**
+     * PR 4a — records skipped because one record ALONE exceeded a limit (`record too large`): over `limits.rawBytes`
+     * raw, or over `limits.frameBytes` compressed, or refused with a 413 that no split can shrink. Each was written off
+     * with `markSkipped`, so it is in the gap counters `status` reports as "skipped … will not be sent later".
+     */
+    readonly recordsTooLarge?: number;
+    /**
+     * PR 5 — set when the last attempt got NO response at all (a refused connection, a timeout), so a caller can tell a server
+     * that could not be reached apart from one that answered and asked to wait. Absent whenever a response arrived. It
+     * changes no decision here: both are `later`.
+     */
+    readonly unreachable?: true;
+    /** PR 4a — deltas this call acknowledged or skipped past, when more than one. */
+    readonly deltas?: number;
+    /** PR 4a — `true` when the call stopped on the hook's budget with bytes still unsent. The offset is where it left off. */
+    readonly more?: boolean;
 };
 export interface DeliveryContext {
     readonly home: string;
@@ -444,23 +504,36 @@ export interface DeliveryContext {
      * reads, awaits or parses a 2xx body.
      */
     readonly readConversationId?: boolean;
+    /**
+     * PR 4a — WHEN THE HOOK'S SEND BUDGET ENDS, epoch ms. Set by the hook path only. `deliver()` starts a further delta (or a
+     * 413 split's retry) only while at least `MIN_NEXT_DELTA_BUDGET_MS` of it remains, and leaves the rest of the span for the
+     * next event or `vibecommit finalize`. Unset (`finalize`, `connect`) means no deadline.
+     */
+    readonly deadlineAtMs?: number;
+    /** PR 4a — the clock `deadlineAtMs` is measured on. A test seam; defaults to `Date.now`. */
+    readonly clock?: () => number;
+    /** PR 4a — the delta size limits. A test seam; defaults to the server-derived constants in `policy.ts`. */
+    readonly limits?: {
+        readonly rawBytes: number;
+        readonly frameBytes: number;
+    };
 }
 /**
- * Send the undelivered span of one transcript file and apply the failure policy.
+ * Send the undelivered span of one transcript file, in deltas — PR 4a.
  *
- * **At most one NETWORK attempt per hook, still — exactly D56 §D8's rule.** A
- * `finalize` lean retry (below) is the one exception D56 §D8 itself does not
- * cover: it governs HOOKS, and `finalize` is a synchronous, user-invoked verb
- * that already makes 1 + up to `FINALIZE_DRAIN_MAX_ITERATIONS` requests by
- * design (VL's explicit ruling, `TODOS[182]`). On the hook path, `later` still
- * 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.
+ * Without a `cutter` this is the single request it always was: everything from the offset to EOF, at most one attempt.
+ * With one (every production caller), the span goes out as record-aligned deltas, each acknowledged before the offset
+ * moves past it:
  *
- * Never throws: the caller is a hook, and an exception on this path is the
- * contract breaking. Every failure resolves to a `Delivery`.
+ *   - **A hook sends deltas only while its budget lasts** (`ctx.deadlineAtMs`) and leaves the rest for its next event or
+ *     `vibecommit finalize`; `Delivery.more` says it stopped early. `finalize` and `connect` set no deadline and run on.
+ *   - **It stops at the first delta that is not `ok`** and returns that delta's outcome: `later` and `fatal` hold exactly
+ *     the bytes that failed, so a resume starts at the next unacknowledged delta, with no resend and no gap. A
+ *     `capture_not_approved` 403 on any delta is such a stop, so its pending beat is printed once.
+ *   - **A skipped oversize record does not stop it.** The records after it still go out.
+ *   - **`connect`'s conversation id survives a partial run** (DX D8): it is read from the first 2xx that carries it, no later
+ *     delta reads a body, and it is returned even when a later delta came back `later`.
  *
- * `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.
+ * ⛔ A 2xx never changes a delta's outcome, and a hook reads no body (eng-2 D2): the only body read is `connect`'s opt-in.
  */
-export declare function deliver(ctx: DeliveryContext, eof: number, readBody: (from: number, to: number) => Uint8Array | null): Promise<Delivery>;
+export declare function deliver(ctx: DeliveryContext, eof: number, readBody: (from: number, to: number) => Uint8Array | null, cutter?: RecordCutter): Promise<Delivery>;