@adhd/backlog 0.1.8 → 1.0.0

package/README.md

@@ -1,103 +1,354 @@
 # @adhd/backlog
 
-A structured, queryable, multi-agent-safe **graph store** for backlog items (bugs,
-debt, features, investigations, plans) — a replacement for ad-hoc `BACKLOG.md`
-editing that stays compatible with the existing markdown convention this repo
-already uses.
+A structured, queryable, concurrent-safe backlog for bugs, debt, features, and
+investigations — served from one graph store over a CLI, an MCP server, an HTTP
+API, and an in-process client.
 
-Built on `@adhd/sox-graph-store` (bi-temporal nodes/edges over SQLite) and mounted
-live via `@adhd/apigen-core-client` (no code generation — `extract()` →
-`composeSchemas()` → `plugin.run()`).
+## Why
 
-See `SPEC.md` (functional spec: personas, data model, status vocabulary,
-operation surface) and `DESIGN.md` (technical design: graph mapping, claim
-protocol, env/apigen wiring) in this package for the full contract.
+The problem this solves: a plain `BACKLOG.md` file has no way to represent
+"someone is already working on this," no way to enforce that a closed item
+cites the fix that closed it, no structured way to ask "what's open in this
+component," and no safe way for two agents to edit it at once. `@adhd/backlog`
+replaces that file with a real store: issues are addressed by a stable `uid`,
+every mutation is audited, claims are leases with staleness detection, and
+queries are structured filters instead of `grep`.
+
+## Install
 
 ```bash
-pnpm add @adhd/backlog
+pnpm add -g @adhd/backlog
+adhd-backlog --help
 ```
 
