@adhd/backlog 0.1.9 → 1.0.1

package/write/create-issue.d.ts

@@ -0,0 +1,253 @@
+import { IWriteStoreHandle } from './tx.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.
+ */
+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 interface ICreateIssueInput {
+    title: string;
+    body: string;
+    /** uid or name — resolved per §6.1; REQUIRED (every issue has a component chain). NEVER minted by this verb (§1/§6.1). */
+    project: string;
+    /** uid or name, scoped within `project` — RESOLVED ONLY, never created. Omitted (undefined) resolves to `project`'s reserved default component `(root)` (§3/§6.1/§8 AC-23) — a THIRD case, distinct from a resolved or an unresolved name. */
+    component?: string;
+    /** catalog name or uid; default is the project's configured `policy.defaultKind`, falling back to the global `"issue"` row. An unresolved NAME mints; a uid-shaped ref that does not resolve throws (§6.1). */
+    kind?: string;
+    /** catalog name or uid; default is `policy.defaultStatus`, falling back to the global `"open"` row (minted with `terminal:false` if it does not yet exist). An unresolved NAME mints with `terminal:false`; a uid-shaped ref that does not resolve throws (§6.1). */
+    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[];
+    /** 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. */
+    assignee?: string;
+    /**
+     * The item-level disclosure-contract git context — a plain metadata scalar
+     * (a sibling of {@link assignee}, no edge), persisted verbatim into the
+     * `issue` node's metadata and surfaced by reads as `IIssueCard.gitContext`.
+     *
+     * Repo `AGENTS.md`'s "Cite what you read" rule fixes the shape of a
+     * `Citations:` block as `Citations: [<active git context>, <agent name>,
+     * <active plan or task>, …]` — the git context is the block's FIRST
+     * element. This field carries it. It is ITEM-level, deliberately NOT a
+     * per-citation `ref`: the block renders it once, at its head, so a
+     * multi-citation item never repeats it. Omitted ⇒ nothing is stored, and
+     * every read/render path is byte-for-byte unchanged.
+     */
+    gitContext?: 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;
+    /**
+     * The duplicate-gate control (§6.3.2, resolved in full at §6.4). Default
+     * `'abort'`. Only meaningful when the pre-write similarity scan (§6.4
+     * point 1) surfaces ≥1 candidate at/above `project_policy.dedupe_threshold`
+     * — a zero-candidate scan proceeds to a normal create regardless of this
+     * value (§6.4 point 3, first sentence).
+     *
+     * - `'abort'` — nothing is written; `{created:false,
+     *   reason:'duplicate-suppressed', duplicateCandidates}`.
+     * - `'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
+     *   (`has_note`) to the TOP-scoring candidate instead, carrying the
+     *   would-be issue's title+body verbatim.
+     */
+    duplicateAction?: 'abort' | 'force' | 'comment';
+    /**
+     * §4b/§6.2 — waits for the fire-and-forget on-write embedding round-trip
+     * (`embedding-observer.ts`'s `scheduleIssueEmbedding`) before `createIssue`
+     * returns, when `true` and `handle.embedding` is configured. Default
+     * (`false`/omitted): fire-and-forget — the embed/vector-upsert and its
+     * `embedding_upserted`/`embedding_failed` audit row happen in the
+     * background, after this function has already returned to its caller.
+     * A `true` value with NO `handle.embedding` configured is a harmless no-op
+     * (nothing to await — `scheduleIssueEmbedding` resolves immediately).
+     * Per-call, not per-handle — §6.2 specifies this field as kept verbatim
+     * on `create`/`update`, living on the input type for each verb
+     * (`ICreateIssueInput` here, `IUpdateIssueInput` in `update.ts`), not on
+     * `IDuplicateScanHandle`.
+     */
+    awaitEmbed?: boolean;
+}
+/**
+ * A dedupe candidate surfaced at filing time (§6.4), carrying the cosine
+ * similarity that produced it — see {@link scanForDuplicates}'s own doc
+ * comment for where that number comes from and why it is the only score
+ * this gate will accept.
+ */
+export interface IDuplicateCandidate {
+    uid: string;
+    title: string;
+    /** Cosine similarity in `[0,1]`, straight off the vector channel — directly comparable to `project_policy.dedupe_threshold`. */
+    score: number;
+}
+/**
+ * The search substrate `createIssue`'s duplicate gate needs (§6.4 point 1),
+ * threaded alongside {@link IWriteStoreHandle} rather than folded into it:
+ * `IWriteStoreHandle` (tx.ts) is the write layer's OWN minimal dependency
+ * shape (`adapter`+`typePolicy`) and is not this slice's file to widen.
+ * Structurally — not nominally — compatible with `query/query.ts`'s
+ * `IQueryStoreHandle`: every real call site (`TestIssueStore` in tests,
+ * and the not-yet-built store-bootstrap module in production, §6.3.2's own
+ * `awaitEmbed` doc comment) already carries BOTH a `graph` and a `search`
+ * alongside the write handle's `adapter`/`typePolicy`, so a caller who
+ * already has an `IQueryStoreHandle`-shaped object satisfies this by
+ * construction — no adapter/wrapper needed.
+ *
+ * `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
+ * 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.
+ */
+export interface IDuplicateScanHandle {
+    readonly graph?: GraphBackend;
+    readonly search?: {
+        readonly backend: StoreSearchBackend;
+        embedQuery?(text: string): Promise<Float32Array>;
+    };
+}
+/**
+ * The "plain" card fields (§6.5) this verb already has in hand after a
+ * create — never field-projected, unlike a `query` response.
+ *
+ * BUG-APIGEN-CORE-CLIENT-BARE-NAME-COLLISION-001: named `ICreateIssueCard`,
+ * not `IIssueCard`, deliberately. `query/types.ts` also exports an
+ * `IIssueCard` (the fields-projected card `query`/`get` return, every field
+ * but `uid` optional) — both interfaces were reachable from `api.d.ts`'s
+ * type graph, and apigen's extraction (`ts-json-schema-generator`, invoked
+ * per-operation but apparently resolving/caching declarations by bare name
+ * across the whole extracted program) non-deterministically resolved the
+ * `IIssueCard` bare name to EITHER declaration depending on extraction
+ * order — confirmed empirically: `dist/index.js` (CJS) resolved `query`'s
+ * own `items: IIssueCard[]` to THIS file's stricter shape (wrongly requiring
+ * `project`/`component`/`createdAt`), while `dist/index.mjs` (ESM) failed to
+ * resolve it at all (`items: {}`, unconstrained) — from the exact same
+ * source, built in the same pass. This is what broke `backlog_query`'s MCP
+ * `oneOf` output-schema validation the moment `get()`'s return type union
+ * (AC-11) made the extractor visit both `IIssueCard` declarations. The
+ * correct, permanent fix is what's below: give the two interfaces distinct
+ * bare names so extraction can never conflate them, not a workaround in the
+ * `get()`/`query()` call sites. Filed as
+ * BUG-APIGEN-CORE-CLIENT-BARE-NAME-COLLISION-001 (apigen-core-client, out of
+ * this package's ownership) — this rename is the local mitigation; the
+ * extractor itself should also stop keying declarations by bare name.
+ *
+ * This rename fixes the CJS path (`dist/index.js`, the only bundle any real
+ * transport here — CLI, MCP-stdio, HTTP serve — ever spawns/requires;
+ * confirmed empirically, `dist/index.mjs` is loaded by none of them). It does
+ * NOT fix a second, DISTINCT defect also present in `dist/index.mjs`: every
+ * `$ref` to a NAMED exported interface (`ICreateIssueCard` here,
+ * `IDuplicateCandidate`, `IIssueCard`, …) dereferences to `{}` (empty/
+ * unconstrained) in the ESM build specifically, while inline/anonymous
+ * object types on the SAME operation (e.g. `ICreateIssueResult.commentedOn`)
+ * resolve correctly in both builds — ruling out a general extraction
+ * failure and pointing at `dereferenceSchema`'s named-`$ref` resolution
+ * specifically misbehaving under ESM. Reproduced on `create`'s `item`/
+ * `duplicateCandidates` fields, which this file's own diff never touched,
+ * so it predates and is independent of the collision above. Filed
+ * separately as BUG-APIGEN-CORE-CLIENT-ESM-DEREF-EMPTY-001 — not fixed
+ * here (out of this package's ownership, and no real consumer loads
+ * `dist/index.mjs` today), but must not be silently dropped.
+ */
+export interface ICreateIssueCard {
+    uid: string;
+    title: string;
+    kind: string;
+    status: string;
+    priority?: string;
+    project: string;
+    component: string;
+    createdAt: string;
+    assignee?: string;
+    author?: string;
+    closedAt?: string;
+    /** The item-level disclosure-contract git context, echoed back from {@link ICreateIssueInput.gitContext} — present iff one was supplied. */
+    gitContext?: string;
+}
+/**
+ * `ICreateOutcome` (§6.3.2's Output section, verbatim shape — ONE interface
+ * with optional fields, deliberately NOT a discriminated union): `created`
+ * is the only field guaranteed present. Every other field's presence is
+ * conditional per §6.4/§6.3.2:
+ *
+ * - `uid`/`item` — present iff `created`.
+ * - `duplicateCandidates` — present iff the scan surfaced ≥1 candidate
+ *   at/above threshold (§6.4 point 3) — on `'abort'` (suppressed) AND on
+ *   `'force'` (written anyway, reported for audit) AND on `'comment'`.
+ *   Absent entirely on a zero-candidate scan, regardless of
+ *   `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).
+ * - `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.
+ */
+export interface ICreateIssueResult {
+    created: boolean;
+    uid?: string;
+    item?: ICreateIssueCard;
+    duplicateCandidates?: IDuplicateCandidate[];
+    reason?: 'duplicate-suppressed';
+    supersededUid?: string;
+    commentedOn?: {
+        uid: string;
+        noteId: string;
+    };
+}
+/**
+ * Maximum length of the item-level `gitContext` disclosure scalar, enforced
+ * at WRITE time by every verb that accepts one (`create` here, `transition`).
+ * The field is free-form caller text that the markdown renderer interpolates
+ * inline (`query/markdown.ts`'s `sanitizeGitContext` is the render-side half
+ * of the same guarantee), so an unbounded value would let a single issue's
+ * citation block balloon arbitrarily. Shared by both write paths so the
+ * `create`/`transition` caps never drift.
+ */
+export declare const MAX_GIT_CONTEXT_LENGTH = 512;
+/** Rejects an over-long `gitContext` before any write runs (E_VALIDATION, never retried). A non-string (e.g. an untyped CLI/HTTP/MCP JSON `null`) is skipped here — the caller's own `typeof === 'string'` normalization treats it as absent. */
+export declare function assertGitContextWithinCap(value: string | undefined): void;
+/**
+ * Create a new issue (§4, §6.3.2). One `immediate` transaction; `skipDedupe:
+ * true` on every entity write (§1) via `writeNodeTx`.
+ *
+ * Errors: `InvalidArgumentError` (missing/blank `title`/`body`/`project`/`by`,
+ * or a blank `citations[i].file`), `CatalogNotFoundError('project'|'component'|
+ * 'kind'|'status'|'priority'|'agent', ref)` (`'component'` fires only when a
+ * name/uid was GIVEN and did not resolve — omitting `component` never throws
+ * it), `CitationUnverifiableError(file, allowedExternalRoots)` (policy-gated
+ * via `project_policy.citation_requires_sha`, and only when the project has a
+ * known `path` — a path-less project records `sha:"unverified"` verbatim; a
+ * path-present project still rejects a target whose canonical path lies
+ * 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`/
+ * `WriteIOError` (§4c — an exhausted driver-level retry on the underlying
+ * `immediate` transaction).
+ */
+export declare function createIssue(handle: IWriteStoreHandle & IDuplicateScanHandle, input: ICreateIssueInput): Promise<ICreateIssueResult>;

