@adhd/backlog 0.1.9 → 1.0.1

package/store/lifecycle.d.ts

@@ -1,36 +0,0 @@
-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>;
-/**
- * `transitionStatus(id, 'IN_PROGRESS', ...)` + an implicit `claimItem(id, by)`.
- * If the item is actively claimed (not stale) by someone else, the claim
- * step returns `held` and startWork refuses — starting work on a
- * contended item would silently override the claim protocol otherwise.
- */
-export declare function startWorkNode(store: GraphBacklogStore, repo: string, humanId: string, by: string): Promise<BacklogItem>;
-export declare function addCitationNode(store: GraphBacklogStore, repo: string, humanId: string, citation: Citation): Promise<BacklogItem>;
-export declare function appendNoteNode(store: GraphBacklogStore, repo: string, humanId: string, by: string, text: string): Promise<BacklogItem>;
-/**
- * Marks every terminal, non-excluded item in scope as archived
- * (`metadata.archivedAt`) and returns them — the graph node itself is NEVER
- * deleted (bi-temporal history is permanent). Rendering the archived set to
- * CHANGELOG.md-formatted markdown is `client.ts`'s job (via `markdown.ts`) —
- * store/* never depends on markdown.ts (DESIGN.md §1 layering).
- */
-export declare function archiveTerminalItems(store: GraphBacklogStore, scope: StatsScope, opts?: ArchiveOpts): Promise<BacklogItem[]>;

package/store/mapping.d.ts

@@ -1,101 +0,0 @@
-import { BacklogItem, BacklogStatus, Citation, Note, Priority } from '../model.js';
-import { NodeRecord } from '@adhd/sox-graph-store';
-
-export declare const BACKLOG_ITEM_TAG = "backlog-item";
-export declare const BACKLOG_PLAN_TAG = "backlog-plan";
-export declare const BACKLOG_ASSIGNEE_TAG = "backlog-assignee";
-/**
- * Mirrors `@adhd/sox-graph-store`'s PRIVATE (unexported) `hashContent()`
- * (`sha256(content.trim().toLowerCase())`) exactly. Needed only by
- * `updateItemNode` (crud.ts), which writes `node.content`/`node.content_hash`
- * directly via raw SQL (DESIGN.md §14's sanctioned escape hatch for the one
- * gap `touch()` doesn't cover — DEBT-BACKLOG-CONTENT-IMMUTABLE-001) and must
- * keep `content_hash` consistent with the `content` it just wrote, exactly as
- * `writeNode()` would have. If upstream ever changes its normalization, this
- * copy must change with it — there is no shared primitive to import instead.
- */
-export declare function computeContentHash(content: string): string;
-/**
- * `@adhd/sox-graph-store`'s `searchNodes(query)` binds `query` DIRECTLY as an
- * FTS5 `MATCH` argument, parsed by FTS5's own boolean/column-filter query
- * grammar — NOT a plain-text search. `searchNodes`'s own `query.replace(/"/g,
- * '""')` cannot make this safe for arbitrary text: doubling an EXISTING `"`
- * always yields an EVEN number of quote characters in the output, so a
- * caller can never end up with a validly single-quoted phrase this way
- * (verified empirically — wrapping a title in quotes before calling
- * `searchNodes` still throws). A title containing a bare `-`, `:`, `(`, `)`,
- * or `"` (all real English titles — "off-by-one", "fix: the thing" — not
- * edge cases) crashes `createItemNode`'s dedupe scan outright with a raw
- * `SqliteError`, since `force:true` (the only path that SKIPS the dedupe
- * scan) is not the default. `dedupeScan` (crud.ts) uses this to strip every
- * FTS5-syntax-significant character to a space before searching — this is
- * BEHAVIOR-PRESERVING for the already-working case (a title with no special
- * characters passes through unchanged, still an implicit-AND bareword
- * query), and merely prevents the CRASH for the common case that hits one.
- */
-/**
- * Strips every FTS5-syntax-significant character to a space before a title/
- * grep term ever reaches `searchNodes`'s raw MATCH bind (dedupeScan and
- * `queryItemNodes`'s grep path, BUG-BACKLOG-DEDUPE-FTS-SYNTAX-CRASH-001).
- *
- * The original fix (2026-07) only stripped the small set of characters found
- * in the reported crash: `"():^*-`. `#` (an entirely ordinary character in a
- * real title, e.g. "Fixes #123" or this file's own regression test) was
- * discovered independently to ALSO crash `searchNodes` with `fts5: syntax
- * error near "#"` — and probing FTS5's actual grammar directly (not
- * guessing) turned up a much longer list that crashes the same way: `. { }
- * ~ [ ] @ ! $ % & = < > ? / \ ; ,` — `{` is the most dangerous of these
- * (`no such column: create` — it gets parsed as column-filter syntax rather
- * than merely erroring, a correctness risk beyond a crash). A second
- * whack-a-mole char-by-char addition would leave the same class of gap open
- * for whatever punctuation mark comes up next, so this strips every
- * character that is NOT a Unicode letter, number, underscore, or whitespace
- * — the complete, non-enumerable-by-hand safe set for an FTS5 bareword
- * query — rather than continuing to enumerate a denylist.
- */
-export declare function sanitizeFtsQuery(text: string): string;
-/**
- * The JSON shape persisted in `node.meta` (DESIGN.md §2.2/§4.1). Every
- * mutating store operation reads the CURRENT full object, computes a new
- * COMPLETE object, and writes it back via `mutateMetadata` — `touch()`
- * replaces `meta` wholesale (verified, DESIGN.md §14 point 4), so a partial
- * write here would silently drop every other field.
- */
-export interface BacklogNodeMeta {
-    humanId: string;
-    kind: string;
-    family: string;
-    title: string;
-    body: string;
-    status: BacklogStatus;
-    priority?: Priority;
-    repo: string;
-    projectPath?: string;
-    plan?: string;
-    /** Source markdown path this item was imported from, if any (DEBT-BACKLOG-IMPORT-PLAN-PROVENANCE-001). */
-    importedFrom?: string;
-    assignee?: string;
-    claimedBy?: string;
-    claimedAt?: string;
-    citations: Citation[];
-    notes: Note[];
-    createdAt: string;
-    updatedAt: string;
-    /** Set by archiveResolved — excludes the item from renderToMarkdown's default view. */
-    archivedAt?: string;
-    /** Dedupe-scan exact-match fields (DESIGN.md §2.4). */
-    dedupeSymbol?: string;
-    dedupePath?: string;
-    dedupeErrorText?: string;
-}
-export declare function humanIdKind(humanId: string): string;
-export declare function humanIdFamily(humanId: string): string;
-/** See the file-level DEVIATION doc comment for why the marker is appended. */
-export declare function buildNodeContent(repo: string, humanId: string, title: string, body: string): string;
-export declare function buildNodeName(repo: string, humanId: string): string;
-/** DESIGN.md §2.2 — importance derived deterministically from priority. */
-export declare function importanceForPriority(priority: Priority | undefined): number;
-export declare function buildTags(kind: string, family: string, userTags?: readonly string[]): string[];
-/** A node counts as a live backlog item iff it carries the tag AND is not superseded (DESIGN.md §14). */
-export declare function isLiveBacklogItemNode(node: NodeRecord): boolean;
-export declare function toBacklogItem(node: NodeRecord): BacklogItem;

