@adhd/backlog 1.0.5 → 1.0.6

package/query/types.d.ts

@@ -1,17 +1,8 @@
-/**
- * types.ts — the read/query-layer's own shared types (SPEC.md §5, §5a, §6.1, §6.5).
- *
- * These are the TYPESCRIPT shapes for the `get`/`query` verbs (§6.3.1, §6.5)
- * and the §3a registry read views. They intentionally mirror SPEC.md's own
- * `IIssue*`/`IProject*` interfaces field-for-field — this file is the single
- * place those interfaces are declared for the read layer; `get.ts`/`query.ts`/
- * `registry.ts` all import from here rather than re-declaring their own
- * copies, and the six sibling write verbs (`update`/`transition`/`claim`/
- * `relate`/`move`/`delete`) should import {@link IIssueCard} /
- * {@link IIssueField} from here too, rather than re-declaring a third copy
- * alongside `create-issue.ts`'s own `IIssueCard` (see this module's own
- * top-level doc comment in `index.ts` for the reconciliation note).
- */
+import { CatalogKindName, ICatalogTerm, ICatalogView } from './views/catalog.js';
+import { SpecFreshness } from './spec-staleness.js';
+import { ICitationRecord } from '../citation.js';
+import { IObligationAppliesTo, IObligationOverride, IObligationSeverity, IPredicate } from '../write/obligation.js';
+
 /** Identity is the global `uid` (SPEC.md §6.1) — a single scalar, never a composite key. */
 export type IssueUid = string;
 /**
@@ -32,31 +23,25 @@ export type IssueUid = string;
  * response) and is therefore NEVER included in the default card.
  */
 export type IIssuePlainField = 'uid' | 'title' | 'kind' | 'status' | 'priority' | 'project' | 'component' | 'createdAt' | 'updatedAt' | 'assignee' | 'author' | 'closedAt' | 'gitContext';
-export type IIssuePseudoField = 'body' | 'citations' | 'notes' | 'auditTrail' | 'blockers' | 'related' | '_score' | '_vector';
+export type IIssuePseudoField = 'body' | 'citations' | 'notes' | 'auditTrail' | 'blockers' | 'related' | '_score' | '_vector' | 'blocksOut' | 'dependents' | 'partOf' | 'obligations' | 'verdict' | 'spec' | 'similar';
 export type IIssueField = IIssuePlainField | IIssuePseudoField;
 export declare const ISSUE_PLAIN_FIELDS: readonly IIssuePlainField[];
 export declare const ISSUE_PSEUDO_FIELDS: readonly IIssuePseudoField[];
 export declare function isKnownIssueField(name: string): name is IIssueField;
 /** SPEC.md §6.5: "Default (`fields` omitted): the exact five-field terse card established by `DEFAULT_CARD_FIELDS`." */
 export declare const DEFAULT_ISSUE_CARD_FIELDS: readonly IIssuePlainField[];