package/write/delete.d.ts

@@ -0,0 +1,39 @@
+import { IWriteStoreHandle } from './tx.js';
+
+export interface IDeleteIssueInput {
+    uid: string;
+    /** REQUIRED — the human-readable explanation for the invalidation, still a real requirement (§6.3.7). */
+    reason: string;
+    /** The acting agent or person, as a name (§6.3's opening rule). REQUIRED. */
+    by: string;
+    /**
+     * §4b/§6.2/§8 AC-4 ("invalidating an issue removes its vector") — waits for
+     * the fire-and-forget vector-deletion round-trip before `deleteIssue`
+     * returns, when `true` and `handle.embedding` is configured. Default
+     * (`false`/omitted): fire-and-forget, matching `create`/`update`'s own
+     * default.
+     */
+    awaitEmbed?: boolean;
+}
+export interface IDeleteIssueOutcome {
+    uid: string;
+    invalidated: true;
+}
+/**
+ * Soft-invalidate a live issue (§6.3.7). One `immediate` transaction: resolve
+ * `uid` → live `issue` node (tx-scoped, never `getNodeByUid` itself, §4c) →
+ * hand-composed `UPDATE node SET t_invalid = ?, meta = ? WHERE rowid = ?`
+ * (mirroring `invalidate`'s own SQL exactly, merging `invalidatedReason`/
+ * `invalidatedAt` into the EXISTING `meta` — never a wholesale replace, §4a)
+ * → `writeAudit` (§4a), against the SAME `tx` handle throughout. NEVER a hard
+ * row deletion — the row and its full audit trail survive untouched, only
+ * `t_invalid`/`meta` change.
+ *
+ * Errors: `InvalidArgumentError` (`uid`/`by`/`reason` missing or blank),
+ * `IssueNotFoundError` (no LIVE `issue` node carries `uid` — including an
+ * ALREADY-deleted `uid`, per this file's own doc comment on why that is a
+ * deliberate divergence from the library's bare `invalidate` mirror),
+ * `WriteContentionError`/`WriteIOError` (§4c — an exhausted driver-level
+ * retry on the underlying `immediate` transaction).
+ */
+export declare function deleteIssue(handle: IWriteStoreHandle, input: IDeleteIssueInput): Promise<IDeleteIssueOutcome>;

