@adhd/backlog 0.1.8 → 1.0.0

package/markdown.d.ts

@@ -1,75 +0,0 @@
-import { BacklogFilter, BacklogItem, BacklogStatus, MalformedHeaderInfo, Priority } from './model.js';
-
-declare const LEGACY_TERMINAL_DONE: string[];
-declare const LEGACY_TERMINAL_WORKAROUND: string[];
-declare const LEGACY_TERMINAL_DISMISSED: string[];
-declare const LEGACY_TERMINAL: Set<string>;
-export declare function normalizeLegacyStatus(rawLabel: string): BacklogStatus;
-/**
- * Classify a free-form status string into a {label, open} pair — ported
- * verbatim from tools/util/backlog.mjs:56-82 (`classifyStatus`). Backlog
- * Status lines are prose, so an open signal must win over a closed word when
- * both are present.
- */
-export declare function classifyStatus(raw: string | undefined): {
-    label: string;
-    open: boolean;
-} | null;
-/** Ported verbatim from tools/util/backlog.mjs:84-96 (`detectStatus`). */
-export declare function detectStatus(headerLine: string, body: string): {
-    label: string;
-    open: boolean;
-};
-/** Ported verbatim from tools/util/backlog.mjs:98-104 (`detectPriority`). */
-export declare function detectPriority(headerLine: string, body: string): string;
-export interface ParsedMarkdownItem {
-    id: string;
-    kind: string;
-    family: string;
-    title: string;
-    level: number;
-    line: number;
-    headerLine: string;
-    status: string;
-    open: boolean;
-    terminal: boolean;
-    priority: string;
-    body: string;
-}
-export interface ParseWithDiagnosticsResult {
-    items: ParsedMarkdownItem[];
-    malformedHeaders: MalformedHeaderInfo[];
-}
-/** Ported (structure preserved) from tools/util/backlog.mjs:106-155 (`parse`). */
-export declare function parseBacklogMarkdown(text: string): ParsedMarkdownItem[];
-/**
- * Same parse as {@link parseBacklogMarkdown}, plus `malformedHeaders` — every
- * `##`/`###` line that looks like a corrupted/typo'd id header and was
- * dropped instead of parsed into an item (DEBT-BACKLOG-IMPORT-SILENT-DROP-001).
- * `importFromMarkdown` (client.ts) uses this to populate `ImportResult.malformedHeaders`.
- */
-export declare function parseBacklogMarkdownWithDiagnostics(text: string): ParseWithDiagnosticsResult;
-/**
- * SPEC.md §5.6 `renderToMarkdown` — one `###` block per item. Archived-item
- * exclusion (SPEC.md §5.4 `archiveResolved`'s "renderToMarkdown's default
- * view excludes them") happens one layer up, in `client.ts`'s
- * `renderToMarkdown`, which has access to the raw node `metadata.archivedAt`
- * flag — `BacklogItem` (SPEC.md §4.1) deliberately carries no `archivedAt`
- * field of its own, so this function (pure, no store access) cannot filter
- * on it and takes an already-filtered `items` array.
- */
-export declare function renderItemsToMarkdown(items: BacklogItem[]): string;
-/** Ported from tools/util/backlog.mjs:351-361 (`buildChangelogSection`). */
-export declare function buildChangelogSection(items: BacklogItem[], date: string): string;
-/** Applies the SAME filters `applyFilters`/`BacklogFilter` describes, used only for markdown-side symmetry checks in tests. */
-export declare function matchesFilter(item: ParsedMarkdownItem, filter: BacklogFilter): boolean;
-export interface ParsedImportItem {
-    humanId: string;
-    title: string;
-    body: string;
-    status: BacklogStatus;
-    priority?: Priority;
-}
-/** Bridges the legacy parser's raw shape into the canonical vocabulary (SPEC.md §5.6 `importFromMarkdown`). */
-export declare function toImportItems(parsed: ParsedMarkdownItem[]): ParsedImportItem[];
-export { LEGACY_TERMINAL, LEGACY_TERMINAL_DONE, LEGACY_TERMINAL_DISMISSED, LEGACY_TERMINAL_WORKAROUND };

package/migration-admin.d.ts

