opencode-swarm 7.163.1 → 7.164.1

package/dist/cli/{skill-generator-0es21fck.js → skill-generator-wqbazppk.js}

@@ -33,34 +33,33 @@ import {
   sanitizeSlug,
   selectCandidateEntries,
   writeEvalStub
-} from "./index-n985274d.js";
-import"./index-08y8pccg.js";
-import"./index-hm239n1p.js";
+} from "./index-e630pvvw.js";
+import"./index-wnf1ej2q.js";
+import"./index-k8j7m0e2.js";
 import"./index-rtry5xyf.js";
 import"./index-q7sjgr1y.js";
-import"./index-f923njwh.js";
-import"./index-4p0wyz5p.js";
-import"./index-66073kej.js";
+import"./index-jczbtx2x.js";
+import"./index-1af3rb5n.js";
+import"./index-pmmfhzsp.js";
 import"./index-zg9d392c.js";
 import"./index-n832052r.js";
-import"./index-dtn0pne5.js";
+import"./index-v56mhyhs.js";
 import"./index-z6xqpmqg.js";
 import"./index-r3mvsbtq.js";
-import"./index-tnpf9wwv.js";
-import"./index-x2f1f011.js";
+import"./index-862c0xhc.js";
+import"./index-2s40e3b0.js";
 import"./index-9e6fdz2h.js";
 import"./index-4rhhvd1a.js";
-import"./index-cqgpvx2d.js";
-import"./index-9xd073d4.js";
+import"./index-j0ajeary.js";
+import"./index-2yd732fd.js";
 import"./index-zjygnfay.js";
 import"./index-ae75rja9.js";
-import"./index-n2mhyect.js";
-import"./index-n67vx5zw.js";
+import"./index-6kd3jnaf.js";
+import"./index-6t35714n.js";
 import"./index-bk5tah7q.js";
-import"./index-9crtmnqg.js";
-import"./index-3b762978.js";
-import"./index-2zgjcmmc.js";
-import"./index-ed5ykebp.js";
+import"./index-36nt17m8.js";
+import"./index-f9nfknjg.js";
+import"./index-1b1h770t.js";
 import"./index-7g4c7s5r.js";
 import"./index-bpmtbmy9.js";
 import"./index-zgwm4ryv.js";

package/dist/cli/{sqlite-loader-c92413n7.js → sqlite-loader-8zefc142.js}

@@ -3,7 +3,7 @@ import {
   _internals,
   createNodeDatabaseCtor,
   loadDatabaseCtor
-} from "./index-n249fbw7.js";
+} from "./index-zaab1wz9.js";
 import"./index-a76rekgs.js";
 export {
   loadDatabaseCtor,

package/dist/cli/{telemetry-x4zggfd7.js → telemetry-q51s6tyt.js}

@@ -14,7 +14,7 @@ import {
   startHeartbeatTracking,
   stopHeartbeatTracking,
   telemetry
-} from "./index-2zgjcmmc.js";
+} from "./index-1b1h770t.js";
 import"./index-bpmtbmy9.js";
 import"./index-a76rekgs.js";
 export {

package/dist/cli/{worktree-collision-ownership-043dg8gg.js → worktree-collision-ownership-c0030qbm.js}

@@ -6,14 +6,13 @@ import {
   WORKTREE_PROVISIONING_OWNER_LEASE_MS,
   removeWorktreeProvisioningOwner,
   scanWorktreeProvisioningOwnersForRecovery
-} from "./index-fckfgptr.js";
+} from "./index-qbr05tbw.js";
 import {
   scanDelegationFallbacksForRecovery,
   scanDelegationsForRecovery
-} from "./index-ma52g2pq.js";
+} from "./index-yc415pzf.js";
 import"./index-ddszzne4.js";