package/write/embed-drain.d.ts

@@ -0,0 +1,68 @@
+import { StoreAdapter } from '@adhd/sox-store-adapter';
+
+/** The round-trip an embed entry represents — mirrors `IScheduleEmbeddingInput.action`. */
+export type EmbedAction = 'upsert' | 'delete';
+/**
+ * `'pending'` until the producer settles the entry; then one of the four
+ * terminal outcomes. `'unrecorded'` means the round-trip failed AND its
+ * `embedding_failed` audit row could not be written — the outcome is not
+ * durably recorded anywhere, which is the loudest signal this module carries.
+ */
+export type EmbedOutcome = 'pending' | 'upserted' | 'deleted' | 'failed' | 'unrecorded';
+/** One scheduled embed, as the drain sees it. */
+export interface IPendingEmbed {
+    /** The graph node's store-adapter `rowid` the vector is keyed on — never `uid`. */
+    readonly subjectRowid: number;
+    /** The issue's `uid` — carried for diagnostics and the `embedding_failed` audit row. */
+    readonly subjectUid: string;
+    /** The identity of whoever performed the subject write. */
+    readonly actor: string;
+    readonly action: EmbedAction;
+    /**
+     * The promise `scheduleIssueEmbedding` returned. Typed `unknown` rather than
+     * the producer's `Promise<EmbedOutcome>` because the drain only ever awaits
+     * settlement, never reads the value — the outcome is read off {@link outcome},
+     * which the producer sets in a `.then` on this same promise.
+     */
+    readonly settled: Promise<unknown>;
+    /** `'pending'` until the producer settles it. */
+    outcome: EmbedOutcome;
+}
+/** The result of a bounded drain. */
+export interface IEmbedDrainResult {
+    /** How many entries settled (to any terminal outcome) during the drain. */
+    readonly drained: number;
+    /** Entries still `'pending'` when the bound elapsed — the close path records these durably. */
+    readonly stillPending: readonly IPendingEmbed[];
+    /** Of `stillPending`, how many the close path recorded as `embedding_failed` before closing. */
+    readonly recordedAsFailed: number;
+    /** Entries whose outcome could NOT be durably recorded — a loud, non-zero-exit signal. */
+    readonly unrecorded: readonly IPendingEmbed[];
+}
+export interface IEmbedDrainOptions {
+    /** Override the drain bound. A tuning threshold, never a feature gate (ADR-0013 D3). */
+    readonly timeoutMs?: number;
+}
+/** The per-adapter registry surface the producer and the close path share. */
+export interface IEmbedDrainRegistry {
+    /** Add an entry; returns the disposer the producer calls once `settled` resolves to a recorded outcome. */
+    register(entry: IPendingEmbed): () => void;
+    /** Number of entries currently tracked (pending or retained-unrecorded). */
+    readonly size: number;
+    snapshot(): readonly IPendingEmbed[];
+    /** Await every in-flight embed, bounded; drain-until-empty. */
+    drain(opts?: IEmbedDrainOptions): Promise<IEmbedDrainResult>;
+}
+/**
+ * Tuning constant — a threshold, never a feature gate (ADR-0013 D3).
+ *
+ * The deleted `store/embed-queue.ts` drain was unbounded (no numeric guard in
+ * its history — verified via `git log -p` across every revision of that file),
+ * so there is no original value to recover. 30s is deliberately generous: a
+ * warm local fastembed ONNX embed is sub-second, and even a cold model load
+ * finishes well inside it; the bound exists only to stop a wedged round-trip
+ * from hanging process exit forever.
+ */
+export declare const DEFAULT_EMBED_DRAIN_TIMEOUT_MS = 30000;
+/** The registry for `adapter`, creating it on first use. */
+export declare function embedDrainFor(adapter: StoreAdapter): IEmbedDrainRegistry;

