@adhd/backlog 1.0.4 → 1.0.6

package/write/create-issue.d.ts

@@ -1,21 +1,16 @@
+import { ISimilarCandidate, SimilarityScanDegradedReason } from './similarity-scan.js';
 import { IWriteStoreHandle } from './tx.js';
+import { ICitation } from '../citation.js';
 import { StoreSearchBackend } from '@adhd/sox-hybrid-search';
 import { GraphBackend } from '@adhd/sox-graph-store';
 
 /**
- * A filing-time citation (§6.3.2, carried forward from the established `Citation` shape in
- * spirit — `blastRadius` stays best-effort, `model.ts:110-120`). Named
- * `ICitationInput` here (not the spec's bare `Citation`) per this repo's
- * "prefix shared/data interfaces with `I`" convention.
+ * A filing-time citation. `ICitation` — the ONE contract, defined in
+ * `../citation.ts` — is imported here and re-exported below so an existing
+ * importer of `ICitationInput` from this module keeps compiling; the shape and
+ * the persisted codec live in exactly one place (`../citation.ts`), never here.
  */
-export interface ICitationInput {
-    file: string;
-    lines?: string;
-    context?: string;
-    symbol?: string;
-    /** Best-effort enrichment payload — not re-specified here; carried through verbatim into the citation node's metadata. */
-    blastRadius?: unknown;
-}
+export type { ICitation, ICitationInput } from '../citation.js';
 export interface ICreateIssueInput {
     title: string;
     body: string;
@@ -29,7 +24,7 @@ export interface ICreateIssueInput {
     status?: string;
     /** catalog name or uid; genuinely OPTIONAL — §6.3.2 states minting behavior for a GIVEN unresolved name but, unlike `kind`/`status`, states no fallback for the omitted case; omitted therefore writes no `has_priority` edge at all (a deliberate reading of §6.3.2's more precise per-field text over §4's summary prose — see this project's own README/CHANGELOG note on this slice for the citation). An unresolved NAME mints with `rank` = one past the current max (lowest urgency); a uid-shaped ref that does not resolve throws. */
     priority?: string;
-    citations?: ICitationInput[];
+    citations?: ICitation[];
     /** catalog agent name/uid; defaults to `by`. An unresolved NAME mints; a uid-shaped ref that does not resolve throws (§6.1). */
     author?: string;
     /** Plain metadata scalar (§6.2) — no edge. */
@@ -48,6 +43,27 @@ export interface ICreateIssueInput {
      * every read/render path is byte-for-byte unchanged.
      */
     gitContext?: string;
+    /**
+     * A **dedupe-scoping hint only**: the uid of the item this one is being
+     * filed under. It names a parent so the pre-write similarity scan (§6.4
+     * point 1) EXCLUDES that item AND its `part_of` ancestor chain from the
+     * duplicate candidate set, so a child that deliberately restates its
+     * parent's intent is not suppressed as a duplicate OF that parent (defect
+     * c5460239: a child of C7 reproduced `created:false`/
+     * `duplicate-suppressed` with its own parent as the top candidate at
+     * 0.9811). A child restating its GRANDPARENT is likewise not suppressed,
+     * because the ancestry walk spans the whole `part_of` chain.
+     *
+     * It writes NO `part_of` edge — `relate` is the sole `part_of` writer
+     * (§6.3.6). Because it only scopes the read-side scan, it is invisible on
+     * the emitted card and nothing new is persisted; it has no effect once a
+     * create is not a duplicate. An unresolvable uid throws
+     * `IssueNotFoundError` (fail loud, ADR-0002 D5), never silently ignored.
+     *
+     * A uid ONLY, never a name (matching `relate`'s `sourceUid`/`targetUid` uid
+     * convention, §1/§6.1).
+     */
+    dedupeExcludeUid?: string;
     /** The acting identity — agent or person (§6.3's opening rule) — REQUIRED on every mutating verb. A missing/blank value throws `InvalidArgumentError('by', ...)` before any write runs. */
     by: string;
     /**
@@ -58,7 +74,16 @@ export interface ICreateIssueInput {
      * value (§6.4 point 3, first sentence).
      *
      * - `'abort'` — nothing is written; `{created:false,
-     *   reason:'duplicate-suppressed', duplicateCandidates}`.
+     *   reason:'duplicate-suppressed', duplicateCandidates}`. If the scan was
+     *   degraded in the ONE way that can NEVER resolve on its own —
+     *   `no-embed-query`, the backend wired without `embedQuery` so the
+     *   calibrated channel can never run — it also fails closed with
+     *   `{created:false, reason:'duplicate-scan-degraded',
+     *   duplicateScanDegraded:true, duplicateScanDegradedReason:'no-embed-query'}`
+     *   (BUG 4e8fce2a). A `no-vector-scores` degrade (indistinguishable at read
+     *   time from benign on-write embedding lag) or a `no-search-backend`
+     *   degrade (dedupe never mounted) instead PROCEEDS and carries the
+     *   `duplicateScanDegraded` signal.
      * - `'force'` — the write proceeds to a genuinely new, distinct `uid`
      *   despite the match; `duplicateCandidates` is still reported.
      * - `'comment'` — no new issue node is written; a `note` node is attached
@@ -94,6 +119,54 @@ export interface IDuplicateCandidate {
     /** Cosine similarity in `[0,1]`, straight off the vector channel — directly comparable to `project_policy.dedupe_threshold`. */
     score: number;
 }
+/**
+ * Why {@link scanForDuplicates} could not produce a calibrated comparison —
+ * i.e. why the gate did NOT actually scan for duplicates despite being asked
+ * to. See {@link IDuplicateScanOutcome.degraded}.
+ *
+ * C9: this is now an ALIAS of the shared scan's own reason union
+ * (`write/similarity-scan.ts`), so the create gate and the `view:'similar'`
+ * cluster block can never drift on what "degraded" means. The name and every
+ * member are unchanged, so existing importers/tests are unaffected.
+ */
+export type DuplicateScanDegradedReason = SimilarityScanDegradedReason;
+/**
+ * The result of {@link scanForDuplicates}. Its `candidates` arm is the
+ * pre-existing return value; `degraded` is the missing signal this type now
+ * carries (BUG 4e8fce2a).
+ *
+ * **`degraded` is the distinction the gate previously could not make.**
+ * Before this type existed, `scanForDuplicates` returned only
+ * `IDuplicateCandidate[]`, so an empty array meant EITHER "the scan ran and
+ * genuinely found nothing" OR "the scan could not run at all" — two states
+ * with opposite safety meanings that the caller had no way to tell apart. The
+ * abort branch (`createIssue`) then treated both as "no duplicates" and wrote
+ * the item, so `duplicateAction:'abort'` silently FAILED OPEN whenever the
+ * semantic substrate was degraded (no search backend, no `embedQuery`, or an
+ * empty/mismatched vector space). See {@link scanForDuplicates}'s own doc
+ * comment for exactly which conditions set this flag.
+ */
+export interface IDuplicateScanOutcome {
+    candidates: IDuplicateCandidate[];
+    /**
+     * C9 — advisory CROSS-project candidates surfaced alongside the
+     * same-project `candidates`. Never suppress a create, never fire
+     * `comment`, and the scan writes no edge for them (AC3). Empty when the
+     * scope is `same-project` (the default).
+     */
+    similarCandidates?: ISimilarCandidate[];
+    /**
+     * `true` iff the scan could NOT perform a calibrated duplicate comparison
+     * for the in-scope issues — no vector channel ran, so `candidates` is empty
+     * because the gate is blind, NOT because the store is clean. Always `false`
+     * when the project genuinely has zero issues to compare against, or when
+     * `dedupeScanEnabled` is off: those are complete (if empty) scans, not
+     * degraded ones.
+     */
+    degraded: boolean;
+    /** Set iff `degraded` — the concrete reason, never a generic "unavailable". */
+    degradedReason?: DuplicateScanDegradedReason;
+}
 /**
  * The search substrate `createIssue`'s duplicate gate needs (§6.4 point 1),
  * threaded alongside {@link IWriteStoreHandle} rather than folded into it:
@@ -109,19 +182,22 @@ export interface IDuplicateCandidate {
  *
  * `search.embedQuery` is declared OPTIONAL here (unlike
  * `IQueryStoreHandle.search.embedQuery`, which is mandatory) specifically to
- * express §6.4 point 4's degraded case: a `StoreSearchBackend` can be wired
- * (FTS/text always available, since it runs off the graph store directly)
- * while no embedding model/vector space is configured — the search
- * itself stays callable, just scoped to `signals:[{text}]` rather than
- * `signals:[{text},{vec}]` (and, having no vector channel, surfacing no
- * duplicate candidates — see {@link scanForDuplicates}). `search` itself stays OPTIONAL (no backend
+ * express §6.4 point 4's `no-embed-query` degraded case: a `StoreSearchBackend`
+ * can be wired (FTS/text runs off the graph store directly) while no embedding
+ * model/vector space is configured, so the CALIBRATED (vector) channel can
+ * never run. `scanForDuplicates` reports that as `degradedReason:
+ * 'no-embed-query'`, and `createIssue`'s `abort` FAILS CLOSED on it — a
+ * persistent configuration absence the operator must fix, never a transient.
+ * (It deliberately does NOT fall back to a text-only scan: BM25 is
+ * uncalibrated and would reintroduce the false-positive class — see
+ * {@link scanForDuplicates}.) `search` itself stays OPTIONAL (no backend
  * mounted at all) for the same "never silently go dark" posture §6.4 point 4
- * states, but applied one layer further out: `scanForDuplicates` treats a
- * wholly-absent backend as "scan unavailable" (zero candidates, `create`
- * proceeds normally) rather than throwing — filing an issue must never hard-
- * fail because the product-feature-only dedupe UX (§6.4's own framing: "a
- * missed warning, not a correctness defect") happens to be unwired in a given
- * environment.
+ * states, but applied one layer further out: `scanForDuplicates` reports a
+ * wholly-absent backend as `no-search-backend` (zero candidates, `create`
+ * PROCEEDS and carries the signal) rather than throwing — filing an issue must
+ * never hard-fail because the product-feature-only dedupe UX (§6.4's own
+ * framing: "a missed warning, not a correctness defect") happens to be
+ * unwired in a given environment.
  */
 export interface IDuplicateScanHandle {
     readonly graph?: GraphBackend;
@@ -202,7 +278,19 @@ export interface ICreateIssueCard {
  *   `duplicateAction` — this is NOT an empty array in that case (§6.4 point
  *   3, first sentence).
  * - `reason` — present iff `!created` and the gate suppressed the write
- *   (`duplicateAction:'abort'`, the default).
+ *   (`duplicateAction:'abort'`, the default) OR refused it because the scan
+ *   was degraded in the never-resolvable `no-embed-query` way
+ *   (`'duplicate-scan-degraded'`, BUG 4e8fce2a — see
+ *   {@link IDuplicateScanOutcome}).
+ * - `duplicateScanDegraded`/`duplicateScanDegradedReason` — present iff the
+ *   pre-write scan could not run a calibrated comparison
+ *   ({@link scanForDuplicates}'s `degraded`), on EVERY outcome: on the
+ *   `'abort'` refusal for the never-resolvable `no-embed-query` degrade
+ *   (`created:false`, `reason:'duplicate-scan-degraded'`), and on
+ *   `'force'`/`'comment'`/the `no-vector-scores` and `no-search-backend`
+ *   `'abort'` paths where the write proceeded anyway.
+ *   This is the field that makes a degraded scan non-silent: absent on a
+ *   healthy scan (the common case), so byte-for-byte unchanged there.
  * - `commentedOn` — present iff `duplicateAction:'comment'` fired.
  * - `supersededUid` — always absent from `createIssue` alone; only the
  *   `supersedes` composition (§6.3.2, not yet built here) would set it.
@@ -212,12 +300,32 @@ export interface ICreateIssueResult {
     uid?: string;
     item?: ICreateIssueCard;
     duplicateCandidates?: IDuplicateCandidate[];
-    reason?: 'duplicate-suppressed';
+    /**
+     * C9 — advisory cross-project similarity candidates. Present iff the
+     * configured `similarityScope` is wider than `same-project` and the scan
+     * surfaced at least one. Purely informational: it never changes whether the
+     * write proceeded, and the scan writes no `similar_to` edge (AC2/AC3).
+     */
+    similarCandidates?: ISimilarCandidate[];
+    reason?: 'duplicate-suppressed' | 'duplicate-scan-degraded';
+    /** Present iff the pre-write scan was degraded — see this interface's own doc comment. Paired with {@link duplicateScanDegradedReason}. */
+    duplicateScanDegraded?: boolean;
+    /** Why the scan was degraded. Present iff {@link duplicateScanDegraded}. */
+    duplicateScanDegradedReason?: DuplicateScanDegradedReason;
     supersededUid?: string;
     commentedOn?: {
         uid: string;
         noteId: string;
     };
+    /**
+     * C1 AC8 — how the issue's component was resolved. `'explicit'` when the
+     * caller supplied `component` and it resolved; `'default-root'` when the
+     * caller supplied none and the project's reserved `(root)` default was used.
+     * Makes "silently defaulted" distinguishable from "resolved": a supplied
+     * component that does NOT resolve still throws `CatalogNotFoundError` and
+     * never reaches this field.
+     */
+    placementResolved?: 'explicit' | 'default-root';
 }
 /**
  * Maximum length of the item-level `gitContext` disclosure scalar, enforced
@@ -246,7 +354,13 @@ export declare function assertGitContextWithinCap(value: string | undefined): vo
  * outside the project root AND every `citationAllowedExternalRoots` entry —
  * the carve-out, BUG c6d35272 — and the error names those roots),
  * `InvalidArgumentError('duplicateAction', ...)`
- * (an unrecognized value — §6.4), `WriteContentionError`/
+ * (an unrecognized value — §6.4), the `dedupeExcludeUid` resolution errors
+ * (`IssueNotFoundError` / `AmbiguousReferenceError` / `InvalidArgumentError` /
+ * `StaleSupersedeError` — via `resolveIssueByUid`, see
+ * {@link resolveDedupeExcludeIds}) when a `dedupeExcludeUid` was supplied but
+ * does not resolve to a live, non-superseded `issue` — fail loud, ADR-0002 D5;
+ * c5460239),
+ * `WriteContentionError`/
  * `WriteIOError` (§4c — an exhausted driver-level retry on the underlying
  * `immediate` transaction).
  */

package/write/errors.d.ts

@@ -162,6 +162,35 @@ export declare class CatalogNotFoundError extends BacklogWriteError {
     readonly retryable = false;
     constructor(catalogKind: string, ref: string);
 }
+/**
+ * A uid reference matched MORE THAN ONE live node by prefix. Carries the
+ * candidate set (`uid` + `kind` + `name`) as structured data so a caller can
+ * disambiguate and re-run, and renders every candidate into the message.
+ *
+ * The resolver NEVER auto-selects among the candidates — silently returning
+ * the wrong item is strictly worse than refusing. Distinct from
+ * `IssueNotFoundError` (an exact uid that is genuinely absent) so a caller can
+ * branch structurally: an ambiguous reference is actionable (re-run with a
+ * longer prefix or the full uid), a missing one is not.
+ *
+ * `E_VALIDATION`, never retryable — retrying the identical short reference
+ * resolves to the identical candidate set.
+ */
+export declare class AmbiguousReferenceError extends BacklogWriteError {
+    readonly ref: string;
+    readonly candidates: ReadonlyArray<{
+        uid: string;
+        kind: string;
+        name: string;
+    }>;
+    readonly code: "E_VALIDATION";
+    readonly retryable = false;
+    constructor(ref: string, candidates: ReadonlyArray<{
+        uid: string;
+        kind: string;
+        name: string;
+    }>);
+}
 /**
  * A flat-catalog write named a token that differs from an EXISTING LIVE row of
  * the SAME kind only by letter case (`IN_PROGRESS` vs `in_progress`, `high` vs
@@ -208,9 +237,16 @@ export declare class InvalidArgumentError extends BacklogWriteError {
 /** No live `issue` node carries the given `uid` (SPEC.md §6.1). */
 export declare class IssueNotFoundError extends BacklogWriteError {
     readonly uid: string;
+    readonly asPrefix: boolean;
     readonly code: "E_VALIDATION";
     readonly retryable = false;
-    constructor(uid: string);
+    /**
+     * @param uid The uid (or uid prefix) the caller passed in.
+     * @param asPrefix Set by the prefix resolver when `uid` was a short prefix
+     *   rather than a full uid, so the message says "no item matches" instead of
+     *   implying the caller passed a complete uid that is simply absent.
+     */
+    constructor(uid: string, asPrefix?: boolean);
 }
 /**
  * `claim` (§6.3.5): the lease is held by someone else, not yet stale, and the
@@ -355,6 +391,81 @@ export declare class BacklogValidationError extends BacklogWriteError {
     readonly retryable = false;
     constructor(field: string, detail?: string);
 }
+/**
+ * A supplied anchor locator is outside the closed grammar (`path:<file>[:<line>]`
+ * | `url:<url>` | `query:<cql>` | `registry:<ref>`), or is a bare `path:line`
+ * with no `digest`. A caller-input mistake, so `E_VALIDATION`, never retryable —
+ * nothing is written and retrying the identical locator fails identically.
+ */
+export declare class AnchorLocatorInvalidError extends BacklogWriteError {
+    readonly locator: string;
+    readonly code: "E_VALIDATION";
+    readonly retryable = false;
+    constructor(locator: string, detail?: string);
+}
+/**
+ * `recheck` named an `attestation` uid that is not a live `attestation` node.
+ * Distinct from {@link IssueNotFoundError} (an `issue` uid) and
+ * {@link CatalogNotFoundError} so a caller can branch on the missing record
+ * kind; `E_VALIDATION`, never retryable.
+ */
+export declare class AttestationNotFoundError extends BacklogWriteError {
+    readonly uid: string;
+    readonly code: "E_VALIDATION";
+    readonly retryable = false;
+    constructor(uid: string);
+}
+/**
+ * `obligate` (C4, DESIGN §2 Primitive 3) was handed a `requirement` outside the
+ * CLOSED predicate core — an unknown `op`, a missing/ill-typed leaf
+ * (`evidence.kind`, `relation.type`/`direction`, a non-array `all_of`/`any_of`
+ * `of`, a `not` whose `of` is not a predicate), an unexpected extra key, or an
+ * `evidence.min < 1`. Raised by `assertValidPredicate` BEFORE any transaction
+ * opens, so an invalid predicate never holds a write lock.
+ *
+ * `E_VALIDATION`, never retryable — nothing is written, and retrying the
+ * identical predicate fails identically. Distinct from `InvalidArgumentError`
+ * so a caller can tell "the argument envelope was malformed" from "the
+ * predicate grammar was violated".
+ */
+export declare class InvalidPredicateError extends BacklogWriteError {
+    readonly detail: string;
+    readonly code: "E_VALIDATION";
+    readonly retryable = false;
+    constructor(detail: string);
+}
+/**
+ * `unobligate` named a uid that is not a live `obligation` node. Distinct from
+ * {@link IssueNotFoundError} (an `issue` uid) and {@link CatalogNotFoundError}
+ * so a caller can branch on the missing record kind; `E_VALIDATION`, never
+ * retryable.
+ */
+export declare class ObligationNotFoundError extends BacklogWriteError {
+    readonly uid: string;
+    readonly code: "E_VALIDATION";
+    readonly retryable = false;
+    constructor(uid: string);
+}
+/**
+ * `appendSpecRevision`'s `base_revision` no longer matches the ticket's current
+ * spec pointer — a concurrent spec edit won the CAS. `E_VALIDATION`,
+ * `retryable: false`, and mapped EXPLICITLY to the envelope code
+ * `precondition_failed` in `api.ts`'s `ERROR_CLASS_TO_ENVELOPE_CODE` (C10 AC6):
+ * the `E_VALIDATION` fallthrough would otherwise return `validation`.
+ *
+ * A stale `base_revision` is NOT resource contention — no other actor holds the
+ * node; the *caller's own* read is out of date and must be re-read before
+ * retrying — so it belongs with the existing refusing-write preconditions
+ * (`IssueTerminalError`, `CitationUnverifiableError`), not with `conflict`
+ * (reserved for a resource another actor holds). No write runs.
+ */
+export declare class SpecRevisionConflictError extends BacklogWriteError {
+    readonly expected: string;
+    readonly actual: string;
+    readonly code: "E_VALIDATION";
+    readonly retryable = false;
+    constructor(expected: string, actual: string);
+}
 /**
  * Classify a caught, RAW driver-level error (never one of our own
  * {@link BacklogWriteError} subclasses — those are already decided and must
@@ -399,3 +510,87 @@ export declare function classifyDriverError(err: unknown): IWriteError;
  * immediately after `assertNonBlank('by', input.by)` at every mutating verb.
  */
 export declare function assertNotBareRoleLiteral(field: string, value: string): void;
+/**
+ * (C5) A terminal transition was refused because a `block`-severity obligation
+ * is unsatisfied (DESIGN §2 Primitive 3). `E_VALIDATION` → the envelope maps
+ * it to `precondition_failed`, with the structured `IGateRefusal` in
+ * `error.details.refusal` (adhd ADR-0004 — object-shaped, never a `{result}`
+ * envelope). Thrown from INSIDE `transition`'s open `BEGIN IMMEDIATE`
+ * transaction and BEFORE any write, so the throw rolls the transaction back and
+ * a re-read shows the status unchanged.
+ *
+ * `E_VALIDATION`, never retryable — retrying the identical payload against
+ * unchanged obligations fails identically (the caller must satisfy or override
+ * the obligation first).
+ *
+ * Deliberately declared ATTACHED to `errors.ts`'s end (after every existing
+ * export) and importing `IGateRefusal` via an inline `import(...)` type, so
+ * this additive change shifts NO existing line and leaves `CONTRACT.md`'s
+ * `(errors.ts:NNN)` anchors (enforced by `contract-anchors.spec.ts`) true.
+ */
+export declare class ObligationUnsatisfiedError extends BacklogWriteError {
+    readonly refusal: import('./gate.js').IGateRefusal;
+    readonly code: "E_VALIDATION";
+    readonly retryable = false;
+    constructor(refusal: import('./gate.js').IGateRefusal);
+}
+/**
+ * (C5) A claimed override of a refusing obligation is not permitted: the caller
+ * is not in the obligation's `override.actors`, or the override carries a blank
+ * reason. An override ALWAYS requires a recorded reason (DESIGN §2 Primitive 3
+ * — "not a configurable boolean"), so a blank one is refused, never treated as
+ * a silent pass.
+ *
+ * `E_VALIDATION` → `precondition_failed`, never retryable.
+ */
+export declare class OverrideNotPermittedError extends BacklogWriteError {
+    readonly obligationUid: string;
+    readonly actor: string;
+    readonly code: "E_VALIDATION";
+    readonly retryable = false;
+    constructor(obligationUid: string, actor: string);
+}
+/**
+ * (C6) A verb's entry precondition was refused by a live block-severity verdict
+ * condition — today only `claim` (DESIGN §2 Primitive 3/4: taking blocked work
+ * is the observed failure). `E_VALIDATION` → the envelope maps it to
+ * `precondition_failed`, with the structured `ICondition` in
+ * `error.details.refusal` (adhd ADR-0004 — object-shaped, never a `{result}`
+ * envelope). Thrown from INSIDE `claim`'s open `BEGIN IMMEDIATE` transaction
+ * and BEFORE any write, so the throw rolls the transaction back and the item
+ * is left unclaimed.
+ *
+ * `E_VALIDATION`, never retryable — retrying the identical payload against an
+ * unchanged blocker fails identically (the caller must clear the blocker, or
+ * `force` and record it first).
+ *
+ * Declared ATTACHED to `errors.ts`'s end (after every existing export) and
+ * importing `ICondition` via an inline `import(...)` type, so this additive
+ * change shifts NO existing line and leaves `CONTRACT.md`'s `(errors.ts:NNN)`
+ * anchors (enforced by `contract-anchors.spec.ts`) true.
+ */
+export declare class PreconditionRefusedError extends BacklogWriteError {
+    readonly refusal: import('../query/types.js').ICondition;
+    readonly code: "E_VALIDATION";
+    readonly retryable = false;
+    constructor(refusal: import('../query/types.js').ICondition);
+}
+/**
+ * `removeCitation` named a uid that is not a LIVE `citation` node — absent,
+ * already removed, or a uid naming a node of a DIFFERENT kind (the "foreign
+ * citation" refusal). Distinct from `IssueNotFoundError` (an `issue` uid) and
+ * `CatalogNotFoundError` (a registry/`catalog` ref) so a caller can branch on
+ * the missing record kind; `E_VALIDATION`, never retryable.
+ *
+ * Declared ATTACHED to `errors.ts`'s end (after every existing export, like
+ * `ObligationUnsatisfiedError`/`OverrideNotPermittedError`/
+ * `PreconditionRefusedError` before it), so this additive change shifts NO
+ * existing line and leaves `CONTRACT.md`'s `(errors.ts:NNN)` anchors
+ * (enforced by `contract-anchors.spec.ts`) true.
+ */
+export declare class CitationNotFoundError extends BacklogWriteError {
+    readonly uid: string;
+    readonly code: "E_VALIDATION";
+    readonly retryable = false;
+    constructor(uid: string);
+}

package/write/gate.d.ts

@@ -0,0 +1,67 @@
+import { ITxNodeRow } from './tx.js';
+import { IVerdict } from '../query/types.js';
+import { AdapterTransaction } from '@adhd/sox-store-adapter';
+
+/** The closed refusal-reason vocabulary (DESIGN §2 Primitive 4's governed core, scoped to the write gate). */
+export type IGateReasonCode = 'EvidenceUnverified' | 'EvidenceStale' | 'BlockedBy' | 'MissingObligation' | 'ClaimStale' | 'ReferenceUnresolved' | 'Unknown';
+/**
+ * The object-shaped refusal payload (adhd ADR-0004 — carried in
+ * `error.details.refusal`, never as a `{result}` envelope).
+ */
+export interface IGateRefusal {
+    code: IGateReasonCode;
+    message: string;
+    /** The obligation that refused, when the refusal is obligation-scoped. */
+    obligationUid?: string;
+    /** The thing to fix — blocker uid / attestation uid. */
+    subject?: string;
+    /** For EvidenceUnverified: the `claim.kind` the obligation required. */
+    required_kind?: string;
+    /** The mechanical check that produced the refusal (e.g. 'default_branch_ancestor'). */
+    performed_check?: string;
+}
+export interface IGateEvaluation {
+    satisfied: boolean;
+    refusals: IGateRefusal[];
+    /** Pairs recorded as `satisfies` edges on success. */
+    satisfiedBy: Array<{
+        obligationUid: string;
+        attestationUid: string;
+    }>;
+    /** Obligations whose on_fail is 'warn' and predicate false — recorded, never refusing. */
+    warnings: IGateRefusal[];
+}
+/** The gated transition's inputs, threaded from `transition.ts`'s open `tx`. */
+export interface IGateInput {
+    issueRowid: number;
+    fromStatus: string;
+    toStatus: string;
+    effectiveActor: string;
+    at: string;
+    /** A caller-supplied override attempt; honoured only for a listed actor + a non-blank reason. */
+    override?: {
+        reason: string;
+    };
+}
+/**
+ * Evaluate the transition-scoped obligations of `issueRowid` for `from → to`
+ * INSIDE the caller's open `tx`. Never writes. `effectiveActor` enables the
+ * listed-actor override.
+ *
+ * Returns a typed {@link IGateEvaluation}; the caller decides whether to throw
+ * ({@link ObligationUnsatisfiedError}) and writes the `satisfies` edges on
+ * success. Throws {@link OverrideNotPermittedError} when an override is
+ * claimed by an actor not listed on the refusing obligation, or carries a
+ * blank reason.
+ */
+export declare function evaluateTransitionGateTx(tx: AdapterTransaction, input: IGateInput): Promise<IGateEvaluation>;
+/**
+ * Derive the verdict INSIDE the caller's open tx, through rungs 1–2 only
+ * (claim is a precondition, never a full anchor re-resolve). Never writes;
+ * reuses C4's {@link evaluatePredicate} with the tx-scoped {@link
+ * makeTxResolver} and C6's own `orderConditions`/`computeActionable`.
+ */
+export declare function evaluateVerdictTx(tx: AdapterTransaction, issueRow: ITxNodeRow, input: {
+    at: string;
+    claimStaleAfterMin: number;
+}): Promise<IVerdict>;

package/write/merge-project.d.ts

@@ -0,0 +1,54 @@
+import { IWriteStoreHandle } from './tx.js';
+
+export interface IMergeProjectInput {
+    /** The duplicate / retiring row — an exact uid. */
+    fromUid: string;
+    /** The canonical survivor — a uid or a name (resolved live). */
+    toUid: string;
+    /** identity; asserted non-blank + not a bare role literal */
+    by: string;
+}
+export interface IMergeProjectOutcome {
+    survivorUid: string;
+    retiredUid: string;
+    /** How many issues' `owns_component` chains were re-pointed onto the survivor. */
+    movedIssues: number;
+    /** Always true — the retired uid is never reusable. */
+    retired: true;
+}
+export interface IRmProjectInput {
+    uid: string;
+    reason: string;
+    by: string;
+}
+/**
+ * Merge duplicate project `fromUid` into canonical `toUid` in ONE
+ * `BEGIN IMMEDIATE` transaction: re-point every component owned by `fromUid`
+ * (its `owns_project` edges AND each component's `meta.projectUid`) onto
+ * `toUid`, set `fromUid.meta.redirectTo = toUid` + `fromUid.meta.retiredAt`,
+ * stamp `t_invalid`, and write an audit row.
+ *
+ * Idempotent: a second call with the same `(from,to)` is a no-op success
+ * (`movedIssues: 0`) — the retired `from` row is still readable by uid, its
+ * `meta.redirectTo` already names the survivor.
+ *
+ * @throws CatalogNotFoundError `fromUid` is not a `project` row, or `toUid`
+ *   does not resolve to a LIVE project.
+ * @throws InvalidArgumentError `toUid` equals `fromUid`, or `fromUid` is
+ *   already retired pointing at a DIFFERENT survivor (never silently
+ *   re-chain).
+ */
+export declare function mergeProject(handle: IWriteStoreHandle, input: IMergeProjectInput): Promise<IMergeProjectOutcome>;
+/**
+ * Soft-retire a project WITHOUT a survivor: set `meta.retiredAt`, stamp
+ * `t_invalid`, and audit. No `redirectTo` is written, so its old name resolves
+ * to nothing (the row is retired, not redirected).
+ *
+ * Idempotent: a second call against an already-retired row is a success no-op.
+ *
+ * @throws CatalogNotFoundError `uid` is not a `project` row.
+ */
+export declare function rmProject(handle: IWriteStoreHandle, input: IRmProjectInput): Promise<{
+    uid: string;
+    retired: true;
+}>;