-/** A citation, projected for read (mirrors the write layer's `ICitationInput` shape plus the server-computed `sha`). */
-export interface IIssueCitation {
-    uid: string;
-    file: string;
-    lines?: string;
-    /**
-     * Free-text prose for this citation (the write layer's `ICitationInput.context`).
-     * NOT the item's disclosure-contract git context — that is ITEM-level
-     * provenance and lives on {@link IIssueCard.gitContext}, a sibling of
-     * `assignee`, rendered once at the head of the `Citations:` block. This
-     * per-citation `context` is never rendered by `markdown.ts` and cannot carry
-     * the git context.
-     */
-    context?: string;
-    symbol?: string;
-    sha: string;
-    at: string;
-}
+/**
+ * A citation, projected for read — the ONE citation contract
+ * (`../citation.ts`'s `ICitationRecord`: `ICitation` plus the server-computed
+ * `uid`/`sha`/`at` and the persisted `target_type`) with no re-declaration
+ * here. `context` is the per-citation free-text prose (the contract's
+ * `context`, persisted on the node's `content` column); it is NOT the item's
+ * disclosure-contract git context, which is ITEM-level provenance on
+ * {@link IIssueCard.gitContext} and rendered once at the head of the block.
+ * `revision`, when present, names the git revision the target was resolved
+ * against (a revision-pinned citation).
+ */
+export type IIssueCitation = ICitationRecord;
 export interface IIssueNote {
     uid: string;
     author: string;
@@ -78,6 +63,91 @@ export interface IIssueRef {
     uid: string;
     title: string;
     status: string;
+    /**
+     * Which live relation produced this ref (C2 — structural legibility).
+     * ADDITIVE — existing consumers reading `uid`/`title`/`status` are
+     * unaffected. `related` now surfaces every live relation type: `relates_to`
+     * and `part_of` in both directions, and `blocks` (outbound, tagged
+     * `blocks`) / incoming (tagged `blocked_by`). `similar_to` (C9's reviewed
+     * similarity link) and the reserved `duplicate_of` are declared here for
+     * the same ref shape's future producers.
+     */
+    rel?: 'relates_to' | 'part_of' | 'blocks' | 'blocked_by' | 'similar_to' | 'duplicate_of';
+}
+/**
+ * A declared obligation, projected for read (C4). This is the STORED shape,
+ * never an evaluation: `requirement` is the predicate as written, and nothing
+ * on the read path resolves it (that is C5's gate / C6's verdict). `on_fail` is
+ * returned verbatim so a caller can see the declared severity.
+ *
+ * The predicate/applies-to/override types are imported `import type`-only from
+ * `write/obligation.ts` — the grammar is declared in exactly one place, and a
+ * type-only import introduces no runtime dependency from `query/**` onto
+ * `write/**` (the two are already coupled on `write/errors.js`).
+ */
+export interface IObligationView {
+    uid: string;
+    applies_to: IObligationAppliesTo;
+    requirement: IPredicate;
+    on_fail: IObligationSeverity;
+    override?: IObligationOverride;
+}
+/**
+ * Provenance of an `IIssueCard._score` (DESIGN §2 Invariant 5: "a `score_kind`
+ * provenance tag on every derived score"). A rank-derived score (`rrf`) is
+ * ORDINAL — never to be labelled or read as a similarity/confidence; `bm25`
+ * is likewise corpus-relative. A consumer that sees a bare `_score` with no
+ * `_score_kind` cannot know which regime produced it, which is exactly the
+ * conflation this tag prevents.
+ */
+export type IScoreKind = 'rrf' | 'bm25' | 'cosine' | 'rank' | 'priority';
+/**
+ * The closed CONDITION type vocabulary. A `Condition` names one thing that can
+ * make an item non-actionable (or warn about it); `status` says whether that
+ * named condition HOLDS (`{type:'Blocked',status:True}` ⇒ the item IS blocked).
+ */
+export type IConditionType = 'Blocked' | 'Obligation' | 'Evidence' | 'Claim' | 'Reference' | 'Budget';
+/** Whether the NAMED condition holds. `Unknown` is a first-class "could not determine", distinct from `False`. */
+export type IConditionStatus = 'True' | 'False' | 'Unknown';
+/** `block` flips actionability false; `warn` is reported but never blocks (systemd Condition-vs-Assert split). */
+export type IConditionSeverity = 'block' | 'warn';
+/**
+ * The governed reason-code core (DESIGN §2 Primitive 4) plus the
+ * `<domain>/<Code>` extension namespace. `Unknown` is the honest "the check
+ * was not run / could not be decided".
+ */
+export type IVerdictReasonCode = 'BlockedBy' | 'MissingObligation' | 'EvidenceUnverified' | 'EvidenceStale' | 'ClaimStale' | 'ReferenceUnresolved' | 'Unknown' | `${string}/${string}`;
+/**
+ * TRI-STATE (DESIGN §2 Primitive 4) — NEVER a bare boolean. `'unknown'` is
+ * never a green light: a caller that handles only booleans must be told, and
+ * the list path must report `'unknown'` rather than `true` where it cannot
+ * afford the rung. `false` iff a `block`-severity condition is `True`;
+ * `'unknown'` iff a `block`-severity condition is `Unknown` (and none is
+ * `True`); otherwise `true`.
+ */
+export type IActionable = boolean | 'unknown';
+/** One named condition of a {@link IVerdict}. */
+export interface ICondition {
+    type: IConditionType;
+    /** Whether the NAMED condition HOLDS: `True` on a `Blocked` condition = IS blocked. */
+    status: IConditionStatus;
+    severity: IConditionSeverity;
+    code: IVerdictReasonCode;
+    message?: string;
+    /** The thing to fix (blocker uid / attestation uid / obligation uid). */
+    subject?: string;
+}
+/**
+ * The verdict — derived on read, never stored (`revision` is the node's own
+ * current content revision, so a caller can detect staleness; there is no
+ * materialized status field anywhere).
+ */
+export interface IVerdict {
+    actionable: IActionable;
+    evaluated_at: string;
+    revision: number;
+    /** Ordered block-severity first, then warn. */
+    conditions: ICondition[];
 }
 /**
  * The projected issue card (SPEC.md §6.5's `IIssueCard`). Every field is
@@ -116,7 +186,52 @@ export interface IIssueCard {
     blockers?: IIssueRef[];
     related?: IIssueRef[];
     _score?: number;
+    /** Provenance tag for `_score` (DESIGN §2 Invariant 5). Present iff `_score` is; a rank-derived score is ordinal, never similarity/confidence. */
+    _score_kind?: IScoreKind;
     _vector?: number[];
+    /** Outbound `blocks` — issues that cannot start until this one is terminal. */
+    blocksOut?: IIssueRef[];
+    /**
+     * Transitive dependent count: how many nodes reach THIS node via `blocks`
+     * (inclusive of direct dependents). Deterministic, scope-bounded (bounded to
+     * a page's candidate id set on a list read; unbounded but cycle-safe on a
+     * single `get`).
+     */
+    dependents?: number;
+    /** The `part_of` parent, if any (`n:1` — at most one). */
+    partOf?: IIssueRef | null;
+    /** The declared obligations on this item, in `has_obligation` edge order. */
+    obligations?: IObligationView[];
+    /** The derived actionability verdict + its typed reasons. */
+    verdict?: IVerdict;
+    /**
+     * C10 — the work item's current spec revision pointer. The card carries the
+     * revision uid + its `'sha256:<hex>'` token (the token a reader holds and
+     * compares) and the sequence — NEVER the revision body. Absent when the item
+     * has no spec, or when the `spec` pseudo field was not requested.
+     */
+    spec?: IIssueSpecProjection;
+    /**
+     * C9 — reviewed `similar_to` links touching this item, both directions
+     * (`ISimilarLinks`). This is the ADVISORY similarity relation, populated
+     * only when explicitly requested via `fields:['similar']`; it never includes
+     * the reserved `duplicate_of` same-judgement relation.
+     */
+    similar?: ISimilarLinks;
+}
+/**
+ * C10 — the spec pointer projected onto an issue card (DESIGN §12). Additive:
+ * a consumer can hold `spec_revision_token` and later hand it to `spec-check`
+ * to learn whether it has gone stale.
+ */
+export interface IIssueSpecProjection {
+    /** The current revision uid (the pointer's target). */
+    spec_revision: string;
+    /** `'sha256:<hex>'` — the token a reader holds and compares. */
+    spec_revision_token: string;
+    revision_seq: number;
+    /** Present only when the caller supplied a token to compare against. */
+    freshness?: SpecFreshness;
 }
 /**
  * `get`'s uid-addressed shape (SPEC.md §6.3.1/§6.5/AC-13) — the implementation
@@ -128,6 +243,17 @@ export interface IIssueCard {
 export interface IIssueGetByUidInput {
     uid: IssueUid;
     fields?: readonly IIssueField[];
+    /** Bounds the `auditTrail`/`citations`/`related`/`blockers` pseudo fields to the LAST N rows (preserving each resolver's own order — the audit trail's oldest-first order is sliced to its tail). */
+    lastN?: number;
+    /** Cursor for the bounded sub-collection (opaque; from the previous page's last returned uid). */
+    after?: string;
+    /**
+     * C6 — the highest verdict ladder rung this `get` may run. Default 3 (the
+     * single-item default); a caller may raise it to 5 for a full anchor
+     * re-resolve. The list views never accept this and always derive at rung 2
+     * (DESIGN §2 Primitive 4, "Bounded derivation").
+     */
+    deriveThrough?: 1 | 2 | 3 | 4 | 5;
 }
 /** SPEC.md §6.5's `IIssueFilter`. */
 export interface IIssueFilter {
@@ -171,6 +297,14 @@ export interface IIssueFilter {
         since?: string;
         until?: string;
     };
+    /**
+     * C9 — uid of X: return items linked `similar_to` X (i.e. the SOURCE side of
+     * an outgoing `similar_to` edge whose target is X). Renamed from the removed
+     * `duplicateOf`; `similar_to` is the reviewed similarity relation.
+     */
+    similarTo?: string;
+    /** C9 — true: return items with ≥1 incoming `similar_to` link (the DST side). Renamed from the removed `hasDuplicates`. */
+    hasSimilar?: boolean;
 }
 export type IIssueSort = 'priority' | 'updated' | 'created' | 'relevance' | 'textMatch';
 export type IIssueSortDirection = 'asc' | 'desc';