package/write/embedding-config.d.ts

@@ -0,0 +1,81 @@
+import { BacklogConfig } from '../env.js';
+import { Scope } from '@adhd/environment-base-spec';
+import { Environment } from '@adhd/environment';
+
+/** The reloadable slice — exactly `BacklogConfig['embedding']`, by value. */
+export interface EmbeddingConfig {
+    readonly enabled: boolean;
+    readonly provider: string;
+    readonly model: string;
+}
+/** A change detector over the config LAYERS feeding `embedding.*`. */
+export interface EmbeddingFingerprint {
+    /**
+     * The resolution cascade's own content hash
+     * (`Environment.version.configHash`) as of the last observation. Covers
+     * EVERY field, so it is compared only to decide whether the file content
+     * actually changed — never to decide what to adopt.
+     */
+    readonly configHash: string;
+    /** Cheap pre-gate: path -> `${mtimeMs}:${size}` (or `absent`) per layer file. */
+    readonly files: ReadonlyArray<{
+        path: string;
+        stamp: string;
+    }>;
+}
+export interface EmbeddingLiveConfig {
+    /** Effective NOW — the last ADOPTED on-disk value, not the startup snapshot. */
+    current(): EmbeddingConfig;
+    /** Last value observed on disk (may equal `current()` after a refresh). */
+    configured(): EmbeddingConfig;
+    /** True when on-disk says enabled but the effective value is still disabled. */
+    divergent(): boolean;
+    /** Cheap stat pre-gate, then (on change) rebuild + adopt. */
+    refresh(): {
+        changed: boolean;
+        from: EmbeddingConfig;
+        to: EmbeddingConfig;
+    };
+    fingerprint(): EmbeddingFingerprint;
+}
+/** Options mirroring the subset of `BuildBacklogEnvOptions` that selects the config layers. */
+export interface BacklogConfigLayerOptions {
+    scope?: Scope;
+    adhdRoot?: string;
+    cwd?: string;
+    namespace?: string;
+}
+/**
+ * The resolved config LAYER FILE paths the `backlog` environment cascade reads
+ * — system/global `config.yaml` plus, when a project root resolves,
+ * `config.yaml` + `config.local.yaml` there.
+ *
+ * Enumerated from `@adhd/environment-builder`'s own `resolveEnvironmentContext`
+ * (the SAME root resolution `Environment`'s constructor runs) and the
+ * base-spec's `CONFIG_FILENAME`/`LOCAL_CONFIG_FILENAME` constants — never a
+ * hand-built `~/.adhd/...` path that could drift from the builder's scheme.
+ * Duplicates are collapsed: an explicit `adhdRoot` overrides BOTH the `global`
+ * and `system` root bases in `resolveRoots`, so those two layers resolve to the
+ * same file under test isolation and must be fingerprinted once.
+ */
+export declare function backlogConfigLayerFiles(opts?: BacklogConfigLayerOptions): string[];
+/**
+ * Builds the live holder for one long-lived process.
+ *
+ * @param opts.baseline the `ctx.env` `startBacklogServer` already built — its
+ *   `config.embedding` is the effective value until a refresh adopts a change,
+ *   and its `version.configHash` is the "startup hash" the divergence WARN
+ *   reports.
+ * @param opts.rebuild `() => buildBacklogEnv(<the SAME opts>)` — a fresh
+ *   `Environment`, never a mutation of `baseline`.
+ * @param opts.layerFiles the resolved config layer paths (see
+ *   {@link backlogConfigLayerFiles}); called on every observation, cheap.
+ * @param opts.log where an adoption (`'info'`) or a re-read failure (`'warn'`)
+ *   is reported. The write layer's only sink is `console.error`.
+ */
+export declare function createEmbeddingLiveConfig(opts: {
+    baseline: Environment<BacklogConfig>;
+    rebuild: () => Environment<BacklogConfig>;
+    layerFiles: () => readonly string[];
+    log: (level: 'info' | 'warn', message: string) => void;
+}): EmbeddingLiveConfig;