@@ -1,26 +0,0 @@
-import { MigrationPhase } from './model.js';
-import { BacklogConfig } from './env.js';
-import { Environment } from '@adhd/environment';
-
-/**
- * Mirrors `@adhd/environment-builder`'s own internal `roots.ts` global-root
- * formula (`~/.<orgNamespace>/<project>/<namespace>/config.yaml`) using ONLY
- * the public fields the `@adhd/environment` `Environment` instance exposes
- * (`orgNamespace`/`project`/`namespace`) — `@adhd/backlog` does not depend on
- * the internal `environment-builder` package directly, so this is a
- * deliberate, narrow re-derivation, not an import of a private module.
- * `adhdRootOverride` mirrors `EnvironmentOptions.adhdRoot`'s own test-isolation
- * escape hatch (see `BuildBacklogEnvOptions`) for tests that must never touch
- * the real machine-global `~/.adhd`.
- */
-export declare function globalConfigPath(env: Environment<BacklogConfig>, adhdRootOverride?: string): string;
-/**
- * Reads the existing global `config.yaml` (if any), deep-merges in
- * `migration.phase`, and writes it back — preserving every OTHER key already
- * in the file (e.g. a previously-set `db.busyTimeoutMs` override) rather than
- * clobbering the whole file. A missing or malformed existing file is treated
- * as empty (never fatal for a write), mirroring
- * `@adhd/environment-builder`'s own `readLayerFile` tolerance for a corrupt
- * layer. Returns the absolute path written, for caller confirmation.
- */
-export declare function writeMigrationPhase(env: Environment<BacklogConfig>, phase: MigrationPhase, adhdRootOverride?: string): string;

package/model.d.ts

