@adhd/backlog 0.1.2 → 0.1.3

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

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;