-import"./index-w7ekntej.js";
-import"./index-dtn0pne5.js";
+import"./index-v56mhyhs.js";
 import"./index-z6xqpmqg.js";
 import {
   bunSpawn
@@ -23,12 +22,11 @@ import {
   resolveGitExecutable
 } from "./index-9e6fdz2h.js";
 import"./index-4rhhvd1a.js";
-import"./index-cqgpvx2d.js";
+import"./index-j0ajeary.js";
 import"./index-zjygnfay.js";
-import"./index-9crtmnqg.js";
-import"./index-3b762978.js";
-import"./index-2zgjcmmc.js";
-import"./index-ed5ykebp.js";
+import"./index-36nt17m8.js";
+import"./index-f9nfknjg.js";
+import"./index-1b1h770t.js";
 import"./index-7g4c7s5r.js";
 import"./index-bpmtbmy9.js";
 import"./index-zgwm4ryv.js";

package/dist/cli/{worktree-isolation-hk42yxw7.js → worktree-isolation-09qq8066.js}

@@ -21,67 +21,64 @@ import {
   sanitizeWorktreeTaskId,
   standardWorktreeByCallID,
   standardWorktreeSerializationSessions
-} from "./index-0tervb1m.js";
-import"./index-xyhmt813.js";
-import"./index-qynqyfgj.js";
-import"./index-r56f3f81.js";
-import"./index-d3azve4r.js";
-import"./index-0103w5pf.js";
+} from "./index-2ee2g27m.js";
+import"./index-6097tx05.js";
+import"./index-wv4b01ex.js";
+import"./index-r5jn0ah5.js";
+import"./index-5084szce.js";
+import"./index-vkckf2ch.js";
 import"./index-txdagbh7.js";
-import"./index-n249fbw7.js";
 import"./index-3146wmgv.js";
-import"./index-n985274d.js";
-import"./index-2v06a1yh.js";
-import"./index-t34daffb.js";
+import"./index-e630pvvw.js";
+import"./index-6ay5zp1v.js";
+import"./index-h2f21caa.js";
 import"./index-70ha9e09.js";
-import"./index-c8s9a3zh.js";
-import"./index-9ss2m4rs.js";
-import"./index-7n9jznv0.js";
+import"./index-y2f5s2cf.js";
+import"./index-hcn69kp0.js";
+import"./index-zaab1wz9.js";
+import"./index-x2qmpkth.js";
 import"./index-zsrtt42s.js";
-import"./index-g3znh2yd.js";
+import"./index-hzaw10zh.js";
 import"./index-3f7hqtgg.js";
-import"./index-fckfgptr.js";
-import"./index-08y8pccg.js";
-import"./index-hm239n1p.js";
+import"./index-qbr05tbw.js";
+import"./index-wnf1ej2q.js";
+import"./index-k8j7m0e2.js";
 import"./index-rtry5xyf.js";
-import"./index-zjme8atd.js";
-import"./index-d9gdwh34.js";
-import"./index-ma52g2pq.js";
+import"./index-n1wcq816.js";
+import"./index-5bza8nxz.js";
+import"./index-yc415pzf.js";
 import"./index-ddszzne4.js";
-import"./index-mmngnxev.js";
-import"./index-w7ekntej.js";
-import"./index-2n1ym7jb.js";
-import"./index-kvra3nv1.js";
-import"./index-8ada7ag7.js";
+import"./index-b98r3pyv.js";
+import"./index-vdgw2k4c.js";
+import"./index-dhzsvmx6.js";
 import"./index-556ja8an.js";
 import"./index-4fwbbad3.js";
 import"./index-b43rt5ph.js";
 import"./index-q7sjgr1y.js";
-import"./index-f923njwh.js";
-import"./index-4p0wyz5p.js";
+import"./index-jczbtx2x.js";
+import"./index-1af3rb5n.js";
 import {
   resolveWorktreeIsolationConfig
-} from "./index-66073kej.js";
+} from "./index-pmmfhzsp.js";
 import"./index-zg9d392c.js";
 import"./index-n832052r.js";