@@ -1,437 +0,0 @@
-/**
- * model.ts — the `BacklogItem` domain shape and every operation-surface input
- * / output type. Ported verbatim from `SPEC.md` §4/§5. Pure types + a handful
- * of tiny, dependency-free classification helpers — no store/env imports.
- */
-export type BacklogStatus = 'OPEN' | 'IN_PROGRESS' | 'PARTIAL' | 'OUTSTANDING' | 'DEFERRED' | 'BLOCKED' | 'MIXED' | 'UNKNOWN' | 'FIXED' | 'RESOLVED' | 'DONE' | 'SHIPPED' | 'VERIFIED' | 'REMOVED' | 'MITIGATED' | 'SUPERSEDED' | 'INVALID' | 'DUPLICATE' | 'WONTFIX';
-/** §4.2 rule 3 — terminal-done + terminal-workaround: require ≥1 citation. */
-export declare const TERMINAL_DONE_STATUSES: ReadonlySet<BacklogStatus>;
-export declare const TERMINAL_WORKAROUND_STATUSES: ReadonlySet<BacklogStatus>;
-/** §4.2 rule 3 — terminal-dismissed: require a reason (citation optional). */
-export declare const TERMINAL_DISMISSED_STATUSES: ReadonlySet<BacklogStatus>;
-export declare const TERMINAL_STATUSES: ReadonlySet<BacklogStatus>;
-export declare function isTerminalStatus(status: BacklogStatus): boolean;
-/** §4.2 rule 3 — "a transition INTO any terminal status requires evidence." */
-export declare function requiresCitation(status: BacklogStatus): boolean;
-export declare function requiresReason(status: BacklogStatus): boolean;
-export type Priority = 'CRITICAL' | 'HIGH' | 'MEDIUM' | 'LOW';
-export interface Citation {
-    /** Repo-relative path, matching the global CLAUDE.md citation format. */
-    file: string;
-    /** e.g. "42-58"; omit for a whole-file citation. */
-    lines?: string;
-    /** Free text — active git context / agent name / model, per the citation format. */
-    context?: string;
-}
-export interface Note {
-    by: string;
-    at: string;
-    text: string;
-}
-export interface BacklogItem {
-    /** The graph node id (see DESIGN.md §2). Never exposed to markdown; internal only. */
-    nodeId: number;
-    /** Human-facing id, e.g. "BUG-APIGEN-014". Unique within (repo, family). */
-    humanId: string;
-    /** First hyphen segment of humanId, e.g. "BUG". Open vocabulary — not an enum. */
-    kind: string;
-    /** humanId with the trailing "-NNN" stripped, e.g. "BUG-APIGEN". */
-    family: string;
-    title: string;
-    /** Markdown body — the full entry text minus the header line. */
-    body: string;
-    status: BacklogStatus;
-    priority?: Priority;
-    /** Stable repo slug — see SPEC.md §3 "Repo identity". */
-    repo: string;
-    /** Package-relative path within the repo, e.g. "packages/apigen/apigen-core-client". Optional — repo-level items omit it. */
-    projectPath?: string;
-    /** Plan slug this item is attached to, if any — e.g. "agent-registry-schema". */
-    plan?: string;
-    /** Source markdown path this item was imported from, if any (DEBT-BACKLOG-IMPORT-PLAN-PROVENANCE-001). */
-    importedFrom?: string;
-    /** Durable ownership — who this item is assigned to (may differ from the active claimant). */
-    assignee?: string;
-    /** Ephemeral claim lease — see SPEC.md §5. */
-    claimedBy?: string;
-    claimedAt?: string;
-    citations: Citation[];
-    notes: Note[];
-    tags: string[];
-    createdAt: string;
-    updatedAt: string;
-}
-/**
- * BUG-BACKLOG-REPO-LOOKUP-UX-001: a `(repo, humanId)` miss is frequently NOT
- * "this item doesn't exist" but "this item exists under a DIFFERENT `repo`
- * string" (e.g. `"adhd"` vs `"PseudoSky/adhd"` both live in the same store
- * for what is logically one project). `foundInRepos` — populated by
- * `store/query.ts`'s `buildNotFoundError` helper, which every throw site now
- * calls instead of constructing this directly — carries the OTHER repo
- * value(s) the humanId actually lives under, so the thrown message names the
- * fix instead of leaving the caller to guess.
- */
-export declare class BacklogItemNotFoundError extends Error {
-    readonly foundInRepos: string[];
-    constructor(repo: string, humanId: string, foundInRepos?: string[]);
-}
-export declare class CitationRequiredError extends Error {
-    constructor(status: BacklogStatus);
-}
-export declare class ReasonRequiredError extends Error {
-    constructor(status: BacklogStatus);
-}
-export declare class ClaimHeldError extends Error {
-    readonly heldBy: string;
-    readonly heldSince: string;
-    constructor(heldBy: string, heldSince: string);
-}
-export declare class DependencyCycleError extends Error {
-    readonly cycle: string[];
-    constructor(cycle: string[]);
-}
-/**
- * BUG-BACKLOG-HUMANID-COLLISION-001 (fix #1 — write-time guard):
- * `createItemNode` rejects a `family` that is missing/empty/whitespace-only
- * UNLESS `idOverride` is also given (SPEC.md §5.1's `CreateItemInput.family`
- * contract: "required unless idOverride given"). Thrown BEFORE
- * `allocateHumanIdAndInsert`/`computeNextHumanId` ever run, so a caller that
- * omits `family` (previously silently coerced to the literal string
- * `"undefined"` by `computeNextHumanId`'s template literal, producing
- * `humanId: "undefined-001"` and colliding with every other item that hit
- * the same bug) now fails loudly instead of minting a collision. This is
- * defense in depth: it must hold regardless of whether an upstream caller's
- * own input-schema validation (e.g. apigen-core-client's extracted
- * `CreateItemInput` schema, BUG-APIGEN-CORE-CLIENT-001) enforces `family` as
- * required — the store's own write path must never trust the caller alone.
- */
-export declare class InvalidArgumentError extends Error {
-    readonly argument: string;
-    constructor(argument: string, message: string);
-}
-/**
- * BUG-BACKLOG-HUMANID-COLLISION-001 (fix #2 — read-time guard): every
- * `(repo, humanId)`-keyed lookup used to silently resolve to "whichever
- * live node is found first" when more than one live node shared the same
- * key (the exact shape of the pre-existing `"undefined-001"` collisions,
- * and the root cause of a real mis-transition this session — see the
- * backlog item's body). Any lookup that finds >1 live match now throws this
- * instead of guessing, listing every colliding `nodeId` so a caller can
- * disambiguate (there is no tool-level nodeId-addressed path yet — the
- * caller must go through the store's own repair primitives, e.g.
- * `renameHumanId`, to resolve the collision).
- */
-export declare class AmbiguousHumanIdError extends Error {
-    readonly nodeIds: number[];
-    constructor(repo: string, humanId: string, nodeIds: number[]);
-}
-export interface DedupeScanInput {
-    symbol?: string;
-    path?: string;
-    errorText?: string;
-}
-export interface CreateItemInput {
-    family: string;
-    idOverride?: string;
-    title: string;
-    body: string;
-    repo: string;
-    projectPath?: string;
-    priority?: Priority;
-    tags?: string[];
-    plan?: string;
-    /** Source markdown path this item is being imported from, if any (DEBT-BACKLOG-IMPORT-PLAN-PROVENANCE-001). */
-    importedFrom?: string;
-    dedupeScan?: DedupeScanInput;
-    /** Skip the dedupe gate and file anyway (planner override after reviewing candidates). */
-    force?: boolean;
-    /**
-     * Citations to attach at creation time (BUG-BACKLOG-CREATE-ITEM-DROPS-CITATIONS-001).
-     * Previously absent from this interface entirely — a caller passing
-     * `citations` on create got a success response with the item created and
-     * the citations silently discarded (no such field existed to carry them
-     * through). Validated the same way as every other citation write path
-     * (`Citation.file` non-empty — see `lifecycle.ts`'s `assertValidCitation`)
-     * and rejected as a whole (no partial write) before allocation runs.
-     */
-    citations?: Citation[];
-}
-export interface CreateItemResult {
-    item: BacklogItem;
-    created: boolean;
-    duplicateCandidates: BacklogItem[];
-    /**
-     * BUG-BACKLOG-REPO-LOOKUP-UX-001: set (soft warning, never blocks the
-     * write) when `input.repo` doesn't match any repo value already known to
-     * this store — a likely typo/inconsistent-repo-string drift (e.g. filing
-     * under `"adhd"` when every existing item uses `"PseudoSky/adhd"`) rather
-     * than a genuine first-time-use of a new repo, which is always allowed.
-     */
-    repoWarning?: string;
-}
-export interface UpdateItemInput {
-    title?: string;
-    body?: string;
-    tags?: string[];
-    projectPath?: string;
-    /**
-     * Provenance owner of this item (the source-file path that authored it).
-     * Only ever set to BACKFILL a legacy row whose `importedFrom` was never
-     * stamped (created before the provenance field existed) — see
-     * `importFromMarkdown`'s owning-import branch. An already-stamped owner is
-     * immutable and must never be reassigned via this patch.
-     */
-    importedFrom?: string;
-}
-export interface BacklogFilter {
-    repo?: string;
-    projectPath?: string;
-    status?: BacklogStatus | 'open' | 'closed';
-    kind?: string;
-    family?: string;
-    priority?: Priority;
-    plan?: string;
-    assignee?: string;
-    claimedBy?: string;
-    tags?: string[];
-    grep?: string;
-    /**
-     * Exact-match on `BacklogItem.importedFrom` — the sourcePath that OWNS an
-     * item's canonical content (DEBT-BACKLOG-IMPORT-SCOPE-CROSSFILE-001).
-     * Needed for a root-level `BACKLOG.md` projection: filtering by bare
-     * `{repo}` alone would also surface every item cross-referenced FROM root
-     * by a plan/package file (which correctly carries a `plan`/`projectPath`
-     * of its own once ownership-gating lands) — `importedFrom` is the only
-     * field that reliably answers "does THIS file own this item's content",
-     * independent of which OTHER files also cite the same id.
-     */
-    importedFrom?: string;
-    /**
-     * Repo-level projection selector (MIGRATION.md §2.2 "root BACKLOG.md =
-     * repo-only, no projectPath/plan"). When true, returns only items that carry
-     * NEITHER a `projectPath` NOR a `plan` — i.e. items owned by the repo root
-     * rather than a package or plan projection. Unlike the `importedFrom`
-     * workaround it does not depend on provenance, so a freshly tool-created
-     * repo-level item (which has no `importedFrom`) still appears in the root
-     * projection — the Phase-3 DoD ("a fresh create-item appears in the
-     * regenerated BACKLOG.md") requires this. Cross-referenced items that carry a
-     * `plan`/`projectPath` render in that plan/package projection instead, never
-     * duplicated into root.
-     */
-    rootLevel?: boolean;
-    /**
-     * Drops items with `metadata.archivedAt` set (BACKLOG-adoption's
-     * `archiveResolved` — SPEC.md §5.4). `renderToMarkdown` always applies
-     * this internally (a markdown projection never shows archived rows), but
-     * `listItems`/`queryItemNodes` do NOT default to it — auditing/reporting
-     * consumers legitimately need to see archived items too. A caller that
-     * needs to reproduce `renderToMarkdown`'s exact item set through
-     * `listItems` (e.g. `render-projections.mjs`/`parity-check.mjs` verifying
-     * a rendered projection against the graph's own view of the same filter —
-     * BUG-BACKLOG-RENDER-VERIFY-ARCHIVED-MISMATCH-001) must set this
-     * explicitly; otherwise the two queries diverge on every archived row.
-     */
-    excludeArchived?: boolean;
-    limit?: number;
-    offset?: number;
-}
-export interface StatsScope {
-    repo?: string;
-    projectPath?: string;
-}
-export interface BacklogStats {
-    total: number;
-    open: number;
-    closed: number;
-    byStatus: Record<string, number>;
-    byKind: Record<string, number>;
-    byFamily: Record<string, number>;
-    byPriority: Record<string, number>;
-    byRepo: Record<string, number>;
-}
-export interface DependencyGraph {
-    nodes: Array<{
-        humanId: string;
-        title: string;
-        status: BacklogStatus;
-    }>;
-    edges: Array<{
-        from: string;
-        to: string;
-        rel: 'DEPENDS_ON' | 'RELATES_TO' | 'PART_OF';
-    }>;
-}
-export type TopoOrderResult = {
-    ok: true;
-    order: string[];
-} | {
-    ok: false;
-    cycle: string[];
-};
-export interface ClaimOpts {
-    /** Minutes after which an unrenewed claim is considered abandoned. Default: 30 (DESIGN.md §4.2). */
-    staleAfterMin?: number;
-    /** Explicitly override a claim that is NOT stale (human-confirmed abandonment). */
-    force?: boolean;
-}
-export type ClaimStatus = 'claimed' | 'renewed' | 'reclaimed-stale' | 'held';
-export interface ClaimResult {
-    status: ClaimStatus;
-    claimedBy: string;
-    claimedAt: string;
-    /** Only present when status === 'held'. */
-    heldBy?: string;
-    heldSince?: string;
-    /** Only present when status === 'reclaimed-stale' — the abandoned claimant, for audit. */
-    previousClaimant?: string;
-}
-export interface ReleaseResult {
-    status: 'released' | 'release-noop';
-    wasClaimedBy?: string;
-}
-export interface TransitionOpts {
-    by: string;
-    note?: string;
-    citations?: Citation[];
-    reason?: string;
-}
-export interface ArchiveOpts {
-    /** Exclude specific humanIds from the sweep even though they're terminal (mirrors tools/util/backlog.mjs's --exclude). */
-    exclude?: string[];
-}
-export interface ArchiveResult {
-    archivedCount: number;
-    changelogMarkdown: string;
-}
-export interface ImportMarkdownInput {
-    path: string;
-    repo: string;
-    projectPath?: string;
-    /** Plan slug to attach every imported item to (DEBT-BACKLOG-IMPORT-PLAN-PROVENANCE-001) — replaces the post-import attachToPlan-per-id workaround. */
-    plan?: string;
-    /**
-     * Provenance path recorded on each imported node's `importedFrom` field
-     * (DEBT-BACKLOG-IMPORT-PLAN-PROVENANCE-001). Defaults to `path` when
-     * omitted — the file actually read IS the source, so a caller only needs
-     * to set this explicitly when it differs (e.g. importing from a scratch
-     * copy but wanting the ORIGINAL path recorded).
-     */
-    sourcePath?: string;
-    dryRun?: boolean;
-}
-/** A `##`/`###` header line that failed the strict `HEADER_RE` id pattern but looks like an attempted id (DEBT-BACKLOG-IMPORT-SILENT-DROP-001). */
-export interface MalformedHeaderInfo {
-    /** 1-based line number in the source file. */
-    line: number;
-    headerLine: string;
-}
-export interface ImportResult {
-    parsed: number;
-    created: number;
-    skippedDuplicates: number;
-    /**
-     * Of `skippedDuplicates` (an already-existing humanId), how many had a
-     * title/body/priority/status that DIFFERED from the graph's current copy
-     * and were refreshed to match the re-imported source
-     * (BUG-BACKLOG-IMPORT-INSERT-ONLY-NO-UPDATE-001 — re-importing used to be
-     * pure insert-only: a status/content change made directly in a
-     * `BACKLOG.md` file after the first import was silently never reflected
-     * in the graph on a later re-import). An unchanged existing item is a
-     * true no-op — never counted here.
-     */
-    updated: number;
-    errors: Array<{
-        humanId: string;
-        message: string;
-    }>;
-    /** Headers that look like a corrupted/typo'd id and were dropped instead of parsed — never silent (DEBT-BACKLOG-IMPORT-SILENT-DROP-001). */
-    malformedHeaders: MalformedHeaderInfo[];
-    /** See `CreateItemResult.repoWarning` (BUG-BACKLOG-REPO-LOOKUP-UX-001) — computed once for `input.repo`, not per item. */
-    repoWarning?: string;
-}
-export interface AuditTrailEntry {
-    at: string;
-    kind: 'created' | 'transition' | 'claim' | 'note' | 'citation' | 'supersession';
-    detail: Record<string, unknown>;
-}
-export interface AuditTrailResult {
-    humanId: string;
-    history: AuditTrailEntry[];
-    supersessionChain?: {
-        supersedes?: string;
-        supersededBy?: string;
-    };
-}
-export type MigrationPhase = 'not-started' | 'phase-1' | 'phase-2' | 'phase-3' | 'phase-4' | 'phase-5' | 'complete';
-export interface MigrationStatusResult {
-    phase: MigrationPhase;
-    /** One-line human-readable meaning of `phase`, e.g. "phase-2: BACKLOG.md is still authoritative; the tool is shadow-running in parity-check mode." */
-    description: string;
-    /** True once the graph (not hand-edited markdown) is authoritative — phase-3 and later. */
-    toolIsAuthoritative: boolean;
-}
-/** `setMigrationPhase`'s result — `MigrationStatusResult` plus the absolute
- *  path of the GLOBAL `config.yaml` the new phase was persisted to (so a
- *  caller can confirm this was a durable, cross-process write, not merely an
- *  in-memory value). */
-export interface SetMigrationPhaseResult extends MigrationStatusResult {
-    configPath: string;
-}
-/** One item's move within a `RepoMigrationPlan` — always dry-runnable, never mutates on its own. */
-export interface RepoMigrationPlanItem {
-    nodeId: number;
-    /** The humanId this item currently carries in `fromRepo`. */
-    humanId: string;
-    /**
-     * The humanId this item will carry in `toRepo` — identical to `humanId`
-     * unless `renamed` is true. Deterministic: preserves the item's `family`
-     * prefix and picks the next free number in that family within `toRepo`
-     * (mirrors `computeNextHumanId`'s own `max + 1` allocation rule), scanning
-     * BOTH `toRepo`'s pre-existing items AND every earlier item in this same
-     * plan already assigned a number in that family — so two colliding items
-     * sharing a family (e.g. two different `BUG-001`s) never collide with each
-     * other's rename target either.
-     */
-    targetHumanId: string;
-    /** True iff `humanId` already exists as a LIVE item in `toRepo` and had to be renamed to avoid an id collision. */
-    renamed: boolean;
-    title: string;
-    status: BacklogStatus;
-}
-/**
- * The full, deterministic plan for moving every live item out of `fromRepo`
- * into `toRepo` — computed by a pure read-only scan (`planRepoMigration`),
- * safe to call repeatedly and to inspect before ever mutating anything.
- */
-export interface RepoMigrationPlan {
-    fromRepo: string;
-    toRepo: string;
-    items: RepoMigrationPlanItem[];
-    /** Count of `items` where `renamed === true` — the collision count. */
-    collisionCount: number;
-}
-/** Per-item outcome of actually executing a `RepoMigrationPlan`. Every planned item gets exactly one of these — nothing is ever silently dropped. */
-export interface RepoMigrationItemResult {
-    nodeId: number;
-    fromHumanId: string;
-    toHumanId: string;
-    renamed: boolean;
-    ok: boolean;
-    /** Present iff `ok === false` — the item was left untouched in `fromRepo`, never partially moved. */
-    error?: string;
-}
-/**
- * `migrateRepo`'s result. When `dryRun` is true (the default — a caller must
- * pass `dryRun:false` explicitly to mutate anything), `results` is absent and
- * NOTHING was written; `plan` alone previews exactly what would happen.
- */
-export interface RepoMigrationResult {
-    fromRepo: string;
-    toRepo: string;
-    dryRun: boolean;
-    plan: RepoMigrationPlan;
-    /** Present only when `dryRun === false`. One entry per `plan.items` entry, same order. */
-    results?: RepoMigrationItemResult[];
-    succeeded?: number;
-    failed?: number;
-}

