@adhd/backlog 1.0.4 → 1.0.6

package/query/views/stats.d.ts

@@ -1,5 +1,6 @@
 import { IQueryStoreHandle } from '../query.js';
 import { IIssueFilter } from '../types.js';
+import { GraphBackend, NodeRecord } from '@adhd/sox-graph-store';
 
 export interface IPriorityMatrixRow {
     priority: string;
@@ -20,11 +21,39 @@ export interface IPriorityMatrixInput {
     /** `project`/`component`/`kind`/`status` only (§6.5 rule 3's edge-scoped dimensions, restricted to what a priority breakdown composes with) — any other key throws. */
     filter?: IIssueFilter;
 }
+/**
+ * An `IIssueFilter`'s placement/kind/status dimensions resolved to the
+ * concrete set of LIVE, non-superseded issue nodes they match — the exact
+ * scoping `priorityMatrix` counts over. See
+ * {@link resolveScopedLiveIssueNodes}.
+ */
+export interface IScopedLiveIssues {
+    nodes: NodeRecord[];
+    statusScope: NonNullable<IIssueFilter['status']>;
+}
+/**
+ * Resolve an `IIssueFilter`'s placement/kind/status dimensions to the concrete
+ * set of LIVE, non-superseded issue NODES they match — the exact scoping
+ * `priorityMatrix` (and, via it, `report`) counts over. Exported so `report`
+ * composes this ONE implementation rather than re-deriving it (ADR-0002).
+ *
+ * `nodes: []` (never `undefined`) when a placement dimension resolved to an
+ * empty set or the status scope matched nothing, so callers branch on one
+ * shape. `statusScope` always names the scope applied — `'open'` when the
+ * filter omitted `status`, mirroring `priorityMatrix`'s BUG-023 default.
+ */
+export declare function resolveScopedLiveIssueNodes(graph: GraphBackend, filter: IIssueFilter | undefined): Promise<IScopedLiveIssues>;
 /** SPEC.md §5's status-aware priority matrix (BUG-023). */
 export declare function priorityMatrix(handle: IQueryStoreHandle, input?: IPriorityMatrixInput): Promise<IPriorityMatrixResult>;
 export interface IPartOfRollupInput {
     /** The root issue's `uid` (§6.1). Throws `IssueNotFoundError` if it does not resolve to a live issue. */
     uid: string;
+    /** Count-only mode: return the counts, omit the `childrenOpenUids` uid list entirely. */
+    countOnly?: boolean;
+    /** Max uids in `childrenOpenUids` when not count-only (default 50, max 1000). */
+    limit?: number;
+    /** Opaque cursor for the paged uid list — pass the previous page's `nextCursor`. */
+    after?: string;
 }
 export interface IPartOfRollupResult {
     uid: string;
@@ -32,9 +61,16 @@ export interface IPartOfRollupResult {
     childrenTotal: number;
     childrenOpen: number;
     childrenClosed: number;
-    /** `uid`s of the still-open descendants — the actionable half, mirroring the `IIssueRef`-shaped convention `card.ts`'s `blockers`/`related` already use. */
-    childrenOpenUids: readonly string[];
+    /** `uid`s of the still-open descendants — the actionable half, mirroring the `IIssueRef`-shaped convention `card.ts`'s `blockers`/`related` already use. Absent in count-only mode, or present and bounded by `limit`. */
+    childrenOpenUids?: readonly string[];
+    /** Pass back as `after` for the next page; absent ⇒ no further open-descendant uids. */
+    nextCursor?: string;
+    /** True iff more open-descendant uids exist beyond this page. */
+    hasMore?: boolean;
 }
+/** Default/maximum uid-list page size for {@link partOfRollup}'s non-count-only mode. */
+export declare const DEFAULT_PART_OF_ROLLUP_LIMIT = 50;
+export declare const MAX_PART_OF_ROLLUP_LIMIT = 1000;
 /**
  * SPEC.md §5's `part_of` + derived two-axis rollup (FEAT-005), realized as
  * ONE axis here — children-open/closed over the FULL transitive subtree

package/readiness.d.ts

@@ -0,0 +1,29 @@
+import { IServiceFailure } from './lifecycle.js';
+
+export interface IReadinessTimer {
+    setTimeout(fn: () => void, ms: number): unknown;
+    clearTimeout(handle: unknown): void;
+}
+/** The minimal composed-server surface the probe needs. */
+export interface IReadinessHandle {
+    pkg: {
+        fns: Record<string, (...args: unknown[]) => unknown>;
+        createClient: () => Promise<unknown>;
+    };
+    operations: readonly {
+        id: string;
+    }[];
+    store: unknown;
+}
+export interface IReadinessProbeOpts {
+    timeoutMs: number;
+    /** Injectable one-shot timer so a test uses a virtual clock, never sleep. */
+    timer?: IReadinessTimer;
+    /** Test seam: the exact serving-path call to drive. */
+    invoke?: () => Promise<unknown>;
+}
+export interface IReadinessResult {
+    ready: boolean;
+    failure?: IServiceFailure;
+}
+export declare function probeReadiness(handle: IReadinessHandle, opts: IReadinessProbeOpts): Promise<IReadinessResult>;

package/retry-policy.d.ts

@@ -0,0 +1,44 @@
+export interface IResiliencePolicy {
+    maxAttempts: number;
+    baseMs: number;
+    maxMs: number;
+    budgetMs: number;
+    breakerFailureThreshold: number;
+    breakerResetMs: number;
+}
+/** Full jitter: `rand() * min(maxMs, baseMs * 2**attempt)`. */
+export declare function fullJitterDelay(attempt: number, p: Pick<IResiliencePolicy, 'baseMs' | 'maxMs'>, rand: () => number): number;
+export type IBreakerState = 'closed' | 'open' | 'half-open';
+export declare class CircuitBreaker {
+    private failures;
+    private openedAt;
+    private probing;
+    private readonly failureThreshold;
+    private readonly resetMs;
+    private readonly now;
+    constructor(p: {
+        failureThreshold: number;
+        resetMs: number;
+        now?: () => number;
+    });
+    state(): IBreakerState;
+    /** open → refuse (no attempt). closed/half-open → allow one. */
+    tryPass(): boolean;
+    /** → closed. */
+    onSuccess(): void;
+    /** → open after threshold (or immediately on a failed half-open probe). */
+    onFailure(): void;
+}
+export interface IResilienceDeps {
+    graceMs: number;
+    rand: () => number;
+    now: () => number;
+    sleep: (ms: number) => Promise<void>;
+}
+/**
+ * Wraps the connect/handshake of ONE call. Applies `graceMs` to the FIRST
+ * attempt's deadline (the cold-start window) BEFORE any retry, then retries
+ * with full jitter inside a total `budgetMs`; refuses immediately when the
+ * breaker is open. On budget exhaustion / open breaker → {@link ServiceNotReadyError}.
+ */
+export declare function withResilience<T>(fn: (attempt: number, deadlineMs: number) => Promise<T>, p: IResiliencePolicy, breaker: CircuitBreaker, deps: IResilienceDeps): Promise<T>;

package/serve.d.ts

@@ -23,7 +23,7 @@ export interface RunServeCommandOpts {
  * (never a bare `Error`) so `runServeCommand` can catch it and hand it to
  * `failUsage` instead of letting it reach the bin guard's stack-trace path.
  */
-export declare const SERVE_HELP_TEXT = "backlog serve [--transport mcp|http|both] [--port N] [--host H]\n\nStarts the long-lived backlog server (MCP and/or HTTP), matching one of the\nprocess's own configured transports to the way an agent host or a script\nexpects to reach it.\n\n  --transport <name>  mcp | http | both (default: mcp)\n  --port <N>           HTTP listen port (default: 3300; ignored for mcp-only)\n  --host <name>         HTTP listen host (default: 127.0.0.1; ignored for mcp-only)\n\nExamples:\n  backlog serve\n  backlog serve --transport http --port 3300\n  backlog serve --transport both --host 0.0.0.0\n";
+export declare const SERVE_HELP_TEXT = "backlog serve [--transport mcp|http|both] [--port N] [--host H]\n\nStarts the long-lived backlog server (MCP and/or HTTP), matching one of the\nprocess's own configured transports to the way an agent host or a script\nexpects to reach it.\n\n  --transport <name>  mcp | http | both (default: from ADHD_BACKLOG_SERVICE_TRANSPORT\n                      / the service.* config, else mcp)\n  --port <N>           HTTP listen port (default: from ADHD_BACKLOG_SERVICE_PORT\n                      / the service.* config, else 3300; ignored for mcp-only)\n  --host <name>         HTTP listen host (default: from ADHD_BACKLOG_SERVICE_HOST\n                      / the service.* config, else 127.0.0.1; ignored for mcp-only)\n  --ready-file <path>   Write the service report to <path> once the server is\n                        READY (the serving path answered), atomically, and\n                        again on every state change.\n  --probe               Run the serving-path readiness probe once, print the\n                        report as JSON, and exit 0 (ready) / 1 (not ready).\n\nExamples:\n  backlog serve\n  backlog serve --transport http --port 3300\n  backlog serve --transport both --host 0.0.0.0\n  backlog serve --transport mcp --ready-file /run/backlog/ready.json\n  backlog serve --probe\n";
 /** Runs until the process receives SIGTERM/SIGINT (the normal way a host
  *  process manager — or `.mcp.json`'s own stdio transport lifecycle — stops
  *  a long-lived MCP/HTTP server), then resolves cleanly. */

package/server.d.ts

@@ -1,3 +1,5 @@
+import { IServiceReport } from './lifecycle.js';
+import { BACKLOG_VERBS } from './vocabulary.js';
 import { BacklogCtx } from './api.js';
 import { HttpVerb } from '@adhd/apigen-engine-naming';
 import { composeSchemas, Operation, Plugin, Logger, OutputPlugin, RunInput } from '@adhd/apigen-core-client';
@@ -83,7 +85,7 @@ export declare const BACKLOG_HOST_COMMANDS: readonly string[];
  *
  * Order is the SPEC.md §4/§6 declaration order, not alphabetical; compare as sets.
  */
-export declare const BACKLOG_VERBS: readonly string[];
+export { BACKLOG_VERBS };
 /**
  * One mounted operation, projected to all four transports backlog serves.
  *
@@ -149,8 +151,43 @@ export declare function describeMountedSurface(operations: readonly Operation[])
  * shipped surface automatically.
  */
 export declare function resolveExpectedMcpToolNames(operations: readonly Operation[], usePlugins?: readonly Plugin[]): string[];
+/**
+ * The full advertised surface, one entry per pinned data verb, each projecting
+ * to the identical `id`/`mcpTool`/`cliCommand` a real mounted operation has.
+ *
+ * Derived from {@link BACKLOG_VERBS} (the single pinned list) so it can never
+ * drift from what `server.verbs.spec.ts` checks; {@link assertSurfaceIsReal}
+ * proves each entry is actually present in the built package.
+ */
+export declare function describeBacklogSurface(): IMountedOperationSurface[];
+/**
+ * Assert that every advertised verb is a REAL mounted operation in the built
+ * package — the AC3 mechanism, and the fix for the `enrich` class of defect
+ * (an agent spec that advertises a verb this tool does not implement).
+ *
+ * Reads the baked operation descriptors (`dist/api.ir.json`, the SAME artifact
+ * every real mount composes from) and compares its projected surface against
+ * {@link describeBacklogSurface} **both ways**: a verb advertised but absent
+ * from the build throws (naming it), and an operation mounted but absent from
+ * the pinned list also throws (a split brain). The artifact reader is
+ * synchronous and content-hash validated; a missing/stale artifact is a hard
+ * failure, never a silent pass (an unverifiable surface is not a real one).
+ *
+ * Library-only / NEVER mounted (`index.ts` re-exports it): it opens no store.
+ */
+export declare function assertSurfaceIsReal(): void;
 export interface StartOpts {
-    transport: 'http' | 'mcp' | 'both';
+    /**
+     * OPTIONAL on purpose (D-A apply-fix): an omitted transport must NOT
+     * pre-empt the resolved `service.*` cascade. `resolveServiceConfig`'s
+     * precedence is explicit opts > `ADHD_BACKLOG_SERVICE_TRANSPORT` > layer
+     * files > the `'mcp'` code default, and it only consults `opts.transport`
+     * when it is actually present — so `serve.ts` must pass `undefined` (not a
+     * materialised `'mcp'`) when the operator did not type `--transport`.
+     * `createBacklogServer` mounts from the RESOLVED `serviceConfig.transport`,
+     * never from this raw field.
+     */
+    transport?: 'http' | 'mcp' | 'both';
     port?: number;
     host?: string;
     scope?: Scope;
@@ -205,9 +242,40 @@ export declare function buildBacklogApigenPackage(ctx: BacklogCtx | (() => Backl
     surface: IMountedOperationSurface[];
     operations: Operation[];
 }>;
+/**
+ * The long-lived server handle (D-A, Segment D). Additive: existing callers
+ * keep using {@link startBacklogServer} (unchanged `Promise<void>` signature).
+ */
+export interface IBacklogServerHandle {
+    report(): IServiceReport;
+    whenReady(): Promise<void>;
+    /** Resolves when the server has fully closed (store released). Additive. */
+    whenClosed(): Promise<void>;
+    /** Abort the transports and release the store. Idempotent. */
+    close(): Promise<void>;
+}
 /**
  * Opens (or reuses) the backlog store + env, mounts every `client.ts` export
  * live via `@adhd/apigen-plugin-api-fastify` and/or `@adhd/apigen-plugin-mcp`
- * — no code generation.
+ * — no code generation — and returns a lifecycle handle.
+ *
+ * D-A additions: resolves + validates `service.*` config, runs the load-time
+ * artifact drift check, and drives the `starting → live → ready` lifecycle
+ * with a serving-path readiness probe. `startBacklogServer` (below) is the
+ * unchanged-signature wrapper over this function.
+ */
+export declare function createBacklogServer(opts: StartOpts & {
+    onStateChange?: (r: IServiceReport) => void;
+    /**
+     * `--probe` mode: compose the serving path but do NOT mount a network
+     * transport. The readiness probe drives the SAME composed invoker the
+     * tools use, so a live socket is not required — and skipping the mount
+     * avoids a one-shot probe process being kept alive by a listening socket.
+     */
+    probeOnly?: boolean;
+}): Promise<IBacklogServerHandle>;
+/**
+ * UNCHANGED public signature (`Promise<void>`, resolves on close) — a thin
+ * wrapper over {@link createBacklogServer} for existing callers.
  */
 export declare function startBacklogServer(opts: StartOpts): Promise<void>;

package/service-config.d.ts

@@ -0,0 +1,109 @@
+import { StartOpts } from './server.js';
+import { BacklogConfig } from './env.js';
+import { Environment } from '@adhd/environment';
+import { Scope } from '@adhd/environment-base-spec';
+
+export type IServiceTransport = 'mcp' | 'http' | 'both';
+export interface IArtifactIdentity {
+    kind: 'path' | 'package';
+    /** kind:'path' — sha256 hex of the resolved entry file. */
+    sha256?: string;
+    /** kind:'package' — the published name + version to match. */
+    name?: string;
+    version?: string;
+}
+export interface IServiceConfig {
+    transport: IServiceTransport;
+    port: number;
+    host: string;
+    scope: Scope;
+    /** MUST be absolute (or the literal ':memory:' test path). */
+    dbPath: string;
+    busyTimeoutMs: number;
+    server: {
+        /** Absolute path, or a PATH-resolvable bin (`npx`/`node`). `''` = unset. */
+        command: string;
+        identity: IArtifactIdentity;
+    };
+    readiness: {
+        timeoutMs: number;
+    };
+    connect: {
+        /** Pre-connect deadline extension — the cold-start grace window. */
+        graceMs: number;
+        /** Total wall-clock budget across all attempts (bounded, never unbounded). */
+        budgetMs: number;
+        maxAttempts: number;
+        baseMs: number;
+        maxMs: number;
+        breakerFailureThreshold: number;
+        breakerResetMs: number;
+    };
+}
+/**
+ * The schema owner for the `service.*` subtree — the allow-list unknown keys
+ * are checked against. The keys are FULL dot-paths; `env.ts`'s spec declares
+ * exactly this set and a unit test asserts the two cannot drift.
+ *
+ * D-A apply-fix (2026-09-27): four keys that were RESOLVED but consumed by
+ * nothing were REMOVED rather than shipped as silent no-ops (the finding's
+ * "wire it, or stop declaring it" rule):
+ *   - `service.namespace` — directly contradicts `env.ts`'s own contract that
+ *     namespace selection is explicit-parameter-only
+ *     (`BuildBacklogEnvOptions.namespace`), never resolved from an env var or
+ *     config file; a key that can never be honored only misleads.
+ *   - `service.serverArgs` — this process IS the server; nothing ever LAUNCHES
+ *     `server.command` (its sole consumer is the load-time artifact-drift
+ *     check, which ignores args), so args had no role.
+ *   - `service.readinessIntervalMs` / `service.readinessMaxMissedTicks` — they
+ *     describe a serving-loop watchdog TICK, but no such tick exists here and
+ *     a same-process watchdog cannot observe its own frozen event loop;
+ *     genuinely a later (external-supervisor) slice.
+ * The remaining keys are all APPLIED: transport/port/host mount the server,
+ * `serverCommand` drives `assertServerArtifact`, `connect*` drives
+ * `withResilience` around the serving-path readiness probe, and
+ * `readinessTimeoutMs` caps one probe.
+ */
+export declare const SERVICE_CONFIG_KEYS: readonly string[];
+/**
+ * True when `candidate` is an executable bin reachable on `PATH`. An absolute
+ * path is NOT automatically accepted here — the drift check owns absolute
+ * existence; this helper only answers "can the shell find this bare name".
+ */
+export declare function isPathResolvableBin(candidate: string): boolean;
+/**
+ * Resolves, validates and freezes the `service.*` configuration for one
+ * process. Throws {@link UnknownConfigKeyError} on an unknown key in ANY
+ * layer file and {@link NonAbsolutePathError} on a relative path field.
+ */
+export declare function resolveServiceConfig(opts: StartOpts, env: Environment<BacklogConfig>): IServiceConfig;
+export interface IMcpServerEntry {
+    type?: string;
+    command?: string | string[];
+    args?: string[];
+    env?: Record<string, string>;
+    url?: string;
+}
+/**
+ * Validates ONE host MCP server entry the tool writes or reads. Unknown keys
+ * are a HARD ERROR (the recorded `environment` vs `env` silent no-op is the
+ * exact failure): a key outside the entry's own schema
+ * (`type/command/args/env/url`) throws {@link UnknownMcpConfigKeyError}; a
+ * relative `command` path that is not a PATH-resolvable bin throws
+ * {@link NonAbsolutePathError}.
+ */
+export declare function assertMcpEntryValid(entry: unknown, hostPath: string): asserts entry is IMcpServerEntry;
+/**
+ * Load-time drift check. Resolves `server.command` to an absolute path (or a
+ * PATH-resolvable bin recorded with its resolved path), asserts it EXISTS, is
+ * EXECUTABLE, and that its content identity matches `server.identity`:
+ *
+ *   - `kind:'path'`    → sha256(resolved file) === identity.sha256
+ *   - `kind:'package'` → the resolved package's package.json version === identity.version
+ *
+ * On missing/drift → {@link ArtifactDriftError} naming the resolved absolute
+ * path — it refuses to start rather than launch a phantom. A PURE read: it
+ * mutates nothing. A `command` that is unset (`''`) is a no-op, so a process
+ * that is not configured to launch an external artifact is never blocked.
+ */
+export declare function assertServerArtifact(server: IServiceConfig['server']): void;

package/service-errors.d.ts

@@ -0,0 +1,51 @@
+import { BacklogWriteError } from './write/errors.js';
+
+/** An unknown key under the `service.*` config subtree in a layer file. */
+export declare class UnknownConfigKeyError extends BacklogWriteError {
+    readonly code: "E_VALIDATION";
+    readonly retryable = false;
+    /** The offending key, WITHOUT the `service.` prefix (e.g. `bogusKey`). */
+    readonly key: string;
+    /** The absolute layer file the key was found in. */
+    readonly file: string;
+    constructor(key: string, file: string);
+}
+/** A path-valued config field that is neither absolute nor a PATH bin. */
+export declare class NonAbsolutePathError extends BacklogWriteError {
+    readonly code: "E_VALIDATION";
+    readonly retryable = false;
+    readonly field: string;
+    readonly value: string;
+    constructor(field: string, value: string);
+}
+/** An unknown key inside a host MCP server entry (the `environment` vs `env`
+ *  silent no-op is the exact failure this prevents). */
+export declare class UnknownMcpConfigKeyError extends BacklogWriteError {
+    readonly code: "E_VALIDATION";
+    readonly retryable = false;
+    /** The host config file the entry lives in. */
+    readonly entry: string;
+    readonly key: string;
+    /** Closest allowed key, when one is close enough to suggest. */
+    readonly suggestion?: string;
+    constructor(entry: string, key: string, suggestion?: string);
+}
+/** The configured server artifact is missing, non-executable, or its content
+ *  identity does not match what was installed. */
+export declare class ArtifactDriftError extends BacklogWriteError {
+    readonly code: "E_VALIDATION";
+    readonly retryable = false;
+    readonly expected: string;
+    readonly actual: string;
+    readonly resolvedPath: string;
+    constructor(expected: string, actual: string, resolvedPath: string);
+}
+/** A readiness/liveness failure surfaced by the resilience layer (a bounded
+ *  budget was exhausted, or the breaker refused the attempt). */
+export declare class ServiceNotReadyError extends BacklogWriteError {
+    readonly code: "E_VALIDATION";
+    readonly retryable = true;
+    readonly state: string;
+    readonly failure?: string;
+    constructor(state: string, failure?: string);
+}