@@ -182,7 +316,7 @@ export type IIssueSortDirection = 'asc' | 'desc';
  * `listLocations`, distinct from the issue-search views above (§6.1:
  * "conflating the two would be wrong").
  */
-export type IIssueView = 'list' | 'ready' | 'graph' | 'order' | 'stale' | 'similar' | 'overlap' | 'projects' | 'components' | 'locations';
+export type IIssueView = 'list' | 'ready' | 'graph' | 'order' | 'stale' | 'similar' | 'overlap' | 'projects' | 'components' | 'locations' | 'kinds' | 'catalogs';
 export type IIssueQueryFormat = 'json' | 'markdown';
 /** SPEC.md §5, §6.1's `axis` — the grouping dimension for `overlapUids` (§6.2). */
 export type IOverlapAxis = 'file' | 'project' | 'component' | 'author';
@@ -220,6 +354,8 @@ export interface IIssueQueryInput {
     overlapUids?: readonly string[];
     /** `view:'stale'` only — minutes since `claimedAt`; falls back to `project_policy.claim_stale_after_min` (default 30) when omitted. */
     staleAfterMin?: number;
+    /** C8 — `view:'catalogs'` only: narrow to one vocabulary catalog. Omitted ⇒ every catalog's terms (the same set `view:'kinds'` exposes). */
+    catalog?: CatalogKindName;
 }
 export declare const MAX_QUERY_LIMIT = 1000;
 export declare const DEFAULT_QUERY_LIMIT = 50;
