@adhd/backlog 0.1.2 → 0.1.4

package/model.d.ts

@@ -90,6 +90,41 @@ export declare class DependencyCycleError extends Error {
     readonly cycle: string[];
     constructor(cycle: string[]);
 }
+/**
+ * BUG-BACKLOG-HUMANID-COLLISION-001 (fix #1 — write-time guard):
+ * `createItemNode` rejects a `family` that is missing/empty/whitespace-only
+ * UNLESS `idOverride` is also given (SPEC.md §5.1's `CreateItemInput.family`
+ * contract: "required unless idOverride given"). Thrown BEFORE
+ * `allocateHumanIdAndInsert`/`computeNextHumanId` ever run, so a caller that
+ * omits `family` (previously silently coerced to the literal string
+ * `"undefined"` by `computeNextHumanId`'s template literal, producing
+ * `humanId: "undefined-001"` and colliding with every other item that hit
+ * the same bug) now fails loudly instead of minting a collision. This is
+ * defense in depth: it must hold regardless of whether an upstream caller's
+ * own input-schema validation (e.g. apigen-core-client's extracted
+ * `CreateItemInput` schema, BUG-APIGEN-CORE-CLIENT-001) enforces `family` as
+ * required — the store's own write path must never trust the caller alone.
+ */
+export declare class InvalidArgumentError extends Error {
+    readonly argument: string;
+    constructor(argument: string, message: string);
+}
+/**
+ * BUG-BACKLOG-HUMANID-COLLISION-001 (fix #2 — read-time guard): every
+ * `(repo, humanId)`-keyed lookup used to silently resolve to "whichever
+ * live node is found first" when more than one live node shared the same
+ * key (the exact shape of the pre-existing `"undefined-001"` collisions,
+ * and the root cause of a real mis-transition this session — see the
+ * backlog item's body). Any lookup that finds >1 live match now throws this
+ * instead of guessing, listing every colliding `nodeId` so a caller can
+ * disambiguate (there is no tool-level nodeId-addressed path yet — the
+ * caller must go through the store's own repair primitives, e.g.
+ * `renameHumanId`, to resolve the collision).
+ */
+export declare class AmbiguousHumanIdError extends Error {
+    readonly nodeIds: number[];
+    constructor(repo: string, humanId: string, nodeIds: number[]);
+}
 export interface DedupeScanInput {
     symbol?: string;
     path?: string;

package/package.json

@@ -1,24 +1,25 @@
 {
   "name": "@adhd/backlog",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "bin": {
     "backlog": "index.js"
   },
   "dependencies": {
+    "@adhd/apigen-core-client": "^0.3.0",
+    "@adhd/apigen-engine-naming": "^0.2.2",
+    "@adhd/apigen-plugin-api-fastify": "^0.2.3",
+    "@adhd/apigen-plugin-batch": "^0.2.2",
+    "@adhd/apigen-plugin-cli-output": "^0.2.3",
+    "@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.3",
+    "@adhd/environment-base-spec": "^0.1.0",
     "@adhd/sox-graph-store": "^0.3.0",
     "better-sqlite3": "^12.10.0",
-    "@adhd/environment": "^0.1.2",
-    "@adhd/environment-base-spec": "^0.1.0",
-    "@adhd/apigen-core-client": "^0.2.1",
-    "@adhd/apigen-plugin-api-fastify": "^0.2.1",
-    "@adhd/apigen-plugin-openapi": "^0.2.1",
-    "@adhd/apigen-plugin-mcp": "^0.2.1",
-    "@adhd/apigen-plugin-batch": "^0.2.0",
-    "@adhd/apigen-plugin-cli-output": "^0.2.1",
-    "@adhd/apigen-engine-naming": "^0.2.1",
-    "yaml": "1.10.3",
     "pino": "10.3.1",
-    "pino-pretty": "13.1.3"
+    "pino-pretty": "13.1.3",
+    "yaml": "1.10.3"
   },
   "assets": [
     "skill"

package/store/crud.d.ts

@@ -1,6 +1,39 @@
 import { GraphBacklogStore } from './graph-backlog-store.js';
 import { BacklogItem, CreateItemInput, CreateItemResult, UpdateItemInput } from '../model.js';
 
+/**
+ * Minimum fraction of the NEW item's meaningful title tokens that must also
+ * appear in a CANDIDATE's title for the candidate to count as a duplicate
+ * (BUG-BACKLOG-DEDUPE-FTS-WEAK-MATCH-001). Exported so callers/tests can
+ * tune it without touching this file's internals.
+ *
+ * Why title-to-title overlap instead of the FTS hit's bm25 `score`:
+ * `store.graph.searchNodes()` (`@adhd/sox-graph-store`) DOES return a
+ * per-hit `score` (`-fts_node.rank`, i.e. a positive, higher-is-better bm25
+ * score) — but bm25 is corpus- and document-length-relative, not an absolute
+ * similarity measure, and empirically it does NOT discriminate this bug's
+ * failure mode: a live probe reproducing the exact reported case (a short
+ * generic new title vs. a long, verbose, unrelated document that happens to
+ * repeat a couple of the new title's common words many times) scored
+ * `~0.0000109`, while a genuine short-title-vs-short-title near-duplicate
+ * scored `~0.0000113` — the SAME order of magnitude, with no clean
+ * separating threshold between them. A long document's sheer token count
+ * inflates its bm25 term-frequency component enough to rival a real
+ * duplicate's score. Title-to-title token overlap has no such document-
+ * length confound: a new item's title can only ever match against a
+ * candidate's (typically similarly short) title, so incidental repetition
+ * buried in a long candidate BODY can no longer count toward "looks like a
+ * duplicate" at all.
+ *
+ * 0.5 (at least half the new title's meaningful tokens must recur in the
+ * candidate's title) was chosen because DESIGN.md §2.4's own worked example
+ * ("same bug, different words") is a near-total title rewrite that still
+ * shares most of its content words ("database connection pool leaks under
+ * load" -> "the database connection pool leaks under load" is 6/6); dropping
+ * to a small minority match (e.g. 1-2 shared generic words out of 5) is
+ * exactly the false-positive shape this bug reports and must NOT pass.
+ */
+export declare const TITLE_OVERLAP_MIN_FRACTION = 0.5;
 declare function dedupeScan(store: GraphBacklogStore, repo: string, input: CreateItemInput): BacklogItem[];
 export declare function createItemNode(store: GraphBacklogStore, input: CreateItemInput): CreateItemResult;
 export declare function getItemNode(store: GraphBacklogStore, repo: string, humanId: string): BacklogItem | null;

package/store/query.d.ts

@@ -6,6 +6,20 @@ 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): NodeRecord[];
 export declare function listItems(store: GraphBacklogStore, filter?: BacklogFilter): 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): NodeRecord | null;
 /**
  * Finds every LIVE node carrying this `humanId`, across ALL repos (no

package/store/structure.d.ts

@@ -33,3 +33,32 @@ export declare function mergeItemsNode(store: GraphBacklogStore, repo: string, k
 export declare function setPriorityNode(store: GraphBacklogStore, repo: string, humanId: string, priority: Priority): BacklogItem;
 export declare function attachToPlanNode(store: GraphBacklogStore, repo: string, humanId: string, planSlug: string): void;
 export declare function assignItemNode(store: GraphBacklogStore, repo: string, humanId: string, to: string, by: string): 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): BacklogItem;