package/store/mutate-metadata.d.ts

@@ -1,8 +0,0 @@
-import { BacklogNodeMeta } from './mapping.js';
-import { GraphBacklogStore } from './graph-backlog-store.js';
-
-export declare class NotFoundError extends Error {
-    readonly nodeId: number;
-    constructor(nodeId: number);
-}
-export declare function mutateMetadata<M = BacklogNodeMeta>(store: GraphBacklogStore, nodeId: number, updater: (current: M) => M): Promise<M>;

package/store/query.d.ts

@@ -1,68 +0,0 @@
-import { BacklogNodeMeta } from './mapping.js';
-import { GraphBacklogStore } from './graph-backlog-store.js';
-import { AuditTrailResult, BacklogFilter, BacklogItem, DependencyGraph, StatsScope, TopoOrderResult, BacklogItemNotFoundError } from '../model.js';
-import { NodeRecord } from '@adhd/sox-graph-store';
-
-/** Raw NodeRecord query — used internally where the full node (not just the mapped BacklogItem) is needed. */
-export declare function queryItemNodes(store: GraphBacklogStore, filter?: BacklogFilter): Promise<NodeRecord[]>;
-export declare function listItems(store: GraphBacklogStore, filter?: BacklogFilter): Promise<BacklogItem[]>;
-/**
- * BUG-BACKLOG-HUMANID-COLLISION-001 fix #2: this is THE shared `(repo,
- * humanId) -> NodeRecord` lookup every store module funnels through
- * (`crud.ts`/`lifecycle.ts`/`structure.ts`/`client.ts`'s `requireItem*`
- * helpers all call this, directly or via `buildNotFoundError`'s sibling
- * miss path). It used to silently resolve to "whichever live node happens
- * to match `name`, else whichever is first" when more than one live node
- * shared the same `(repo, humanId)` key — the exact shape of the
- * pre-existing `"undefined-001"` collisions, and the root cause of a real
- * mis-transition (see the backlog item body: a `resolveItem` call intended
- * for one node silently landed on a different, unrelated one). Any lookup
- * that finds >1 live match now throws `AmbiguousHumanIdError` instead of
- * guessing.
- */
-export declare function findItemNode(store: GraphBacklogStore, repo: string, humanId: string): Promise<NodeRecord | null>;
-/**
- * Finds every LIVE node carrying this `humanId`, across ALL repos (no
- * `namespace` filter) — BUG-BACKLOG-REPO-LOOKUP-UX-001's "did you mean repo
- * X?" hint needs this to distinguish "this humanId truly doesn't exist" from
- * "it exists, just filed under a different repo string than the caller
- * passed." Used only on the miss path (`buildNotFoundError`) — never on the
- * hot successful-lookup path, so it costs nothing when a lookup is correct.
- */
-export declare function findHumanIdInAnyRepo(store: GraphBacklogStore, humanId: string): Promise<NodeRecord[]>;
-/**
- * Every distinct repo value any LIVE backlog item is currently filed under.
- * Used by `createItemNode`'s soft repo-drift warning (write-time half of
- * BUG-BACKLOG-REPO-LOOKUP-UX-001) — an empty store (no items yet) has no
- * "known" repos, so the very first item filed under any repo string never
- * triggers a false-positive warning.
- */
-export declare function knownRepos(store: GraphBacklogStore): Promise<Set<string>>;
-/**
- * Builds the `BacklogItemNotFoundError` every miss site throws — the single
- * place that decides whether a "did you mean repo X?" hint is warranted
- * (BUG-BACKLOG-REPO-LOOKUP-UX-001, read-time half). Callers pass the SAME
- * `(repo, humanId)` they just failed to find via `findItemNode` — this
- * re-queries WITHOUT the `namespace` restriction to see if the humanId lives
- * under a different repo string instead.
- */
-export declare function buildNotFoundError(store: GraphBacklogStore, repo: string, humanId: string): Promise<BacklogItemNotFoundError>;
-export declare function computeStats(store: GraphBacklogStore, scope?: StatsScope): Promise<import('../model.js').BacklogStats>;
-export declare function spotlight(store: GraphBacklogStore, scope?: StatsScope, limit?: number): Promise<BacklogItem[]>;
-export declare function blockers(store: GraphBacklogStore, repo: string, humanId: string): Promise<BacklogItem[]>;
-export declare function readyItems(store: GraphBacklogStore, scope?: StatsScope): Promise<BacklogItem[]>;
-export declare function dependencyGraph(store: GraphBacklogStore, scope?: StatsScope): Promise<DependencyGraph>;
-export declare function topoOrder(store: GraphBacklogStore, scope?: StatsScope): Promise<TopoOrderResult>;
-export declare function staleClaims(store: GraphBacklogStore, maxAgeMin: number, scope?: StatsScope): Promise<BacklogItem[]>;
-/**
- * Bi-temporal history + supersession chain (SPEC.md §5.6, DESIGN.md §2.3).
- * DEVIATION: the store does not persist a full mutation event log (no
- * separate transitions/claims-over-time table) — `history` is therefore
- * honestly derived from the durable fields we DO keep (a synthetic
- * `created` entry, every real `note`, every real `citation`), not a
- * fabricated replay of every status/claim change. Citation entries reuse
- * `item.updatedAt` as their timestamp since `Citation` carries no `at` field
- * of its own. Filed as DEBT-BACKLOG-AUDIT-TRAIL-PARTIAL-001.
- */
-export declare function auditTrail(store: GraphBacklogStore, repo: string, humanId: string): Promise<AuditTrailResult>;
-export type { BacklogNodeMeta };