package/store/audit-log.d.ts

@@ -1,16 +0,0 @@
-import { GraphBacklogStore } from './graph-backlog-store.js';
-import { AuditTrailEntry } from '../model.js';
-
-export declare const BACKLOG_AUDIT_EVENT_TAG = "backlog-audit-event";
-/**
- * Records one `transition`/`claim` event for the item at `itemNodeId`.
- * `content` is a uniqueness-marker string (mirrors `buildNodeContent()`'s
- * own reasoning, `mapping.ts`) — `@adhd/sox-graph-store`'s global
- * content-hash dedup would otherwise be free to collapse two
- * byte-identical events (e.g. two items independently transitioning
- * `OPEN`→`IN_PROGRESS` with no `by`/`reason` at all) into ONE node.
- */
-export declare function writeAuditEvent(store: GraphBacklogStore, itemNodeId: number, repo: string, humanId: string, kind: AuditTrailEntry['kind'], detail: Record<string, unknown>): Promise<void>;
-/** Every persisted event for `itemNodeId`, oldest first — ready to merge
- *  straight into `auditTrail()`'s `history` array. */
-export declare function queryAuditEvents(store: GraphBacklogStore, itemNodeId: number): Promise<AuditTrailEntry[]>;

package/store/claim.d.ts

@@ -1,24 +0,0 @@
-import { GraphBacklogStore } from './graph-backlog-store.js';
-import { ClaimOpts, ClaimResult, ReleaseResult } from '../model.js';
-
-/** DESIGN.md §4.2 — matches STALE_CLAIM_S = 30*60 at state-transition.js:601. */
-export declare const DEFAULT_STALE_AFTER_MIN = 30;
-export declare class ClaimContentionError extends Error {
-    readonly heldBy: string;
-    constructor(heldBy: string, by: string);
-}
-/**
- * DESIGN.md §4.2 — the exact branch table:
- *   unclaimed                              -> claimed
- *   by === claimedBy                       -> renewed (no contention check, ever)
- *   by !== claimedBy, age <= staleAfterMin -> held (refuse, no write)
- *   by !== claimedBy, age >  staleAfterMin -> reclaimed-stale
- *   by !== claimedBy, opts.force           -> proceeds anyway (reclaimed-stale-shaped)
- */
-export declare function claimItemNode(store: GraphBacklogStore, nodeId: number, by: string, opts?: ClaimOpts): Promise<ClaimResult>;
-/** SPEC.md §5.3 — "always succeeds (bumps claimedAt), no contention check, ever." */
-export declare function renewClaimNode(store: GraphBacklogStore, nodeId: number, by: string): Promise<ClaimResult>;
-/** DESIGN.md §4.2 — releasing an already-unclaimed item is a no-op, never an error. */
-export declare function releaseClaimNode(store: GraphBacklogStore, nodeId: number, by: string, opts?: {
-    force?: boolean;
-}): Promise<ReleaseResult>;

