@edspencer/paddock 0.71.2 → 0.72.1

package/packages/server/dist/transcripts-migration.d.ts

@@ -0,0 +1,336 @@
+import { type TranscriptsMode } from "./transcripts.js";
+/**
+ * The three-state classification the modal's table renders, plus the budget
+ * escape hatch.
+ *
+ * `unknown` is not a fourth kind of conflict — it is "we stopped looking", and
+ * it is treated as `diverged` (default unchecked) because that is the
+ * conservative direction.
+ */
+export type MigrationState = "new" | "fast-forward" | "diverged" | "unknown";
+/** Why the banner is not offered. */
+export type MigrationIneligibleReason = "already-host" | "env-shadowed" | "profile-paranoid" | "nothing-pending" | "scan-failed";
+/** Non-fatal conditions the modal should surface. */
+export type MigrationWarningCode = "host-store-unreadable" | "chats-dir-unreadable" | "env-shadowed" | "memory-collision" | "unexpected-entries";
+/** The env var that shadows `claude.transcripts` — see `config.ts:1481`. */
+export declare const TRANSCRIPTS_ENV_VAR = "PADDOCK_CLAUDE_TRANSCRIPTS";
+/**
+ * Where unchecked chats are preserved: a SIBLING of `.chats/`, not a child.
+ *
+ * #882 specified `.chats/pre-migration/`, which cannot work — that directory is
+ * "anything", so `pointChatsDirAt` declines the redirect and the migration
+ * built to fix #708 ships #708's symptom. Design §5.1 verified it against the
+ * real `ensureProjectChats`. Named here because the plan reports the path and
+ * the execute half must use the same one.
+ */
+export declare const PRESERVE_DIR_NAME = ".chats-pre-migration";
+/**
+ * Bytes stage 3 (and the diverged rows' comparison columns) may read across one
+ * whole request. The worst case is a *product* of chat count and transcript
+ * size and neither is under our control, so it is bounded rather than trusted.
+ */
+export declare const DIVERGENCE_SCAN_BUDGET_BYTES: number;
+/** One copy of a chat, for a diverged row's comparison columns. */
+export interface MigrationSide {
+    /** Absolute path of this copy. */
+    path: string;
+    sizeBytes: number;
+    /** Filesystem mtime. Present always; NOT a proxy for activity (#863). */
+    mtime: string;
+    /**
+     * Conversation records — `user`/`assistant`, excluding meta and
+     * task-notification records (the `last-activity.ts` rule, shared not copied).
+     *
+     * Present only where a decision needs it: on `diverged` rows, and only while
+     * the scan budget lasts. Counting it requires a full parse of the file, so
+     * populating it on every row would cost a complete read of every transcript
+     * and make the plan endpoint's realistic case ~60× its measured cost. See the
+     * PR body for why this deviates from the design's `required` list.
+     */
+    messageCount?: number;
+    /** ISO 8601 timestamp of the last real message; absent when none is datable. */
+    lastMessageAt?: string;
+}
+/** One row of the modal's table.
+ *
+ * `identical` is deliberately NOT a {@link MigrationState}: the plan omits
+ * identical chats from its rows entirely, because there is no decision for the
+ * user to make about one, and widening the published enum would put a value in
+ * the OpenAPI contract that the table can never render. The EXECUTE half still
+ * needs to know — an identical chat has a copy on both sides and therefore has
+ * a disposition (host's survives, Paddock's is preserved) — so the scan carries
+ * it as a flag on the row and {@link buildMigrationPlan} filters those rows out.
+ */
+export interface MigrationChatRow {
+    sessionId: string;
+    /** The chat's set name, else its auto-name. Absent when neither exists. */
+    name?: string;
+    /** First user message, truncated. Absent when unreadable. */
+    preview?: string;
+    state: MigrationState;
+    /** How the checkbox starts: true for `new`/`fast-forward`. */
+    defaultSelected: boolean;
+    /** The copy in `.chats/`. Always present. */
+    own: MigrationSide;
+    /** The copy in the host store. Absent if and only if state is `new`. */
+    host?: MigrationSide;
+    /** For `fast-forward`, which side is the descendant and will survive. */
+    ahead?: "own" | "host";
+    /** Sidecars that move with this chat: `<id>/…` and `.reverts/<id>-*.jsonl`. */
+    extras: string[];
+    /**
+     * Byte-identical on both sides. Internal to the scan — stripped from the
+     * plan's rows and counted in `totals.identical` instead. See the doc above.
+     */
+    identical?: boolean;
+}
+/** One project's slice of the plan. */
+export interface MigrationProjectPlan {
+    /** Project slug; the empty string is the root workspace. */
+    slug: string;
+    name: string;
+    chatsDir: string;
+    hostStore: string;
+    preserveDir: string;
+    chats: MigrationChatRow[];
+    /**
+     * Entries of `.chats/` that move with the PROJECT rather than with any one
+     * chat — `memory/`, flat `agent-<hex>.jsonl` sidechain transcripts, an
+     * orphaned `<id>/` with no transcript.
+     *
+     * Not in the design's schema. Added because the postcondition moves them and
+     * the standing rule is that nothing moves unannounced: without this the
+     * completion summary could not say "and 132 memory files", which is the
+     * single sharpest item in the design's own inventory (§5).
+     */
+    projectExtras: string[];
+}
+export interface MigrationWarning {
+    code: MigrationWarningCode;
+    /** The project it applies to. Absent for instance-wide warnings. */
+    slug?: string;
+    message: string;
+    paths?: string[];
+}
+export interface MigrationTotals {
+    chats: number;
+    new: number;
+    fastForward: number;
+    diverged: number;
+    unknown: number;
+    /** Identical on both sides, omitted from the rows. Reported so a count lower
+     *  than the user's chat total always has an explanation. */
+    identical: number;
+    defaultSelected: number;
+}
+export interface MigrationPlan {
+    mode: TranscriptsMode;
+    configPath: string;
+    configVersion: string | null;
+    projects: MigrationProjectPlan[];
+    sweepers: {
+        stores: number;
+        chats: number;
+    };
+    totals: MigrationTotals;
+    scanBudgetExhausted: boolean;
+    warnings: MigrationWarning[];
+}
+export interface MigrationProbe {
+    mode: TranscriptsMode;
+    eligible: boolean;
+    reason?: MigrationIneligibleReason;
+    envVar?: string;
+    /**
+     * Transcripts that would migrate. A LOWER BOUND by contract — see
+     * {@link probeMigration} for why this implementation can afford to make it
+     * exact, and for the one case where a pending project reports 0.
+     */
+    pendingChats: number;
+    pendingProjects: number;
+    scannedProjects: number;
+    computedAt: string;
+}
+/** The subset of a project this module needs — kept minimal so it is testable
+ *  against plain fixtures rather than a whole `ProjectStore`. */
+export interface MigrationProjectRef {
+    slug: string;
+    name: string;
+    /** The METADATA dir — where `.chats/` lives. */
+    dir: string;
+    /** The agent's cwd — what the host store's encoded name is built from. NOT
+     *  `dir` for a repo-backed or linked project (#187/#206). */
+    workingDir: string;
+}
+export interface MigrationInput {
+    /** The transcripts mode this process resolved at boot. */
+    mode: TranscriptsMode;
+    /** The resolved posture profile — `paranoid` suppresses the banner (§10.4). */
+    profile: string;
+    /** True when `PADDOCK_CLAUDE_TRANSCRIPTS` is set: the config write is inert. */
+    envShadowed: boolean;
+    projects: MigrationProjectRef[];
+    /** The USER's own `~/.claude` — the destination store's root. */
+    userHome: string;
+    /** Absolute path of the file the POST would write to. */
+    configPath: string;
+    /** Fingerprint of that file as read for this response. */
+    configVersion: string | null;
+    /** Sweeper working dirs (`<dataDir>/sweepers/<slug>/`), by slug. */
+    sweeperDirs?: Map<string, string>;
+    /** Per-session display name/preview, when the caller has them cheaply. */
+    names?: Map<string, {
+        name?: string;
+        preview?: string;
+    }>;
+    /**
+     * Override the per-request divergence-scan budget. Exists so a test can
+     * exhaust it with kilobytes instead of the 256 MB of pathological transcripts
+     * the real bound would need — the exhaustion path is the one that must not be
+     * silent, so it has to be exercised rather than reasoned about.
+     */
+    scanBudgetBytes?: number;
+}
+interface ChatsDirListing {
+    /** Session ids with a `<id>.jsonl` in `.chats/`. */
+    chats: string[];
+    /** Session ids with a `<id>/` sidecar directory. */
+    chatDirs: Set<string>;
+    /** Entries that move with the project rather than with a chat. */
+    projectExtras: string[];
+    /** Entries matching no known pattern. */
+    unexpected: string[];
+    hasReverts: boolean;
+    hasMemory: boolean;
+    /** Total entries — the probe's whole question. */
+    entryCount: number;
+}
+/** Drop the memoised probe answers (tests; a config write). */
+export declare function resetMigrationProbeCache(): void;
+/**
+ * "Is there anything to migrate?" — one `readdir` per project, no transcript
+ * read and no host-store read at all (§10.1).
+ *
+ * Memoised per project on `mtimeMs:size` of `.chats/` plus the config version,
+ * which costs one `stat` to validate — that is what lets the banner be fetched
+ * on every page load. The host-store term the design's §3.4 cache key carried
+ * is gone with the host-store read it was there for.
+ *
+ * ### `pendingChats` is a lower bound that this implementation makes exact
+ *
+ * The design frames it as a lower bound because the probe "stops counting once
+ * the answer is known". `fs.readdir` hands back the whole list in one call, so
+ * there is no per-entry short-circuit to be had and counting the `*.jsonl`
+ * entries is free — the number is exact. It is still *reported* as a lower
+ * bound, because that is the contract clients were given and narrowing it later
+ * is a breaking change; but the field is `>= 0` rather than `∈ {0, 1}`.
+ *
+ * The one wrinkle the corrected predicate introduces: eligibility is about
+ * ENTRIES and `pendingChats` counts TRANSCRIPTS, so a `.chats/` holding only
+ * `memory/` is `eligible: true` with `pendingChats: 0`. That combination is
+ * correct, not a contradiction — there is real work to do and no chat to do it
+ * to — and it makes the schema's "exact only when 0" gloss wrong in one
+ * direction. Callers must key the banner off `eligible`, never off the count.
+ *
+ * ### `mode === "host"` is not on its own a reason to refuse
+ *
+ * The predicate is the same under both modes, which is the #882 ruling (§2)
+ * superseding the design's §7.2. `host` shipped as an unconditional refusal on
+ * the reasoning "already migrated, nothing to offer", and that is wrong for the
+ * one instance that most needs the offer: flipping to `host` while `.chats/`
+ * still held anything is #708's STRANDED state. `pointChatsDirAt` declines the
+ * redirect against a non-empty real directory (`transcripts.ts:145`), so the old
+ * transcripts sit in a real `.chats/` that nothing reads — and the probe told
+ * exactly those users there was nothing to do.
+ *
+ * The distinction is the DIRECTORY, and it is why {@link readChatsDir} `lstat`s:
+ *
+ * | `.chats/` under `host` | Eligible | Why |
+ * |---|---|---|
+ * | symlink into the host store | no — `already-host` | migrated; the redirect is planted |
+ * | empty real directory | no — `already-host` | the next boot plants it by itself |
+ * | non-empty real directory | **yes** | stranded: the redirect was declined |
+ *
+ * The first two are the overwhelmingly common case and must stay ineligible —
+ * showing a migration banner to everyone who has already migrated is worse than
+ * the bug this narrows. Under `host` the execute path moves the files and skips
+ * the config write (`configWritten: false`, `restartRequired: true`); the next
+ * boot then finds an empty `.chats/`, plants the redirect, and the stranded
+ * chats reappear. That closes the `own → host` half of #708.
+ */
+export declare function probeMigration(input: MigrationInput): Promise<MigrationProbe>;
+/**
+ * One project, classified — everything both halves of the feature need, read
+ * from disk exactly once.
+ *
+ * Shared rather than duplicated because the execute half's step 4 is
+ * "re-enumerate from disk and reconcile the plan against reality" (§4.1): it
+ * needs the *same* classifier, not a similar one. A second enumeration written
+ * against the same directory shapes would drift, and the direction it would
+ * drift in is "execute moves a file the preview promised it would not".
+ */
+export interface MigrationProjectScan {
+    ref: MigrationProjectRef;
+    chatsDir: string;
+    hostStore: string;
+    preserveDir: string;
+    listing: ChatsDirListing;
+    /** False when the host store could not be read; every row is then `unknown`. */
+    hostReadable: boolean;
+    /** `.reverts/` BASE NAMES owned by each chat (not paths — the move helper
+     *  rebuilds both sides from the store roots). */
+    revertsByChat: Map<string, string[]>;
+    /** Every chat, INCLUDING the identical ones the plan omits. */
+    rows: MigrationChatRow[];
+    projectExtras: string[];
+    warnings: MigrationWarning[];
+    candidates: ScanCandidate[];
+}
+/** A conflicted pair that stage 2 could not settle, deferred to stage 3. */
+interface ScanCandidate {
+    row: MigrationChatRow;
+    /** Path of the longer side — the one that would be scanned. */
+    longerPath: string;
+    longerBytes: number;
+    shorterPath: string;
+    shorterBytes: number;
+    /** Which side is longer, i.e. which would be `ahead` on a hit. */
+    longerSide: "own" | "host";
+    /** The ancestor-candidate uuid, or undefined when the tail read found none. */
+    uuid?: string;
+}
+/**
+ * Build the modal's plan: every chat in every project's `.chats/`, classified
+ * against its host store.
+ *
+ * Chats identical on both sides are omitted from the rows — there is no
+ * decision to make — but they are counted in `totals.identical` so a row count
+ * lower than the user's chat total always has an explanation. They still
+ * migrate: the postcondition is about `.chats/` being empty, not about which
+ * chats the user picked.
+ */
+export declare function buildMigrationPlan(input: MigrationInput): Promise<MigrationPlan>;
+/**
+ * Classify one project's `.chats/` against its host store.
+ *
+ * Returns `null` when there is nothing there to migrate: no `.chats/`, an
+ * already-planted symlink, or an empty directory. Everything else — including
+ * an unreadable store — comes back as a scan carrying its own warnings, because
+ * the execute half has to decide what to do about it rather than have it
+ * swallowed here.
+ *
+ * The stage-3 candidates are returned UNSETTLED. Settling them is one shared
+ * budget across the whole request, so the caller has to own it — see
+ * {@link settleCandidates}.
+ */
+export declare function scanProject(project: MigrationProjectRef, input: MigrationInput): Promise<MigrationProjectScan | null>;
+/**
+ * Stage 3 over the deferred candidates, smallest-first against one shared
+ * budget. Ascending order means the budget settles as many rows as it can
+ * before it runs out, and — because it is ascending — the first row that does
+ * not fit proves every later one does not either.
+ *
+ * Returns whether any row came back `unknown`.
+ */
+export declare function settleCandidates(candidates: ScanCandidate[], budgetBytes: number): Promise<boolean>;
+export {};