-import"./index-dtn0pne5.js";
+import"./index-v56mhyhs.js";
 import"./index-z6xqpmqg.js";
 import"./index-r3mvsbtq.js";
-import"./index-tnpf9wwv.js";
-import"./index-x2f1f011.js";
+import"./index-862c0xhc.js";
+import"./index-2s40e3b0.js";
 import"./index-9e6fdz2h.js";
 import"./index-4rhhvd1a.js";
-import"./index-cqgpvx2d.js";
-import"./index-9xd073d4.js";
+import"./index-j0ajeary.js";
+import"./index-2yd732fd.js";
 import"./index-zjygnfay.js";
 import"./index-ae75rja9.js";
-import"./index-n2mhyect.js";
-import"./index-n67vx5zw.js";
+import"./index-6kd3jnaf.js";
+import"./index-6t35714n.js";
 import"./index-bk5tah7q.js";
-import"./index-9crtmnqg.js";
-import"./index-3b762978.js";
-import"./index-2zgjcmmc.js";
-import"./index-ed5ykebp.js";
+import"./index-36nt17m8.js";
+import"./index-f9nfknjg.js";
+import"./index-1b1h770t.js";
 import"./index-7g4c7s5r.js";
 import"./index-bpmtbmy9.js";
 import"./index-zgwm4ryv.js";