package/store/crud.d.ts

@@ -1,62 +0,0 @@
-import { GraphBacklogStore } from './graph-backlog-store.js';
-import { BacklogItem, CreateItemInput, CreateItemResult, UpdateItemInput } from '../model.js';
-
-/**
- * Minimum fraction of the NEW item's meaningful title tokens that must also
- * appear in a CANDIDATE's title for the candidate to count as a duplicate
- * (BUG-BACKLOG-DEDUPE-FTS-WEAK-MATCH-001). Exported so callers/tests can
- * tune it without touching this file's internals.
- *
- * Why title-to-title overlap instead of the FTS hit's bm25 `score`:
- * `store.graph.searchNodes()` (`@adhd/sox-graph-store`) DOES return a
- * per-hit `score` (`-fts_node.rank`, i.e. a positive, higher-is-better bm25
- * score) — but bm25 is corpus- and document-length-relative, not an absolute
- * similarity measure, and empirically it does NOT discriminate this bug's
- * failure mode: a live probe reproducing the exact reported case (a short
- * generic new title vs. a long, verbose, unrelated document that happens to
- * repeat a couple of the new title's common words many times) scored
- * `~0.0000109`, while a genuine short-title-vs-short-title near-duplicate
- * scored `~0.0000113` — the SAME order of magnitude, with no clean
- * separating threshold between them. A long document's sheer token count
- * inflates its bm25 term-frequency component enough to rival a real
- * duplicate's score. Title-to-title token overlap has no such document-
- * length confound: a new item's title can only ever match against a
- * candidate's (typically similarly short) title, so incidental repetition
- * buried in a long candidate BODY can no longer count toward "looks like a
- * duplicate" at all.
- *
- * 0.5 (at least half the new title's meaningful tokens must recur in the
- * candidate's title) was chosen because DESIGN.md §2.4's own worked example
- * ("same bug, different words") is a near-total title rewrite that still
- * shares most of its content words ("database connection pool leaks under
- * load" -> "the database connection pool leaks under load" is 6/6); dropping
- * to a small minority match (e.g. 1-2 shared generic words out of 5) is
- * exactly the false-positive shape this bug reports and must NOT pass.
- */
-export declare const TITLE_OVERLAP_MIN_FRACTION = 0.5;
-declare function dedupeScan(store: GraphBacklogStore, repo: string, input: CreateItemInput): Promise<BacklogItem[]>;
-export declare function createItemNode(store: GraphBacklogStore, input: CreateItemInput): Promise<CreateItemResult>;
-export declare function getItemNode(store: GraphBacklogStore, repo: string, humanId: string): Promise<BacklogItem | null>;
-/**
- * DEVIATION (mitigated — DEBT-BACKLOG-CONTENT-IMMUTABLE-001): `@adhd/sox-graph-store`
- * exposes no PUBLIC primitive to update a node's `content` column after
- * creation (`touch()`'s `Partial<NodeMeta>` covers
- * name/summary/topic/tags/importance/confidence/tExpires/metadata — never
- * `content`; verified against the real source). `title` updates the `summary`
- * column (source of truth for the API) AND `metadata.title`; `body` updates
- * `metadata.body` (source of truth for the API). Below, a title/body change
- * ALSO re-synchronizes the FTS-indexed `content`/`content_hash` columns
- * directly via `adapter.executeRun` on the store-owned `adapter` handle —
- * the same DESIGN.md §14-sanctioned escape hatch `structure.ts`'s
- * `removeDependencyNode` already uses for the one other gap (`edge`
- * deletion) the `GraphBackend` API lacks, now routed through the store-
- * adapter's query surface (F-01/F-02: the raw `store.db` handle is gone).
- * This is safe specifically because `fts_node_au` (the real schema's `AFTER
- * UPDATE ON node` trigger — `~/dev/ai/sox-ecosystem/libs/data/graph/graph-store/
- * src/index.ts`'s `FTS_TRIGGERS`) re-indexes `fts_node` automatically on
- * ANY write to `node.content`/`name`/`summary`, so no separate FTS statement
- * is needed here.
- */
-export declare function updateItemNode(store: GraphBacklogStore, repo: string, humanId: string, patch: UpdateItemInput): Promise<BacklogItem>;
-export declare function softDeleteItemNode(store: GraphBacklogStore, repo: string, humanId: string, reason: string): Promise<void>;
-export { dedupeScan };

