@adhd/backlog 0.1.6 → 0.1.8

package/model.d.ts

@@ -145,6 +145,16 @@ export interface CreateItemInput {
     dedupeScan?: DedupeScanInput;
     /** Skip the dedupe gate and file anyway (planner override after reviewing candidates). */
     force?: boolean;
+    /**
+     * Citations to attach at creation time (BUG-BACKLOG-CREATE-ITEM-DROPS-CITATIONS-001).
+     * Previously absent from this interface entirely — a caller passing
+     * `citations` on create got a success response with the item created and
+     * the citations silently discarded (no such field existed to carry them
+     * through). Validated the same way as every other citation write path
+     * (`Citation.file` non-empty — see `lifecycle.ts`'s `assertValidCitation`)
+     * and rejected as a whole (no partial write) before allocation runs.
+     */
+    citations?: Citation[];
 }
 export interface CreateItemResult {
     item: BacklogItem;
@@ -367,3 +377,61 @@ export interface MigrationStatusResult {
 export interface SetMigrationPhaseResult extends MigrationStatusResult {
     configPath: string;
 }
+/** One item's move within a `RepoMigrationPlan` — always dry-runnable, never mutates on its own. */
+export interface RepoMigrationPlanItem {
+    nodeId: number;
+    /** The humanId this item currently carries in `fromRepo`. */
+    humanId: string;
+    /**
+     * The humanId this item will carry in `toRepo` — identical to `humanId`
+     * unless `renamed` is true. Deterministic: preserves the item's `family`
+     * prefix and picks the next free number in that family within `toRepo`
+     * (mirrors `computeNextHumanId`'s own `max + 1` allocation rule), scanning
+     * BOTH `toRepo`'s pre-existing items AND every earlier item in this same
+     * plan already assigned a number in that family — so two colliding items
+     * sharing a family (e.g. two different `BUG-001`s) never collide with each
+     * other's rename target either.
+     */
+    targetHumanId: string;
+    /** True iff `humanId` already exists as a LIVE item in `toRepo` and had to be renamed to avoid an id collision. */
+    renamed: boolean;
+    title: string;
+    status: BacklogStatus;
+}
+/**
+ * The full, deterministic plan for moving every live item out of `fromRepo`
+ * into `toRepo` — computed by a pure read-only scan (`planRepoMigration`),
+ * safe to call repeatedly and to inspect before ever mutating anything.
+ */
+export interface RepoMigrationPlan {
+    fromRepo: string;
+    toRepo: string;
+    items: RepoMigrationPlanItem[];
+    /** Count of `items` where `renamed === true` — the collision count. */
+    collisionCount: number;
+}
+/** Per-item outcome of actually executing a `RepoMigrationPlan`. Every planned item gets exactly one of these — nothing is ever silently dropped. */
+export interface RepoMigrationItemResult {
+    nodeId: number;
+    fromHumanId: string;
+    toHumanId: string;
+    renamed: boolean;
+    ok: boolean;
+    /** Present iff `ok === false` — the item was left untouched in `fromRepo`, never partially moved. */
+    error?: string;
+}
+/**
+ * `migrateRepo`'s result. When `dryRun` is true (the default — a caller must
+ * pass `dryRun:false` explicitly to mutate anything), `results` is absent and
+ * NOTHING was written; `plan` alone previews exactly what would happen.
+ */
+export interface RepoMigrationResult {
+    fromRepo: string;
+    toRepo: string;
+    dryRun: boolean;
+    plan: RepoMigrationPlan;
+    /** Present only when `dryRun === false`. One entry per `plan.items` entry, same order. */
+    results?: RepoMigrationItemResult[];
+    succeeded?: number;
+    failed?: number;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adhd/backlog",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "bin": {
     "backlog": "index.js"
   },
@@ -13,10 +13,10 @@
     "@adhd/apigen-plugin-ir-cache": "^0.1.0",
     "@adhd/apigen-plugin-mcp": "^0.2.3",
     "@adhd/apigen-plugin-openapi": "^0.2.2",
-    "@adhd/environment": "^0.1.6",
+    "@adhd/environment": "^0.1.5",
     "@adhd/environment-base-spec": "^0.1.0",
     "@adhd/sox-graph-store": "^0.8.4",
-    "@adhd/sox-store-adapter": "^0.5.8",
+    "@adhd/sox-store-adapter": "^0.7.0",
     "@adhd/sox-telemetry": "^0.2.0",
     "pino": "10.3.1",
     "pino-pretty": "13.1.3",

package/store/lifecycle.d.ts

@@ -1,6 +1,19 @@
 import { GraphBacklogStore } from './graph-backlog-store.js';
 import { ArchiveOpts, BacklogItem, BacklogStatus, Citation, StatsScope, TransitionOpts } from '../model.js';
 
+/**
+ * `Citation.file` is required at the TypeScript/JSON-Schema level
+ * (BUG-APIGEN-CORE-CLIENT-001 makes that presence check reach the extracted
+ * schema), but presence alone still accepts `""`/whitespace — a citation
+ * with no actual file is not evidence. Every write path that accepts a
+ * caller-supplied `Citation` (inline on `transitionStatus`/`resolveItem`, and
+ * standalone `addCitation`) runs every entry through this before it is
+ * persisted. Also reused by `crud.ts`'s `createItemNode` and
+ * `structure.ts`'s `supersedeItemNode` for citations supplied inline on
+ * `CreateItemInput` (BUG-BACKLOG-CREATE-ITEM-DROPS-CITATIONS-001) — one
+ * validation rule, every write path.
+ */
+export declare function assertValidCitation(citation: Citation): void;
 export declare function transitionStatusNode(store: GraphBacklogStore, repo: string, humanId: string, status: BacklogStatus, opts: TransitionOpts): Promise<BacklogItem>;
 /** Sugar for transitionStatus into any terminal status (SPEC.md §5.4). */
 export declare function resolveItemNode(store: GraphBacklogStore, repo: string, humanId: string, status: BacklogStatus, opts: TransitionOpts): Promise<BacklogItem>;

package/store/repo-migration.d.ts

@@ -0,0 +1,51 @@
+import { GraphBacklogStore } from './graph-backlog-store.js';
+import { BacklogItem, RepoMigrationItemResult, RepoMigrationPlan, RepoMigrationPlanItem, RepoMigrationResult } from '../model.js';
+
+/**
+ * Pure, read-only, deterministic migration plan for every LIVE item whose
+ * `namespace` is `fromRepo` — deliberately namespace-scoped (not
+ * `metadata.repo`-scoped) so an item whose two repo fields have already
+ * diverged (found empirically: `FEAT-001`/`FEAT-002`, `namespace:"adhd"` but
+ * `metadata.repo:"PseudoSky/adhd"`) is still picked up and fully repaired,
+ * not silently skipped because its rendered `repo` already "looks" correct.
+ *
+ * Collision resolution walks `sourceItems` in humanId order (stable,
+ * reproducible across repeated calls) and, for a colliding humanId, assigns
+ * the next free number in that family — tracked in an in-memory
+ * `familyMaxInTarget` map seeded from `toRepo`'s REAL current max per family
+ * and incremented for every rename already planned earlier in this same
+ * pass, so two same-family collisions in one batch never target each other.
+ */
+export declare function planRepoMigration(store: GraphBacklogStore, fromRepo: string, toRepo: string): Promise<RepoMigrationPlan>;
+/**
+ * Executes exactly ONE planned move, re-verifying the live state at the
+ * exact node still matches what the plan assumed (a stale plan — the source
+ * item moved/mutated, or the target humanId got claimed — since planning
+ * throws `InvalidArgumentError` rather than silently proceeding on bad
+ * assumptions; `executeRepoMigration` catches this per-item so one stale
+ * entry never aborts the whole batch or gets silently skipped).
+ *
+ * Mirrors `structure.ts`'s `renameHumanIdNode` exactly, generalized to also
+ * rewrite `namespace` (which `renameHumanIdNode` deliberately refuses to
+ * touch — same-repo only) — see this module's top-of-file doc comment for
+ * why `touch()` cannot do that column and a raw `UPDATE` is required.
+ */
+export declare function migrateRepoItemNode(store: GraphBacklogStore, item: RepoMigrationPlanItem, fromRepo: string, toRepo: string, actor: string): Promise<BacklogItem>;
+/**
+ * Executes every item in `plan`, sequentially (each rename must observe the
+ * previous item's real committed state before computing/verifying the next
+ * — see `planRepoMigration`'s doc comment on why this must not run in
+ * parallel). Every planned item gets exactly one result — `ok:true` or
+ * `ok:false` with `error` — so a failure is always visible and never
+ * silently drops an item from the report; a per-item failure does not abort
+ * the remaining items (an aborted batch would leave an unpredictable subset
+ * moved with no way to tell which from the caller's plan alone).
+ */
+export declare function executeRepoMigration(store: GraphBacklogStore, plan: RepoMigrationPlan, actor: string): Promise<RepoMigrationItemResult[]>;
+/**
+ * The single entry point client.ts/CLI/MCP expose. `dryRun` defaults to
+ * `true` — a caller MUST pass `dryRun:false` explicitly to mutate anything,
+ * so a bare "preview this migration" call (e.g. an agent double-checking
+ * before committing) can never accidentally execute.
+ */
+export declare function migrateRepo(store: GraphBacklogStore, fromRepo: string, toRepo: string, actor: string, dryRun?: boolean): Promise<RepoMigrationResult>;

package/store/serve-lock.d.ts

@@ -0,0 +1,42 @@
+/** Thrown when another live process already holds the serve lock for this
+ *  store. Carries the holder's pid and the lock file path so callers can
+ *  surface both — refusing SILENTLY (a bare non-zero exit with no reason)
+ *  is exactly the failure mode that let this incident go undetected. */
+export declare class ServeLockHeldError extends Error {
+    readonly holderPid: number;
+    readonly lockPath: string;
+    constructor(holderPid: number, lockPath: string);
+}
+export interface ServeLockHandle {
+    /** Idempotent. Removes the lock file ONLY if it still names this process
+     *  as holder (never deletes a lock a later process legitimately took over
+     *  after detecting this one as stale — that would delete a live peer's
+     *  lock out from under it). */
+    release: () => void;
+}
+/** `:memory:` has no filesystem identity — no cross-process concern, no lock. */
+export declare function isLockableDbPath(dbPath: string): boolean;
+/** Canonicalizes to the realpath when the file (or its parent dir) exists,
+ *  so two spellings of the same store collapse to one lock identity; falls
+ *  back to a plain absolute resolve when nothing on disk exists yet (a
+ *  not-yet-created db is still a valid lock anchor — mirrors sox-ecosystem's
+ *  `singleton.ts` `canonicalizePath`, reimplemented here for the same reason
+ *  noted in this file's header). */
+export declare function canonicalDbPath(dbPath: string): string;
+export declare function serveLockPath(dbPath: string): string;
+/**
+ * Acquire the `backlog serve` writer lock for `dbPath`. Fails LOUD and
+ * IMMEDIATELY (no spin-wait/retry-until-timeout — a refused `serve` should
+ * say why right now, not silently poll and eventually give up) when a live
+ * holder is found: throws {@link ServeLockHeldError} naming the holder's
+ * pid. A lock file whose recorded pid is no longer alive (crash, SIGKILL,
+ * native panic — the same "can't run cleanup code" cases
+ * `signal-cleanup.ts`'s own doc comment is honest about) is detected via a
+ * liveness probe on READ, not relied on to have been cleaned up by the dead
+ * process, and is reclaimed automatically.
+ *
+ * Call this BEFORE opening the store; release the returned handle only
+ * AFTER the store is fully closed (see this file's header re: the
+ * shutdown-window).
+ */
+export declare function acquireServeLock(dbPath: string): ServeLockHandle;

package/store/signal-cleanup.d.ts

@@ -0,0 +1,38 @@
+export interface SignalCleanupHandle {
+    /** Removes the listeners this call installed (idempotent). Call from the
+     *  owning function's own `finally` once its normal-path cleanup has run,
+     *  so a signal arriving AFTER that point is not double-handled. */
+    dispose: () => void;
+}
+/**
+ * Installs SIGINT/SIGTERM handlers that run `cleanup()` at most once, then
+ * exit with the conventional 128+signum code. `cleanup` is expected to be
+ * `closeGraphBacklogStoreSafe`-shaped (never throws) but is wrapped so a
+ * defect there can never suppress the exit or hang the process.
+ *
+ * @param cleanup Releases this connection's own store lease. Called with no
+ *   arguments; capture whatever store handle it needs via closure — this
+ *   lets callers install the handler BEFORE the store finishes opening
+ *   (`cleanup` reads a `let store` that may still be `undefined` at signal
+ *   time, in which case the underlying `closeGraphBacklogStoreSafe(undefined)`
+ *   is a documented no-op).
+ * @param onExit Test-only override for `process.exit` (never overridden in
+ *   production) so a red→green test can observe "would have exited with N"
+ *   without actually terminating the test runner's process.
+ */
+export declare function installSignalCleanup(cleanup: () => Promise<void>, onExit?: (code: number) => void): SignalCleanupHandle;
+/**
+ * True iff nothing on this process already listens for SIGINT/SIGTERM.
+ * `startBacklogServer` uses this to avoid installing a SECOND, competing
+ * handler when its caller (`serve.ts`'s `runServeCommand`) has already
+ * registered its own SIGINT/SIGTERM → `AbortController.abort()` handling
+ * BEFORE ever calling into this function — that existing handler already
+ * overrides Node's default terminate-without-cleanup behaviour for the
+ * entire async store-open window, and it drives a *graceful* drain (fastify/
+ * MCP transport teardown via the aborted `signal`) that a second,
+ * unconditional close+`process.exit` handler would race and potentially cut
+ * short. Direct/embedded callers of `startBacklogServer` that do NOT go
+ * through `serve.ts` have no such external coverage, so they get this
+ * module's own handler instead.
+ */
+export declare function hasExternalSignalHandling(): boolean;