package/store/repo-migration.d.ts

@@ -1,51 +0,0 @@
-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

@@ -1,42 +0,0 @@
-/** 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/structure.d.ts

@@ -1,66 +0,0 @@
-import { GraphBacklogStore } from './graph-backlog-store.js';
-import { BacklogItem, CreateItemInput, Priority } from '../model.js';
-
-export declare function addDependencyNode(store: GraphBacklogStore, repo: string, humanId: string, dependsOnHumanId: string): Promise<void>;
-/**
- * `@adhd/sox-graph-store` exposes no edge-delete primitive (only
- * `invalidate()` for nodes, bi-temporal) — DESIGN.md §14 explicitly sanctions
- * a raw `DELETE` on the store-owned handle as the one place the adapter
- * reaches past the `GraphBackend` API, confirmed against the real `edge`
- * table column names (`src`/`dst`/`rel`). F-01/F-02: routed through the
- * store-adapter's `executeRun` query surface (the raw `store.db` handle is
- * gone) — same SQL, same semantics.
- */
-export declare function removeDependencyNode(store: GraphBacklogStore, repo: string, humanId: string, dependsOnHumanId: string): Promise<void>;
-export declare function linkRelatedNode(store: GraphBacklogStore, repo: string, humanIdA: string, humanIdB: string): Promise<void>;
-/**
- * DESIGN.md §14 point 2 (CONFIRMED against the real source): `supersede(oldId,
- * newContent, meta)` writes `SUPERSEDES` new -> old, sets `is_superseded=1`
- * on the old node, and mints the new node — ALL in one internal transaction.
- * It does NOT invalidate the old node (`t_invalid` stays null) — SPEC.md
- * §5.5 additionally requires the old item to become bi-temporally invalid
- * with `reason`, so this composes `supersede()` with a status update (BEFORE
- * invalidation — `touch()`/`mutateMetadata` throw once `t_invalid` is set)
- * and a final `invalidate(oldId, reason)`.
- */
-export declare function supersedeItemNode(store: GraphBacklogStore, repo: string, oldHumanId: string, newInput: CreateItemInput, reason: string): Promise<BacklogItem>;
-/** Creates N children, each linked child PART_OF parent. Parent is left open. */
-export declare function splitItemNode(store: GraphBacklogStore, repo: string, parentHumanId: string, children: CreateItemInput[]): Promise<BacklogItem[]>;
-/**
- * `SAME_AS(drop -> keep)` per DESIGN.md §14 point 2 (obsolete -> canonical,
- * matching the `supersede()` convention), then `invalidate(drop, reason)`.
- * Returns the KEPT item.
- */
-export declare function mergeItemsNode(store: GraphBacklogStore, repo: string, keepHumanId: string, dropHumanId: string, reason: string): Promise<BacklogItem>;
-export declare function setPriorityNode(store: GraphBacklogStore, repo: string, humanId: string, priority: Priority): Promise<BacklogItem>;
-export declare function attachToPlanNode(store: GraphBacklogStore, repo: string, humanId: string, planSlug: string): Promise<void>;
-export declare function assignItemNode(store: GraphBacklogStore, repo: string, humanId: string, to: string, by: string): Promise<BacklogItem>;
-/**
- * BUG-BACKLOG-HUMANID-COLLISION-001 fix #3 (repair primitive): re-ids a
- * single, `nodeId`-scoped live backlog item to a new `humanId` within the
- * same `repo`. `nodeId`-scoped (not `(repo, oldHumanId)`-keyed) so this is
- * unambiguous EVEN under the exact collision it exists to repair — every
- * other `(repo, humanId)`-keyed lookup in this file would throw
- * `AmbiguousHumanIdError` on a colliding key (fix #2, `findItemNode`), so a
- * repair tool needs a way in that doesn't go through that same lookup.
- *
- * There is no tool-level rename/re-id operation exposed anywhere in this
- * store today (the backlog item's fix direction #5 explicitly calls this
- * gap out) — this is that primitive, added as part of this fix, kept
- * store-internal (not wired to `client.ts`/the MCP surface) since it is a
- * narrow one-off repair tool, not a general-purpose end-user operation.
- *
- * Guards:
- *  - the node at `nodeId` must be live and its CURRENT `metadata.humanId`
- *    must equal `oldHumanId` (sanity check — refuses to rename the wrong
- *    node out from under a caller who mis-copied a nodeId).
- *  - `newHumanId` must not already resolve to a DIFFERENT live node in this
- *    `repo` (refuses to rename INTO a fresh collision).
- *  - re-derives `kind`/`family` from `newHumanId`, rebuilds `tags` (swapping
- *    the old kind/family tags for the new ones, preserving every other
- *    user tag) and the node `name`/`content`/`content_hash` (which both bake
- *    in `repo::humanId` — DESIGN.md §2.2, mapping.ts's `buildNodeName`/
- *    `buildNodeContent`) so the renamed node is indistinguishable from one
- *    that was always minted under `newHumanId`.
- */
-export declare function renameHumanIdNode(store: GraphBacklogStore, repo: string, nodeId: number, oldHumanId: string, newHumanId: string): Promise<BacklogItem>;