package/store/ids.d.ts

@@ -1,24 +0,0 @@
-import { GraphBacklogStore } from './graph-backlog-store.js';
-import { NodeRecord } from '@adhd/sox-graph-store';
-
-/**
- * Resolves the humanId to insert under (either `idOverride`, re-verified for
- * an already-live node, or the next auto-allocated `family-NNN`) and invokes
- * `insert(humanId, existing)` — ALL inside one retried `.immediate()`
- * transaction, so no other concurrent `.immediate()`-wrapped write can
- * interleave between "the id was resolved" and "a node claiming it landed".
- * `existing` is the already-live node under `idOverride` (re-checked HERE,
- * not just by an earlier, racy caller-side check) — `insert` is expected to
- * short-circuit on a non-null `existing` exactly like `createItemNode`'s
- * documented idempotent-reimport behavior, but now race-free.
- */
-export declare function allocateHumanIdAndInsert<T>(store: GraphBacklogStore, repo: string, family: string, idOverride: string | undefined, insert: (humanId: string, existing: NodeRecord | null) => T): Promise<T>;
-/**
- * @deprecated kept ONLY as a standalone id-generator for any caller that does
- * not need an atomic insert alongside it. `createItemNode`/
- * `supersedeItemNode` no longer use this (see `allocateHumanIdAndInsert`'s
- * doc comment for why splitting allocate-then-insert-later is unsafe under
- * concurrency). Still correct in isolation — just NOT TOCTOU-safe when the
- * caller's own insert happens in a separate, later transaction.
- */
-export declare function allocateHumanId(store: GraphBacklogStore, repo: string, family: string): Promise<string>;