package/dist/db/canonical-project.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Canonical project identity for the SQLite durable-state foundation (issue #2480).
+ *
+ * Policy (docs/sqlite-durable-state.md §Identity):
+ * - This helper answers ONE question: "are these two directory spellings the same project
+ *   root, so they must share ONE `.swarm/swarm.db` connection?" It is project-root
+ *   IDENTITY, not security-sensitive file equivalence — those are different threat models
+ *   and deliberately different helpers (issue #2474 / Workstream B1 owns the repo-wide
+ *   identity rollout; this is the DB-layer-scoped implementation D1 builds on).
+ * - Resolution: `path.resolve` (lexical cleanup) → best-effort `fs.realpathSync`
+ *   (collapses symlinks/junctions and, on Windows, expands 8.3 short names) →
+ *   case-fold the WHOLE key on win32 only. On POSIX, case is significant: `/a/B` and
+ *   `/a/b` are different roots and must stay isolated.
+ * - Never throws: if `realpathSync` fails (broken symlink, permission, race), the
+ *   lexically-resolved path is used as-is. A canonicalization failure must not prevent
+ *   the project DB from opening; it only risks a duplicate handle for exotic spellings,
+ *   which is the pre-existing behavior.
+ */
+import { realpathSync } from 'node:fs';
+/** DI seam for tests (fault-injected realpath failures). */
+export declare const _internals: {
+    realpathSync: typeof realpathSync;
+};
+/**
+ * Return the canonical cache key for a project directory.
+ *
+ * - `C:\Proj` and `c:\proj\` map to one key on Windows (one DB handle).
+ * - A symlink or junction to the same directory maps to one key on every platform.
+ * - Distinct POSIX casings remain distinct roots.
+ */
+export declare function canonicalProjectKey(directory: string): string;

package/dist/db/db-errors.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Typed errors for the SQLite durable-state foundation (issue #2480).
+ *
+ * Callers use `category` to make fail-open decisions and to emit ONE coalesced
+ * advisory per condition instead of repeating raw SQLite errors. Messages never
+ * contain SQL text or user file contents; at most the `.swarm/swarm.db` artifact
+ * name appears.
+ */
+export type ProjectDbErrorCategory = 'mkdir_failed' | 'driver_unavailable' | 'open_failed' | 'migration_failed';
+export type DbWriteErrorCategory = 'disk_full' | 'read_only' | 'corrupt' | 'busy' | 'unknown';
+export declare class ProjectDbError extends Error {
+    readonly category: ProjectDbErrorCategory;
+    constructor(category: ProjectDbErrorCategory, message: string);
+}
+export declare class DbWriteError extends Error {
+    readonly category: DbWriteErrorCategory;
+    constructor(category: DbWriteErrorCategory, message: string);
+}
+/**
+ * Classify a write/open failure into a `DbWriteErrorCategory` from errno and
+ * SQLite error text. Used by the group-commit writer to decide retry/degrade
+ * behavior (issue #2480 disk-full / read-only / corrupt handling).
+ */
+export declare function classifyDbWriteError(err: unknown): DbWriteErrorCategory;

package/dist/db/driver-parity.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Bun ↔ Node driver-parity contract for `.swarm/swarm.db` (issue #2480
+ * obligation 2).
+ *
+ * A single suite, run against WHATEVER driver the shared sqlite loader
+ * resolved:
+ * - under `bun test`: the real `bun:sqlite` driver (and the node adapter
+ *   against the strict fake in `sqlite-loader.test.ts`);
+ * - under the merge-queue smoke job (`scripts/repro-1873.mjs`, 3-OS, real
+ *   Node 22): the real `node:sqlite` driver through the adapter.
+ *
+ * The contract pins the behavioral deltas documented for #1873/#2480:
+ * - EXACT parameter counts: every bound-parameter call must pass exactly as
+ *   many values as the statement has placeholders. `node:sqlite` rejects a
+ *   mismatched count (`SQLITE_RANGE`); `bun:sqlite` tolerates some lax forms.
+ *   Portable code never relies on the lax form.
+ * - Multi-statement strings only through the no-parameter `run(sql)` path
+ *   (which routes to `exec` on both drivers).
+ * - Transaction + SAVEPOINT nesting round trip.
+ * - WAL / busy_timeout / synchronous pragma reads.
+ */
+import type { Database } from 'bun:sqlite';
+export interface DriverParityProbe {
+    /** True when the resolved driver is the node:sqlite adapter. */
+    isNodeAdapter: boolean;
+}
+/**
+ * Assert the driver-parity contract on a FRESH database (the caller owns its
+ * lifecycle and closes it). Throws on the first violation.
+ */
+export declare function runDriverParityContract(db: Database, probe?: DriverParityProbe): void;

package/dist/db/durability.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Per-table durability classes for `.swarm/swarm.db` (issue #2480 obligation 4).
+ *
+ * SQLite's `synchronous` pragma is connection-scoped and takes effect at the next
+ * commit, so "per-table durability classes" are implemented by escalating the
+ * pragma around write transactions whose target table demands it:
+ *
+ * - `full`  — terminal-state streams (authoritative rows whose loss changes an
+ *   outcome): `synchronous = FULL` for the wrapping transaction. Authoritative
+ *   state must never inherit the rebuildable-index durability setting.
+ * - `normal` — telemetry/operational/diagnostic rows: `synchronous = NORMAL`
+ *   (WAL + NORMAL is durable across application crashes; only an OS/power
+ *   failure can lose the tail — acceptable for rebuildable streams).
+ *
+ * A batch that contains ANY `full`-class write runs the WHOLE transaction at
+ * FULL (escalation rule, group-commit writer consults `batchDurabilityClass`).
+ */
+import type { Database } from 'bun:sqlite';
+/** The durability class of every table in `.swarm/swarm.db`. */
+export declare const DURABILITY_CLASSES: Readonly<Record<string, 'full' | 'normal'>>;
+/** Escalation rule: any full-class op makes the whole batch full-class. */
+export declare function batchDurabilityClass(classes: Iterable<'full' | 'normal'>): 'full' | 'normal';
+/** Apply the `synchronous` pragma for a durability class. Cheap and idempotent. */
+export declare function applySynchronousForClass(db: Database, cls: 'full' | 'normal'): void;
+/**
+ * Run `fn` with the connection's `synchronous` pragma set for `cls`, restoring
+ * NORMAL afterwards. `fn` is expected to complete its own transaction (or be
+ * composed inside one); the pragma takes effect at commit time.
+ *
+ * The connection default is NORMAL (telemetry class), so restoring NORMAL — not
+ * "the previous value" — is the correct post-condition: nothing outside the
+ * foundation ever sets a different value on this connection.
+ *
+ * NESTING CAVEAT (final-critic note): nesting a normal-class helper inside an
+ * open full-class transaction would restore NORMAL before the OUTER commit.
+ * No production path nests these helpers today (group-commit ops never call
+ * the qa-gate/receipt writers); if nesting is ever introduced, restore the
+ * pre-call value instead.
+ */
+export declare function withDurabilityClass<T>(db: Database, cls: 'full' | 'normal', fn: () => T): T;

package/dist/db/group-commit-writer.d.ts

@@ -0,0 +1,117 @@
+/**
+ * Group-commit writer for `.swarm/swarm.db` low-risk stores (issue #2480
+ * obligation 8: "queue -> one txn per flush").
+ *
+ * Design:
+ * - One writer per canonical project root, created lazily on first use and
+ *   closed with the DB handle (`closeGroupCommitWriter`). Nothing here runs at
+ *   plugin init.
+ * - `enqueue(op)` queues a write op. A flush applies EVERY queued op inside
+ *   ONE `BEGIN IMMEDIATE` transaction (the qa-gate-profile lock precedent —
+ *   plain `db.transaction()` issues a deferred BEGIN that lets two writers
+ *   deadlock-escalate to SQLITE_BUSY under two-windows contention).
+ * - Durability escalation: if any op in the batch is `full`-class, the whole
+ *   transaction runs with `PRAGMA synchronous = FULL` (authoritative state
+ *   never inherits the rebuildable-index setting); otherwise NORMAL.
+ * - Backpressure: the queue is bounded; overflow forces a synchronous flush
+ *   rather than dropping writes.
+ * - Failure handling: a `BEGIN IMMEDIATE` busy or a disk-full/read-only
+ *   failure keeps the queue intact, classifies the error (`db-errors.ts`),
+ *   and coalesces to ONE advisory/telemetry signal per degradation episode
+ *   (cooldown); the next flush retries. Ops themselves throwing rolls the
+ *   transaction back and rethrows (the enqueuing store decides fail-open).
+ */
+import type { Database } from 'bun:sqlite';
+import { type DbWriteErrorCategory } from './db-errors.js';
+import { getProjectDb } from './project-db.js';
+/** A single durable write, applied inside a flush transaction. */
+export interface GroupCommitOp {
+    /** Durability class of the target table/stream (escalation input). */
+    durability: 'full' | 'normal';
+    /** Apply the write. Must only touch `.swarm/swarm.db` via the given handle. */
+    run: (db: Database) => void;
+}
+/**
+ * Detect "the underlying handle was closed" failures across BOTH drivers:
+ * bun:sqlite says "database has closed"; node:sqlite raises
+ * ERR_INVALID_STATE "database is not open".
+ */
+declare function isClosedHandleError(err: unknown): boolean;
+/** Queue bound — overflow forces a synchronous flush (never a silent drop). */
+export declare const MAX_QUEUED_OPS = 1024;
+/** Ops at or above this count trigger an immediate synchronous flush. */
+export declare const FLUSH_THRESHOLD_OPS = 64;
+/**
+ * Test seam (repo `_internals` convention): the self-heal rebind's handle
+ * acquisition, injectable so tests can deterministically exercise the
+ * eviction-on-double-closed-handle path (a rebind that returns an ALREADY
+ * closed handle).
+ */
+export declare const _internals: {
+    getProjectDb: typeof getProjectDb;
+    isClosedHandleError: typeof isClosedHandleError;
+};
+export declare class GroupCommitWriter {
+    private db;
+    private queue;
+    private flushing;
+    private degraded;
+    private lastAdvisoryAt;
+    private closed;
+    /**
+     * Canonical cache key this writer was registered under (set by
+     * getGroupCommitWriter). A flush against a CLOSED underlying handle —
+     * possible when a close site evicted the DB handle without closing the
+     * writer — evicts the writer from the registry so the next store call
+     * rebinds to the fresh handle instead of failing forever.
+     */
+    private registryKey;
+    constructor(db: Database);
+    get queuedOpCount(): number;
+    /** #2480: record the registry key for self-healing eviction. */
+    bindRegistryKey(key: string): void;
+    /**
+     * Queue a write op. A synchronous flush runs immediately when the queue
+     * reaches the flush threshold (backpressure), and again at the hard
+     * `MAX_QUEUED_OPS` bound. Throws `DbWriteError` from an inline flush
+     * (threshold or hard bound) when the flush fails — the op is then NOT
+     * accepted; the caller's fail-open handling owns the loss.
+     */
+    enqueue(op: GroupCommitOp): void;
+    /**
+     * Apply every queued op in ONE immediate transaction. On op failure the
+     * transaction rolls back and the error rethrows (queue emptied — the ops
+     * are not idempotently retryable by this layer). On busy/disk-full/
+     * read-only the queue is RETAINED and a typed `DbWriteError` throws.
+     *
+     * Self-healing (#2480): if the underlying handle was CLOSED underneath
+     * this writer (a close site evicted the DB handle without closing the
+     * writer — the pre-fix /swarm close shape), the flush rebinds to a fresh
+     * handle ONCE and re-applies the batch, so post-close writes complete
+     * transparently instead of failing until restart.
+     */
+    flushSync(): void;
+    /** Async facade over the synchronous flush (callers `await` durability). */
+    flush(): Promise<void>;
+    /** Close the writer and drop any unflushed queue. */
+    close(): void;
+    private applyBatch;
+    private noteDegraded;
+    /** Test/observability access to the degradation state. */
+    get degradation(): {
+        category: DbWriteErrorCategory;
+        until: number;
+    } | null;
+}
+/**
+ * Return the group-commit writer for a project root, creating it (and the DB
+ * handle) lazily on first use. Never runs at plugin init.
+ */
+export declare function getGroupCommitWriter(directory: string): GroupCommitWriter;
+/** Flush + close the writer for a root (dispose/exit/close paths). */
+export declare function closeGroupCommitWriter(directory: string): void;
+/** Flush + close every writer, then close every DB handle. Test/close use. */
+export declare function closeAllGroupCommitWriters(): void;
+/** Number of open writers (tests/observability). */
+export declare function getOpenGroupCommitWriterCount(): number;
+export {};

package/dist/db/health.d.ts

@@ -0,0 +1,35 @@
+/**
+ * swarm.db health probe (issue #2480 obligation 5).
+ *
+ * The one sanctioned read-only surface for diagnose-style health checks: runs
+ * the size-capped quick_check + pragma/migration-failure probes and returns a
+ * structured snapshot. Keeping the SQL here (inside `src/db/**`) means the
+ * raw-handle confinement and writer-registry seams stay honest — callers like
+ * `diagnose-service` consume a plain object.
+ */
+/** quick_check size cap: an oversized DB reports `too_large` instead of scanning inline. */
+export declare const SWARM_DB_QUICK_CHECK_MAX_BYTES: number;
+export type SwarmDbHealthSnapshot = {
+    kind: 'absent';
+} | {
+    kind: 'too_large';
+    sizeBytes: number;
+} | {
+    kind: 'open';
+    quickCheck: string;
+    journalMode: string;
+    pageCount: number;
+    migrationFailures: number;
+    /** #2480 review F-07: stale marker file present (a recorded
+     * failure whose cleanup could not run — surfaced for diagnosis). */
+    staleMarker: boolean;
+} | {
+    kind: 'error';
+    category: string;
+    message: string;
+};
+/**
+ * Probe `.swarm/swarm.db` health. Never opens-for-create (an absent DB is
+ * `absent`, which callers render as healthy) and never throws.
+ */
+export declare function getSwarmDbHealthSnapshot(directory: string): SwarmDbHealthSnapshot;

package/dist/db/insight-candidate-store.d.ts

@@ -0,0 +1,61 @@
+/**
+ * swarm.db store for insight candidates (issue #2480 D1 migration).
+ *
+ * Replaces `.swarm/insight-candidates.jsonl` (locked read-modify-write JSONL
+ * queue) with the append-only event-stream pattern:
+ *
+ * - Table `insight_candidate` — PK (stream_id, version) is the
+ *   UNIQUE(stream_id, version) stream contract; versions are assigned
+ *   MAX(version)+1 inside the appending transaction.
+ * - `appendInsightCandidatesDb` batches appends through the group-commit
+ *   writer (queue -> one txn per flush).
+ * - `consumeInsightCandidatesDb` is the dual-contract transaction: SELECT the
+ *   pending batch + UPDATE consumed_at for exactly those versions in ONE
+ *   `BEGIN IMMEDIATE` transaction, so concurrent appends and consumes can
+ *   never lose or double-take a candidate.
+ * - Telemetry-sink retention: consumed rows are DELETE-pruned after 7 days,
+ *   and the pending queue is FIFO-capped at 500 (both bounds carried over
+ *   from the legacy store's limits).
+ *
+ * Payloads are opaque serialized JSON strings; the hook layer owns parsing,
+ * validation, and identity (`resolveInsightCandidateId` recomputes identity
+ * from content, so no id column exists).
+ */
+/** The single stream id used by this store (table is stream-shaped for D2+). */
+export declare const INSIGHT_CANDIDATE_STREAM_ID = "insight-candidates";
+/** Legacy queue filename (imported then cold-archived as `.jsonl.imported`). */
+export declare const INSIGHT_CANDIDATES_LEGACY_FILE = "insight-candidates.jsonl";
+/** FIFO cap on pending (unconsumed) candidates — carried over from the file store. */
+export declare const INSIGHT_PENDING_CAP = 500;
+/** Consumed-row retention window (telemetry-sink DELETE-based retention). */
+export declare const INSIGHT_CONSUMED_RETENTION_DAYS = 7;
+export interface InsightCandidateRow {
+    payload: string;
+    createdAt: string;
+}
+/**
+ * One-time (per process, per canonical root) lazy import of the legacy
+ * `.swarm/insight-candidates.jsonl` queue. Never runs at plugin init.
+ */
+export declare function ensureInsightLegacyImported(directory: string): void;
+/**
+ * Append candidates to the stream via the group-commit writer and await the
+ * flush (the legacy store's append was awaited too — durability semantics
+ * are preserved; batching coalesces concurrent callers and multi-candidate
+ * calls into one transaction).
+ */
+export declare function appendInsightCandidatesDb(directory: string, rows: InsightCandidateRow[]): Promise<void>;
+/**
+ * Atomically consume up to `limit` pending candidates: the SELECT and the
+ * consumed_at UPDATE happen in ONE immediate transaction (dual-contract
+ * event+state transition). Consumed rows older than the retention window are
+ * DELETE-pruned in the same transaction. Returns the consumed payloads,
+ * oldest first.
+ */
+export declare function consumeInsightCandidatesDb(directory: string, limit: number): string[];
+/** Count pending (unconsumed) candidates — status/diagnostics surface. */
+export declare function countPendingInsightCandidatesDb(directory: string): number;
+/** List pending payloads, oldest first (postmortem raw-content surface). */
+export declare function listPendingInsightCandidatesDb(directory: string, max: number): string[];
+/** Test hook: reset the per-process import guards. */
+export declare function _resetInsightImportGuards(): void;

package/dist/db/legacy-import.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Idempotent legacy file → swarm.db import (issue #2480 obligation 3).
+ *
+ * Contract (docs/sqlite-durable-state.md §Legacy import):
+ * - Legacy artifact PRESENT + target table/stream EMPTY → import every record
+ *   in ONE `BEGIN IMMEDIATE` transaction (emptiness re-checked inside the
+ *   transaction so a concurrent importer cannot double-import) → on commit,
+ *   rename the artifact to `<name>.imported` (bounded Windows rename retry).
+ * - Crash before commit → nothing imported; the next run retries (idempotent).
+ * - Crash after commit before rename → the next run sees a NON-empty table;
+ *   the stale file is left in place (never re-imported, never silently
+ *   deleted) with a once-per-process warning. This also covers a file that
+ *   reappeared because an older plugin version wrote it again: those lines
+ *   are preserved on disk rather than destroyed.
+ * - Artifact absent, or table already populated → no-op.
+ *
+ * Import runs lazily on first store use, never at plugin init (the
+ * knowledge-receipts migration precedent).
+ */
+import { renameSync } from 'node:fs';
+import { getProjectDb } from './project-db.js';
+/**
+ * Size cap for a single legacy artifact import (#2480 review F-02 — same
+ * guard convention as MAX_TRACEABILITY_BYTES in design-doc-drift). The live
+ * stores were FIFO/entry-bounded when they were files, so anything beyond
+ * this is pathological; it is skipped inert (never imported, never renamed)
+ * rather than loaded into memory.
+ */
+export declare const MAX_LEGACY_IMPORT_BYTES: number;
+export interface LegacyImportResult {
+    /** Rows imported (0 when the import conditions were not met). */
+    imported: number;
+    /** Lines/files skipped because they failed validation. */
+    skipped: number;
+    /** True when the legacy artifact was renamed to `.imported`. */
+    archived: boolean;
+}
+declare function warnStaleLegacyOnce(key: string, fileName: string): void;
+/**
+ * DI seam for tests: the LOW-LEVEL rename is fault-injectable so the retry
+ * loop itself stays under test (replacing the loop would test nothing).
+ */
+export declare const _internals: {
+    renameSync: typeof renameSync;
+    warnStaleLegacyOnce: typeof warnStaleLegacyOnce;
+    maxLegacyImportBytes: () => number;
+};
+/**
+ * Import a legacy `.jsonl` file into an append-only stream table.
+ *
+ * `parseLine` returns the row payload string for a valid line or null to skip
+ * (corrupt line). Rows are inserted with versions 1..n in file order. The
+ * emptiness probe is `streamCount(db)` (e.g. rows for the stream).
+ */
+export declare function importLegacyJsonl(directory: string, opts: {
+    fileName: string;
+    /** Count existing rows for the target stream (inside the txn). */
+    streamCount: (db: ReturnType<typeof getProjectDb>) => number;
+    /** Insert one row at the given version; payload from the parsed line. */
+    insertRow: (db: ReturnType<typeof getProjectDb>, version: number, payload: string) => void;
+    parseLine: (line: string) => string | null;
+}): LegacyImportResult;
+/**
+ * Import a family of legacy `.json` files into an entity table keyed by
+ * `(kind, phase)`. Files are discovered by exact prefix/suffix match in
+ * `.swarm/` (readdir — no user-supplied paths), the phase is parsed from the
+ * filename, and each file's parsed+validated object becomes the row payload.
+ */
+export declare function importLegacyJsonFiles(directory: string, opts: {
+    filePrefix: string;
+    kind: string;
+    /** Count existing rows for the kind (inside the txn). */
+    kindCount: (db: ReturnType<typeof getProjectDb>) => number;
+    /** Upsert one row; payload is the serialized JSON file content. */
+    upsertRow: (db: ReturnType<typeof getProjectDb>, phase: number, payload: string) => void;
+}): LegacyImportResult;
+export {};