-## Usage
+This installs the `adhd-backlog` CLI binary. The same package also runs as an
+MCP server, an HTTP API, and an importable client library — see
+[Transports](#transports).
 
-```ts
-import { createItem, listItems, claimItem, transitionStatus } from '@adhd/backlog';
-import { buildBacklogEnv } from '@adhd/backlog';
-import { openGraphBacklogStore } from '@adhd/backlog';
+## Quickstart
+
+Issues live under a **project** (and, optionally, a **component**), both
+resolved by name or `uid`. File the project first — `create` never mints one.
+File every issue with the correct project **and component**: a component-less
+item lands on the project's reserved `(root)` component and is invisible to
+component-scoped queries. The agent-facing filing rules and the real misfiling
+hazards live in [`skill/SKILL.md` §4](skill/SKILL.md).
 
-const env = buildBacklogEnv();
-env.ensureDirs();
-const store = openGraphBacklogStore(env.files.db);
-const ctx = { store, env };
+```bash
+adhd-backlog upsert-project --input '{
+  "name": "demo-project",
+  "path": "/tmp/demo",
+  "by": "agent:worker-1"
+}'
+```
 
-const { item } = await createItem(ctx, {
-  family: 'BUG-EXAMPLE',
-  title: 'Example bug',
-  body: 'Something is broken.',
-  repo: 'PseudoSky/adhd',
-});
+```json
+{"ok":true,"data":{"uid":"49ec673b-…","created":true,"project":{"uid":"49ec673b-…","name":"demo-project","path":"/tmp/demo"}}}
+```
 
-await claimItem(ctx, item.repo, item.humanId, 'implementer:abc123');
-await transitionStatus(ctx, item.repo, item.humanId, 'FIXED', {
-  by: 'implementer:abc123',
-  citations: [{ file: 'entrypoint/backlog/src/client.ts' }],
-});
+File an issue against it:
 
-const open = await listItems(ctx, { repo: item.repo, status: 'open' });
+```bash
+adhd-backlog create --input '{
+  "title": "Query pagination drops the last page under offset paging",
+  "body": "offset+limit near the end of a result set silently returns fewer rows than `total` implies.",
+  "project": "demo-project",
+  "priority": "HIGH",
+  "gitContext": "feat/backlog-hard-replacement @ 4bf902fc",
+  "by": "agent:worker-1"
+}'
 ```
 
-## Running as a live server (no codegen)
+```json
+{"ok":true,"data":{"created":true,"uid":"b3b2da0e-…","item":{"uid":"b3b2da0e-…","title":"Query pagination drops the last page under offset paging","kind":"issue","status":"open","priority":"HIGH","project":"49ec673b-…","component":"65c4e373-…","createdAt":"2026-09-24T00:14:38.802Z","author":"agent:worker-1","gitContext":"feat/backlog-hard-replacement @ 4bf902fc"}}}
+```
 
-```ts
-import { startBacklogServer } from '@adhd/backlog';
+> `project` and `component` in the result are `uid`s, not names. `gitContext`
+> is described under [Citations & git context](#citations--git-context).
+
+Query for it:
+
+```bash
+adhd-backlog query --input '{"filter":{"project":"demo-project","status":"open"}}'
+```
+
+```json
+{"ok":true,"data":{"view":"list","items":[{"uid":"b3b2da0e-…","title":"Query pagination drops the last page under offset paging","kind":"issue","status":"open","priority":"HIGH"}],"hasMore":false},"meta":{"total":1,"returned":1,"limit":50}}
+```
+
+Move it forward — a `transition` records the status change in the issue's audit
+trail. A non-empty `note` is required by default
+(`project_policy.transition_requires_note`); a terminal status additionally
+requires verifiable `citations` **only if** the project's policy turns citation
+enforcement on (`citationRequired`, default `false`):
+
+```bash
+adhd-backlog transition --input '{
+  "uid": "b3b2da0e-…",
+  "toStatus": "in-progress",
+  "note": "reproduced with limit:10, offset:95 against a 100-row set",
+  "by": "agent:worker-1"
+}'
+```
+
+```json
+{"ok":true,"data":{"uid":"b3b2da0e-…","fromStatus":"open","toStatus":"in-progress","transitionUid":"9bcb9844-…"}}
+```
+
+A failed call returns the same envelope with `ok:false` instead of throwing:
+
+```json
+{"ok":false,"error":{"code":"item_not_found","message":"No live issue found for uid \"does-not-exist\"","details":{"retryable":false}}}
+```
+
+Every output above was captured from the built binary
+(`entrypoint/backlog/dist/index.js`); `uid`s are truncated with `…`. See
+[Which build these docs describe](#which-build-these-docs-describe).
+
+## Key features
+
+### 1. One shared graph store, concurrent-safe by design
+
+The store is not a file you edit — it is a graph database that many processes
+read and write at once. There is no single-writer lock; concurrency is bounded
+by real transactions and leases. File the same item from two agents and one
+wins cleanly, with correct audit rows. (SPEC.md §3/§4; `src/write/tx.ts`.)
+
+### 2. Leased claims for multi-agent work
+
+`claim` is a lease, not a flag: it is idempotent for the same claimant
+(`renew`), self-healing when stale, and it protects the item — a competing
+`transition` by another agent is refused with `conflict` until the lease is
+released or goes stale.
+
+```bash
+adhd-backlog claim --input '{"uid":"b3b2da0e-…","by":"agent:worker-1","action":"claim"}'
+```
+
+```json
+{"ok":true,"data":{"uid":"b3b2da0e-…","status":"claimed","claimedBy":"agent:worker-1","claimedAt":"2026-09-24T00:14:39.978Z"}}
+```
+
+### 3. Structured, verifiable citations
+
+A citation is `{ file, lines?, context?, symbol? }`, not hand-typed markdown.
+When a project enforces citations, a terminal transition is rejected with
+`precondition_failed` unless every cited file resolves inside the project's own
+registered path. Name a `symbol` and the store shells out to
+`gitnexus impact <symbol>` at write time to stamp a best-effort `blastRadius`
+on the citation.
+
+### 4. A registry that answers "where does this live?"
+
+`lookup` resolves a tool name, file path, or URL to its owning
+project/component — before you reach for `find`. `query` also lists the
+registry directly:
+
+```bash
+adhd-backlog get --input '{"registry":"project","name":"demo-project"}'
+```
 
-const abort = new AbortController();
-await startBacklogServer({ transport: 'both', port: 3400, signal: abort.signal });
+```json
+{"ok":true,"data":{"uid":"49ec673b-…","name":"demo-project","path":"/tmp/demo","components":[{"name":"(root)"}],"locations":[]}}
 ```
 
-- `POST /backlog/client-d/create-item`, `GET /backlog/client-d/get-item`, ... —
-  every `client.ts` export, mounted live via `@adhd/apigen-plugin-api-fastify`.
-  (The `client-d` route segment is not a typo — see `DESIGN.md` §7's CLI
-  section / `SPEC.md` §7's transport table for why it's there.)
-- Every export is also available as an MCP tool (e.g. `backlog_client_d_get_item`)
-  via `@adhd/apigen-plugin-mcp` (stdio transport by default).
+### 5. Optional semantic search, optional Markdown rendering
+
+With embeddings off (the default), keyword filtering (`filter.grep`),
+exact/registry lookup, and every write verb work fully. Turn them on and
+`query`'s natural-language `text` routes to semantic ranking; ask for a semantic
+read with no backend and you get a precise `rag_not_configured` error rather
+than a silent empty result. `query --input '{"format":"markdown", …}'` renders
+every item-list view as Markdown.
+
+### 6. N-way fan-out with `batch action`
 
-## CLI (`backlog`, live apigen mount — no codegen)
+Run one operation over many items instead of N one-at-a-time calls. `operation`
+is the mounted id (`backlog/create`, …); each item wraps its payload under
+`input`; `mode` (`parallel`/`serial`/`chained`), `onItemError`, `concurrency`,
+and `itemTimeoutMs` govern the run.
 
 ```bash
-pnpm add -g @adhd/backlog   # installs the `backlog` bin
-backlog --help              # live-derived command listing
-backlog create-item --input '{"family":"BUG-EXAMPLE","title":"t","body":"b","repo":"org/repo"}'
-backlog get-item --repo org/repo --human-id BUG-EXAMPLE-001
-backlog list-items --filter '{"status":"OPEN"}'
-```
-
-- Same architecture as the HTTP/MCP transports above — `entrypoint/backlog/src/cli.ts`'s
-  `runBacklogCli()` reuses `buildBacklogApigenPackage()` and hands it straight
-  to `@adhd/apigen-plugin-cli-output`'s `run()`. No `apigen generate`, no
-  bespoke argument parsing — routing, flag parsing, validation, dispatch, and
-  exit codes all come from that plugin.
-- **You type `backlog <command>`, never the internal `client-d` segment.**
-  `runBacklogCli` derives the real command-table prefix from the live
-  `operations` list at runtime (`resolveCommandPrefix`) and prepends it before
-  dispatch — so `backlog get-item …` resolves even though the plugin's real
-  command table is keyed `backlog client-d get-item` internally (same
-  `client-d` artifact as the HTTP/MCP routes above; the CLI is the one
-  transport that hides it from the caller).
-- Flags are the schema's domain params, kebab-cased (`humanId` → `--human-id`);
-  object/array-typed params take a JSON string (`--input '{...}'`,
-  `--filter '{...}'`).
-- Exit codes follow `@adhd/apigen-base-errors`'s `CLI_EXIT_CODE` table: `0`
-  success, `2` invalid argument (bad/unknown flag, failed validation), `4`
-  unknown command, etc. Result is printed as JSON to stdout; errors as JSON to
-  stderr.
-- Honors the same `ADHD_BACKLOG_SCOPE`/`ADHD_ENV_SCOPE` scope env vars as the
-  library API (see Scope below) — there is no separate CLI-only config.
-- `runBacklogCli(argv?, opts?)` is also exported for in-process programmatic
-  use (e.g. a test harness), symmetric with `startBacklogServer`.
-
-## Scope
-
-Resolved via `@adhd/environment` (see `env.ts`): `global` (default —
-`~/.adhd/backlog/<namespace>/data/backlog.db`, spans every repo on the
-machine), `project` (`<projectRoot>/.adhd/backlog/<namespace>/data/backlog.db`,
-one repo), or `system`. See `SPEC.md` §3 for the full resolution order.
+adhd-backlog batch action --input '{
+  "operation": "backlog/get",
+  "items": [{"input": {"uid": "does-not-exist"}}]
+}'
+```
+
+### 7. Supersede-safe history
+
+A `body` edit does not mutate in place — it mints a successor issue and carries
+the previous node's edges (claims, citations, notes, transitions, relations)
+forward to it. The old `uid` remains queryable history: addressing it returns
+`conflict` and names the live successor, so a stale uid can never silently
+resolve to the wrong record.
+
+```json
+{"ok":false,"error":{"code":"conflict","message":"Issue \"63c2f57e-…\" was superseded by a body edit and is no longer the live issue; it now lives under \"e3b32183-…\"","details":{"retryable":false}}}
+```
+
+## Command surface
+
+Every verb takes a single `--input` flag carrying one JSON object; there are no
+per-field flags. Eighteen operations (the 17 verbs plus `batch`):
+
+| Verb              | CLI                             | MCP tool                   |
+| ----------------- | ------------------------------- | -------------------------- |
+| `get`             | `adhd-backlog get`              | `backlog_get`              |
+| `query`           | `adhd-backlog query`            | `backlog_query`            |
+| `priorityMatrix`  | `adhd-backlog priority-matrix`  | `backlog_priority_matrix`  |
+| `partOfRollup`    | `adhd-backlog part-of-rollup`   | `backlog_part_of_rollup`   |
+| `openCurve`       | `adhd-backlog open-curve`       | `backlog_open_curve`       |
+| `lookup`          | `adhd-backlog lookup`           | `backlog_lookup`           |
+| `create`          | `adhd-backlog create`           | `backlog_create`           |
+| `update`          | `adhd-backlog update`           | `backlog_update`           |
+| `transition`      | `adhd-backlog transition`       | `backlog_transition`       |
+| `claim`           | `adhd-backlog claim`            | `backlog_claim`            |
+| `relate`          | `adhd-backlog relate`           | `backlog_relate`           |
+| `move`            | `adhd-backlog move`             | `backlog_move`             |
+| `delete`          | `adhd-backlog delete`           | `backlog_delete`           |
+| `upsertProject`   | `adhd-backlog upsert-project`   | `backlog_upsert_project`   |
+| `upsertComponent` | `adhd-backlog upsert-component` | `backlog_upsert_component` |
+| `upsertLocation`  | `adhd-backlog upsert-location`  | `backlog_upsert_location`  |
+| `rmLocation`      | `adhd-backlog rm-location`      | `backlog_rm_location`      |
+| `batch`           | `adhd-backlog batch action`     | `batch_action`             |
+
+`--help` prints these as `backlog <verb>`; the CLI also accepts the bare
+`adhd-backlog <verb>` form shown above, and accepts the explicit namespace
+prefix at any position. `get`/`query`/`lookup` are reads.
+`create`/`update`/`transition`/`claim`/`relate`/`move`/`delete` mutate one
+issue. The four `upsert*`/`rmLocation` verbs manage the **registry** —
+projects, components, and locations. `batch action` fans any one of them out
+over many items.
+
+## Transports
+
+`adhd-backlog` mounts one set of operation descriptors onto every host — there
+is no per-transport reimplementation, so a change to a verb's behavior is
+simultaneously true everywhere:
+
+- **CLI** — `adhd-backlog <verb> --input '<json>'`
+- **MCP** — tools named `backlog_<verb>` (e.g. `backlog_create`, `backlog_query`)
+- **HTTP** — a REST API generated from the same descriptors, with an OpenAPI document
+- **In-process** — the package's exported client library, for embedding the store in a Node process
+
+## Envelope
+
+Every verb call returns one of two shapes, on every transport:
+
+```ts
+{ ok: true,  data: T, warnings?: string[], meta?: { total, returned, limit?, offset?, truncated? } }
+{ ok: false, error: { code, message, details? }, warnings?: string[] }
+```
+
+`meta` is present on list-shaped reads (`query`) and its `total` is the true
+match count _before_ `limit`/`offset` are applied; a truncated page sets
+`data.hasMore: true` and `data.nextCursor`, so a short result never silently
+looks complete.
+
+### Error codes
+
+| Code                  | Meaning                                                                                                                         | CLI exit code |
+| --------------------- | ------------------------------------------------------------------------------------------------------------------------------- | ------------- |
+| `not_found`           | A referenced catalog entry (project/component/kind/status/priority) doesn't exist                                               | 4             |
+| `item_not_found`      | The addressed issue doesn't exist                                                                                               | 1             |
+| `invalid_argument`    | Malformed flag or parameter shape                                                                                               | 2             |
+| `validation`          | Schema rejection — unknown filter key, unknown projection field, over-limit                                                     | 2             |
+| `store_busy`          | Store contention (a lease or a write conflict); `details.retryable` and `details.retryAfterMs` indicate whether/how to retry    | 1             |
+| `rag_not_configured`  | A semantic/similarity read was requested but no embedding backend is configured, or the vector space is empty                   | 1             |
+| `conflict`            | Someone else holds the claim, a single-valued relation is already taken, or a supersede raced                                   | 1             |
+| `precondition_failed` | A gate refused the write — a terminal transition missing its required citation/note, or a citation that couldn't be verified against a known project path | 1             |
+| `internal`            | Unclassified server-side failure                                                                                                | 1             |
+
+Success always exits 0. `item_not_found` and `internal` are deliberately
+distinct codes even though they share exit code 1 — a caller distinguishes
+"this uid doesn't exist" from "something broke" by `error.code`, not by exit
+code alone.
+
+### Citations & git context
+
+A citation is `{ file, lines?, context?, symbol? }`. Pass `citations` on
+`create`, or on the `transition` that moves an issue into a terminal status
+when the project's policy requires it.
+
+The item-level **`gitContext`** is separate from a citation's own `context`:
+it records the repo disclosure contract's `<active git context>` — the first
+element of a `Citations:` block (`Citations: [<active git context>, …]`).
+Pass it on `create`, or on a `transition` to update it. It is stored on the
+issue itself, and a `format:'markdown'` query renders it once at the head of
+the item's `Citations:` block. Omit it and nothing is stored.
+
+### Which build these docs describe
+
+These docs describe `entrypoint/backlog/dist/index.js` built from revision
+`9df2a5c7`, whose `create`/`transition` inputs include `gitContext`. A
+**globally installed** `adhd-backlog` may be an older build (it is whatever was
+last published/installed); on such a build `gitContext` is not in the schema
+and is rejected with `invalid_argument`, and the stats/rollup ops
+(`priority-matrix` / `part-of-rollup` / `open-curve`) are absent. Run
+`adhd-backlog --help` and compare the `backlog create` / `backlog
+priority-matrix` lines against this page if a documented field or verb is
+refused.
+
+## Library API
+
+Beyond the CLI/MCP/HTTP surface, the package exports its query layer
+(`src/query/index.ts`), including three rollup/stats read views that are **not**
+members of `query.view`:
+
+- `priorityMatrix(handle, { filter? })` — a status-aware per-priority count
+  breakdown (defaults to open work; `filter.status` may be `'open'`, `'closed'`,
+  `'all'`, or a status name).
+- `partOfRollup(handle, { uid })` — transitive `part_of` descendants of an
+  issue, counted once each regardless of chain depth.
+- `openCurve(handle, { filter?, at })` — per-sampled-instant counts of issues
+  that existed and how many were open, reconstructed from the audit trail.
+
+Reach them by importing `@adhd/backlog` in-process. The same three are also
+mounted as operations — `priority-matrix` / `part-of-rollup` / `open-curve` on
+the CLI (`backlog_priority_matrix` / `backlog_part_of_rollup` /
+`backlog_open_curve` on MCP); see the command surface above.
+
+## Configuration
+
+Configuration cascades over `@adhd/environment`, prefixed `ADHD_BACKLOG_`
+(later layers override earlier: built-in default → config file → environment
+variable). The store defaults to a single shared **global** scope — one backlog
+spanning every project on the machine, not one per repository — so an agent
+working across repos sees the same graph everywhere unless it explicitly opts
+into a narrower scope.
+
+| Setting            | Env var                                               | Default                    | Notes                                                        |
+| ------------------ | ----------------------------------------------------- | -------------------------- | ------------------------------------------------------------ |
+| Database path      | `ADHD_BACKLOG_DATABASE_PATH`                          | resolved under the scope root | Where the graph store's data file lives                   |
+| Write busy timeout | `ADHD_BACKLOG_DATABASE_BUSY_TIMEOUT_MS`               | `5000`                     | How long a write waits on a contended lock before giving up  |
+| Log level          | `ADHD_BACKLOG_LOG_LEVEL`                              | `info`                     | `trace`\|`debug`\|`info`\|`warn`\|`error`\|`fatal`\|`silent` |
+| Scope              | `ADHD_BACKLOG_SCOPE` (falls back to `ADHD_ENV_SCOPE`) | `global`                   | Which store root to resolve against                          |
+| Namespace          | `--namespace <value>` CLI flag (no env var)           | `production`               | Which path segment under the scope root to resolve against (`<root>/backlog/<namespace>/…`) — one of `production`\|`test`\|`sandbox`. `--namespace sandbox` ALSO mints a fresh throwaway root and writes a real `config.yaml` there with `embedding.enabled: false`, so a sandboxed invocation is isolated along two independent axes plus a deliberate config, never an accident of an empty directory |
+| Semantic search    | `ADHD_BACKLOG_EMBEDDING_ENABLED`                      | `false`                    | See below                                                    |
+| Embedding provider | `ADHD_BACKLOG_EMBEDDING_PROVIDER`                     | `fastembed`                | Only consulted when embedding is enabled                     |
+| Embedding model    | `ADHD_BACKLOG_EMBEDDING_MODEL`                        | `bge-base-en-v1.5` (768-dim) | Only consulted when embedding is enabled                   |
+
+**Embedding (semantic search) is entirely optional.** With it left at its
+default (`false`), `@adhd/backlog` works fully — every verb, keyword filtering
+(`filter.grep`), and exact/registry lookup all function with no embedding
+backend at all. Turning `filter.semantic`, `filter.anchor`, `view:"similar"`,
+`sort:"relevance"`, or `fields:["_vector"]` on without an embedding backend
+configured doesn't crash anything — it returns a `rag_not_configured` error
+that says exactly that, so a caller can tell "not available" apart from "no
+matches." Enabling embedding requires two optional dependencies to be
+installed alongside the package and a store backend that supports native
+vector storage; if either is missing, backlog logs the reason and leaves
+semantic search unconfigured rather than failing to start.
+
+## Further docs
+
+- [`skill/SKILL.md`](skill/SKILL.md) — the full agent-facing command surface, worked examples, and filing rules.
+- [`SPEC.md`](SPEC.md) — the functional specification: operation surface, status vocabulary, acceptance criteria.
+- [`DATA_MODEL.md`](DATA_MODEL.md) — the node/edge model this package reads and writes.
+- [`CHANGELOG.md`](CHANGELOG.md) — version history.
+
+## Contributing
+
+See [`CONTRIBUTING.md`](CONTRIBUTING.md). This package is MIT-licensed under
+[`LICENSE`](LICENSE); security policy: [`SECURITY.md`](../../SECURITY.md).

package/api.d.ts

@@ -0,0 +1,146 @@
+import { IUpsertProjectInput, IUpsertProjectOutcome, IUpsertComponentInput, IUpsertComponentOutcome, IUpsertLocationInput, IUpsertLocationOutcome, IRmLocationInput, IRmLocationOutcome } from './write/catalog.js';
+import { IDeleteIssueInput, IDeleteIssueOutcome } from './write/delete.js';
+import { IMoveIssueInput, IMoveIssueOutcome } from './write/move.js';
+import { IRelateInput, IRelateOutcome } from './write/relate.js';
+import { IClaimInput, IClaimOutcome } from './write/claim.js';
+import { ITransitionInput, ITransitionOutcome } from './write/transition.js';
+import { IUpdateIssueInput, IUpdateIssueOutcome } from './write/update.js';
+import { ICreateIssueInput, ICreateIssueResult } from './write/create-issue.js';
+import { IIssueGetInput, IIssueGetResult, IIssueQueryInput, IIssueQueryResult, ILookupResult } from './query/types.js';
+import { IPriorityMatrixInput, IPriorityMatrixResult, IPartOfRollupInput, IPartOfRollupResult, IOpenCurveInput, IOpenCurveResult } from './query/views/stats.js';
+import { IOutcomeEnvelope } from './envelope.js';
+import { GraphBacklogStore } from './store/graph-backlog-store.js';
+import { BacklogConfig } from './env.js';
+import { Environment } from '@adhd/environment';
+
+/** The one type apigen special-cases via the `ctx-name-only` invariant. */
+export interface BacklogCtx {
+    store: GraphBacklogStore;
+    env: Environment<BacklogConfig>;
+    /**
+     * Test-isolation escape hatch ONLY — mirrors `BuildBacklogEnvOptions.adhdRoot`
+     * (the same value passed to `buildBacklogEnv({ adhdRoot })` when constructing
+     * `env`). NEVER set this in production code (`server.ts`/`cli.ts` never do).
+     */
+    adhdRoot?: string;
+}
+/**
+ * Fetch one issue by `uid`, projected to the requested `fields`.
+ *
+ * Defaults to the same five-field card `query` returns
+ * (`uid`, `kind`, `title`, `status`, `priority`).
+ */
+export declare function get(ctx: BacklogCtx, input: IIssueGetInput): Promise<IOutcomeEnvelope<IIssueGetResult>>;
+/**
+ * Search, filter, group and paginate issues.
+ *
+ * Supports field projection, keyset and offset pagination, the `view`/`groupBy`
+ * aggregate axes, and `grep`/`semantic` text filters.
+ */
+export declare function query(ctx: BacklogCtx, input: IIssueQueryInput): Promise<IOutcomeEnvelope<IIssueQueryResult>>;
+/**
+ * SPEC.md §5's status-aware priority matrix (BUG-023) — a per-priority
+ * breakdown of issue counts, scoped by `project`/`component`/`kind`/`status`.
+ *
+ * An omitted `input.filter.status` scopes to OPEN work (a deliberate
+ * divergence from `query`'s `list` default, where an omitted status means "no
+ * restriction"); the applied scope is echoed on `data.statusScope`, so a
+ * default-scoped result can never be mistaken for an all-status one. `{}` is a
+ * valid input.
+ *
+ * A read op, NOT a `query.view` member: it returns a matrix
+ * (`{rows, unassigned, statusScope}`) rather than a `{view, items}` list
+ * permutation, and mounting it as a view would force `IIssueQueryInput` to
+ * carry axes (`at`, an issue root) the other views must reject. Uses only
+ * `handle.graph` — hence `needsSemantic:false`/`probeSpace:false`, so this op
+ * never pays the cold semantic-backend bootstrap (`queryHandle`'s own doc
+ * comment).
+ */
+export declare function priorityMatrix(ctx: BacklogCtx, input: IPriorityMatrixInput): Promise<IOutcomeEnvelope<IPriorityMatrixResult>>;
+/**
+ * SPEC.md §5's `part_of` hierarchy rollup (FEAT-005) — every TRANSITIVE
+ * descendant of the root issue `input.uid` via `part_of` (issue → issue,
+ * `n:1`), counted exactly once each regardless of chain depth, split into
+ * `childrenOpen`/`childrenClosed` (plus the open descendants' uids).
+ *
+ * A read op, NOT a `query.view` member: it is rooted at an issue (`uid`), a
+ * per-op input no list view carries. Uses only `handle.graph` — see
+ * {@link priorityMatrix}'s note on the `queryHandle` gates.
+ */
+export declare function partOfRollup(ctx: BacklogCtx, input: IPartOfRollupInput): Promise<IOutcomeEnvelope<IPartOfRollupResult>>;
+/**
+ * SPEC.md §5's `validAt` cumulative-open curve — for each sampled ISO-8601
+ * instant in `input.at`, how many in-scope issues EXISTED then and, of those,
+ * how many were reconstructed as OPEN then (never the issue's current status;
+ * see `openCurve`'s own doc comment for the reconstruction rule).
+ *
+ * A read op, NOT a `query.view` member: it returns a time series
+ * (`{points}`) keyed by a caller-given instant list, an axis no list view has.
+ * Uses only `handle.graph` — see {@link priorityMatrix}'s note on the
+ * `queryHandle` gates.
+ */
+export declare function openCurve(ctx: BacklogCtx, input: IOpenCurveInput): Promise<IOutcomeEnvelope<IOpenCurveResult>>;
+/**
+ * Resolve a free-text reference to a project, component or location in the
+ * registry.
+ */
+export declare function lookup(ctx: BacklogCtx, input: {
+    q: string;
+}): Promise<IOutcomeEnvelope<ILookupResult>>;
+/** File a new issue, minting its `uid` and linking it to a project component. */
+export declare function create(ctx: BacklogCtx, input: ICreateIssueInput): Promise<IOutcomeEnvelope<ICreateIssueResult>>;
+/**
+ * Edit an existing issue.
+ *
+ * A `body` change supersedes the issue, minting a fresh `uid`; every other
+ * change edits the existing node in place. `status` is not editable here —
+ * use `transition`.
+ */
+export declare function update(ctx: BacklogCtx, input: IUpdateIssueInput): Promise<IOutcomeEnvelope<IUpdateIssueOutcome>>;
+/** Move an issue to a new status, recording the transition in its audit trail. */
+export declare function transition(ctx: BacklogCtx, input: ITransitionInput): Promise<IOutcomeEnvelope<ITransitionOutcome>>;
+/** Take, renew or release an exclusive working lease on an issue. */
+export declare function claim(ctx: BacklogCtx, input: IClaimInput): Promise<IOutcomeEnvelope<IClaimOutcome>>;
+/** Create or remove a typed relationship between two issues. */
+export declare function relate(ctx: BacklogCtx, input: IRelateInput): Promise<IOutcomeEnvelope<IRelateOutcome>>;
+/** Re-file an issue under a different project component. */
+export declare function move(ctx: BacklogCtx, input: IMoveIssueInput): Promise<IOutcomeEnvelope<IMoveIssueOutcome>>;
+/**
+ * Soft-delete an issue.
+ *
+ * The node is closed off bi-temporally, never physically removed — its audit
+ * trail and every edge pointing at it remain readable.
+ */
+declare function remove(ctx: BacklogCtx, input: IDeleteIssueInput): Promise<IOutcomeEnvelope<IDeleteIssueOutcome>>;
+/**
+ * Create or update a project by `name`.
+ *
+ * On first creation, also mints the project's reserved default component
+ * `(root)`. A repeat call against an existing project is idempotent.
+ */
+export declare function upsertProject(ctx: BacklogCtx, input: IUpsertProjectInput): Promise<IOutcomeEnvelope<IUpsertProjectOutcome>>;
+/** Create or update a component by `(project, name)`. */
+export declare function upsertComponent(ctx: BacklogCtx, input: IUpsertComponentInput): Promise<IOutcomeEnvelope<IUpsertComponentOutcome>>;
+/**
+ * Create or find a location by `(component, locType, value)`.
+ *
+ * A component referenced by bare name (rather than uid) requires `project`
+ * to disambiguate it.
+ */
+export declare function upsertLocation(ctx: BacklogCtx, input: IUpsertLocationInput): Promise<IOutcomeEnvelope<IUpsertLocationOutcome>>;
+/** Soft-remove a location by `uid`. */
+export declare function rmLocation(ctx: BacklogCtx, input: IRmLocationInput): Promise<IOutcomeEnvelope<IRmLocationOutcome>>;
+/**
+ * SPEC §6.7 names this verb `delete` on every mount (`backlog_delete`,
+ * `backlog delete`, `DELETE /issue`). `export async function delete` is a
+ * syntax error — `delete` is a reserved word — but an export CLAUSE may alias
+ * to any IdentifierName, reserved words included, and apigen resolves the
+ * mounted name from `sf.getExportedDeclarations()` (ts-morph's own
+ * rename/re-export resolver, which extract.ts documents as covering "named
+ * exports — local, renamed, AND re-exported"). So the operation mounts as
+ * `delete` while the implementation keeps a legal identifier.
+ *
+ * Do NOT "simplify" this to `export async function remove`: that silently
+ * renames the tool to `backlog_remove` on all four transports.
+ */
+export { remove as delete };