npm - @happyvertical/smrt-core - Versions diffs - 0.51.14 → 0.51.17 - Mend

@happyvertical/smrt-core 0.51.14 → 0.51.17

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (16) hide show

package/dist/manifest/static-manifest.js +1 -1
package/dist/manifest/static-manifest.js.map +1 -1
package/dist/manifest/store.js +1 -1
package/dist/manifest.json +1 -1
package/dist/migrations/differ.d.ts.map +1 -1
package/dist/migrations/differ.js +33 -18
package/dist/migrations/differ.js.map +1 -1
package/dist/schema/live-parity.d.ts.map +1 -1
package/dist/schema/live-parity.js +13 -0
package/dist/schema/live-parity.js.map +1 -1
package/dist/schema/text-cast-probe.d.ts +10 -0
package/dist/schema/text-cast-probe.d.ts.map +1 -1
package/dist/schema/text-cast-probe.js +67 -0
package/dist/schema/text-cast-probe.js.map +1 -1
package/dist/smrt-knowledge.json +3 -3
package/package.json +4 -4

package/dist/schema/text-cast-probe.js.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"text-cast-probe.js","names":[],"sources":["../../src/schema/text-cast-probe.ts"],"sourcesContent":["/*\n Shared \"probe, then cast\" helpers for text-column type convergence (#2771,\n * #2772).\n \n Two drift shapes on a table SMRT itself creates share one problem: a live\n * `text` column holds values that would parse losslessly into the manifest's\n * declared PostgreSQL type (`timestamptz` or `jsonb`), but the differ cannot\n * know that without looking at the data. `probeCastSafety()` answers that with\n * a genuine, exception-safe cast attempt — not a shape heuristic — over every\n * non-null value, and returns one sample so a fail-closed diagnostic can name\n * the offending value without dumping the whole column into JS.\n \n PostgreSQL has no `TRY_CAST`/safe-cast builtin before 17 (`pg_input_is_valid`),\n * and this fleet targets 16 (see `.github/workflows/postgres-tests.yml`), so a\n * real per-row safe cast needs PL/pgSQL's exception handling. That handler is\n * created as a session-scoped (`pg_temp`) function, which is why the create\n * statement and the probe query run inside one `db.transaction()` — the two\n * must land on the same physical connection, and a pooled adapter only\n * guarantees that within one transaction. `target_type` is never derived from\n * column data (always the literal `'jsonb'`/`'timestamptz'` this module\n * passes), so the dynamic `EXECUTE format(...)` it builds cannot be steered by\n * a row value; `%L` quotes the probed value as a literal.\n /\n\nimport type { DatabaseInterface } from '@happyvertical/sql';\nimport { formatDefaultValue, quoteIdentifier } from './sql-identifiers.js';\n\n/* Outcome of a server-side cast-safety probe over one column's non-null values. /\nexport type ShapeProbeResult =\n \| { status: 'clean' }\n \| { status: 'dirty'; count: number; sample?: string }\n \| { status: 'unavailable'; reason: string };\n\n/\n Mask a probed sample value for display in a diagnostic message: keep just\n * enough of the value to recognize it without echoing a full record verbatim\n * into logs/CI output (`created_at`/`_meta_data` values are user data).\n /\nexport function maskSampleValue(value: string): string {\n if (value.length === 0) return '(empty)';\n if (value.length <= 6)\n return `${'•'.repeat(value.length)} (length ${value.length})`;\n return `${value.slice(0, 3)}…${value.slice(-3)} (length ${value.length})`;\n}\n\n/* Session-scoped helper function name; `pg_temp` keeps it off the real schema. /\nconst PROBE_FUNCTION = 'pg_temp.smrt_probe_cast_ok';\n\n/\n PostgreSQL's \"special\" date/time input values (see the \"Special Values\"\n * table in the PostgreSQL docs). Every one of these parses successfully to\n * `timestamptz` — `probeCastSafety`'s real-cast test alone would call a text\n * column literally holding the string `now` or `infinity` \"clean\" — but\n * casting them evaluates to the migration's execution time or an infinite\n * sentinel, silently destroying the original value with no error and no\n * advisory. They must never be treated as safe, regardless of what a bare\n * cast attempt reports.\n /\nconst TIMESTAMPTZ_SPECIAL_VALUES = new Set([\n 'epoch',\n 'infinity',\n '-infinity',\n 'now',\n 'today',\n 'tomorrow',\n 'yesterday',\n 'allballs',\n]);\n\n/\n A `timestamptz` cast is only safe to apply unattended when the source text\n * already carries an explicit UTC offset (`Z` or `+HH[:MM]`/`-HH[:MM]`) —\n * without one, PostgreSQL interprets the value under the migrating\n session's* `TimeZone` setting, so the exact same text can cast to a\n * different instant on a different run/server. That ambiguity is exactly\n * what `--legacy-timezone=UTC` exists to resolve explicitly; the probe must\n * fail closed (not silently guess UTC) so naive values route to that opt-in\n * path instead of being auto-converged.\n /\n// PostgreSQL's ARE (\"advanced regular expression\") dialect, matched with the\n// case-insensitive `~` operator server-side — not a JS RegExp, and not\n// derived from one, since the two dialects diverge on escaping/anchoring.\nconst TIMESTAMPTZ_EXPLICIT_OFFSET_SQL_PATTERN =\n '^[0-9]{4}-[0-9]{2}-[0-9]{2}([ T][0-9]{2}:[0-9]{2}(:[0-9]{2}(\\\\.[0-9]+)?)?)?[[:space:]](Z\|[+-][0-9]{2}(:?[0-9]{2})?)$';\n\n/\n `target` is one of this module's own literal type names — never data —\n * so building the DDL by interpolation is safe; there is no column, table,\n * or row value in this string.\n /\nfunction renderCreateProbeFunctionSql(): string {\n const specialValuesArray = [...TIMESTAMPTZ_SPECIAL_VALUES]\n .map((value) => `'${value}'`)\n .join(',');\n return (\n `CREATE OR REPLACE FUNCTION ${PROBE_FUNCTION}(value text, target_type text) ` +\n 'RETURNS boolean LANGUAGE plpgsql AS $$ ' +\n 'BEGIN ' +\n 'IF value IS NULL THEN RETURN true; END IF; ' +\n \"IF target_type = 'timestamptz' THEN \" +\n `IF lower(trim(value)) = ANY (ARRAY[${specialValuesArray}]) THEN RETURN false; END IF; ` +\n `IF trim(value) !~ '${TIMESTAMPTZ_EXPLICIT_OFFSET_SQL_PATTERN}' THEN RETURN false; END IF; ` +\n 'END IF; ' +\n \"EXECUTE format('SELECT %L::%s', value, target_type); \" +\n 'RETURN true; ' +\n 'EXCEPTION WHEN OTHERS THEN RETURN false; ' +\n 'END; $$'\n );\n}\n\nfunction renderProbeQuerySql(\n tableName: string,\n columnName: string,\n targetType: 'timestamptz' \| 'jsonb',\n): string {\n const column = quoteIdentifier(columnName);\n const table = quoteIdentifier(tableName);\n const isValid = `${PROBE_FUNCTION}(${column}::text, '${targetType}')`;\n return (\n `SELECT count() AS invalid_count, ` +\n `min(CASE WHEN NOT ${isValid} THEN ${column}::text END) AS sample_value ` +\n `FROM ${table} WHERE ${column} IS NOT NULL AND NOT ${isValid}`\n );\n}\n\nfunction classifyProbeRows(\n rows: { invalid_count?: unknown; sample_value?: unknown }[],\n): ShapeProbeResult {\n const count = Number(rows[0]?.invalid_count);\n if (!Number.isFinite(count)) {\n return {\n status: 'unavailable',\n reason: 'probe returned a non-numeric count',\n };\n }\n if (count === 0) return { status: 'clean' };\n const sample = rows[0]?.sample_value;\n return {\n status: 'dirty',\n count,\n ...(typeof sample === 'string' ? { sample } : {}),\n };\n}\n\n/\n Probe every non-null value of a candidate `text` column for whether it can\n * cast losslessly to `timestamptz` or `jsonb`, using a real, exception-safe\n * cast attempt (not a shape heuristic) so an invalid-calendar timestamp or a\n * structurally-malformed-but-bracket-balanced JSON document is caught the\n * same as an obviously wrong value. Any failure to run the probe (adapter\n * without transaction support, a missing table mid-run, a test double\n * without a realistic response) resolves to `unavailable` — callers must not\n * treat that as \"clean\"; SMRT never coerces or discards data on an unproven\n * assumption.\n /\nexport async function probeCastSafety(\n db: DatabaseInterface,\n tableName: string,\n columnName: string,\n targetType: 'timestamptz' \| 'jsonb',\n): Promise<ShapeProbeResult> {\n if (!db.transaction) {\n return {\n status: 'unavailable',\n reason: 'adapter does not support transactions',\n };\n }\n try {\n return await db.transaction(async (tx) => {\n await tx.query(renderCreateProbeFunctionSql());\n const result = await tx.query(\n renderProbeQuerySql(tableName, columnName, targetType),\n );\n const rows = (Array.isArray(result) ? result : (result?.rows ?? [])) as {\n invalid_count?: unknown;\n sample_value?: unknown;\n }[];\n return classifyProbeRows(rows);\n });\n } catch (error) {\n return {\n status: 'unavailable',\n reason: error instanceof Error ? error.message : String(error),\n };\n }\n}\n\n/\n Column-conversion options shared by {@link renderTimestamptzColumnConversion}\n * and {@link renderJsonbColumnConversion}.\n \n `hasLiveDefault` and `manifestDefaultValue` are independent: PostgreSQL\n * rejects `ALTER COLUMN ... TYPE` outright whenever the column has any\n * existing default that cannot be auto-cast to the target type — this is\n * true whether or not the manifest itself declares a default (a legacy\n * `text` column with `DEFAULT ''` blocks the ALTER exactly the same as one\n * the manifest also wants a default on), so `DROP DEFAULT` must be gated on\n * the live default. `SET DEFAULT` afterward must be gated on the\n * manifest default instead: re-establishing a live-only default the\n * manifest no longer declares would silently resurrect drift\n * `compareColumnConstraints` is supposed to report and let an operator\n * choose to drop (see #2771/#2772 review findings: DROP/TYPE/SET DEFAULT\n * mirrors the pre-existing `generateTypeUpgradeSQL` path, and the DROP gate\n * must key off live state PostgreSQL itself enforces, not manifest intent).\n /\ninterface ColumnConversionOptions {\n hasLiveDefault?: boolean;\n manifestDefaultValue?: unknown;\n}\n\n/\n Render the one-time PostgreSQL conversion of a legacy `text` column to\n * native `timestamptz`, once {@link probeCastSafety} has confirmed every\n * non-null value casts safely.\n /\nexport function renderTimestamptzColumnConversion(\n tableName: string,\n columnName: string,\n options: ColumnConversionOptions = {},\n): string[] {\n const table = quoteIdentifier(tableName);\n const column = quoteIdentifier(columnName);\n const hasManifestDefault = options.manifestDefaultValue !== undefined;\n const statements: string[] = [];\n if (options.hasLiveDefault \|\| hasManifestDefault) {\n statements.push(`ALTER TABLE ${table} ALTER COLUMN ${column} DROP DEFAULT`);\n }\n statements.push(\n `ALTER TABLE ${table} ALTER COLUMN ${column} TYPE timestamptz USING ${column}::timestamptz`,\n );\n if (hasManifestDefault) {\n const formattedDefault = formatDefaultValue(\n options.manifestDefaultValue,\n 'TIMESTAMP',\n );\n statements.push(\n `ALTER TABLE ${table} ALTER COLUMN ${column} SET DEFAULT ${formattedDefault}`,\n );\n }\n return statements;\n}\n\n/\n Render the one-time PostgreSQL conversion of a legacy `text` column to\n * native `jsonb`, once {@link probeCastSafety} has confirmed every non-null\n * value casts safely.\n */\nexport function renderJsonbColumnConversion(\n tableName: string,\n columnName: string,\n options: ColumnConversionOptions = {},\n): string[] {\n const table = quoteIdentifier(tableName);\n const column = quoteIdentifier(columnName);\n const hasManifestDefault = options.manifestDefaultValue !== undefined;\n const statements: string[] = [];\n if (options.hasLiveDefault \|\| hasManifestDefault) {\n statements.push(`ALTER TABLE ${table} ALTER COLUMN ${column} DROP DEFAULT`);\n }\n statements.push(\n `ALTER TABLE ${table} ALTER COLUMN ${column} TYPE jsonb USING ${column}::jsonb`,\n );\n if (hasManifestDefault) {\n const formattedDefault = formatDefaultValue(\n options.manifestDefaultValue,\n 'JSON',\n );\n statements.push(\n `ALTER TABLE ${table} ALTER COLUMN ${column} SET DEFAULT ${formattedDefault}::jsonb`,\n );\n }\n return statements;\n}\n"],"mappings":"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"}
1	+ {"version":3,"file":"text-cast-probe.js","names":[],"sources":["../../src/schema/text-cast-probe.ts"],"sourcesContent":["/*\n Shared \"probe, then cast\" helpers for text-column type convergence (#2771,\n * #2772).\n \n Two drift shapes on a table SMRT itself creates share one problem: a live\n * `text` column holds values that would parse losslessly into the manifest's\n * declared PostgreSQL type (`timestamptz` or `jsonb`), but the differ cannot\n * know that without looking at the data. `probeCastSafety()` answers that with\n * a genuine, exception-safe cast attempt — not a shape heuristic — over every\n * non-null value, and returns one sample so a fail-closed diagnostic can name\n * the offending value without dumping the whole column into JS.\n \n PostgreSQL has no `TRY_CAST`/safe-cast builtin before 17 (`pg_input_is_valid`),\n * and this fleet targets 16 (see `.github/workflows/postgres-tests.yml`), so a\n * real per-row safe cast needs PL/pgSQL's exception handling. That handler is\n * created as a session-scoped (`pg_temp`) function, which is why the create\n * statement and the probe query run inside one `db.transaction()` — the two\n * must land on the same physical connection, and a pooled adapter only\n * guarantees that within one transaction. `target_type` is never derived from\n * column data (always the literal `'jsonb'`/`'timestamptz'` this module\n * passes), so the dynamic `EXECUTE format(...)` it builds cannot be steered by\n * a row value; `%L` quotes the probed value as a literal.\n /\n\nimport type { DatabaseInterface } from '@happyvertical/sql';\nimport { formatDefaultValue, quoteIdentifier } from './sql-identifiers.js';\n\n/* Outcome of a server-side cast-safety probe over one column's non-null values. /\nexport type ShapeProbeResult =\n \| { status: 'clean' }\n \| {\n status: 'dirty';\n count: number;\n sample?: string;\n /\n `duplicate_keys`: every value casts, but `count` JSON objects carry\n * duplicate keys that `jsonb` would silently collapse (#3041).\n * `preservation_unverified`: every value casts, but the duplicate-key\n * walk did not finish (its bound, a lock wait); `count` is 0 and no\n * conversion may be offered, but the decision must stay visible.\n /\n reason?: 'duplicate_keys' \| 'preservation_unverified';\n /* Why the preservation walk did not finish (`preservation_unverified`). /\n detail?: string;\n }\n \| { status: 'unavailable'; reason: string };\n\n/\n Mask a probed sample value for display in a diagnostic message: keep just\n * enough of the value to recognize it without echoing a full record verbatim\n * into logs/CI output (`created_at`/`_meta_data` values are user data).\n /\nexport function maskSampleValue(value: string): string {\n if (value.length === 0) return '(empty)';\n if (value.length <= 6)\n return `${'•'.repeat(value.length)} (length ${value.length})`;\n return `${value.slice(0, 3)}…${value.slice(-3)} (length ${value.length})`;\n}\n\n/* Session-scoped helper function name; `pg_temp` keeps it off the real schema. /\nconst PROBE_FUNCTION = 'pg_temp.smrt_probe_cast_ok';\n\n/\n PostgreSQL's \"special\" date/time input values (see the \"Special Values\"\n * table in the PostgreSQL docs). Every one of these parses successfully to\n * `timestamptz` — `probeCastSafety`'s real-cast test alone would call a text\n * column literally holding the string `now` or `infinity` \"clean\" — but\n * casting them evaluates to the migration's execution time or an infinite\n * sentinel, silently destroying the original value with no error and no\n * advisory. They must never be treated as safe, regardless of what a bare\n * cast attempt reports.\n /\nconst TIMESTAMPTZ_SPECIAL_VALUES = new Set([\n 'epoch',\n 'infinity',\n '-infinity',\n 'now',\n 'today',\n 'tomorrow',\n 'yesterday',\n 'allballs',\n]);\n\n/\n A `timestamptz` cast is only safe to apply unattended when the source text\n * already carries an explicit UTC offset (`Z` or `+HH[:MM]`/`-HH[:MM]`) —\n * without one, PostgreSQL interprets the value under the migrating\n session's* `TimeZone` setting, so the exact same text can cast to a\n * different instant on a different run/server. That ambiguity is exactly\n * what `--legacy-timezone=UTC` exists to resolve explicitly; the probe must\n * fail closed (not silently guess UTC) so naive values route to that opt-in\n * path instead of being auto-converged.\n /\n// PostgreSQL's ARE (\"advanced regular expression\") dialect, matched with the\n// case-insensitive `~` operator server-side — not a JS RegExp, and not\n// derived from one, since the two dialects diverge on escaping/anchoring.\nconst TIMESTAMPTZ_EXPLICIT_OFFSET_SQL_PATTERN =\n '^[0-9]{4}-[0-9]{2}-[0-9]{2}([ T][0-9]{2}:[0-9]{2}(:[0-9]{2}(\\\\.[0-9]+)?)?)?[[:space:]](Z\|[+-][0-9]{2}(:?[0-9]{2})?)$';\n\n/\n `target` is one of this module's own literal type names — never data —\n * so building the DDL by interpolation is safe; there is no column, table,\n * or row value in this string.\n /\nfunction renderCreateProbeFunctionSql(): string {\n const specialValuesArray = [...TIMESTAMPTZ_SPECIAL_VALUES]\n .map((value) => `'${value}'`)\n .join(',');\n return (\n `CREATE OR REPLACE FUNCTION ${PROBE_FUNCTION}(value text, target_type text) ` +\n 'RETURNS boolean LANGUAGE plpgsql AS $$ ' +\n 'BEGIN ' +\n 'IF value IS NULL THEN RETURN true; END IF; ' +\n \"IF target_type = 'timestamptz' THEN \" +\n `IF lower(trim(value)) = ANY (ARRAY[${specialValuesArray}]) THEN RETURN false; END IF; ` +\n `IF trim(value) !~ '${TIMESTAMPTZ_EXPLICIT_OFFSET_SQL_PATTERN}' THEN RETURN false; END IF; ` +\n 'END IF; ' +\n \"EXECUTE format('SELECT %L::%s', value, target_type); \" +\n 'RETURN true; ' +\n 'EXCEPTION WHEN OTHERS THEN RETURN false; ' +\n 'END; $$'\n );\n}\n\nfunction renderProbeQuerySql(\n tableName: string,\n columnName: string,\n targetType: 'timestamptz' \| 'jsonb',\n): string {\n const column = quoteIdentifier(columnName);\n const table = quoteIdentifier(tableName);\n const isValid = `${PROBE_FUNCTION}(${column}::text, '${targetType}')`;\n return (\n `SELECT count() AS invalid_count, ` +\n `min(CASE WHEN NOT ${isValid} THEN ${column}::text END) AS sample_value ` +\n `FROM ${table} WHERE ${column} IS NOT NULL AND NOT ${isValid}`\n );\n}\n\n/\n One set-based jsonb cast over every non-null value: `count(expr)` forces\n * the cast for each row, and any value jsonb rejects raises instead of\n * returning, so success alone proves the column clean.\n /\nfunction renderSetCastQuerySql(tableName: string, columnName: string): string {\n const column = quoteIdentifier(columnName);\n const table = quoteIdentifier(tableName);\n return `SELECT count((${column}::text)::jsonb) AS cast_count FROM ${table}`;\n}\n\nfunction classifyProbeRows(\n rows: { invalid_count?: unknown; sample_value?: unknown }[],\n): ShapeProbeResult {\n const count = Number(rows[0]?.invalid_count);\n if (!Number.isFinite(count)) {\n return {\n status: 'unavailable',\n reason: 'probe returned a non-numeric count',\n };\n }\n if (count === 0) return { status: 'clean' };\n const sample = rows[0]?.sample_value;\n return {\n status: 'dirty',\n count,\n ...(typeof sample === 'string' ? { sample } : {}),\n };\n}\n\n/\n Probe every non-null value of a candidate `text` column for whether it can\n * cast losslessly to `timestamptz` or `jsonb`, using a real, exception-safe\n * cast attempt (not a shape heuristic) so an invalid-calendar timestamp or a\n * structurally-malformed-but-bracket-balanced JSON document is caught the\n * same as an obviously wrong value. Any failure to run the probe (adapter\n * without transaction support, a missing table mid-run, a test double\n * without a realistic response) resolves to `unavailable` — callers must not\n * treat that as \"clean\"; SMRT never coerces or discards data on an unproven\n * assumption.\n /\nexport async function probeCastSafety(\n db: DatabaseInterface,\n tableName: string,\n columnName: string,\n targetType: 'timestamptz' \| 'jsonb',\n): Promise<ShapeProbeResult> {\n const castResult = await probeCastOnly(db, tableName, columnName, targetType);\n if (targetType !== 'jsonb' \|\| castResult.status !== 'clean') {\n return castResult;\n }\n return probeJsonbKeyPreservation(db, tableName, columnName);\n}\n\n/\n #3041 review finding: a successful jsonb cast proves castability, not\n * preservation. `jsonb` keeps only the last of duplicate object keys (it\n * also drops key order and insignificant whitespace, which SMRT never\n * treats as data). Walk every object node, nested ones included, and\n * compare its key count as `json` against `jsonb`; any object that would\n * lose a key makes the column dirty so the conversion stays a fail-closed\n * advisory instead of a silent, irreversible rewrite. The result columns\n * reuse the cast probe's names so one classifier reads both.\n /\nasync function probeJsonbKeyPreservation(\n db: DatabaseInterface,\n tableName: string,\n columnName: string,\n): Promise<ShapeProbeResult> {\n if (!db.transaction) {\n return {\n status: 'unavailable',\n reason: 'adapter does not support transactions',\n };\n }\n try {\n const result = await db.transaction(async (tx) => {\n await tx.query(\n `SET LOCAL statement_timeout = '${PRESERVATION_PROBE_TIMEOUT}'`,\n );\n return tx.query(renderDuplicateKeyQuerySql(tableName, columnName));\n });\n const rows = (Array.isArray(result) ? result : (result?.rows ?? [])) as {\n invalid_count?: unknown;\n sample_value?: unknown;\n }[];\n const classified = classifyProbeRows(rows);\n return classified.status === 'dirty'\n ? { ...classified, reason: 'duplicate_keys' }\n : classified;\n } catch (error) {\n // #3041 review finding: the cast already proved the column castable, so\n // a walk that ran and gave up (typically the timeout below) is not the\n // \"could not probe\" state `unavailable` means -- returning it would\n // silently withdraw the conversion. Fail closed, visibly.\n return {\n status: 'dirty',\n count: 0,\n reason: 'preservation_unverified',\n detail: error instanceof Error ? error.message : String(error),\n };\n }\n}\n\nfunction renderDuplicateKeyQuerySql(\n tableName: string,\n columnName: string,\n): string {\n const column = quoteIdentifier(columnName);\n const table = quoteIdentifier(tableName);\n // Only containers recurse (scalars are pruned at the edge), and each\n // object node is checked from its own key list -- a duplicate is a key\n // that appears more than once -- so no subtree is re-parsed as jsonb and\n // the walk stays linear in the number of container nodes.\n const containers = \"json_typeof(value) IN ('object', 'array')\";\n return (\n 'WITH RECURSIVE nodes(v) AS (' +\n `SELECT (${column}::text)::json FROM ${table} ` +\n `WHERE ${column} IS NOT NULL AND json_typeof((${column}::text)::json) IN ('object', 'array') ` +\n 'UNION ALL ' +\n 'SELECT child.value FROM nodes CROSS JOIN LATERAL (' +\n \"SELECT value FROM json_each(CASE WHEN json_typeof(nodes.v) = 'object' THEN nodes.v ELSE '{}'::json END) \" +\n `WHERE ${containers} ` +\n 'UNION ALL ' +\n \"SELECT value FROM json_array_elements(CASE WHEN json_typeof(nodes.v) = 'array' THEN nodes.v ELSE '[]'::json END) \" +\n `WHERE ${containers}` +\n ') AS child) ' +\n 'SELECT count() AS invalid_count, min(v::text) AS sample_value FROM nodes ' +\n \"WHERE json_typeof(v) = 'object' AND EXISTS (\" +\n 'SELECT 1 FROM json_object_keys(v) AS k(key) GROUP BY k.key HAVING count() > 1)'\n );\n}\n\n/\n Upper bound for the preservation walk. A timeout resolves to\n * `unavailable` -- the conversion is then not proposed (never a silent\n * collapse), and `db:status` live parity still reports the json/jsonb drift\n * without probing, so the column does not disappear from view.\n /\nconst PRESERVATION_PROBE_TIMEOUT = '60s';\n\nasync function probeCastOnly(\n db: DatabaseInterface,\n tableName: string,\n columnName: string,\n targetType: 'timestamptz' \| 'jsonb',\n): Promise<ShapeProbeResult> {\n if (!db.transaction) {\n return {\n status: 'unavailable',\n reason: 'adapter does not support transactions',\n };\n }\n if (targetType === 'jsonb') {\n // #3041 review finding: the per-row PL/pgSQL probe opens a\n // subtransaction per value, and native `json` columns are the large\n // legacy `_meta_data`-style ones. A single set-based cast that succeeds\n // proves every value castable (preservation is checked separately, see\n // `probeJsonbKeyPreservation`); only a failed cast falls through to the\n // per-row probe for the count and sample.\n try {\n const castCount = await db.transaction(async (tx) => {\n const result = await tx.query(\n renderSetCastQuerySql(tableName, columnName),\n );\n const rows = (\n Array.isArray(result) ? result : (result?.rows ?? [])\n ) as {\n cast_count?: unknown;\n }[];\n return rows[0]?.cast_count;\n });\n // Only a realistic answer counts as proof; anything else (an adapter\n // or test double that does not return the count) takes the per-row\n // probe below instead.\n if (\n castCount !== undefined &&\n castCount !== null &&\n Number.isFinite(Number(castCount))\n ) {\n return { status: 'clean' };\n }\n } catch {\n // Fall through: the per-row probe classifies the failure (dirty\n // values, or unavailable for a missing table / unrealistic adapter).\n }\n }\n try {\n return await db.transaction(async (tx) => {\n await tx.query(renderCreateProbeFunctionSql());\n const result = await tx.query(\n renderProbeQuerySql(tableName, columnName, targetType),\n );\n const rows = (Array.isArray(result) ? result : (result?.rows ?? [])) as {\n invalid_count?: unknown;\n sample_value?: unknown;\n }[];\n return classifyProbeRows(rows);\n });\n } catch (error) {\n return {\n status: 'unavailable',\n reason: error instanceof Error ? error.message : String(error),\n };\n }\n}\n\n/\n Column-conversion options shared by {@link renderTimestamptzColumnConversion}\n * and {@link renderJsonbColumnConversion}.\n \n `hasLiveDefault` and `manifestDefaultValue` are independent: PostgreSQL\n * rejects `ALTER COLUMN ... TYPE` outright whenever the column has any\n * existing default that cannot be auto-cast to the target type — this is\n * true whether or not the manifest itself declares a default (a legacy\n * `text` column with `DEFAULT ''` blocks the ALTER exactly the same as one\n * the manifest also wants a default on), so `DROP DEFAULT` must be gated on\n * the live default. `SET DEFAULT` afterward must be gated on the\n * manifest default instead: re-establishing a live-only default the\n * manifest no longer declares would silently resurrect drift\n * `compareColumnConstraints` is supposed to report and let an operator\n * choose to drop (see #2771/#2772 review findings: DROP/TYPE/SET DEFAULT\n * mirrors the pre-existing `generateTypeUpgradeSQL` path, and the DROP gate\n * must key off live state PostgreSQL itself enforces, not manifest intent).\n /\ninterface ColumnConversionOptions {\n hasLiveDefault?: boolean;\n manifestDefaultValue?: unknown;\n}\n\n/\n Render the one-time PostgreSQL conversion of a legacy `text` column to\n * native `timestamptz`, once {@link probeCastSafety} has confirmed every\n * non-null value casts safely.\n /\nexport function renderTimestamptzColumnConversion(\n tableName: string,\n columnName: string,\n options: ColumnConversionOptions = {},\n): string[] {\n const table = quoteIdentifier(tableName);\n const column = quoteIdentifier(columnName);\n const hasManifestDefault = options.manifestDefaultValue !== undefined;\n const statements: string[] = [];\n if (options.hasLiveDefault \|\| hasManifestDefault) {\n statements.push(`ALTER TABLE ${table} ALTER COLUMN ${column} DROP DEFAULT`);\n }\n statements.push(\n `ALTER TABLE ${table} ALTER COLUMN ${column} TYPE timestamptz USING ${column}::timestamptz`,\n );\n if (hasManifestDefault) {\n const formattedDefault = formatDefaultValue(\n options.manifestDefaultValue,\n 'TIMESTAMP',\n );\n statements.push(\n `ALTER TABLE ${table} ALTER COLUMN ${column} SET DEFAULT ${formattedDefault}`,\n );\n }\n return statements;\n}\n\n/\n Render the one-time PostgreSQL conversion of a legacy `text` column to\n * native `jsonb`, once {@link probeCastSafety} has confirmed every non-null\n * value casts safely.\n */\nexport function renderJsonbColumnConversion(\n tableName: string,\n columnName: string,\n options: ColumnConversionOptions = {},\n): string[] {\n const table = quoteIdentifier(tableName);\n const column = quoteIdentifier(columnName);\n const hasManifestDefault = options.manifestDefaultValue !== undefined;\n const statements: string[] = [];\n if (options.hasLiveDefault \|\| hasManifestDefault) {\n statements.push(`ALTER TABLE ${table} ALTER COLUMN ${column} DROP DEFAULT`);\n }\n statements.push(\n `ALTER TABLE ${table} ALTER COLUMN ${column} TYPE jsonb USING ${column}::jsonb`,\n );\n if (hasManifestDefault) {\n const formattedDefault = formatDefaultValue(\n options.manifestDefaultValue,\n 'JSON',\n );\n statements.push(\n `ALTER TABLE ${table} ALTER COLUMN ${column} SET DEFAULT ${formattedDefault}::jsonb`,\n );\n }\n return statements;\n}\n"],"mappings":"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"}

