@adhd/backlog 1.0.3 → 1.0.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adhd/backlog",
-  "version": "1.0.3",
+  "version": "1.0.4",
   "bin": {
     "adhd-backlog": "index.js"
   },

package/write/catalog.d.ts

@@ -73,21 +73,32 @@ export interface IMintOrResolveInput {
  * that reads as non-terminal — the drift `catalog-repair.ts` exists to clean
  * up is not regenerated on the next mint.
  *
- * Membership is EXACT and case-sensitive — the same predicate the `(kind,name)`
- * lookup uses (`WHERE name = ?`). A case-variant (`Closed`) is deliberately
- * NOT a member: it is an exact miss, self-heals into its own row (never a
- * throw), and is left to the separately-owned case-fragment repair, which
- * folds names. Spelling the canonical rows here is what pins them; there is
- * exactly ONE such table in the codebase (`catalog-repair.ts` re-exports
- * this set rather than declaring its own).
+ * Membership is decided on the FOLDED name ({@link catalogNameFold}) — the
+ * same Unicode fold the duplicate guard and the case-fragment repair use, never
+ * SQL `lower()`/`NOCASE`, which fold only ASCII `A`–`Z`. The spellings below
+ * are the canonical catalog rows, but the PREDICATE folds, so `Closed`,
+ * `fixed`, `resolved` and `done` all count as reserved. This matters because a
+ * first-ever lowercase `fixed`/`resolved`/`done` has no uppercase row to
+ * collide against; under an exact-case predicate it would seed
+ * `terminal:false` — a closed status the read layer returns as open (backlog
+ * b4525bc3 / d7ec2c50). There is exactly ONE such table in the codebase
+ * (`catalog-repair.ts` re-exports this set rather than declaring its own).
  */
 export declare const RESERVED_TERMINAL_STATUS_NAMES: ReadonlySet<string>;
-/** Whether `name` is EXACTLY one of {@link RESERVED_TERMINAL_STATUS_NAMES} — case-sensitive, the same predicate the `(kind,name)` resolve uses. */
+/** Whether `name` is one of {@link RESERVED_TERMINAL_STATUS_NAMES} under the case fold — so any spelling of the reserved terminal vocabulary (`closed`/`Closed`/`CLOSED`, `fixed`/`FIXED`) counts. */
 export declare function isReservedTerminalStatusName(name: string): boolean;
 /**
  * The flat-catalog find-then-create (§1, §4c, §6.1): `kind`/`status`/
  * `priority`/`agent` are mintable on an unresolved NAME; a uid-shaped `ref`
  * that does not resolve instead throws — minting NEVER applies to a uid.
+ *
+ * A NAME that case-folds to an EXISTING LIVE row of the same kind but is
+ * spelled differently (`IN_PROGRESS` when `in_progress` is live) is REFUSED
+ * with {@link CaseVariantNameError} — never fold-resolved onto the existing
+ * row, never minted as a twin. Identity is exact-case (`WHERE name = ?`), so a
+ * variant is neither the same row nor a genuinely new name; it is ambiguous,
+ * and the ambiguity is stopped here rather than allowed to grow a duplicate
+ * the catalog-invariant guard would then abort every read over.
  */
 export declare function mintOrResolveCatalogTx(tx: AdapterTransaction, input: IMintOrResolveInput): Promise<IResolvedCatalogRow>;
 /**
@@ -108,9 +119,10 @@ export declare function mintOrResolveCatalogTx(tx: AdapterTransaction, input: IM
  * exact `(kind,name)` lookup inside {@link mintOrResolveCatalogTx} finds the
  * seeded row on every subsequent call, so reseeding never duplicates — the
  * store converges to one live `status` row per name. A case-variant name
- * (`Closed` vs a seeded `closed`) is an exact miss, so it self-heals into its
- * own row rather than throwing — the pre-existing resolution property, not a
- * terminality decision (the case-fragment repair folds those separately).
+ * (`Closed` vs a seeded `closed`) is REFUSED by {@link mintOrResolveCatalogTx}
+ * with {@link CaseVariantNameError} rather than folded onto the existing row or
+ * minted as a twin — the same exact-case stop every other flat catalog takes
+ * (see that function's doc comment).
  *
  * A uid-shaped `ref` that does not resolve still throws
  * `CatalogNotFoundError` — minting never applies to a uid (§6.1).

package/write/errors.d.ts

@@ -18,7 +18,7 @@
  * All named classes here are `E_VALIDATION`- or `E_CONSTRAINT`-class
  * members of the same union (SPEC.md §4c, "Two failure-signaling shapes,
  * reconciled into one contract") — `IssueNotFoundError`, `InvalidArgumentError`,
- * `CatalogNotFoundError`, `ClaimHeldError`, `SingleValuedRelationConflictError`,
+ * `CatalogNotFoundError`, `CaseVariantNameError`, `ClaimHeldError`, `SingleValuedRelationConflictError`,
  * `NoteRequiredError`, `CitationRequiredError`, `CitationUnverifiableError` are
  * `E_VALIDATION` (never retryable — thrown before any driver call runs);
  * `StaleSupersedeError` is the one deliberate `E_CONSTRAINT` this spec's own
@@ -162,6 +162,42 @@ export declare class CatalogNotFoundError extends BacklogWriteError {
     readonly retryable = false;
     constructor(catalogKind: string, ref: 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
+ * `HIGH`). Catalog identity is EXACT-case (`DATA_MODEL.md:70-78`; the
+ * `(kind, name)` resolve in `write/catalog.ts` is `WHERE name = ?`), so the
+ * write path REFUSES the variant rather than fold-resolving it onto the
+ * existing row or minting a twin. Accepting it would grow a second live row
+ * that case-folds to the first — the case-fragment defect the uniqueness guard
+ * (`store/catalog-invariant-guard.ts`) exists to catch, which is exactly how
+ * the store wedged (BUG: a mixed-case write minted a twin, then the guard
+ * refused every read).
+ *
+ * The message names BOTH spellings and tells the caller which one to use: the
+ * one already live. The ambiguity is stopped here, at the single write call
+ * site, instead of aborting every read.
+ *
+ * `E_VALIDATION`, never retryable — this is a before-any-mint decision, so
+ * retrying the identical payload fails identically.
+ */
+export declare class CaseVariantNameError extends BacklogWriteError {
+    /** The flat-catalog kind (`status`, `priority`, `kind`, `agent`). */
+    readonly catalogKind: string;
+    /** The name of the row ALREADY LIVE for this kind — the spelling to use. */
+    readonly canonicalName: string;
+    /** The differing name the caller supplied — the spelling that was refused. */
+    readonly offendingName: string;
+    readonly code: "E_VALIDATION";
+    readonly retryable = false;
+    constructor(
+    /** The flat-catalog kind (`status`, `priority`, `kind`, `agent`). */
+    catalogKind: string, 
+    /** The name of the row ALREADY LIVE for this kind — the spelling to use. */
+    canonicalName: string, 
+    /** The differing name the caller supplied — the spelling that was refused. */
+    offendingName: string);
+}
 /** A caller-supplied argument is missing, blank, or fails a project-declared invariant. */
 export declare class InvalidArgumentError extends BacklogWriteError {
     readonly field: string;