@adhd/backlog 0.1.9 → 1.0.1

package/install-skill.d.ts

@@ -7,6 +7,29 @@ export declare const ALL_HOSTS: readonly SkillHost[];
  *  re-derives — and risks desyncing from — this resolution rule. */
 export declare function resolveCodexHomeDir(home: string, homeOverride?: string): string;
 export declare function hostSkillsDir(host: SkillHost, scope: SkillScope, cwd: string, homeOverride?: string): string;
+/**
+ * A USAGE error — the caller typed something wrong — as opposed to a genuine
+ * internal fault. BUG-BACKLOG-INSTALLSKILL-UX-001: `install-skill`/`install`
+ * are special-cased in `cli.ts` BEFORE the apigen command table is built, so
+ * they never get the outcome-envelope error handling the six mounted verbs
+ * get. Their argument errors used to propagate to the bin entry-guard, which
+ * prints `err.stack` — burying a perfectly good one-line message under ten
+ * frames of minified dist. Distinguishing usage errors by TYPE (rather than
+ * catching everything) keeps real faults loud and stack-bearing while giving
+ * typos the short, actionable output the mounted verbs already produce.
+ */
+export declare class BacklogUsageError extends Error {
+    constructor(message: string);
+}
+/**
+ * Prints a usage error the SAME way the apigen-mounted verbs and every
+ * other CLI command's own rejection path already do — a machine-readable
+ * `{"code":"invalid_argument","message":…}` as the last stderr line, exit
+ * code 2 (`CLI_EXIT_CODE['invalid_argument']`) — plus the human-readable
+ * usage text, so a reader gets both the parse and the fix in one screen.
+ */
+export declare function failUsage(err: BacklogUsageError, helpText: string): void;
+export declare const INSTALL_SKILL_HELP_TEXT = "backlog install-skill [--host claude|codex|opencode|all] [--scope user|project]\n\nCopies the packaged backlog SKILL.md into an agent host's skills directory.\n(`backlog install` is the richer successor \u2014 it also registers the MCP server.)\n\n  --host <name>   claude | codex | opencode | all (default: all)\n  --scope <name>  user | project (default: user)\n                  \"user\" is the machine-wide install (~/.claude/skills/...);\n                  there is no \"global\" \u2014 that is spelled \"user\" here.\n\nExamples:\n  backlog install-skill\n  backlog install-skill --host opencode --scope user\n  backlog install-skill --host claude --scope project\n";
 export interface InstallSkillResult {
     host: SkillHost;
     scope: SkillScope;

package/ir-artifact.d.ts

@@ -0,0 +1,86 @@
+import { Operation } from '@adhd/apigen-core-client';
+
+/** The artifact filename emitted into `dist/` by the `ir-artifact` subcommand. */
+export declare const BACKLOG_IR_ARTIFACT_FILENAME = "api.ir.json";
+/**
+ * The extractor version this build expects — the installed
+ * `@adhd/apigen-core-client` package version. An artifact whose recorded
+ * `extractorVersion` differs (e.g. a package baked against one core-client
+ * release and consumed under another) is refused, because a changed extractor
+ * can change extraction output for byte-identical input. This is the SAME
+ * value `extract-live.ts` stamps into every runtime-cache entry
+ * (`CORE_CLIENT_VERSION` there re-exports this constant), so the baked path,
+ * the fallback cache, and the artifact gate can never disagree.
+ *
+ * Read here (not in `extract-live.ts`) precisely because this module must stay
+ * ts-morph-free: a bare `package.json` version read is pure metadata.
+ */
+export declare const EXPECTED_EXTRACTOR_VERSION: string;
+/**
+ * Resolves the directory holding the built `api.d.ts`/`api.ir.json` for the
+ * currently running module. Three layouts are supported without needing to
+ * distinguish them explicitly (published npm package, this repo's own
+ * `nx build backlog` output, and vitest running `src/` in place):
+ *
+ *  1. PUBLISHED (`node_modules/@adhd/backlog/dist/index.js`): `api.d.ts` is a
+ *     sibling of the running module.
+ *  2. DEV-BUILT (`entrypoint/backlog/dist/index.js`): identical sibling shape.
+ *  3. VITEST (`entrypoint/backlog/src/...` transformed in place): `api.d.ts`
+ *     is one level up and back down, under `../dist`.
+ *
+ * Probing "is api.d.ts sitting right next to me?" before falling back to the
+ * vitest-only `../dist` shape covers all three. Moved here from `server.ts`
+ * (verbatim, including this rationale) so the ts-morph-free artifact reader and
+ * `server.ts` share ONE resolution — `extract-live.ts` imports it too, never a
+ * second, drift-prone copy.
+ */
+export declare function backlogDistDir(): string;
+/** Absolute path to the baked artifact inside `distDir`. */
+export declare function bakedIrArtifactPath(distDir: string): string;
+/**
+ * Reads and VALIDATES the baked IR artifact for `distDir`.
+ *
+ * Returns `operations` ONLY when every gate passes; returns `undefined` (and
+ * NEVER throws — a corrupt/partial artifact must degrade to the fallback, not
+ * crash startup) on any of:
+ *  - the artifact file is missing or unreadable;
+ *  - it is not valid JSON, or does not carry an `operations` array;
+ *  - `formatVersion` != the current entry format;
+ *  - `extractorVersion` != {@link EXPECTED_EXTRACTOR_VERSION};
+ *  - `artifactSource` is absent/malformed;
+ *  - `api.d.ts` is missing, its byte length differs from the recorded one, or
+ *    its sha256 does not match the recorded one (SOURCE-HASH-MISMATCH);
+ *  - the `artifactSource.deps` full-`.d.ts`-surface map is absent/malformed, or
+ *    the CURRENT `distDir` `*.d.ts` surface no longer matches it — an imported
+ *    sibling declaration drifted even though `api.d.ts` did not
+ *    (SURFACE-HASH-MISMATCH). Both are the never-serve-stale gate.
+ *
+ * @returns the baked operations, or `undefined` (never a throw) on any of the
+ *   above — every one degrades to the live extraction fallback.
+ */
+export declare function readBakedIrArtifact(distDir: string): Operation[] | undefined;
+/**
+ * Writes the baked IR artifact to `outFile`, recording the provenance the
+ * reader re-validates against: the source `.d.ts` path (audit), its sha256 and
+ * byte length, plus a sha256 per EVERY `*.d.ts` under the artifact's `dist/`
+ * (`artifactSource.deps`). Uses the plugin's shared `atomicWriteJson`, so the
+ * artifact is published atomically and durably exactly like a runtime-cache
+ * entry — a build killed mid-write can never leave a half-written artifact
+ * behind.
+ *
+ * The per-file `deps` map is what makes the reader's freshness gate cover the
+ * FULL extracted surface rather than only `api.d.ts`: extraction resolves
+ * types through `api.d.ts`'s local siblings, so their content is part of what
+ * the recorded `operations` depends on. See {@link readBakedIrArtifact}.
+ *
+ * `extractorVersion` is passed explicitly (the `ir-artifact` subcommand
+ * supplies {@link EXPECTED_EXTRACTOR_VERSION}) rather than read here, so the
+ * written artifact always records the version of the extractor that actually
+ * produced `operations` — not merely the version installed at write time.
+ */
+export declare function writeBakedIrArtifact(args: {
+    apiDts: string;
+    outFile: string;
+    extractorVersion: string;
+    operations: Operation[];
+}): Promise<void>;

package/package.json

@@ -1,27 +1,44 @@
 {
   "name": "@adhd/backlog",
-  "version": "0.1.9",
+  "version": "1.0.1",
   "bin": {
-    "backlog": "index.js"
+    "adhd-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.5",
-    "@adhd/environment-base-spec": "^0.1.0",
-    "@adhd/sox-graph-store": "^0.8.6",
-    "@adhd/sox-store-adapter": "^0.7.0",
-    "@adhd/sox-telemetry": "^0.2.1",
+    "@adhd/apigen-base-logical": "^0.1.3",
+    "@adhd/apigen-core-client": "^0.3.2",
+    "@adhd/apigen-engine-naming": "^0.2.4",
+    "@adhd/apigen-plugin-api-fastify": "^0.2.5",
+    "@adhd/apigen-plugin-batch": "^0.2.4",
+    "@adhd/apigen-plugin-cli-output": "^0.2.5",
+    "@adhd/apigen-plugin-ir-cache": "^0.1.2",
+    "@adhd/apigen-plugin-mcp": "^0.3.0",
+    "@adhd/apigen-plugin-openapi": "^0.2.4",
+    "@adhd/environment": "^0.1.7",
+    "@adhd/environment-base-spec": "^0.1.2",
+    "@adhd/environment-builder": "^0.1.6",
+    "@adhd/sox-graph-store": "^0.11.1",
+    "@adhd/sox-hybrid-search": "^0.5.0",
+    "@adhd/sox-semantic": "^0.1.8",
+    "@adhd/sox-store-adapter": "^0.10.0",
+    "@adhd/sox-telemetry": "^0.3.2",
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "ajv": "^8.20.0",
+    "ajv-formats": "2.1.1",
+    "commander": "^14.0.3",
+    "fastify": "^4.0.0",
     "pino": "10.3.1",
     "pino-pretty": "13.1.3",
+    "ts-json-schema-generator": "^2.3.0",
+    "ts-morph": "^23.0.0",
+    "typescript": "^5.5.0",
+    "vite": "~5.0.13",
     "yaml": "1.10.3"
   },
+  "optionalDependencies": {
+    "@adhd/sox-embedding-provider": "^0.6.0",
+    "@adhd/sox-vector-store": "^0.7.2"
+  },
   "assets": [
     "skill"
   ],
@@ -30,5 +47,24 @@
   "typings": "./index.d.ts",
   "publishConfig": {
     "access": "public"
+  },
+  "description": "Graph-store backlog for multi-agent teams - queryable, claimable, multi-agent-safe issue tracking with CLI and MCP",
+  "keywords": [
+    "backlog",
+    "issue-tracking",
+    "graph",
+    "cli",
+    "mcp",
+    "multi-agent"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/PseudoSky/adhd.git",
+    "directory": "entrypoint/backlog"
+  },
+  "homepage": "https://github.com/PseudoSky/adhd/tree/main/entrypoint/backlog#readme",
+  "bugs": {
+    "url": "https://github.com/PseudoSky/adhd/issues"
   }
 }

package/query/card.d.ts

@@ -0,0 +1,31 @@
+import { IIssueAuditEntry, IIssueCard, IIssueField, IIssueRef } from './types.js';
+import { EdgeRecord, GraphBackend, NodeRecord } from '@adhd/sox-graph-store';
+
+/** SPEC.md §6.5's `assertKnownFields` — unknown name → `BacklogValidationError` naming it, never a silent drop. */
+export declare function assertKnownIssueFields(fields: readonly string[] | undefined): asserts fields is readonly IIssueField[] | undefined;
+/** `status.meta.metadata.terminal` — the closedness knob (DATA_MODEL.md §3, SPEC.md §2). Defaults to `false` for a status row written before the field existed, never `true` by omission (a closedness knob that defaults closed would silently exclude items from open-item views). */
+export declare function isStatusTerminal(statusRecord: NodeRecord | undefined): boolean;
+/** The full audit trail for an issue — `audits` edges FROM the issue (SPEC.md §3: `audits: * → audit (1:n)`, the subject is the edge SOURCE), sorted oldest-first. */
+export declare function resolveAuditTrail(graph: GraphBackend, issueId: number, outgoing?: EdgeRecord[]): Promise<IIssueAuditEntry[]>;
+/**
+ * `blockers` (SPEC.md §5.2's definition, restated onto the `blocks` edge,
+ * §6.2): the set of issues that `blocks` this one (incoming
+ * `blocks` edges — `e.dst === issueId`) and are NOT YET terminal — "what's
+ * actually blocking it right now," never the full historical blocker set.
+ */
+export declare function resolveBlockers(graph: GraphBackend, issueId: number): Promise<IIssueRef[]>;
+/** `related` — both directions of `relates_to` (an `n:m` symmetric-in-practice rel, §3), deduplicated. */
+export declare function resolveRelated(graph: GraphBackend, issueId: number, outgoing?: EdgeRecord[]): Promise<IIssueRef[]>;
+export interface IAssembleIssueCardOptions {
+    /** Score from a `searchRanked`/`searchNodes` response — populates `_score` when requested (§5a). */
+    score?: number;
+    /** Pre-fetched outgoing edges (`getEdges({src: issue.id})`) — pass when the caller already has them (e.g. a batch `query` page) to avoid a redundant round trip. */
+    outgoingEdges?: EdgeRecord[];
+}
+/**
+ * Project `issue` onto the requested `fields` (default: the five-field terse
+ * card, SPEC.md §6.5). `uid` is always populated regardless of `fields`.
+ */
+export declare function assembleIssueCard(graph: GraphBackend, issue: NodeRecord, fields: readonly IIssueField[], opts?: IAssembleIssueCardOptions): Promise<IIssueCard>;
+/** Batch-assemble cards for a page of issue nodes, sharing one `getNodesByIds`-batched catalog/placement resolution pass where possible. Falls back to per-issue assembly (still batches internally) — a cross-issue batch would require a different, `getEdges`-list API this file's dependency (`GraphBackend`) does not expose. */
+export declare function assembleIssueCards(graph: GraphBackend, issues: NodeRecord[], fields: readonly IIssueField[], scoreByUid?: ReadonlyMap<string, number>): Promise<IIssueCard[]>;

package/query/get.d.ts

@@ -0,0 +1,11 @@
+import { IIssueCard, IIssueGetByUidInput } from './types.js';
+import { GraphBackend } from '@adhd/sox-graph-store';
+
+/**
+ * Fetch one issue by `uid`, projected to the requested `fields` (default:
+ * the same five-field card `query` defaults to, SPEC.md §6.3.1/§6.5/AC-13).
+ *
+ * Errors: `IssueNotFoundError(uid)` (no live node carries `uid`),
+ * `BacklogValidationError('fields', ...)` (an unknown field name).
+ */
+export declare function getIssue(graph: GraphBackend, input: IIssueGetByUidInput): Promise<IIssueCard>;

package/query/index.d.ts

@@ -0,0 +1,67 @@
+/**
+ * index.ts — the `@adhd/backlog` read/query layer's public surface
+ * (SPEC.md §5, §5a, §6.1, §6.3.1, §6.5, §3a).
+ *
+ * **Layout:**
+ * - `types.ts` — every shared TS shape (`IIssueCard`, `IIssueField`,
+ *   `IIssueQueryInput`/`IIssueFilter`, `IIssuePage`, registry types). Import
+ *   from here, not from `get.ts`/`query.ts`/`card.ts` directly, to avoid
+ *   depending on an implementation module's re-export surface.
+ * - `resolve.ts` — read-only (non-transactional) uid/name resolution and edge
+ *   traversal, built directly on the bare `GraphBackend` (see that file's own
+ *   doc comment for why this is safe, unlike `write/tx.ts`'s hand-composed
+ *   forms). The six sibling write verbs (`update`/`transition`/`claim`/
+ *   `relate`/`move`/`delete`) should import from here for any READ they need
+ *   OUTSIDE their own `immediate` transaction (e.g. resolving a `filter`
+ *   parameter, or re-reading a node post-commit to build their own outcome's
+ *   card) — never re-implement uid/name resolution a third time.
+ * - `card.ts` — `assembleIssueCard`/`assembleIssueCards`: projects a live
+ *   `issue` `NodeRecord` onto a requested `IIssueField` list. The six sibling
+ *   write verbs' own outcome shapes (`IUpdateOutcome`, `ITransitionOutcome`,
+ *   etc.) embed card-shaped fields (SPEC.md §6.3) — call `assembleIssueCard`
+ *   post-commit rather than hand-rolling a second field-projection pass.
+ * - `get.ts` — the `get` verb (§6.3.1).
+ * - `query.ts` — the `query` verb (§5, §5a, §6.5) and its `view` union
+ *   (`list`/`ready`/`graph`/`order`/`stale`/`similar`/`overlap`).
+ * - `views/registry.ts` — §3a's registry read surface (`projects`/`components`/
+ *   `locations`/`lookup`/registry `get` detail).
+ * - `views/stats.ts` — the stats/rollup read views (§5): the status-aware
+ *   priority matrix (`priorityMatrix`, BUG-023), the `part_of` hierarchy
+ *   rollup (`partOfRollup`, FEAT-005 — transitive, not one-level), and
+ *   `validAt` point-in-time cumulative-open curves (`openCurve`).
+ * - `views/semantic.ts` — the semantic read views (§5a, FEAT-022):
+ *   `querySimilarView` (`view:'similar'`) and the shared fused-relevance
+ *   ranking primitive (`rankByFusedRelevance`). `query.ts`'s `case 'similar':`
+ *   dispatch calls `querySimilarView` directly — there is no second,
+ *   embedding-only `view:'similar'` implementation left in `query.ts`.
+ * - `markdown.ts` — `query`'s `format:'markdown'` rendering (§6.5/§6.6,
+ *   DATA_MODEL.md §8): a pure re-serialization of the SAME `IIssueCard[]`
+ *   `format:'json'` already returns for `list`/`ready`/`stale`/`similar` —
+ *   never a second query path.
+ *
+ * **Reconciliation note for the write layer.** `write/create-issue.ts`
+ * declares its OWN `ICreateIssueCard` (a narrower, always-fully-populated
+ * shape it builds inline from data it already has after a fresh insert — it
+ * never needs a field-projected read; named distinctly from this module's
+ * `IIssueCard` on purpose — see that file's doc comment for
+ * BUG-APIGEN-CORE-CLIENT-BARE-NAME-COLLISION-001, a real apigen-core-client
+ * extraction defect the original shared bare name `IIssueCard` triggered
+ * once both types became simultaneously reachable from `api.d.ts`). This
+ * module's {@link IIssueCard} (from `types.ts`) is the FIELDS-PROJECTED
+ * read-layer shape every OTHER verb should use — the two are intentionally
+ * not unified in this slice (unifying them means either widening
+ * `create-issue.ts`'s always-populated shape to all-optional, or teaching
+ * this module's card assembler to skip a post-insert read entirely; both are
+ * a `create-issue.ts` edit, out of scope for a read-layer-only task). A
+ * future consolidation should re-export `create-issue.ts`'s result through
+ * THIS module's `IIssueCard` instead of maintaining two card shapes.
+ */
+export * from './types.js';
+export * from './resolve.js';
+export * from './card.js';
+export * from './get.js';
+export * from './query.js';
+export * from './views/registry.js';
+export * from './views/stats.js';
+export * from './views/semantic.js';
+export * from './markdown.js';

package/query/markdown.d.ts

@@ -0,0 +1,11 @@
+import { IIssueCard } from './types.js';
+
+/** Renders one `IIssueCard` as a markdown section — title header, never the `uid` (DATA_MODEL.md §8). */
+export declare function renderOneIssueCardMarkdown(card: IIssueCard): string;
+/**
+ * Renders a full page of issue cards as markdown (`query`'s `format:'markdown'`
+ * result) — one `##` section per card, separated by a blank line. An empty
+ * page renders a stated "no results" line rather than an empty string, so a
+ * caller piping this straight to a file never gets a silently blank document.
+ */
+export declare function renderIssueCardsMarkdown(items: readonly IIssueCard[]): string;

package/query/query.d.ts

@@ -0,0 +1,131 @@
+import { IIssueQueryInput, IIssueQueryResult } from './types.js';
+import { IQueryEnvelopeMeta } from '../envelope.js';
+import { StoreSearchBackend } from '@adhd/sox-hybrid-search';
+import { GraphBackend } from '@adhd/sox-graph-store';
+
+/**
+ * The dependencies `query`/the view helpers need. `search` is OPTIONAL —
+ * `@adhd/sox-embedding-provider`/`@adhd/sox-vector-store` are
+ * `optionalDependencies` of this package (package.json), so a store opened
+ * without a configured embedding backend simply cannot serve
+ * `filter.semantic`/`view:'similar'`; those paths throw
+ * `InvalidArgumentError('semantic', ...)` rather than silently degrading to a
+ * grep-only result the caller did not ask for.
+ */
+export interface IQueryStoreHandle {
+    readonly graph: GraphBackend;
+    readonly search?: {
+        readonly backend: StoreSearchBackend;
+        /** Embeds `filter.semantic`'s free text into the SAME vector space `backend`'s vector store was built against. */
+        embedQuery(text: string): Promise<Float32Array>;
+        /**
+         * One-row probe of the REAL vector table: `true` iff at least one vector
+         * exists under this backend's own space. Per-query truth, never a
+         * process-lifetime latch — see `write/bootstrap.ts`'s
+         * {@link isVectorSpacePopulated}. `api.ts`'s `queryHandle` runs this and
+         * snapshots the result onto {@link IQueryStoreHandle.spacePopulated}
+         * before the (synchronous) routing decision reads it.
+         */
+        spacePopulated(): Promise<boolean>;
+    };
+    /**
+     * Snapshot of {@link IQueryStoreHandle.search}'s `spacePopulated()` probe,
+     * taken by `api.ts`'s `queryHandle` when the caller passed a bare `text:`
+     * positional. `resolveTextInput` is synchronous, so the (async) probe
+     * result is resolved onto the handle first; a handle built directly by a
+     * test or the ETL sets it itself. Absent means "unknown" and is treated as
+     * "not populated" — routing then falls back to grep.
+     */
+    readonly spacePopulated?: boolean;
+    /**
+     * Fail-loud vocabulary guard (`store/vocabulary-guard.ts`). When present,
+     * `queryIssuesWithMeta` awaits it before dispatching any view: a store
+     * holding live nodes under a vocabulary this build does not recognize must
+     * never read as `{ok:true, total:0}`. OPTIONAL so a hand-built handle
+     * (tests, the ETL) is unaffected — `api.ts`'s `queryHandle` wires it for
+     * every real host, and it is deliberately re-run per query (not latched at
+     * open) so a long-lived process notices a store rewritten under it.
+     */
+    readonly assertVocabulary?: () => Promise<void>;
+}
+/**
+ * Whether a `query` verb's own input touches the semantic channel at all —
+ * the need-predicate `api.ts`'s `query` call site passes as
+ * `queryHandle(ctx, { needsSemantic: queryNeedsSemanticBackend(input) })`
+ * (SPEC.md §5b point 1). Structural, not a maintained list: it names the
+ * SAME "semantic inputs" vocabulary `env.ts`'s `embedding.enabled` doc
+ * comment already names, plus a bare `text` positional — deciding whether
+ * `text` auto-routes to `semantic` or `grep` itself requires the backend to
+ * be live, so a `text` query must bootstrap it even though it may end up on
+ * the grep route.
+ *
+ * A verb that returns `false` never derives a semantic backend: no embedding
+ * provider construction, no vector-store open, no cold ONNX load.
+ */
+export declare function queryNeedsSemanticBackend(input: IIssueQueryInput): boolean;
+/**
+ * Normalises `input.text` (the natural-language query shared by every mount —
+ * CLI `search`, MCP, HTTP) into `filter.semantic` or `filter.grep`, exactly
+ * ONCE, so every caller gets identical routing rather than each transport
+ * reimplementing it. Routes to `semantic` when the store handle actually
+ * carries a `search` backend AND that backend's space is populated
+ * ({@link IQueryStoreHandle.spacePopulated}, the per-query snapshot of
+ * {@link IQueryStoreHandle.search}'s `spacePopulated()` probe taken by
+ * `api.ts`'s `queryHandle`); otherwise routes to `grep`. A non-empty handle
+ * whose space is still empty must NOT route to semantic: over an empty vector
+ * table `searchRanked` returns zero candidates, which is an empty page — worse
+ * than the grep fallback — so populated-ness is load-bearing, not an
+ * optimization. The matching default `sort` (`'relevance'` / `'textMatch'`)
+ * is only applied when the caller did not pass `sort` explicitly — an
+ * explicit `sort` always wins.
+ *
+ * Exported (in addition to being called internally by {@link queryIssues})
+ * so the sort-precedence rule above can be unit-tested directly: the ranked
+ * grep/semantic branch of `queryList` never echoes the resolved `sort` value
+ * back in its output (it only gates on relevance/textMatch requiring
+ * grep/semantic, then ignores `sort` entirely when ordering ranked results),
+ * so there is no way to observe "explicit sort survived" from `queryIssues`'s
+ * return value alone — `text-routing.spec.ts` asserts on this function's
+ * return value for that one property, and drives every other behaviour
+ * through the real `queryIssues`/real store end-to-end.
+ */
+export declare function resolveTextInput(handle: IQueryStoreHandle, input: IIssueQueryInput): IIssueQueryInput;
+/** {@link queryIssuesWithMeta}'s return shape. */
+export interface IQueryIssuesOutcome {
+    result: IIssueQueryResult;
+    /**
+     * Present only for `view:'list'` — the only view whose result is a
+     * filtered/paginated row set with an honestly countable pre-limit total
+     * (`envelope.ts`'s {@link IQueryEnvelopeMeta}). `view:'ready'` computes
+     * readiness in-memory and stops enumerating once `limit` candidates are
+     * found (`queryReady`'s own doc comment: removing that early exit to count
+     * a true pre-limit total would reintroduce the O(candidates) cost its
+     * grouped-relation-fetch design exists to avoid), `view:'stale'` applies no
+     * limit at all so every row it returns already IS the total, and
+     * `view:'similar'`/`'graph'`/`'order'`/`'overlap'` are a ranking, a graph
+     * projection, a topological order, and an axis grouping respectively — none
+     * of them a filtered row set with a "how many matched" count. Adding a
+     * `meta` to any of those would mean inventing a number this module cannot
+     * stand behind.
+     */
+    meta?: IQueryEnvelopeMeta;
+}
+/**
+ * `queryIssues` (below) plus the transport-facing `meta` the envelope
+ * exposes for a list-shaped read (`api.ts`'s `query` mount is the one caller
+ * that needs it). Every other in-process caller keeps calling `queryIssues`
+ * itself, which discards `meta` and returns exactly the shape it always has.
+ *
+ * `format:'markdown'` (SPEC.md §6.5/§6.6, DATA_MODEL.md §8) is handled here,
+ * as a POST-PROCESSING step over {@link dispatchQueryView}'s always-`json`
+ * result — never a second query path (SPEC.md §6.5: "renders this same page
+ * ... never a second code path"). Only the four item-list views
+ * ({@link MARKDOWN_CAPABLE_VIEWS}) have a markdown rendering rule at all; any
+ * other view (`graph`/`order`/`overlap`/`projects`/`components`/`locations`)
+ * rejects `format:'markdown'` outright rather than silently falling back to
+ * `json` or inventing an ad hoc rendering for a shape DATA_MODEL.md §8 never
+ * describes.
+ */
+export declare function queryIssuesWithMeta(handle: IQueryStoreHandle, rawInput?: IIssueQueryInput): Promise<IQueryIssuesOutcome>;
+/** The `query` verb (SPEC.md §5, §6.5) — dispatches on `input.view`, default `'list'`. */
+export declare function queryIssues(handle: IQueryStoreHandle, rawInput?: IIssueQueryInput): Promise<IIssueQueryResult>;

package/query/resolve.d.ts

@@ -0,0 +1,123 @@
+import { isUidShaped } from '../write/catalog.js';
+import { EdgeRecord, GraphBackend, NodeRecord } from '@adhd/sox-graph-store';
+
+export { isUidShaped };
+/** A resolved catalog/registry row, read-only. */
+export interface IResolvedRef {
+    id: number;
+    uid: string;
+    name: string;
+    record: NodeRecord;
+}
+/**
+ * Resolve `uid` → the live `issue` node, or throw {@link IssueNotFoundError}
+ * (SPEC.md §6.1: "a `uid` with no matching live node throws
+ * `IssueNotFoundError(uid)`"). This is the READ-PATH counterpart of
+ * `write/tx.ts`'s `getNodeByUidTx` — safe to call standalone because it is
+ * not composing a check-then-act write around the result.
+ */
+export declare function resolveIssueByUid(graph: GraphBackend, uid: string): Promise<NodeRecord>;
+/**
+ * Resolve `ref` (uid or name, disambiguated by shape — SPEC.md §6.1) against
+ * `expectedKind`, on the READ path: an unresolved NAME is never an error here
+ * (unlike the write-path `mintOrResolveCatalogTx`) — SPEC.md §6.1's own read-
+ * path rule: "an unresolved `name` is not an error; it resolves to zero
+ * matches." Callers that need read-path "resolve or throw" semantics (e.g.
+ * `get`'s `project`/`component` display resolution once an issue's edges are
+ * already known to exist) use {@link resolveRefOrThrow} instead.
+ */
+export declare function tryResolveRef(graph: GraphBackend, expectedKind: string, ref: string): Promise<IResolvedRef | null>;
+/** Like {@link tryResolveRef}, but throws {@link CatalogNotFoundError} on a miss — for call sites that need "this reference must already exist." */
+export declare function resolveRefOrThrow(graph: GraphBackend, expectedKind: string, ref: string): Promise<IResolvedRef>;
+/** `component`, scoped within `project` (SPEC.md §6.1) — read path, `component.meta.metadata.projectUid` must match. */
+export declare function tryResolveComponentRef(graph: GraphBackend, projectUid: string, ref: string): Promise<IResolvedRef | null>;
+/** The single live edge of `rel` FROM `srcId` (SPEC.md §3's `n:1` rels — `has_kind`/`has_status`/`has_priority`/`authored_by`), or `null` when none exists. */
+export declare function pickSingleEdge(edges: EdgeRecord[], rel: string, srcId: number): EdgeRecord | undefined;
+/**
+ * All edges ORIGINATING at `nodeId` — a single `getEdges({src})` call covers
+ * every `n:1`/`1:n` outgoing rel an issue carries (`has_kind`/`has_status`/
+ * `has_priority`/`authored_by`/`has_note`/`has_citation`/`has_transition`/
+ * `audits`/`relates_to`/`supersedes`/`duplicate_of`/`part_of`/`blocks`) —
+ * cheaper than one `getEdges` call per rel.
+ */
+export declare function getOutgoingEdges(graph: GraphBackend, nodeId: number): Promise<EdgeRecord[]>;
+/** All edges TARGETING `nodeId` — used for the reverse traversals (`owns_component`'s issue→component lookup, `blocks`'s incoming-blocker lookup, `duplicate_of`'s incoming lookup). */
+export declare function getIncomingEdges(graph: GraphBackend, nodeId: number): Promise<EdgeRecord[]>;
+/**
+ * The component that owns `issueId` (SPEC.md §3: `owns_component: component →
+ * issue (1:n)`) and, one hop further, the project that owns that component
+ * (`owns_project: project → component (1:n)`). Every live issue has exactly
+ * one of each (§8 AC-23), so this returns `undefined` only for a
+ * pre-invariant / corrupted row, never as an expected steady-state case.
+ */
+export declare function resolveIssuePlacement(graph: GraphBackend, issueId: number): Promise<{
+    component?: NodeRecord;
+    project?: NodeRecord;
+}>;
+/**
+ * Resolve an edge-scoped filter value (SPEC.md §6.5 rule 3: `kind`/`status`/
+ * `priority`/`project`/`component`/`author` live on EDGES, not `NodeFilter`
+ * columns) to the set of candidate issue rowids satisfying it.
+ *
+ * **Direction is looked up, not assumed.** The six edge-scoped dimensions do
+ * NOT all run the same way: `has_kind`/`has_status`/`has_priority`/
+ * `authored_by` point issue → catalog (the catalog node is the edge TARGET),
+ * while `owns_project`/`owns_component` point catalog → child (the catalog
+ * node is the edge SOURCE). This function previously hard-coded the first
+ * shape — `getEdges({dst: resolved.id, rel})` collecting `src` — for all six,
+ * so calling it for `project`/`component` looked for edges INTO a component
+ * when every real `owns_component` edge points OUT of it, and it silently
+ * returned an EMPTY set for a component that genuinely owned issues. Silent,
+ * because an empty candidate set is indistinguishable from "nothing matched."
+ *
+ * `views/semantic.ts` worked around this by hand-composing its own
+ * source-directed traversal for those two dimensions and reusing this
+ * function only for the four it got right, flagging in its own header that
+ * "a future caller who takes that doc comment at face value for
+ * component/project will reproduce this exact miss." That is now fixed at
+ * source instead: the `edge_kind` row for `rel` carries `source_kind`/
+ * `target_kind` (the same rows `resolveEdgeKindTx` reads on the write path),
+ * so the traversal direction is derived from the data rather than assumed,
+ * and stays correct for any rel added later.
+ *
+ * Returns `undefined` (never an empty array) when `ref` does not resolve to
+ * any live catalog/registry row — SPEC.md §6.1's read-path rule ("an
+ * unresolved name is not an error; it resolves to zero matches") is realized
+ * by the CALLER treating `undefined` as "this filter can never match
+ * anything," short-circuiting the whole query to an empty page rather than
+ * querying with a meaningless empty `ids: []` (which `NodeFilter.ids` would
+ * otherwise interpret as "no restriction" on some backends — never rely on
+ * that ambiguity here).
+ */
+export declare function resolveEdgeScopedCandidates(graph: GraphBackend, input: {
+    rel: string;
+    expectedKind: string;
+    ref: string;
+    projectUid?: string;
+}): Promise<Set<number> | undefined>;
+/** Every live catalog row's `name` for a given open-vocabulary catalog kind — used only to VALIDATE a filter value against what genuinely exists, never to constrain what a caller may create. */
+export declare function fetchCatalogNames(graph: GraphBackend, catalogKind: 'kind' | 'status' | 'priority'): Promise<string[]>;
+/**
+ * Nearest-name suggestions for an unresolved filter value — case-insensitive
+ * edit distance over the catalog's OWN live names, bounded to a distance
+ * proportional to the typo'd value's own length so an unrelated short
+ * catalog name is never suggested for a long, clearly-different value.
+ * Sorted nearest-first, capped at `max`.
+ */
+export declare function suggestClosestCatalogNames(value: string, candidates: readonly string[], max?: number): string[];
+/**
+ * Resolves a multi-valued `kind`/`status`/`priority` filter dimension
+ * (OR-union across `refs`), rejecting with a `BacklogValidationError` naming
+ * every ref that matches NO live catalog row of that kind — see this
+ * section's top doc comment for the full rationale. Never rejects a ref that
+ * resolves to a real row with zero owning issues; that still contributes an
+ * empty set exactly as a plain unresolved-name read would.
+ */
+export declare function resolveValidatedCatalogFilter(graph: GraphBackend, input: {
+    rel: string;
+    catalogKind: 'kind' | 'status' | 'priority';
+    field: string;
+    refs: readonly string[];
+}): Promise<Set<number>>;
+/** Intersect a list of candidate-rowid sets (SPEC.md §6.5 rule 3: "AND semantics — an issue must satisfy every edge-scoped filter given"). An empty input list means "no edge-scoped filter was given" — returns `undefined` (no restriction), never an empty set. */
+export declare function intersectCandidateSets(sets: ReadonlyArray<Set<number>>): Set<number> | undefined;