@vibe-commit/capture 0.8.0 → 0.10.0

package/dist/commands/finalize.d.ts

@@ -32,8 +32,56 @@
  * - Read anywhere but the agent's own transcript root (`admitsTranscript`, the same confinement as a hook).
  */
 import { type IngestCredential } from "../credential.js";
+import { type Isolation, type Target, type TargetRecord } from "../session_targets.js";
+import type { ProjectKeys } from "../project.js";
 import { type Delivery } from "../post.js";
 import { type CommandContext } from "./context.js";
+/** One thing to close: a repo (or the folder) the session's bytes belong to, with everything `closeSession` needs about it. */
+export interface CloseSpec {
+    readonly projectKey: string;
+    readonly redactionRoots: readonly string[];
+    readonly repoSlug: string;
+    readonly worktrees: readonly string[];
+    readonly allowNeverCaptured: boolean;
+    /** The resolver's SCANNED offsets: set for a FOLDER target only, which never sends past them (A-T3 (b)). */
+    readonly sizeCap?: Readonly<Record<string, number>>;
+    readonly isolation?: Isolation;
+    readonly target: Target | null;
+}
+/**
+ * Take the session's one writer lock (O5) and resolve every target the session names, as a session that is OVER (`end` mode, the
+ * only mode that may decide a folder target). The lock is released by the caller's `releases`, after the sends. Shared by
+ * `finalize` and `backfill`: one resolver loop, so a session is judged the same whichever verb closes it.
+ * `busy`: another writer held the session for the whole wait.
+ */
+export declare function resolveSessionTargets(env: {
+    readonly home: string;
+    readonly env: NodeJS.ProcessEnv;
+    readonly nowMs: number;
+    readonly turnEndCwd: string | null;
+}, sessionId: string, transcriptPath: string, known: {
+    readonly keys: ProjectKeys;
+    readonly slugOf: () => string | null;
+} | null, releases: Array<() => void>): Promise<{
+    readonly kind: "busy";
+} | {
+    readonly kind: "ok";
+    readonly targets: readonly Target[];
+    readonly scan: Record<string, number>;
+    /** C27: the session's target record as the resolver just wrote it (the per-target multi flag, the call checkpoints). */
+    readonly record: TargetRecord;
+    /** C27: the dialect isolates records, so a REPO target also delivers only up to what the resolver scanned (a FOLDER target always did). */
+    readonly capRepos: boolean;
+    /** C25: re-stamp the lock; `false` = it is no longer ours and the caller stops before its next write. Pass it to `closeSession`. */
+    readonly heartbeat: () => boolean;
+}>;
+/** What `closeSession` is told for one resolved target: the repo (or folder) and everything `closeSession` needs about it. */
+export declare function closeSpecOf(target: Target, scan: Record<string, number>, facts?: SpecFacts): CloseSpec;
+/** What `resolveSessionTargets` knows beyond the scan offsets: the record (multi flag, call checkpoints) and whether a repo target is capped at the scan. */
+export interface SpecFacts {
+    readonly record: TargetRecord;
+    readonly capRepos: boolean;
+}
 export declare function finalize(ctx: CommandContext, argv: readonly string[]): Promise<number>;
 /**
  * PR 7 (Q2): the ingest address in the environment is one this client refuses to send to. Shared with `backfill`, which
@@ -74,8 +122,23 @@ export interface CloseSessionInput {
      * and sealing before the sub-agent streams arrive "would seal a poorer turn".
      */
     readonly completeSubagents: boolean;
+    /**
+     * Every work tree of the target's repo this session was seen in (its spool sources, O7). Defaults to the ledger work tree alone,
+     * which is the one-source behaviour every caller had before any-folder capture.
+     */
+    readonly worktrees?: readonly string[];
+    /** What the streams may contain beyond structured-path redaction (A-T4). Default: a repo target of `redactionRoots` (R17). */
+    readonly isolation?: Isolation;
+    /** A FOLDER target's per-stream ceiling (the resolver's scanned offsets); delegated streams never send past it. */
+    readonly sizeCap?: Readonly<Record<string, number>>;
     /** The wall-clock budget for the sends of this close, ms. Default `SEND_BUDGET_MS`. A test seam. */
     readonly sendBudgetMs?: number;
+    /**
+     * C25: the session writer lock's heartbeat (`resolveSessionTargets` returns it). Called before every round of delegated sends,
+     * before the main delivery and each drain request, and (through `deliver`) before every request. `false` means the lock is no
+     * longer ours: the close stops before its next write and answers `lock-lost`. Absent: no lock to keep (a test seam).
+     */
+    readonly heartbeat?: () => boolean;
 }
 /** How a close ended. The caller turns it into words; this function prints nothing. */
 export type CloseOutcome = 
@@ -117,6 +180,10 @@ export type CloseOutcome =
 /** `allowNeverCaptured` was false and this repo has no state for the session. Nothing was sent. */
  | {
     readonly kind: "never-captured";
+}
+/** C25: the session's writer lock was taken from us (another writer is on the session). The close stopped before its next write. */
+ | {
+    readonly kind: "lock-lost";
 };
 /**
  * Close ONE session: sub-agent streams first, then the main stream, then (when `seal`) the assertion and the bounded drain.