package/dist/smrt-knowledge.json CHANGED Viewed

@@ -3,12 +3,12 @@
   "sensitiveFieldsExcluded": true,
   "generatedAt": "1970-01-01T00:00:00.000Z",
   "packageName": "@happyvertical/smrt-core",
-  "packageVersion": "0.51.14",
+  "packageVersion": "0.51.17",
   "sourceManifestPath": "dist/manifest.json",
   "agentDocPath": "AGENTS.md",
   "sourceHashes": {
-    "manifest": "94a4c427c50c3c3af63811a7b69f82ca92c26a69ed1a43b7e53ad72c87b39a88",
-    "packageJson": "73eef22a1ad5e719a351a66891ddb0a826f13e95a217fa64bddd4b86153ae515",
+    "manifest": "4f680cca361cf1226a7846d806de2417e3483c82fc1f3c8d0b510b6eb2e94ec4",
+    "packageJson": "a1085f6f5ba439f7501ae4392c9fac3a221d144842bd2896624ee90f66e1e16e",
     "agents": "7e27a7c52729c302d80e9c36bf068fe1811a7ae51eccf66c6a5f9498aaec3318",
     "moduleDoc:agents/object-runtime.md": "34a4e740c109467cd5486c4af0e3bf4b63915697721ab584df0e5506ea9290ca",
     "moduleDoc:agents/revision-guard.md": "aa6b1ddb5b6b49fa27ebbe575ec7fcd6d5ceb35ee25acc702f877a226eb9a99a",

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@happyvertical/smrt-core",
-  "version": "0.51.14",
+  "version": "0.51.17",
   "description": "Core AI agent framework with standardized collections, object-relational mapping, and code generators",
   "author": "HappyVertical",
   "type": "module",
@@ -154,9 +154,9 @@
     "@happyvertical/files": "^0.89.12",
     "@happyvertical/json": "^0.89.12",
     "@happyvertical/logger": "^0.89.12",
-    "@happyvertical/smrt-config": "0.51.14",
-    "@happyvertical/smrt-scanner": "0.51.14",
-    "@happyvertical/smrt-types": "0.51.14",
+    "@happyvertical/smrt-config": "0.51.17",
+    "@happyvertical/smrt-scanner": "0.51.17",
+    "@happyvertical/smrt-types": "0.51.17",
     "@happyvertical/sql": "^0.89.12",
     "@happyvertical/utils": "^0.89.12",
     "@oxc-project/runtime": "^0.150.0",