@adhd/backlog 1.0.4 → 1.0.6

package/citation.d.ts

@@ -0,0 +1,176 @@
+/**
+ * citation.ts — the ONE citation contract (leaf module, zero imports).
+ *
+ * ## Why this module exists
+ *
+ * A citation used to be described by TWO independent, drifting shapes:
+ *
+ *  - the **persisted** encoding `create-issue.ts`/`transition.ts` wrote into a
+ *    `citation` node's `meta` — `{ target, target_type, sha, line, at }` (plus
+ *    the unconsumed `symbol`/`blastRadius`); and
+ *  - the **transport** input `ICitationInput` a caller supplied —
+ *    `{ file, lines?, context?, symbol?, blastRadius? }`,
+ *
+ * with `query/card.ts` hand-inverting one into the other at read time. There
+ * was no single definition of "a citation": a field added to one side silently
+ * failed to round-trip, and the read projection lived in the query layer while
+ * the write encoding lived in the write layer. `DATA_MODEL.md` §4 documented
+ * the persisted set, `SPEC.md` §6.3.2 documented the transport set, and neither
+ * was the source of truth for the other.
+ *
+ * This module is that one source. `ICitation` is THE typed contract; the
+ * persisted encoding is an implementation detail produced by exactly one
+ * function ({@link citationNodeMetadata}) and read back by exactly one function
+ * ({@link citationFromNode}). Nothing else in the package may hand-roll either
+ * direction.
+ *
+ * It is a LEAF with zero imports on purpose: it is imported by the write
+ * verbs, by the query read projection (`query/card.ts`), and by the pure type
+ * barrel (`query/types.ts`), so it must never drag the write or query graph
+ * into a consumer that only needs the shape.
+ *
+ * ## The `revision` field — citing against a git revision, not just the tree
+ *
+ * A citation whose file exists only on an unmerged branch could not be filed
+ * at all: the working-tree sha gate (`citation-path.ts` + `computeCitationSha`)
+ * read the file from the checked-out tree, found nothing, and refused. The
+ * optional {@link ICitation.revision} names a git revision (branch/tag/sha) the
+ * target is resolved against instead — `git show <revision>:<path>` — so
+ * branch-only evidence is citable. The revision is persisted verbatim on the
+ * citation node (`meta.revision`) and surfaced on read, so a reader can tell a
+ * working-tree citation from a revision-pinned one.
+ */
+/**
+ * The ONE citation contract — a caller-facing citation, and the shape every
+ * read projection extends. This is what `SPEC.md` §6.3.2's `Citation` and
+ * `DATA_MODEL.md` §4's `citation` node both mean.
+ *
+ * Field vocabulary (the reconciliation): the persisted node stores
+ * `file` as `meta.target` and `lines` as `meta.line` (the graph-native names
+ * `DATA_MODEL.md` §4 fixes), but the CONTRACT a consumer passes and receives is
+ * always `file`/`lines` — never `target`/`line`. The two are bridged ONLY by
+ * {@link citationNodeMetadata}/{@link citationFromNode}, never at a call site.
+ */
+export interface ICitation {
+    /** The cited target — a repo-relative or absolute filesystem path (the persisted `meta.target`). REQUIRED and non-blank. */
+    file: string;
+    /**
+     * The line or line-range WITHIN `file` (the persisted `meta.line`). OPTIONAL —
+     * a whole-file citation omits it. Kept a free `string` (e.g. `"120-140"`) so
+     * a caller is not forced to narrow to a single integer.
+     *
+     * `lines` (pl.) is the CONTRACT name; `line` is the persisted one end. Both
+     * spellings intentionally diverge from the persisted key — see this
+     * interface's own doc comment.
+     */
+    lines?: string;
+    /**
+     * Free-text prose for THIS citation. Persisted as the citation node's
+     * `content` column (never its `meta`), which is what {@link citationFromNode}
+     * reads back into this field. NOT the item-level disclosure-contract git
+     * context — that lives on the issue (`gitContext`) and is rendered once at
+     * the head of its `Citations:` block, never per-citation.
+     */
+    context?: string;
+    /** The named symbol (`function`/`class`/`method`) this citation points at, when narrower than a whole file. */
+    symbol?: string;
+    /**
+     * Best-effort enrichment payload carried through verbatim. Not re-specified
+     * here (SPEC.md §6.3.2 declares it `CitationBlastRadius`, a type that exists
+     * nowhere in the package): the write layer has always stored whatever
+     * JSON-serializable value a caller passed and `similarity-scan.ts` reads it
+     * only when it is a string. Typed `unknown` to match that existing behavior
+     * exactly rather than introducing a third, narrower shape.
+     */
+    blastRadius?: unknown;
+    /**
+     * A git revision (branch/tag/sha) the `file` is resolved against, instead of
+     * the working tree. Present only for revision-pinned citations — see this
+     * module's header. Persisted as `meta.revision`.
+     */
+    revision?: string;
+}
+/**
+ * The pre-unification name of the transport contract, kept as an alias so an
+ * existing importer (`write/transition.ts`) compiles unchanged. New code
+ * should use `ICitation`; this name means the SAME declaration, never a second
+ * shape.
+ */
+export type ICitationInput = ICitation;
+/**
+ * A citation as PROJECTED FOR READ — the contract plus the server-computed
+ * identity (`uid`), content-address (`sha`), and filing instant (`at`), and the
+ * persisted `target_type` (today always `'path'`). `query/types.ts`'s
+ * `IIssueCitation` extends this, so the read surface and the write surface can
+ * never drift.
+ */
+export interface ICitationRecord extends ICitation {
+    /** The citation node's own uid — the identity `removeCitation` addresses (never a `(target,line)` composite). */
+    uid: string;
+    /** `sha256` of the cited content at filing time, or the fixed sentinel `"unverified"` (§8.5). */
+    sha: string;
+    /** The filing instant (the node's own `meta.at`, falling back to `t_created` for a legacy row). */
+    at: string;
+    /** The persisted target discriminator (`'path'` today). Optional so a legacy row without one still projects. */
+    targetType?: string;
+}
+/**
+ * The minimal node view {@link citationFromNode} needs — a structural subset of
+ * `@adhd/sox-graph-store`'s `NodeRecord` (and of the write layer's
+ * `ITxNodeRow`), so neither type has to be imported here.
+ */
+export interface ICitationNodeView {
+    uid: string;
+    /** `string | null` from the write layer's `ITxNodeRow`, `string | undefined` from the query layer's `NodeRecord` — both accepted. */
+    name: string | null | undefined;
+    content: string;
+    metadata: Record<string, unknown> | undefined;
+    tCreated: string;
+}
+/**
+ * Encode a citation into the `citation` node's `meta` blob — the ONE writer of
+ * the persisted citation encoding. `sha` is computed by the caller (the write
+ * layer's sha gate) and `at` is the write's single logical timestamp, so both
+ * are passed in rather than recomputed here.
+ *
+ * `file` is stored as `target`, `lines` as `line` (the graph-native keys
+ * `DATA_MODEL.md` §4 fixes). `revision` is always present (`null` when absent),
+ * so a stored citation node's shape does not vary by presence of the field.
+ */
+export declare function citationNodeMetadata(citation: ICitation, sha: string, at: string): Record<string, unknown>;
+/**
+ * Decode a `citation` node back into the contract + the server fields — the ONE
+ * reader of the persisted citation encoding. Every field the write side
+ * persists round-trips: `file`↔`target`, `lines`↔`line`, `context`↔`content`,
+ * `symbol`, `blastRadius`, `revision`.
+ *
+ * Defensive on a malformed/legacy row (mirrors the mapping `query/card.ts`
+ * previously hand-rolled, verbatim): a missing `sha` degrades to the
+ * `"unverified"` sentinel (never a fabricated hash), and a missing `at` to the
+ * node's `t_created`. A malformed `meta` never throws — the caller gets a
+ * best-effort projection, never a crash.
+ */
+export declare function citationFromNode(node: ICitationNodeView): ICitationRecord;
+/**
+ * The identity used to DIFF a desired citation set against the live one
+ * (`update`'s citations diff): `file`, `lines`, AND `revision`. Deliberately
+ * excludes `sha`/`context`/`symbol`/`blastRadius` — the diff is add-or-remove
+ * on the citation's TARGET, never an in-place descriptive edit (a citation is
+ * content-addressed evidence; changing its prose is a new citation, so the old
+ * one is removed and the new one added).
+ *
+ * `revision` IS part of the identity, unlike those descriptive fields: two
+ * citations of the same `(file, lines)` resolved against DIFFERENT revisions
+ * are different evidence, so a desired set that changes only a citation's
+ * revision is a genuine remove+add, never a silent no-op.
+ *
+ * A `\u0000` separator makes the key unambiguous (`"a.ts" + "1"` can never
+ * collide with `"a.ts1" + ""`).
+ */
+export declare function citationKey(citation: Pick<ICitation, 'file' | 'lines' | 'revision'>): string;
+/**
+ * {@link citationKey} for a persisted metadata blob (a live citation node),
+ * reading the same `target`/`line`/`revision` ends
+ * {@link citationNodeMetadata} wrote.
+ */
+export declare function citationKeyFromMetadata(metadata: Record<string, unknown> | undefined): string;

