@cleocode/core 2026.6.5 → 2026.6.6

package/dist/store/exodus/column-transforms.d.ts

@@ -0,0 +1,248 @@
+/**
+ * Shared column-value transform layer for the exodus migration.
+ *
+ * The exodus copy (`migrate.ts`) does not move source values byte-for-byte into
+ * the consolidated `cleo.db`: a handful of columns are TRANSFORMED on the way in
+ * so they satisfy the consolidated schema's CHECK constraints (which the legacy
+ * runtime DBs did not carry). Three transform classes exist:
+ *
+ *   1. **Epoch INTEGER → ISO-8601 TEXT** ({@link buildEpochToIsoExpr}) — for any
+ *      target column carrying an ISO-GLOB CHECK ({@link detectIsoGlobColumns}).
+ *      A per-row magnitude heuristic ({@link EPOCH_SECONDS_THRESHOLD}) classifies
+ *      seconds vs milliseconds.
+ *   2. **Legacy enum → canonical member** ({@link ENUM_NORMALIZATIONS} +
+ *      {@link enumNormExpr}) — maps pre-tightening enum aliases (e.g.
+ *      `tasks_commits.conventional_type` `'style'`/`'merge'` → `'chore'`).
+ *   3. **Non-finite REAL → finite** ({@link NUMERIC_CLAMPS} +
+ *      {@link numericClampExpr}) — `Inf`/`-Inf`/`NaN` → a finite in-range value
+ *      (`brain_weight_history.delta_weight`).
+ *
+ * ## Why this module exists (T11809 · AC2)
+ *
+ * Before T11809 these transforms lived ONLY in `migrate.ts`. The parity verifier
+ * (`verify-migration.ts`) digested RAW source values against the TRANSFORMED
+ * target values, so every coerced column (epoch INTEGER vs ISO TEXT, legacy enum
+ * vs canonical, Inf vs clamped) produced a `hashMatch === false` even on a
+ * perfectly lossless migration — a false-negative that aborted the cutover and
+ * lost the batch writes accumulated during the migrating open.
+ *
+ * Extracting the transform logic into ONE shared module lets the verifier digest
+ * the SOURCE side **through the same transforms migrate applied**
+ * ({@link buildDigestExpr}), so equal logical data digests equal. `migrate.ts`
+ * re-imports these primitives so its copy behaviour stays byte-identical; the
+ * verifier imports {@link buildDigestExpr} for the digest-oriented variant.
+ *
+ * @task T11809 (exodus verify applies source-side coercion — hashMatch on equal data)
+ * @task T11546 (epoch→ISO coercion — original)
+ * @task T11547 (enum normalization — original)
+ * @task T11782 (non-finite numeric clamp — original)
+ * @epic T11249 (E6)
+ * @saga T11242
+ */
+import type { DatabaseSync } from 'node:sqlite';
+/**
+ * Determine a safe SQL literal default for a NOT NULL column with no schema
+ * default, given its SQLite type affinity.
+ *
+ * Used by `migrate.ts` to coalesce NULL source values for target-only NOT NULL
+ * columns so that rows are not silently dropped by `INSERT OR IGNORE` when a
+ * source value is NULL (T11533 ROOT CAUSE 2 fix).
+ *
+ * @param colType - Raw `type` string from `PRAGMA table_info` (e.g. `"INTEGER"`,
+ *   `"TEXT"`, `"REAL"`, `"BLOB"`, or compound forms like `"text NOT NULL"`).
+ * @returns A SQL literal string suitable for embedding in a `COALESCE()` call.
+ */
+export declare function typeDefaultLiteral(colType: string): string;
+/**
+ * Function shape for an enum-normalization rule: given the `srcRef` SQL
+ * expression for a column, return a SQL expression that produces the canonical
+ * value.
+ */
+export type NormalizeFn = (srcRef: string) => string;
+/**
+ * Per-(targetTable, column) normalization rules that map legacy enum values to
+ * the canonical enum accepted by the consolidated schema CHECK constraints.
+ *
+ * Each entry is a function that, given the `srcRef` SQL expression for the
+ * column, returns a SQL CASE expression that produces the canonical value.
+ * Rows with already-canonical values pass through unchanged (the ELSE branch).
+ *
+ * ## Brain enum normalizations REMOVED (T11647)
+ *
+ * The brain memory family no longer participates in enum normalization. Its
+ * consolidated exodus target now matches the LEGACY RUNTIME shape, which carries
+ * NO SQL CHECK constraints (the `text({ enum })` unions are enforced at the
+ * application layer only). With no CHECK to satisfy, coercing brain enum values
+ * would be data corruption, not a fix — so every brain enum value is copied
+ * VERBATIM. The historical brain rules (`brain_observations.{source_type,type}`,
+ * `brain_decisions.{confirmation_state,decision_category,confidence,outcome,
+ * decided_by}`) were deleted. The TASKS-domain rules below remain because those
+ * consolidated tables keep their CHECK constraints.
+ *
+ * ## nexus/signaldock enum-drift audit (T11809 · AC1)
+ *
+ * A real-data audit of `nexus.db` (106 MB) and `signaldock.db` (280 KB) against
+ * the consolidated CHECK enums found ZERO out-of-enum values for every
+ * CHECK-constrained column that has source data: `nexus_nodes.kind` (24,482
+ * rows), `nexus_relations.type` (39,163 rows), `nexus_contracts.type` (0 rows),
+ * `nexus_sigils.role` (8 rows), `agent_registry_agents.status` (19 rows),
+ * `agent_registry_users.role` (0 rows). No new normalization entry was required.
+ * The reported "nexus/signaldock drop rows" symptom was in fact the AC2 verify
+ * false-negative (epoch→ISO coercion makes the source digest differ from the
+ * target digest), which fixing {@link buildDigestExpr} resolves — NOT a CHECK
+ * drop. See the T11809 return notes for the full per-column row counts.
+ *
+ * Lookup key: `${targetTable}.${column}` (lowercase, dotted).
+ *
+ * @since T11547 (P0 data-loss fix)
+ * @since T11548 (P0 final enum coverage)
+ * @since T11647 (brain target = runtime shape — brain enum coercions removed)
+ */
+export declare const ENUM_NORMALIZATIONS: ReadonlyMap<string, NormalizeFn>;
+/**
+ * Return a SQL CASE expression that normalises legacy enum values for `col` in
+ * `targetTableName` to the canonical values accepted by the consolidated CHECK,
+ * or return `null` when no normalization rule exists for this (table, column).
+ *
+ * @param targetTableName - Physical consolidated target table name.
+ * @param col             - Column name.
+ * @param srcRef          - SQL expression referencing the source column.
+ * @returns A SQL CASE expression string, or `null` if no rule applies.
+ */
+export declare function enumNormExpr(targetTableName: string, col: string, srcRef: string): string | null;
+/**
+ * Function shape for a numeric-clamp rule: given the `srcRef` SQL expression for
+ * a column, return a SQL expression that maps non-finite values to finite ones.
+ */
+export type NumericClampFn = (srcRef: string) => string;
+/**
+ * Per-(targetTable, column) numeric-clamp rules that coerce non-finite legacy
+ * REAL values (`Inf` / `-Inf` / `NaN`) to a finite in-range value so the row is
+ * NOT silently dropped by `INSERT OR IGNORE`.
+ *
+ * ## Why this exists (T11782)
+ *
+ * 188,926 of 697,780 legacy `brain_weight_history` rows carry
+ * `delta_weight = Inf`/`-Inf` (the R-STDP plasticity writer saturated the delta
+ * before the value was clamped at write time). SQLite stores ±Inf as the IEEE-754
+ * float, but the consolidated `brain_weight_history.delta_weight` column is a
+ * plain `real NOT NULL` with NO CHECK — so a verbatim copy would land the Inf
+ * value. The historical deficit, however, was that those rows tripped a constraint
+ * elsewhere in the copy chain and `INSERT OR IGNORE` dropped them, yielding a
+ * deficit that fired the parity-gate abort. Clamping the non-finite value to a
+ * finite member of the column's domain guarantees every row lands.
+ *
+ * The clamp mirrors the {@link ENUM_NORMALIZATIONS} shape: each entry is a
+ * function `(srcRef) => CASE …`. Finite values pass through unchanged via the
+ * ELSE branch. The `col != col` self-comparison is the canonical SQL NaN guard
+ * (NaN is the only value not equal to itself); `9e999` is the SQLite literal that
+ * evaluates to `+Infinity` (and `-9e999` to `-Infinity`).
+ *
+ * Lookup key: `${targetTable}.${column}` (lowercase, dotted).
+ *
+ * @since T11782 (P0 — brain_weight_history Inf recovery)
+ */
+export declare const NUMERIC_CLAMPS: ReadonlyMap<string, NumericClampFn>;
+/**
+ * Return a SQL CASE expression that clamps non-finite legacy REAL values for
+ * `col` in `targetTableName` to a finite in-range value, or `null` when no
+ * clamp rule exists for this (table, column).
+ *
+ * @param targetTableName - Physical consolidated target table name.
+ * @param col             - Column name.
+ * @param srcRef          - SQL expression referencing the source column.
+ * @returns A SQL CASE expression string, or `null` if no rule applies.
+ */
+export declare function numericClampExpr(targetTableName: string, col: string, srcRef: string): string | null;
+/**
+ * Magnitude threshold distinguishing epoch SECONDS from epoch MILLISECONDS.
+ *
+ * A Unix epoch value for years 2020–2100 is roughly 1.6e9 – 4.1e9 seconds,
+ * or 1.6e12 – 4.1e12 milliseconds. The safe boundary is 1e11 (100 billion):
+ * any value BELOW 1e11 is in seconds (even year 2100 seconds ≈ 4.1e9 < 1e11);
+ * any value AT OR ABOVE 1e11 is in milliseconds (year 2020 ms ≈ 1.6e12 > 1e11).
+ *
+ * This constant is embedded directly in the generated SQL CASE expression so
+ * it is evaluated per-row — each row's epoch is classified independently.
+ */
+export declare const EPOCH_SECONDS_THRESHOLD: 100000000000;
+/**
+ * Build a SQL expression that converts an INTEGER epoch column to ISO-8601 TEXT,
+ * automatically detecting whether the stored value is in seconds or milliseconds
+ * using a magnitude heuristic (T11549 correctness fix).
+ *
+ * ## Heuristic
+ *
+ * A per-row CASE checks whether the column value is below {@link EPOCH_SECONDS_THRESHOLD}
+ * (100 billion). If so, the value is treated as seconds and passed directly to
+ * `strftime(..., 'unixepoch')`. If at or above the threshold, it is divided by
+ * 1000.0 first (milliseconds → seconds).
+ *
+ * This replaces the previous per-source heuristic which failed when individual
+ * columns within a source DB used a different epoch unit than the majority of that
+ * source's columns. The specific bug: `nexus.user_profile.{first_observed_at,
+ * last_reinforced_at}` stores SECONDS (value ≈ 1.78e9) but the nexus source was
+ * labeled `milliseconds`, causing these values to be divided by 1000 and converted
+ * to a 1970 date.
+ *
+ * ## NULL handling
+ *
+ * A NULL source value is preserved as NULL so it passes the `IS NULL` branch of
+ * the ISO GLOB CHECK constraint on the target column.
+ *
+ * @param srcRef - SQL expression referencing the source column value.
+ * @returns A SQL CASE expression producing an ISO-8601 TEXT timestamp.
+ */
+export declare function buildEpochToIsoExpr(srcRef: string): string;
+/**
+ * Parse the DDL for a given table from `sqlite_master` and return the set of
+ * column names that have an ISO GLOB CHECK constraint.
+ *
+ * Reads the raw DDL text and uses a regex to extract column names appearing in
+ * `CHECK ("colname" IS NULL OR "colname" GLOB '[0-9]...')` patterns. This is
+ * robust to Drizzle's generated CHECK format (all CHECK constraints generated
+ * by T11363 follow this exact pattern).
+ *
+ * @param db           - Target DB with the consolidated schema.
+ * @param tableName    - Physical table name (consolidated, e.g. `conduit_messages`).
+ * @param targetSchema - Schema name the target table lives in (`'main'`, or an
+ *   ATTACH alias for cross-scope routing — ADR-090 nexus graph residency, T11539).
+ * @returns Set of column names that require ISO GLOB validation.
+ */
+export declare function detectIsoGlobColumns(db: DatabaseSync, tableName: string, targetSchema?: string): Set<string>;
+/**
+ * Build the SQL expression a column's SOURCE value must pass through so it
+ * matches the canonical value the migration STORES in the target — for use by
+ * the parity verifier's content digest (T11809 · AC2).
+ *
+ * This is the digest-oriented sibling of migrate's `buildSelectExpr`. It applies
+ * the SAME value transforms the migration actually performs — and ONLY those:
+ *
+ *   1. **Epoch→ISO-8601** ({@link buildEpochToIsoExpr}) — when the target has an
+ *      ISO GLOB CHECK and the source column is INTEGER-typed.
+ *   2. **Non-finite numeric clamp** ({@link numericClampExpr}).
+ *   3. **Enum-value normalization** ({@link enumNormExpr}).
+ *   4. **Plain column reference** otherwise.
+ *
+ * Crucially it does NOT add the NOT-NULL `COALESCE(..., type_default)` wrapping
+ * that `buildSelectExpr` uses: that wrapping only ever fires on a NULL source
+ * value that the target stores as a type-default, which is a NULL→default value
+ * CHANGE the digest should not paper over (a genuine NULL→'' divergence remains a
+ * real, visible content difference, not a coercion artifact). The verifier
+ * intentionally omits it so the digest reflects the canonical value transforms
+ * (epoch/enum/clamp) WITHOUT masking a true NULL→default substitution.
+ *
+ * The returned expression is a bare SQL value expression (no `AS "col"` alias)
+ * suitable for embedding directly in a `SELECT <expr> ... ORDER BY ...` digest
+ * query. When no transform applies, a plain quoted column reference is returned.
+ *
+ * @param targetTableName - Physical consolidated target table name (transform
+ *   lookup key).
+ * @param col             - Column name (present in BOTH source and target).
+ * @param srcType         - Raw `type` string from the source `PRAGMA table_info`.
+ * @param isoGlobCols     - Set of target columns carrying an ISO GLOB CHECK.
+ * @returns A SQL value expression that maps the raw source value to the canonical
+ *   value the target stores.
+ */
+export declare function buildDigestExpr(targetTableName: string, col: string, srcType: string, isoGlobCols: ReadonlySet<string>): string;
+//# sourceMappingURL=column-transforms.d.ts.map