package/write/embedding-observer.d.ts

@@ -0,0 +1,80 @@
+import { IPendingEmbed } from './embed-drain.js';
+import { IWriteStoreHandle } from './tx.js';
+
+/**
+ * The `note` every close-time drain failure carries on its `embedding_failed`
+ * audit row — so a vector that was still in flight when the store closed is
+ * distinguishable, in the durable audit trail, from one whose round-trip
+ * itself failed (`scheduleIssueEmbedding`'s own failure note is the error
+ * message). See `graph-backlog-store.ts`'s `closeGraphBacklogStore`.
+ */
+export declare const EMBED_DRAIN_TIMEOUT_NOTE = "embed did not settle before store close \u2014 recorded by the close-time drain (RAG-SPEC.md \u00A72.2)";
+/**
+ * The exact text an issue is embedded from — `${title}\n${body}`.trim().
+ * **This MUST stay byte-identical to `create-issue.ts`'s `scanForDuplicates`
+ * text composition.** The two live in different files (this module vs.
+ * `create-issue.ts`) and compose text for two different purposes (the
+ * on-write vector vs. the pre-write duplicate-scan query vector), but both
+ * ultimately populate/query the SAME vector space under the SAME `modelId`.
+ * If the two ever diverge, `project_policy.dedupe_threshold`'s default (§6.4
+ * point 1's own doc comment: "the scale its own default was chosen against")
+ * silently stops meaning what it was calibrated against — AC-19's gate would
+ * drift without any test noticing, since both sides would still "work" in
+ * isolation. `create-issue.ts` imports this function rather than keeping its
+ * own copy, specifically so the two call sites cannot drift apart in source.
+ */
+export declare function composeEmbedText(title: string, body: string): string;
+interface IScheduleEmbeddingBase {
+    /** The graph node's store-adapter `rowid` the vector is keyed on — never `uid` (see {@link import('./tx.js').IEmbeddingBackend}'s own doc comment). */
+    subjectRowid: number;
+    /** The issue's `uid` — carried through only for the audit row's `target_uid` and diagnostic logging; never used to key the vector store. */
+    subjectUid: string;
+    /** The identity of whoever performed the write — the SAME `input.by` the verb's own subject-write audit row already recorded. */
+    actor: string;
+}
+export type IScheduleEmbeddingInput = (IScheduleEmbeddingBase & {
+    action: 'upsert';
+    content: string;
+}) | (IScheduleEmbeddingBase & {
+    action: 'delete';
+});
+/**
+ * Schedules the embed-or-delete round-trip and REGISTERS its promise with the
+ * per-adapter drain registry (`write/embed-drain.ts`), so a short-lived
+ * process can await it before `close()` instead of losing it. A true no-op
+ * (no registration, no audit row) when `handle.embedding` is unconfigured —
+ * see `IWriteStoreHandle.embedding`'s own doc comment.
+ *
+ * **Non-async wrapper, deliberately.** The body lives in
+ * {@link runEmbedRoundTrip} so this function can register the promise it
+ * creates and read its outcome without re-awaiting it. The returned promise
+ * is still `Promise<void>` and still never rejects, so every existing
+ * `await`/fire-and-forget call site is unchanged. Callers that omit
+ * `awaitEmbed` (the default) get fire-and-forget — the close-time drain is
+ * the backstop that makes it durable anyway.
+ *
+ * Must be called strictly AFTER the caller's own `executeWriteTransaction`
+ * has resolved (i.e. after the subject transaction committed) — never from
+ * inside a transaction closure. `create-issue.ts`/`update.ts`/`delete.ts`
+ * each call this exactly once (twice for `update`'s body-change path — see
+ * this module's own doc comment) outside their `executeWriteTransaction`
+ * callback, and either await the returned promise (`awaitEmbed:true`) or
+ * let it run fire-and-forget (the default).
+ */
+export declare function scheduleIssueEmbedding(handle: IWriteStoreHandle, input: IScheduleEmbeddingInput): Promise<void>;
+/**
+ * Records each still-unsettled embed as a durable `embedding_failed` audit
+ * row, BEFORE the store connection closes — the whole point of the bounded
+ * drain. Called by `graph-backlog-store.ts`'s `closeGraphBacklogStore` with
+ * the `stillPending` list from a timed-out drain.
+ *
+ * Per entry: one `executeWriteTransaction` + `writeAudit` with the
+ * {@link EMBED_DRAIN_TIMEOUT_NOTE}. An entry whose audit write throws lands in
+ * `unrecorded` (its outcome is not durably recorded anywhere) rather than
+ * failing the whole loop — the remaining entries still get their chance.
+ */
+export declare function recordUnsettledEmbedsAsFailed(handle: IWriteStoreHandle, pending: readonly IPendingEmbed[]): Promise<{
+    recorded: IPendingEmbed[];
+    unrecorded: IPendingEmbed[];
+}>;
+export {};