package/envelope.d.ts

@@ -26,7 +26,7 @@
  * Each member names the error class(es) that produce it, so the derivation
  * rule in this file's header can be checked by reading rather than inferred.
  */
-export declare const BACKLOG_ERROR_CODES: readonly ["not_found", "item_not_found", "invalid_argument", "validation", "store_busy", "rag_not_configured", "conflict", "precondition_failed", "internal"];
+export declare const BACKLOG_ERROR_CODES: readonly ["not_found", "item_not_found", "ambiguous_reference", "invalid_argument", "validation", "store_busy", "rag_not_configured", "conflict", "precondition_failed", "internal"];
 /** The closed union of envelope error codes. See {@link BACKLOG_ERROR_CODES}. */
 export type BacklogErrorCode = (typeof BACKLOG_ERROR_CODES)[number];
 /**
@@ -72,6 +72,26 @@ export interface IOutcomeError {
     message: string;
     details?: IOutcomeErrorDetails;
 }
+/**
+ * How exact a labelled count is. `eq` — the value is the true count; `gte` —
+ * the value is a LOWER BOUND (the Elasticsearch `hits.total.relation`
+ * pattern): more rows exist than could be counted at the cost the caller's
+ * request allowed. A count whose exactness is unstated is the defect this
+ * names (DESIGN §2 Invariant 5).
+ */
+export type CountRelation = 'eq' | 'gte';
+/**
+ * A count labelled for what it counts, carrying its own exactness — the
+ * DESIGN §2 Invariant 5 primitive ("a count named for what it counts (with an
+ * exactness relation, or omitted)"). Kept as its own shape rather than
+ * flattened into {@link IQueryEnvelopeMeta} as a bare number so a consumer can
+ * always tell a lower bound from an exact total.
+ */
+export interface ILabelledCount {
+    value: number;
+    /** How exact `value` is: `eq` exact, `gte` a lower bound. */
+    relation: CountRelation;
+}
 /**
  * Pagination truth carried beside the data. `total` is the count BEFORE
  * `limit`/`offset`; `returned` is `data.length`. A silently-truncated list is
@@ -79,7 +99,7 @@ export interface IOutcomeError {
  * there really were.
  */
 export interface IQueryEnvelopeMeta {
-    /** Matching rows before limit/offset — the TRUE count. */
+    /** Matching rows before limit/offset. Exact unless `total_relation` says otherwise (`gte` ⇒ a lower bound). */
     total: number;
     /** Rows actually in `data`. */
     returned: number;
@@ -90,6 +110,20 @@ export interface IQueryEnvelopeMeta {
      * own `limit`. A silent cap is forbidden — if it happens, it is stated here.
      */
     truncated?: boolean;
+    /**
+     * Exactness of `total`: `eq` (or absent) — exact; `gte` — a lower bound
+     * (a capped scan, or a page whose true total is unknowable at list cost).
+     */
+    total_relation?: CountRelation;
+    /**
+     * True iff more rows exist beyond this page. The preferred spelling for the
+     * item-list views (`ready`/`stale`/`similar`) where a true pre-limit `total`
+     * is unknowable at bounded cost — derived by fetching `limit + 1`, never
+     * fabricated.
+     */
+    has_more?: boolean;
+    /** Opaque continuation token for cursor-paged views that are not keyset-paged today. */
+    next_cursor?: string;
 }
 /** The success arm. `data` is always present (never `null` as a stand-in for "missing"). */
 export interface IOutcomeSuccess<T> {

package/index.d.ts

@@ -1,8 +1,28 @@
-export { get, query, priorityMatrix, partOfRollup, openCurve, embeddingStatus, lookup, create, update, transition, claim, relate, move, upsertProject, upsertComponent, upsertLocation, rmLocation, delete, } from './api.js';
+export { get, query, priorityMatrix, partOfRollup, openCurve, report, embeddingStatus, lookup, create, update, addCitation, removeCitation, transition, attest, recheck, obligate, unobligate, specAppend, specCheck, claim, relate, move, upsertProject, upsertComponent, upsertLocation, rmLocation, mergeProject, rmProject, delete, } from './api.js';
 export type { BacklogCtx, IEmbeddingStatusResult } from './api.js';
+export type { IAddCitationInput, IAddCitationOutcome, IRemoveCitationInput, IRemoveCitationOutcome, } from './write/citation.js';
+export type { ICitation, ICitationRecord } from './citation.js';
+export type { IMergeProjectInput, IMergeProjectOutcome, IRmProjectInput, } from './write/merge-project.js';
+export type { IAttestInput, IAttestOutcome, IAttestClaim, IAttestCheck, IAttestationAnchor, AttestRevisionRef, AttestationCheckState, IRecheckInput, IRecheckOutcome, } from './write/attestation.js';
+export { assertValidPredicate, evaluatePredicate, } from './write/obligation.js';
+export type { IObligationView } from './query/types.js';
+export type { IObligationSeverity, IRelationDirection, IPredicate, IObligationAppliesTo, IObligationOverride, IObligateInput, IObligateOutcome, IUnobligateInput, IUnobligateOutcome, IPredicateResolver, } from './write/obligation.js';
+export type { ISpecAnchor, ISpecRevisionMeta, ISpecAppendInput, ISpecAppendOutcome, ISpecPointer, } from './write/spec-revision.js';
+export type { SpecFreshness, ISpecCheckInput, ISpecCheckOutcome, } from './query/spec-staleness.js';
+export { planSpecRevisionReconcile, applySpecRevisionReconcile, } from './write/spec-revision.reconcile.js';
+export type { ISpecReconcileStore, ISpecReconcileStamp, ISpecReconcileHead, ISpecReconcileReport, } from './write/spec-revision.reconcile.js';
 export * from './envelope.js';
-export { startBacklogServer, buildBacklogApigenPackage, resolveExpectedMcpToolNames, } from './server.js';
-export type { StartOpts } from './server.js';
+export { createBacklogServer, startBacklogServer, buildBacklogApigenPackage, resolveExpectedMcpToolNames, describeBacklogSurface, assertSurfaceIsReal, } from './server.js';
+export type { StartOpts, IBacklogServerHandle } from './server.js';
+export { createLifecycle } from './lifecycle.js';
+export type { IServiceFailure, IServiceLifecycle, IServiceReport, IServiceState, } from './lifecycle.js';
+export { probeReadiness } from './readiness.js';
+export type { IReadinessHandle, IReadinessResult, IReadinessTimer, } from './readiness.js';
+export { fullJitterDelay, CircuitBreaker, withResilience, } from './retry-policy.js';
+export type { IResiliencePolicy, IResilienceDeps, IBreakerState, } from './retry-policy.js';
+export { resolveServiceConfig, assertMcpEntryValid, assertServerArtifact, isPathResolvableBin, SERVICE_CONFIG_KEYS, } from './service-config.js';
+export type { IServiceConfig, IServiceTransport, IArtifactIdentity, IMcpServerEntry, } from './service-config.js';
+export { UnknownConfigKeyError, NonAbsolutePathError, UnknownMcpConfigKeyError, ArtifactDriftError, ServiceNotReadyError, } from './service-errors.js';
 export { runBacklogCli, resolveCommandPrefix, prefixCommand, stripNamespaceFlag, } from './cli.js';
 export type { RunBacklogCliOpts } from './cli.js';
 export { buildSearchArgv, SEARCH_FLAGS, SEARCH_HELP, } from './search-shortcut.js';