package/dist/store/exodus/column-transforms.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"column-transforms.d.ts","sourceRoot":"","sources":["../../../src/store/exodus/column-transforms.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAMhD;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAO1D;AAMD;;;;GAIG;AACH,MAAM,MAAM,WAAW,GAAG,CAAC,MAAM,EAAE,MAAM,KAAK,MAAM,CAAC;AAErD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,eAAO,MAAM,mBAAmB,EAAE,WAAW,CAAC,MAAM,EAAE,WAAW,CA0H/D,CAAC;AAEH;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAAC,eAAe,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAIhG;AAMD;;;GAGG;AACH,MAAM,MAAM,cAAc,GAAG,CAAC,MAAM,EAAE,MAAM,KAAK,MAAM,CAAC;AAExD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,eAAO,MAAM,cAAc,EAAE,WAAW,CAAC,MAAM,EAAE,cAAc,CAc7D,CAAC;AAEH;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAC9B,eAAe,EAAE,MAAM,EACvB,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,MAAM,GACb,MAAM,GAAG,IAAI,CAIf;AAaD;;;;;;;;;;GAUG;AACH,eAAO,MAAM,uBAAuB,EAAG,YAAwB,CAAC;AAEhE;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAS1D;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,oBAAoB,CAClC,EAAE,EAAE,YAAY,EAChB,SAAS,EAAE,MAAM,EACjB,YAAY,SAAS,GACpB,GAAG,CAAC,MAAM,CAAC,CAmBb;AAqBD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAgB,eAAe,CAC7B,eAAe,EAAE,MAAM,EACvB,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,MAAM,EACf,WAAW,EAAE,WAAW,CAAC,MAAM,CAAC,GAC/B,MAAM,CAoBR"}