@@ -301,6 +437,7 @@ export type IIssueQueryResult = IIssueListResult | {
 } | {
     view: 'similar';
     items: IIssueCard[];
+    clusters?: ISimilarViewClusterBlock;
 } | {
     view: 'overlap';
     groups: IOverlapGroup[];
@@ -313,6 +450,12 @@ export type IIssueQueryResult = IIssueListResult | {
 } | {
     view: 'locations';
     items: ILocationSummary[];
+} | {
+    view: 'kinds';
+    catalogs: ICatalogView;
+} | {
+    view: 'catalogs';
+    terms: ICatalogTerm[];
 } | IIssueMarkdownResult;
 export interface IProjectSummary {
     uid: string;
@@ -391,6 +534,28 @@ export interface ILookupResult {
     };
     /** Present when only a partial (project-level, or path-prefix) match was found — never a silent null (§3a). */
     hint?: string;
+    /**
+     * C1 — a resolved-by-token hint. When `lookup` recognises `q` as a uid/uid
+     * prefix or a unique issue title, the registry shape does not apply; instead
+     * the caller is told which verb to re-issue (`get`) and with which uid, so a
+     * transport can forward exactly one canonical request rather than guessing.
+     */
+    redirect?: {
+        verb: 'get' | 'query';
+        uid?: string;
+        query?: string;
+    };
+    /**
+     * C1 — the candidate set behind an ambiguity this read CHOSE to surface
+     * rather than fail on. (A `lookup` whose title grep matches ≥2 issues still
+     * throws `AmbiguousReferenceError`; this field exists for callers that
+     * surface candidates alongside a chosen primary.)
+     */
+    candidates?: Array<{
+        uid: string;
+        kind: string;
+        name: string;
+    }>;
 }
 /**
  * `get`'s registry-detail shape (SPEC.md §3a/§8 AC-11) — `get --input
@@ -448,3 +613,53 @@ export type IIssueGetInput = IIssueGetByUidInput | IIssueGetRegistryInput;
  * repro — so no workaround is needed here; this type is plain `IIssueCard`.
  */
 export type IIssueGetResult = IIssueCard | IProjectDetail | IComponentDetail | ILocationDetail;
+/** C9 — one reviewed `similar_to` neighbour of a card, in the compact cross-reference shape. */
+export interface ISimilarRef {
+    uid: string;
+    title: string;
+    status: string;
+    projectUid?: string;
+    repoUrl?: string;
+}
+/** C9 — a card's reviewed `similar_to` links, both directions (`n:m`, so both are sets). */
+export interface ISimilarLinks {
+    /** Items THIS one is linked `similar_to` (outgoing, n:m). */
+    similarTo: ISimilarRef[];
+    /** Items linked `similar_to` THIS one (incoming, n:m). */
+    similarFrom: ISimilarRef[];
+}
+/** C9 — one member of an advisory or linked similarity cluster. */
+export interface ISimilarMember {
+    uid: string;
+    title: string;
+    projectUid: string;
+    projectName: string;
+    componentUid?: string;
+    repoUrl?: string;
+    /** Cosine to the cluster seed (undefined for linked-only members). */
+    score?: number;
+    /** Which independent signals fired, e.g. `['cosine','title-tokens']`. */
+    signals?: string[];
+    /** A `similar_to` target when linked. */
+    linkedTo?: string;
+}
+/** C9 — a single-linkage similarity cluster: `seedUid` is the top-scoring member that anchored it. */
+export interface ISimilarCluster {
+    seedUid: string;
+    members: ISimilarMember[];
+    /** true iff live `similar_to` edges exist among members. */
+    linked: boolean;
+}
+/**
+ * C9 — the additive cluster block `view:'similar'` gains when a scope filter
+ * (`project`/`component`) is present. `candidate` is the advisory,
+ * write-nothing scan output; `linked` is built from existing live `similar_to`
+ * edges only. Without the embedding substrate `candidate` is `[]` (the
+ * documented degraded mode) while `linked` still returns.
+ */
+export interface ISimilarViewClusterBlock {
+    candidate: ISimilarCluster[];
+    linked: ISimilarCluster[];
+    scanned: number;
+    computedAt: string;
+}

package/query/verdict-core.d.ts

@@ -0,0 +1,21 @@
+import { IActionable, ICondition } from './types.js';
+
+/**
+ * The ONE actionability rule (DESIGN §2 Primitive 4).
+ *
+ * - `false` iff at least one `block`-severity condition is `True` (the item IS
+ *   blocked — a definite answer beats an uncertain one);
+ * - `'unknown'` iff any `block`-severity condition is `Unknown` and none is
+ *   `True` (the check could not be run / decided — NEVER a green light);
+ * - otherwise `true`.
+ *
+ * `'Unknown'` is never treated as `false` OR as `true`. `warn`-severity
+ * conditions never affect the result.
+ */
+export declare function computeActionable(conditions: readonly ICondition[]): IActionable;
+/**
+ * Stable ordering: all `block` before all `warn`; within a band, by `code`
+ * then `subject` (both lexical, `undefined` subject sorts first). Pure and
+ * total — two callers ordering the same set always agree.
+ */
+export declare function orderConditions(conditions: readonly ICondition[]): ICondition[];

package/query/verdict.d.ts

@@ -0,0 +1,22 @@
+import { IVerdict } from './types.js';
+import { GraphBackend, NodeRecord } from '@adhd/sox-graph-store';
+
+/** Highest ladder rung `deriveVerdict` may run. */
+export type IVerdictRung = 1 | 2 | 3 | 4 | 5;
+export interface IDeriveVerdictOptions {
+    /**
+     * Highest ladder rung this call is allowed to run. Default 2 (the list
+     * bound). 5 = full re-resolve. A budget stop yields an `Unknown` condition.
+     */
+    maxRung?: IVerdictRung;
+    /** The instant used for staleness maths; defaults to nowISO(). */
+    at?: string;
+    /** Staleness threshold (minutes); defaults to 30 (project_policy default). */
+    claimStaleAfterMin?: number;
+    /** Test instrumentation: invoked with each rung actually evaluated. */
+    onRung?: (rung: number) => void;
+}
+/**
+ * Derive the verdict for a live issue (DESIGN §2 Primitive 4). NEVER writes.
+ */
+export declare function deriveVerdict(graph: GraphBackend, issue: NodeRecord, opts?: IDeriveVerdictOptions): Promise<IVerdict>;

package/query/views/catalog.d.ts

@@ -0,0 +1,47 @@
+import { GraphBackend } from '@adhd/sox-graph-store';
+
+/**
+ * The catalogs this view exposes. `kind`/`status`/`priority` are store-backed
+ * (open vocabularies minted by the write layer); the rest are fixed in-code
+ * vocabularies projected from their validating source.
+ */
+export type CatalogKindName = 'kind' | 'status' | 'priority' | 'relation' | 'field' | 'error_code' | 'location_type' | 'verb';
+/** The in-code source a term was generated from. Named so the catalog is provably generated, not hand-maintained. */
+export type CatalogSource = 'store' | 'edge_kind_table' | 'reserved_terminal_status_names' | 'issue_field_union' | 'error_code_union' | 'valid_location_types' | 'mounted_verb_surface';
+export type CatalogLifecycle = 'active' | 'deprecated';
+export interface ICatalogTerm {
+    /** The term's canonical name. */
+    name: string;
+    /** Live row uid when a store row backs it; absent for in-code source terms. */
+    uid?: string;
+    /** Which vocabulary this term belongs to. */
+    catalog: CatalogKindName;
+    /** The validating source this term was generated from at call time. */
+    source: CatalogSource;
+    lifecycle: CatalogLifecycle;
+    /** Present when deprecated: the term to use instead. */
+    replacedBy?: string;
+    /** For `kind`/`status`/`priority`: the live callers count, read at call time. */
+    usageCount?: number;
+}
+export interface ICatalogView {
+    catalogs: CatalogKindName[];
+    terms: ICatalogTerm[];
+    /** True when any term is a case-fold collision of another within its catalog (the invariant the read layer depends on). */
+    hasCaseCollisions: boolean;
+}
+/**
+ * ONE read view over every vocabulary (AC1). Every non-`store` term is derived
+ * from its in-code source at call time — never a hand-written list — and every
+ * `store` term is a live row with its caller count.
+ *
+ * Read-only: it never opens a transaction and never writes, so it is safe
+ * against any store, including the live one.
+ */
+export declare function catalogView(graph: GraphBackend): Promise<ICatalogView>;
+/**
+ * The terms of ONE catalog (AC1's narrowed sibling). Derived from the SAME
+ * {@link catalogView} — there is no second generation path, so `kinds` and
+ * `catalogs` can never disagree about a catalog's contents.
+ */
+export declare function catalogFor(graph: GraphBackend, catalog: CatalogKindName): Promise<ICatalogTerm[]>;

package/query/views/registry.d.ts

@@ -33,11 +33,31 @@ export declare function getRegistryDetail(graph: GraphBackend, input: {
     name: string;
 }): Promise<ILocationDetail>;
 /**
- * `query --input '{"view":"lookup", "lookup": "<tool|file|url>"}'` (§3a) —
- * classify → match → walk `location → component → project`. Never a silent
- * null: an unresolved query throws `CatalogNotFoundError('location', q)`
- * rather than returning an empty/undefined result, since "no match" is a
- * distinct, actionable outcome from "found, but only a hint" (the `hint`
- * field below).
+ * The optional kind HINT `lookup` accepts (C1, §3a). `q` is the token to
+ * resolve; `kind` narrows which routing branch runs, so a caller that already
+ * knows it is holding an issue uid or a project name can suppress the other
+ * branches instead of relying on the default precedence.
  */
-export declare function lookup(graph: GraphBackend, q: string): Promise<ILookupResult>;
+export interface ILookupInput {
+    q: string;
+    /** optional: `'location' | 'project' | 'component' | 'issue'` */
+    kind?: string;
+}
+/**
+ * `query --input '{"view":"lookup", "lookup": "<tool|file|url|uid|title|project>"}'`
+ * (§3a, C1 AC4) — resolve ANY token a consumer holds to exactly one canonical
+ * answer, or fail loudly naming what was searched.
+ *
+ * Routing order (C1 spec, fixed):
+ *  1. a uid or uid PREFIX → a `redirect` to `get` (the registry shape does not
+ *     apply to a node reached by identity);
+ *  2. an issue TITLE → exactly one hit redirects to `get`; ≥2 is
+ *     `AmbiguousReferenceError`; zero falls through;
+ *  3. the existing location classify→match→walk;
+ *  4. a project `name`/`repoUrl` match;
+ *  then `CatalogNotFoundError('location', q)` — `lookup` is never a silent null.
+ *
+ * Existing location-only consumers keep working: their exact-path query misses
+ * the uid/title/project branches and is served by step 3 unchanged.
+ */
+export declare function lookup(graph: GraphBackend, input: string | ILookupInput): Promise<ILookupResult>;

package/query/views/report.d.ts

@@ -0,0 +1,49 @@
+import { IQueryStoreHandle } from '../query.js';
+import { IIssueFilter } from '../types.js';
+
+/**
+ * `report`'s filter — the four dimensions `priorityMatrix` composes with
+ * (`project`/`component`/`kind`/`status`). `status` is the coarse
+ * `open`/`closed`/`all` selector (never a name list): `report`'s whole point
+ * is a scope-named aggregate, and `statusScope` echoes exactly what was
+ * counted. An omitted `status` defaults to `'open'`, matching `priorityMatrix`.
+ */
+export interface IReportInput {
+    filter?: {
+        project?: string;
+        component?: string;
+        kind?: string | string[];
+        status?: 'open' | 'closed' | 'all';
+    };
+}
+export interface IReportResult {
+    /** Counts by `kind` name (live, in-scope rows only), name-ascending. */
+    byKind: Array<{
+        kind: string;
+        count: number;
+    }>;
+    /** Counts by `priority` name + rank (composed from `priorityMatrix`). */
+    byPriority: Array<{
+        priority: string;
+        rank?: number;
+        count: number;
+    }>;
+    /** Status histogram: status name, its terminal flag, and the count. */
+    byStatus: Array<{
+        status: string;
+        terminal: boolean;
+        count: number;
+    }>;
+    /** Average age in days of OPEN (non-terminal) in-scope items, measured from `tCreated` at report time. */
+    avgAgeDays: number;
+    /** Names what was counted — `'open'` when the filter omitted `status`. */
+    statusScope: NonNullable<IIssueFilter['status']>;
+    /** The instant every time-relative number above was computed against. */
+    computedAt: string;
+}
+/**
+ * SPEC.md §5's grouped rollup (DESIGN §5 AC7) — every count computed from the
+ * store in this call, none stored. See this file's header for the
+ * composition rule.
+ */
+export declare function report(handle: IQueryStoreHandle, input: IReportInput): Promise<IReportResult>;

package/query/views/semantic.d.ts

@@ -72,23 +72,46 @@ export interface IRelevanceRankOptions {
  * `view:'similar'` itself.
  */
 export declare function rankByFusedRelevance(handle: IQueryStoreHandle, opts: IRelevanceRankOptions): Promise<SearchResult[]>;
+/**
+ * `view:'similar'`'s result when the caller also needs completeness truth
+ * (`has_more`/`limit`) — see {@link querySimilarViewWithMeta}. `hasMore` is
+ * derived by fetching one row beyond the page, never fabricated.
+ */
+export interface ISimilarViewResult {
+    items: IIssueCard[];
+    hasMore: boolean;
+    /** The caller-facing page size actually applied. */
+    limit: number;
+}
+/**
+ * `view:'similar'` (SPEC.md §5a) — the plain `IIssueCard[]` every existing
+ * caller (and `semantic.spec.ts`) already reads. Thin wrapper over
+ * {@link querySimilarViewWithMeta}, which also yields the completeness flag
+ * the C7 envelope attaches.
+ */
+export declare function querySimilarView(handle: IQueryStoreHandle, input: IIssueQueryInput): Promise<IIssueCard[]>;
 /**
  * `view:'similar'` (SPEC.md §5a) — `filter.anchor` (item-anchored) or
  * `filter.semantic` (free text), fused text+vec ranked via
- * {@link rankByFusedRelevance}, projected to `IIssueCard`s with `_score`
- * populated when requested (`card.ts`'s existing
- * `IAssembleIssueCardOptions.score` seam — SPEC.md §5a's `_score` exposure).
+ * {@link rankByFusedRelevance}, projected to `IIssueCard`s with `_score`/`_score_kind`
+ * populated when requested (`card.ts`'s `IAssembleIssueCardOptions` seam — SPEC.md
+ * §5a's `_score` exposure; `_score_kind:'rrf'` per DESIGN §2 Invariant 5).
  *
  * The anchor issue is EXCLUDED from its own results (RAG-SPEC.md §3.2's
  * carried-forward "the query item itself is excluded" — SPEC.md §5a does not
  * restate this explicitly, a genuine spec gap this implementation fills per
  * that precedent rather than silently, since "similar to X" trivially
  * self-matching X at rank 1 is a real usability defect, not a feature).
- * Exclusion is done POST-search (fetch one extra candidate, drop the anchor,
+ * Exclusion is done POST-search (fetch beyond the page, drop the anchor,
  * slice to `limit`) rather than by enumerating the whole issue table to
  * subtract one id up front — far cheaper for the common "no other filter"
  * case, and still exactly correct.
  *
+ * **Completeness (`hasMore`):** the fetch is one row beyond the page — plus
+ * one MORE when anchored, since the anchor consumes a slot when it appears in
+ * the window — so `hasMore` is genuinely "a live row exists beyond this page",
+ * not an inference from `items.length === limit`.
+ *
  * Errors: `IssueNotFoundError(anchor)` (SPEC.md §6.1's general `uid`-
  * addressing convention — `anchor` is `uid`-typed per §6.1's own statement
  * that it is "the SAME `uid`-typed field" as every other addressing field;
@@ -98,4 +121,4 @@ export declare function rankByFusedRelevance(handle: IQueryStoreHandle, opts: IR
  * `InvalidArgumentError('filter', ...)` (neither `anchor` nor `semantic`
  * given). `BacklogValidationError('limit', ...)` (out-of-range `limit`).
  */
-export declare function querySimilarView(handle: IQueryStoreHandle, input: IIssueQueryInput): Promise<IIssueCard[]>;
+export declare function querySimilarViewWithMeta(handle: IQueryStoreHandle, input: IIssueQueryInput): Promise<ISimilarViewResult>;