@workbasehq/core 0.2.6 → 0.2.8

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.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@workbasehq/core",
3
- "version": "0.2.6",
3
+ "version": "0.2.8",
4
4
  "type": "module",
5
5
  "exports": {
6
6
  ".": "./src/index.ts",
package/src/config.ts CHANGED
@@ -18,7 +18,7 @@ export { Q, Cond }
18
18
  /** SQLite date formatting with column operands; values use the library wire encoding. */
19
19
  export const Fn = { ...LibraryFn, strftime: (format: string, date: string) => Q.expr(`FN(${JSON.stringify(['STRFTIME', Q.value(format).serialize(), Q.expr(date).serialize()])})`) }
20
20
 
21
- export const CORE_VERSION = '0.2.6'
21
+ export const CORE_VERSION = '0.2.8'
22
22
  const navigationIconSchema = z.enum(['LayoutDashboard', 'Users', 'MapPin', 'Coins', 'Wallet', 'ArrowLeftRight', 'Settings', 'Building2', 'Activity', 'Workflow', 'Database', 'Folder'])
23
23
  const identifier = z.string().regex(/^[a-z][a-z0-9_]*$/)
24
24
  export const serializedExpressionSchema = z.union([z.string().min(1).max(32000), z.record(z.string(), z.unknown()).transform(value => JSON.stringify(value))])
@@ -144,9 +144,17 @@ loader relative to the installed package. There is no instance registry or confi
144
144
  discovery. Worker consumers can omit the optional `tsx` peer.
145
145
 
146
146
  Omit `--config` for a plain SQL database. With a config, migration verifies the SQL
147
- ledger and instance revision/core version, applies plugin migrations, and verifies
148
- their ledger and schema hooks. SQL must already contain the matching
149
- `instance_meta` revision and core version.
147
+ ledger and instance revision, applies plugin migrations, and verifies their ledger
148
+ and schema hooks. SQL must already contain the matching `instance_meta` revision.
149
+ An existing SDK stamp must be a numeric release in the running SDK's major and
150
+ no newer than that SDK. Unsupported stamps fail with
151
+ `migration_instance_revision_mismatch` before any SQL or plugin migrations or
152
+ ledger writes; the version is checked again after SQL and before plugin execution.
153
+ After verification, a stale core version is refreshed on that revision's row,
154
+ including releases with no pending SQL or plugin migrations. Older revision rows
155
+ and migration receipts are preserved; rerunning with the current version writes
156
+ no marker. A failure before the refresh can leave the old stamp; retry the deploy
157
+ to resume verification and refresh it before Worker upload.
150
158
 
151
159
  Files must be contiguous `0001_name.sql`, `0002_name.sql`, etc. Each SQL file and
152
160
  its receipt execute in one D1 HTTP transaction. Changed or missing historical SQL,
@@ -1,7 +1,7 @@
1
1
  import { MigrationDiagnostic } from './diagnostics'
2
2
  import { CORE_VERSION } from '../config'
3
3
  import { hashMigrationRows } from '../schema-compatibility'
4
- import { literal } from '../migrations/schema'
4
+ import { coreVersionSQL, literal } from '../migrations/schema'
5
5
  import { pluginMigrationStatus } from '../kernel/migrations'
6
6
  import type { KernelRegistry } from '../kernel/registry'
7
7
  import { migrateD1, type D1Query, type Migration } from './d1-migrations'
@@ -39,16 +39,38 @@ export function queryDatabase(query: D1Query): D1Database {
39
39
  } } as unknown as D1Database
40
40
  }
41
41
 
42
+ // Match MCP's supported baseline: numeric release versions in the same major,
43
+ // no newer than this SDK. Compare components numerically (0.2.10 > 0.2.8).
44
+ function supportedCoreVersion(value: unknown) {
45
+ const version = typeof value === 'string' && value.match(/^(\d+)\.(\d+)\.(\d+)$/)?.slice(1).map(Number)
46
+ const current = CORE_VERSION.split('.').map(Number)
47
+ return version && version.every(Number.isSafeInteger) && version.join('.') === value && version[0] === current[0] &&
48
+ (version[1] < current[1] || (version[1] === current[1] && version[2] <= current[2]))
49
+ }
50
+
42
51
  export async function migrateInstance(query: D1Query, files: readonly Migration[], kernel: KernelRegistry) {
43
- const legacy = await migrateD1(query, files)
44
52
  const db = queryDatabase(query)
53
+ const metaSQL = 'SELECT revision,core_version FROM instance_meta ORDER BY revision DESC LIMIT 1'
54
+ // Check an existing database before even creating a ledger or applying SQL:
55
+ // a pending SQL file could otherwise overwrite an unsupported SDK stamp.
56
+ const existing = await db.prepare("SELECT name FROM sqlite_master WHERE name='instance_meta'").first()
57
+ if (existing) {
58
+ const stored = await db.prepare(metaSQL).first<{ core_version: string }>()
59
+ if (!supportedCoreVersion(stored?.core_version)) throw new MigrationDiagnostic({ code: 'migration_instance_revision_mismatch' })
60
+ }
61
+ const legacy = await migrateD1(query, files)
45
62
  const rows = await db.prepare('SELECT filename,checksum FROM _migrations ORDER BY filename').all<{ filename: string; checksum: string }>()
46
63
  const expectedRows = [...files].sort((a, b) => a.filename < b.filename ? -1 : a.filename > b.filename ? 1 : 0)
47
64
  if (await hashMigrationRows(rows.results) !== await hashMigrationRows(expectedRows)) throw new MigrationDiagnostic({ code: 'migration_instance_verification_failed' })
48
- const meta = await db.prepare('SELECT revision,core_version FROM instance_meta ORDER BY revision DESC LIMIT 1').first<{ revision: number; core_version: string }>()
49
- if (meta?.revision !== kernel.config.revision || meta.core_version !== CORE_VERSION) throw new MigrationDiagnostic({ code: 'migration_instance_revision_mismatch' })
65
+ const meta = await db.prepare(metaSQL).first<{ revision: number; core_version: string }>()
66
+ if (meta?.revision !== kernel.config.revision || !supportedCoreVersion(meta.core_version)) throw new MigrationDiagnostic({ code: 'migration_instance_revision_mismatch' })
50
67
  await kernel.applyMigrations(db)
51
68
  const status = await pluginMigrationStatus(db, kernel.plugins, kernel.config)
52
69
  if (status.expected !== status.applied) throw new MigrationDiagnostic({ code: 'migration_plugin_verification_failed' })
70
+ // A release can change CORE_VERSION without adding SQL or a config revision.
71
+ // Stamp it only after both ledgers and plugin schema checks have succeeded.
72
+ if (meta.core_version !== CORE_VERSION) await db.prepare(coreVersionSQL(kernel.config.revision)).run()
73
+ const applied = await db.prepare(metaSQL).first<{ revision: number; core_version: string }>()
74
+ if (applied?.revision !== kernel.config.revision || applied.core_version !== CORE_VERSION) throw new MigrationDiagnostic({ code: 'migration_instance_revision_mismatch' })
53
75
  return { ...legacy, pluginMigrations: status.applied }
54
76
  }
@@ -1,7 +1,8 @@
1
1
  import { defineInstance, inspectInstance, type InstanceConfig } from '../config'
2
2
  import { column, createEntity, initialSchema, literal, quote, revisionSQL } from './schema'
3
+ import { rebuildWithNullableRefs, type SupplementalIndex } from './rebuild'
3
4
  export interface MigrationPlan { sql: string; destructive: string[]; blocked: string[]; warnings: string[] }
4
- export function plan(fromConfig: InstanceConfig | null, toConfig: InstanceConfig, options: { allowDestructive?: boolean } = {}): MigrationPlan {
5
+ export function plan(fromConfig: InstanceConfig | null, toConfig: InstanceConfig, options: { allowDestructive?: boolean; indexes?: SupplementalIndex[] } = {}): MigrationPlan {
5
6
  const to = defineInstance(toConfig)
6
7
  if (!fromConfig) return { sql: initialSchema(to), destructive: [], blocked: [], warnings: [] }
7
8
  // An older schema may violate a new presentation invariant; the result must
@@ -10,6 +11,8 @@ export function plan(fromConfig: InstanceConfig | null, toConfig: InstanceConfig
10
11
  if (from.id !== to.id) throw new Error('Cannot migrate between different instance IDs')
11
12
  if (to.revision <= from.revision) throw new Error('Target revision must increase')
12
13
  const sql: string[] = []; const destructive: string[] = []; const blocked: string[] = []; const warnings: string[] = []
14
+ const rebuilds = new Map<string, string[]>()
15
+ const referenceBackfills: string[] = []
13
16
  // Visit removed parents first, then reverse: every child is dropped before its refs.
14
17
  const removed = new Set(Object.keys(from.entities).filter(name => !to.entities[name]))
15
18
  const visited = new Set<string>(); const visiting = new Set<string>(); const parentsFirst: string[] = []
@@ -55,7 +58,19 @@ export function plan(fromConfig: InstanceConfig | null, toConfig: InstanceConfig
55
58
  blocked.push(`Changing an existing column's type/default/constraints requires a manually reviewed migration: ${name}.${key}`)
56
59
  }
57
60
  } else {
58
- if (field.type === 'ref') { blocked.push(`Adding a composite reference requires a manually reviewed migration: ${name}.${key}`); continue }
61
+ if (field.type === 'ref') {
62
+ if (field.required) blocked.push(`Required added reference needs a manually reviewed backfill migration: ${name}.${key}`)
63
+ else if (name === 'users' && (from.account?.entity === name || to.account?.entity === name)) blocked.push(`Account entity users requires a manually reviewed credential-schema migration before adding reference: ${name}.${key}`)
64
+ else {
65
+ const added = rebuilds.get(name) ?? []; added.push(key); rebuilds.set(name, added)
66
+ if (field.backfillFrom) {
67
+ const ref = next.fields[field.backfillFrom.refField]
68
+ // A replay must also preserve links deliberately cleared after the upgrade.
69
+ referenceBackfills.push(`UPDATE ${quote(name)} SET ${quote(key)} = (SELECT source.${quote(field.backfillFrom.valueField)} FROM ${quote(ref.entity!)} source WHERE source.organization_id = ${quote(name)}.organization_id AND source.id = ${quote(name)}.${quote(field.backfillFrom.refField)}) WHERE NOT EXISTS (SELECT 1 FROM instance_meta WHERE revision = ${to.revision});`)
70
+ }
71
+ }
72
+ continue
73
+ }
59
74
  if (field.required && (field.default === undefined || field.default === null)) { blocked.push(`Required added field needs a non-null backfill default: ${name}.${key}`); continue }
60
75
  sql.push(`ALTER TABLE ${quote(name)} ADD COLUMN ${column(key, field)};`)
61
76
  if (field.backfillFrom) {
@@ -79,6 +94,19 @@ export function plan(fromConfig: InstanceConfig | null, toConfig: InstanceConfig
79
94
  if (destructive.length && !options.allowDestructive) blocked.push('Destructive operations require --allow-destructive')
80
95
  if (destructive.length) warnings.push('Review destructive operations and take a backup before applying; this planner never applies SQL.')
81
96
  if (blocked.length) return { sql: `-- BLOCKED: ${blocked.join('\n-- ')}\n`, destructive, blocked, warnings }
82
- sql.push(revisionSQL(to.revision))
97
+ const rebuildSQL = [...rebuilds].map(([name, added]) => rebuildWithNullableRefs(name, from, to, added, options.indexes ?? []))
98
+ // Validate the previous physical schema before any proposed ALTER statements.
99
+ if (rebuildSQL.length) {
100
+ sql.unshift('PRAGMA defer_foreign_keys = ON;', ...rebuildSQL.map(rebuild => rebuild.guard))
101
+ for (const [i, rebuild] of rebuildSQL.entries()) {
102
+ sql.push(rebuild.sql)
103
+ // Keep the entire graph deferred until every table has its final shape.
104
+ if (i === rebuildSQL.length - 1) sql.push(rebuild.check)
105
+ sql.push(rebuild.cleanup)
106
+ }
107
+ sql.push('PRAGMA defer_foreign_keys = OFF;')
108
+ }
109
+ sql.push(...referenceBackfills)
110
+ sql.push(rebuilds.size ? revisionSQL(to.revision).replace('INSERT INTO', 'INSERT OR IGNORE INTO') : revisionSQL(to.revision))
83
111
  return { sql: `-- ${from.id}: revision ${from.revision} -> ${to.revision}\n${sql.join('\n')}\n`, destructive, blocked, warnings }
84
112
  }
@@ -0,0 +1,158 @@
1
+ import type { InstanceConfig } from '../config'
2
+ import { createEntity, literal, quote } from './schema'
3
+
4
+ /** Non-unique, organization-scoped indexes owned by the caller (e.g. configuration MCP). */
5
+ export interface SupplementalIndex { entity: string; name: string; fields: string[] }
6
+
7
+ const differences = ['rowid', 'columns', 'indexes', 'foreign_keys', 'inline_constraints', 'triggers', 'incoming_actions'] as const
8
+
9
+ /** Canonical multiset of top-level definitions. Token boundaries and string
10
+ * contents survive normalization. Quoted identifiers (i), bare words (w),
11
+ * numbers (n), strings (s) and punctuation (p) remain distinct. Only whitespace,
12
+ * identifier quote style/case and definition order are ignored. Numeric states
13
+ * consume decimal/hex digits and signed exponents without swallowing operators.
14
+ * Comments, unknown characters, incomplete tokens and table suffixes fail closed.
15
+ */
16
+ function definitions(table: string) {
17
+ const ch = 'substr(body, pos, 1)', next = 'substr(body, pos + 1, 1)'
18
+ const word = `${ch} GLOB '[a-zA-Z0-9_$]'`
19
+ const digit = `${ch} GLOB '[0-9]'`
20
+ const number = `mode IN ('integer', 'fraction', 'exponent', 'sign', 'digits', 'hex_start', 'hex')`
21
+ const numberEnd = `mode IN ('integer', 'fraction', 'digits', 'hex')`
22
+ const numberMore = `(${digit} AND mode IN ('integer', 'fraction', 'exponent', 'sign', 'digits'))
23
+ OR (${ch} GLOB '[0-9a-fA-F]' AND mode IN ('hex_start', 'hex'))
24
+ OR (${ch} = '.' AND mode = 'integer')
25
+ OR (${ch} IN ('e', 'E') AND mode IN ('integer', 'fraction'))
26
+ OR (${ch} IN ('+', '-') AND mode = 'exponent')
27
+ OR (${ch} IN ('x', 'X') AND mode = 'integer' AND token = '0')`
28
+ const flush = `(mode = 'word' AND NOT (${word})) OR
29
+ (${numberEnd} AND NOT (${numberMore}) AND NOT (${word}) AND ${ch} <> '.')`
30
+ const quoted = `mode IN (${["'", '"', '`', ']'].map(literal).join(', ')})`
31
+ const closing = `${quoted} AND ${ch} = mode`
32
+ const escaped = `${closing} AND ${next} = mode`
33
+ const boundary = `mode = '' AND depth = 0 AND ${ch} IN (',', ')')`
34
+ const space = `${ch} IN (' ', char(9), char(10), char(12), char(13))`
35
+ const opening = `${ch} IN (${["'", '"', '`', '['].map(literal).join(', ')})`
36
+ const punctuation = `${ch} IN (${[...'(),.+-*/%<>=~&|!'].map(literal).join(', ')})`
37
+ return `(WITH RECURSIVE source(body) AS (
38
+ SELECT substr(sql, instr(sql, '(') + 1) FROM sqlite_schema WHERE type = 'table' AND lower(name) = lower(${table})
39
+ ), scan(pos, depth, mode, token, definition, parts) AS (
40
+ SELECT 1, 0, '', '', '', json_array()
41
+ UNION ALL
42
+ SELECT pos + CASE WHEN ${flush} THEN 0 WHEN ${escaped} THEN 2 ELSE 1 END,
43
+ depth + CASE WHEN mode = '' AND ${ch} = '(' THEN 1 WHEN mode = '' AND ${ch} = ')' AND depth > 0 THEN -1 ELSE 0 END,
44
+ CASE WHEN ${flush} THEN ''
45
+ WHEN ${number} THEN CASE
46
+ WHEN NOT (${numberMore}) THEN 'invalid'
47
+ WHEN mode IN ('hex_start', 'hex') THEN 'hex'
48
+ WHEN ${ch} IN ('x', 'X') THEN 'hex_start'
49
+ WHEN ${ch} IN ('e', 'E') THEN 'exponent'
50
+ WHEN ${ch} IN ('+', '-') THEN 'sign'
51
+ WHEN mode IN ('exponent', 'sign', 'digits') THEN 'digits'
52
+ WHEN ${ch} = '.' THEN 'fraction' ELSE mode END
53
+ WHEN ${quoted} THEN CASE WHEN ${closing} AND NOT (${escaped}) THEN '' ELSE mode END
54
+ WHEN mode = 'word' THEN 'word'
55
+ WHEN ${boundary} AND ${ch} = ')' THEN 'done'
56
+ WHEN ${opening} THEN CASE WHEN ${ch} = '[' THEN ']' ELSE ${ch} END
57
+ WHEN ${digit} THEN 'integer'
58
+ WHEN ${ch} = '.' AND ${next} GLOB '[0-9]' THEN 'fraction'
59
+ WHEN ${word} THEN 'word'
60
+ WHEN (${ch} = '-' AND ${next} = '-') OR (${ch} = '/' AND ${next} = '*') THEN 'invalid'
61
+ WHEN (${punctuation}) OR (${space}) THEN '' ELSE 'invalid' END,
62
+ CASE WHEN ${flush} THEN ''
63
+ WHEN ${number} THEN token || ${ch}
64
+ WHEN ${quoted} THEN CASE WHEN ${closing} AND NOT (${escaped}) THEN '' ELSE token || ${ch} END
65
+ WHEN (${word}) OR (${ch} = '.' AND ${next} GLOB '[0-9]') THEN token || ${ch} ELSE '' END,
66
+ CASE WHEN ${flush} THEN definition || json_quote(CASE WHEN mode = 'word' THEN 'w:' || lower(token) ELSE 'n:' || token END) || ','
67
+ WHEN ${number} THEN definition
68
+ WHEN ${quoted} THEN CASE WHEN ${closing} AND NOT (${escaped})
69
+ THEN definition || json_quote(CASE WHEN mode = ${literal("'")} THEN 's:' || token ELSE 'i:' || lower(token) END) || ',' ELSE definition END
70
+ WHEN ${boundary} THEN ''
71
+ WHEN ${opening} OR (${word}) OR (${space}) OR (${ch} = '.' AND ${next} GLOB '[0-9]') THEN definition
72
+ ELSE definition || json_quote('p:' || ${ch}) || ',' END,
73
+ CASE WHEN ${boundary} THEN json_insert(parts, '$[#]', definition) ELSE parts END
74
+ FROM scan, source WHERE mode NOT IN ('done', 'invalid') AND pos <= length(body)
75
+ ) SELECT json_group_array(value) FROM (
76
+ SELECT value FROM scan, source, json_each(parts)
77
+ WHERE mode = 'done' AND trim(substr(body, pos), ' ' || char(9) || char(10) || char(12) || char(13)) = '' ORDER BY value
78
+ ))`
79
+ }
80
+
81
+ /** Use SQLite itself to describe both the physical table and a generator-built
82
+ * witness. Keep automatic indexes and auxiliary index columns in the fingerprint.
83
+ * Compare ASCII-case-folded identifiers rather than history-dependent column/FK
84
+ * IDs. Preserve default expressions and string/numeric literal contents exactly.
85
+ * Body tokens cover CHECK, COLLATE, conflict clauses and FK deferrability, which
86
+ * PRAGMAs do not expose, so unfamiliar DDL still fails closed.
87
+ */
88
+ function fingerprint(name: string, indexNames: [string, string][] = []) {
89
+ const table = literal(name)
90
+ const indexName = indexNames.length ? `CASE lower(name) ${indexNames.map(([physical, canonical]) => `WHEN lower(${literal(physical)}) THEN lower(${literal(canonical)})`).join(' ')} ELSE lower(name) END` : 'lower(name)'
91
+ return `json_object(
92
+ 'rowid', (SELECT wr FROM pragma_table_list WHERE schema = 'main' AND lower(name) = lower(${table})),
93
+ 'columns', (SELECT json_group_array(json_array(lower(name), lower(type), "notnull", dflt_value, pk, hidden)) FROM (SELECT * FROM pragma_table_xinfo(${table}) ORDER BY lower(name))),
94
+ 'indexes', (SELECT json_group_array(json_array(index_name, origin, "unique", partial, json(columns))) FROM (
95
+ SELECT CASE WHEN origin = 'c' THEN ${indexName} ELSE origin END AS index_name, origin, "unique", partial,
96
+ (SELECT json_group_array(json_array(seqno, CASE WHEN cid < 0 THEN cid END, lower(name), "desc", lower(coll), "key")) FROM (SELECT * FROM pragma_index_xinfo(i.name) ORDER BY seqno)) AS columns
97
+ FROM pragma_index_list(${table}) i ORDER BY index_name, columns)),
98
+ 'foreign_keys', (SELECT json_group_array(json_array("table", on_update, on_delete, match, json(columns))) FROM (
99
+ SELECT lower("table") AS "table", on_update, on_delete, match,
100
+ (SELECT json_group_array(json_array(seq, lower("from"), lower("to"))) FROM (SELECT * FROM pragma_foreign_key_list(${table}) WHERE id = fk.id ORDER BY seq)) AS columns
101
+ FROM pragma_foreign_key_list(${table}) fk WHERE seq = 0 ORDER BY "table", on_update, on_delete, match, columns)),
102
+ 'inline_constraints', ${definitions(table)},
103
+ 'triggers', (SELECT count(*) FROM sqlite_schema WHERE type = 'trigger' AND lower(tbl_name) = lower(${table})),
104
+ 'incoming_actions', NOT EXISTS (SELECT 1 FROM sqlite_schema s, pragma_foreign_key_list(s.name) fk WHERE s.type = 'table' AND s.name NOT GLOB '_cf_*' AND s.name NOT GLOB 'sqlite_*' AND lower(fk."table") = lower(${table}) AND (fk.on_delete <> 'NO ACTION' OR fk.on_update <> 'NO ACTION'))
105
+ )`
106
+ }
107
+
108
+ function witness(name: string, expected: string, entity: InstanceConfig['entities'][string], indexes: SupplementalIndex[]) {
109
+ const suffixes = ['org_idx', ...Object.entries(entity.fields).filter(([, f]) => f.type === 'ref' && !f.computed).map(([key]) => `${key}_idx`)]
110
+ const names: [string, string][] = [...suffixes.map(suffix => [`${expected}_${suffix}`, `${name}_${suffix}`] as [string, string]), ...indexes.map((index, i) => [`${expected}_supplemental_${i}`, index.name] as [string, string])]
111
+ return { shape: fingerprint(expected, names), sql: createEntity(expected, entity)
112
+ + '\n' + indexes.map((index, i) => `CREATE INDEX ${quote(`${expected}_supplemental_${i}`)} ON ${quote(expected)} (${['organization_id', ...index.fields].map(quote).join(', ')});`).join('\n')
113
+ }
114
+ }
115
+
116
+ /** The runner must submit the whole migration in one D1 transaction/batch.
117
+ * D1 cannot disable foreign_keys inside that transaction. Defer NO ACTION checks,
118
+ * recreate the original name, validate the final graph, then restore enforcement.
119
+ */
120
+ export function rebuildWithNullableRefs(name: string, previous: InstanceConfig, config: InstanceConfig, added: string[], indexes: SupplementalIndex[]) {
121
+ const entity = config.entities[name]
122
+ let prefix = `workbase_rebuild_${name}_${config.revision}`
123
+ while (['rows', 'guard', 'previous', 'next'].some(suffix => config.entities[`${prefix}_${suffix}`] || previous.entities[`${prefix}_${suffix}`])) prefix += '_'
124
+ const rows = quote(`${prefix}_rows`), guard = quote(`${prefix}_guard`), table = quote(name)
125
+ const fields = Object.entries(entity.fields).filter(([, field]) => !field.computed)
126
+ const columns = ['id', 'organization_id', 'created_at', 'updated_at', 'version', ...fields.map(([key]) => key)]
127
+ const supplemental = indexes.filter(index => index.entity === name)
128
+ const before = `${prefix}_previous`, after = `${prefix}_next`
129
+ const previousIndexes = supplemental.map(index => ({ ...index, fields: index.fields.map(key => previous.entities[name].fields[key] ? key : entity.fields[key]?.renameFrom ?? key) }))
130
+ const previousWitness = witness(name, before, previous.entities[name], previousIndexes)
131
+ const nextWitness = witness(name, after, entity, supplemental)
132
+ const guardSQL = `-- Verify ${name} against fresh generator shapes before any schema changes.
133
+ ${previousWitness.sql}
134
+ ${nextWitness.sql}
135
+ CREATE TABLE ${guard} (
136
+ reason TEXT DEFAULT '' ${differences.map(part => `CONSTRAINT ${quote(`rebuild_requires_review_${name}_${part}`)} CHECK (reason <> ${literal(part)})`).join(' ')},
137
+ ok INTEGER CONSTRAINT rebuild_requires_review CHECK (ok = 1)
138
+ );
139
+ WITH actual(shape) AS (SELECT ${fingerprint(name)}),
140
+ expected(shape) AS (SELECT CASE WHEN EXISTS (SELECT 1 FROM instance_meta WHERE revision = ${config.revision})
141
+ THEN ${nextWitness.shape} ELSE ${previousWitness.shape} END)
142
+ INSERT INTO ${guard} (reason, ok) SELECT
143
+ CASE ${differences.map(part => `WHEN json_extract(actual.shape, '$.${part}') IS NOT json_extract(expected.shape, '$.${part}') THEN ${literal(part)}`).join('\n ')} ELSE '' END,
144
+ actual.shape = expected.shape FROM actual, expected;
145
+ DROP TABLE ${quote(before)};
146
+ DROP TABLE ${quote(after)};`
147
+ // SELECT * comes first deliberately: SQLite keeps its existing column when a
148
+ // fallback alias duplicates it. First apply supplies NULL/default; a replay
149
+ // copies the already-added reference, including links written since apply.
150
+ const fallbacks = added.map(key => `${literal(entity.fields[key].default ?? null)} AS ${quote(key)}`).join(', ')
151
+ return { guard: guardSQL, sql: `-- Rebuild ${name} atomically; physical schema differences require a manually reviewed migration.
152
+ CREATE TABLE ${rows} AS SELECT ${columns.map(quote).join(', ')} FROM (SELECT *, ${fallbacks} FROM ${table});
153
+ DROP TABLE ${table};
154
+ ${createEntity(name, entity)}
155
+ ${supplemental.map(index => `CREATE INDEX ${quote(index.name)} ON ${table} (${['organization_id', ...index.fields].map(quote).join(', ')});`).join('\n')}
156
+ INSERT INTO ${table} (${columns.map(quote).join(', ')}) SELECT ${columns.map(quote).join(', ')} FROM ${rows};
157
+ DROP TABLE ${rows};`, check: `INSERT INTO ${guard} (ok) SELECT NOT EXISTS (SELECT 1 FROM pragma_foreign_key_check);`, cleanup: `DROP TABLE ${guard};` }
158
+ }
@@ -68,6 +68,9 @@ CREATE INDEX memberships_org_role_idx ON memberships(organization_id,role);
68
68
  CREATE TABLE instance_meta (revision INTEGER PRIMARY KEY, core_version TEXT NOT NULL, applied_at TEXT NOT NULL);
69
69
  `
70
70
  export const revisionSQL = (revision: number) => `INSERT INTO instance_meta VALUES (${revision}, '${CORE_VERSION}', strftime('%Y-%m-%dT%H:%M:%fZ','now'));`
71
+ // Revisions are the primary key: preserve older rows and refresh only the current
72
+ // revision's SDK stamp after deploy-time migration verification succeeds.
73
+ export const coreVersionSQL = (revision: number) => `UPDATE instance_meta SET core_version = ${literal(CORE_VERSION)}, applied_at = strftime('%Y-%m-%dT%H:%M:%fZ','now') WHERE revision = ${literal(revision)} AND revision = (SELECT MAX(revision) FROM instance_meta) AND core_version <> ${literal(CORE_VERSION)};`
71
74
  export const initialSchema = (config: InstanceConfig) => configuredSystemSchema(config) + opsSchema + (config.account?.entity === 'users' ? betterAuthSchema.replace('user_id TEXT NOT NULL REFERENCES users(id)', 'user_id TEXT NOT NULL REFERENCES "user"(id)') : betterAuthSchema) + emailDeliverySchema + workflowSchema + Object.entries(config.entities).filter(([n]) => !(n === 'users' && config.account?.entity === n)).map(([n, e]) => createEntity(n, e)).join('\n') + '\n' + revisionSQL(config.revision) + '\n'
72
75
 
73
76
  /** Fresh schemas support configured application roles and the explicit users/account extension.
@@ -207,6 +207,9 @@ export function renderStatement(kernel: KernelRegistry, scope: Scope, ast: Selec
207
207
  return visible
208
208
  }
209
209
  const computed = new Map<string, Condition>()
210
+ const computedOperands = new Map<string, Condition>()
211
+ const computedVisibility = new Map<string, Condition>()
212
+ const emptyComputedReferences = new Map<string, Condition>()
210
213
  const computing = new Set<string>()
211
214
  const presentation = new Map<string, Condition>()
212
215
  function computedValue(field: string): Condition {
@@ -241,17 +244,20 @@ export function renderStatement(kernel: KernelRegistry, scope: Scope, ast: Selec
241
244
  parent = target
242
245
  }
243
246
  if (parent === alias && definition.fields[dependency.field]?.computed) {
244
- const operand = computedValue(dependency.field)
245
- columns.set(dependency.column, operand)
246
- visible.push(Cond.isNotNull(operand))
247
+ computedValue(dependency.field)
248
+ columns.set(dependency.column, computedOperands.get(dependency.field)!)
249
+ visible.push(computedVisibility.get(dependency.field) ?? truth(false))
247
250
  } else if (parent === alias && definition.fields[dependency.field]?.type === 'ref') {
248
251
  const allowed = foreignKeyVisible(dependency.field)
249
- columns.set(dependency.column, new ForeignKeyValue(col(alias, dependency.field), allowed))
252
+ columns.set(dependency.column, col(alias, dependency.field))
250
253
  visible.push(Cond.or([Cond.isNull(col(alias, dependency.field)), allowed]))
251
254
  } else {
252
255
  columns.set(dependency.column, col(parent, dependency.field))
253
256
  if (kernel.config.entities[dependency.entity].label && dependency.field === kernel.config.entities[dependency.entity].displayField) visible.push(Cond.equal(col(parent, '__display_visible'), Q.raw('1')))
254
- if (kernel.config.entities[dependency.entity].fields[dependency.field]?.computed) visible.push(Cond.isNotNull(col(parent, dependency.field)))
257
+ if (kernel.config.entities[dependency.entity].fields[dependency.field]?.computed) visible.push(Cond.equal(col(parent, `__computed_visible_${dependency.field}`), Q.raw('1')))
258
+ else if (kernel.config.entities[dependency.entity].fields[dependency.field]?.type === 'ref') visible.push(Cond.or([
259
+ Cond.isNull(col(parent, `__raw_${dependency.field}`)), Cond.isNotNull(col(parent, dependency.field)),
260
+ ]))
255
261
  }
256
262
  }
257
263
  const source = (target: string) => scopedTable(target, undefined, true, true, info.tables.get(target) ?? new Set())
@@ -265,11 +271,22 @@ export function renderStatement(kernel: KernelRegistry, scope: Scope, ast: Selec
265
271
  }
266
272
  presentation.set(field, new DisplayPartsExpression(info.parts!, columns, nested, source))
267
273
  }
274
+ // Keep the operand and its availability separate internally. Reusing an
275
+ // already-masked operand loses NULL provenance and recursively duplicates
276
+ // visibility probes for every layer of a composed expression.
277
+ const operand = new ComputedExpression(info, columns, [], source)
278
+ computedOperands.set(field, operand)
268
279
  let result: Condition = new ComputedExpression(info, columns, visible, source)
280
+ const dependenciesVisible = visible.length ? Cond.and(visible) : truth(true)
281
+ computedVisibility.set(field, dependenciesVisible)
269
282
  if (definition.fields[field].type === 'ref') {
270
- const operand = result
283
+ // A masked NULL is not absence. Carry both states through computed
284
+ // dependencies, including nullable scalar intermediates and joined rows.
285
+ const empty = Cond.and([dependenciesVisible, Cond.isNull(operand)])
286
+ emptyComputedReferences.set(field, empty)
271
287
  const allowed = Cond.exists(scopedTable(definition.fields[field].entity!, child => Cond.equal(col(child, 'id'), operand), false))
272
- result = new ForeignKeyValue(operand, allowed)
288
+ computedVisibility.set(field, Cond.and([dependenciesVisible, Cond.or([Cond.isNull(operand), allowed])]))
289
+ result = new ForeignKeyValue(operand, Cond.and([dependenciesVisible, allowed]))
273
290
  }
274
291
  computed.set(field, result); computing.delete(field); return result
275
292
  }
@@ -311,7 +328,8 @@ export function renderStatement(kernel: KernelRegistry, scope: Scope, ast: Selec
311
328
  const target = kernel.config.entities[path.entity]
312
329
  // A raw NULL is ordinary absence; a non-null raw FK masked to NULL is
313
330
  // denied. Reuse its masked projection rather than add another EXISTS.
314
- if (target.fields[path.field]?.type === 'ref') labelVisibility.push(Cond.or([
331
+ if (target.fields[path.field]?.computed) labelVisibility.push(Cond.equal(col(parent, `__computed_visible_${path.field}`), Q.raw('1')))
332
+ else if (target.fields[path.field]?.type === 'ref') labelVisibility.push(Cond.or([
315
333
  Cond.isNull(col(parent, `__raw_${path.field}`)), Cond.isNotNull(col(parent, path.field)),
316
334
  ]))
317
335
  if (target.label && path.field === target.displayField) labelVisibility.push(Cond.equal(col(parent, '__display_visible'), Q.raw('1')))
@@ -326,6 +344,10 @@ export function renderStatement(kernel: KernelRegistry, scope: Scope, ast: Selec
326
344
  if (definition?.computed) {
327
345
  const projected = !computedDemand || computedDemand.has(field) ? computedValue(field) : Q.raw('NULL')
328
346
  query = query.field(projected, field)
347
+ if (maskForeignKeys) {
348
+ query = query.field(computedVisibility.get(field) ?? truth(false), `__computed_visible_${field}`)
349
+ if (definition.type === 'ref') query = query.field(emptyComputedReferences.get(field) ?? truth(false), `__empty_${field}`)
350
+ }
329
351
  if (maskForeignKeys && (!computedDemand || computedDemand.has(field)) && needsDisplayParts(kernel.config, entity, field)) {
330
352
  query = query.field(presentation.get(field) ?? Q.raw('NULL'), partsAlias(field))
331
353
  }
@@ -410,6 +432,13 @@ class LabelObject extends Condition {
410
432
  return `CASE WHEN ${id} IS NULL THEN json_object('status', 'unavailable') ELSE json_object('status', 'ok', 'entity', ${value(this.entity).toSQL(flavor)}, 'display', ${display}, 'row', ${row}) END`
411
433
  }
412
434
  }
435
+ /** Only an absent FK on an authorized source row is empty. A failed join is not. */
436
+ class NullableLabel extends Condition {
437
+ constructor(private empty: Condition, private label: ISequelizable) { super() }
438
+ toSQL(flavor: ISQLFlavor) {
439
+ return `CASE WHEN ${this.empty.toSQL(flavor)} THEN json_object('status', 'empty') ELSE ${this.label.toSQL(flavor)} END`
440
+ }
441
+ }
413
442
  export const orderField = (order: Order) => order.label ? sortAlias(order.field) : order.field
414
443
  export function compileRoot(kernel: KernelRegistry, scope: Scope, query: QueryInput, keys?: Scalar[], cost?: QueryCost) {
415
444
  let source = buildSelect(kernel, scope, query.entity, query)
@@ -417,13 +446,20 @@ export function compileRoot(kernel: KernelRegistry, scope: Scope, query: QueryIn
417
446
  add(query.entity, query.search?.fields ?? [])
418
447
  const labelKeys = [...new Set([...(query.labels ?? []), ...Object.keys(query.labelWhere ?? {}), ...(query.search?.fields ?? []).filter(key => labelPath(kernel.config, query.entity, key)), ...(query.orderBy ?? []).filter(o => o.label).map(o => o.field)])]
419
448
  const joins = new Map<string, string>()
449
+ const emptyReference = (parent: string, hop: { source: string; field: string }) =>
450
+ kernel.config.entities[hop.source].fields[hop.field].computed
451
+ ? readableComputed(kernel, scope, hop.source, hop.field) ? Cond.equal(col(parent, `__empty_${hop.field}`), Q.raw('1')) : truth(false)
452
+ : Cond.isNull(col(parent, `__raw_${hop.field}`))
420
453
  for (const key of labelKeys) {
421
454
  const plan = readableLabel(kernel, scope, query.entity, key)
455
+ const first = labelPath(kernel.config, query.entity, key)!.hops[0]
456
+ const empty: Condition[] = [emptyReference('row', first)]
422
457
  let expression: Condition | ReturnType<typeof Q.raw> = Q.raw("json_object('status', 'unavailable')")
423
458
  if (plan) {
424
459
  if (plan.display) add(plan.entity, [plan.display])
425
460
  let parent = 'row'; let path = ''
426
461
  for (const hop of plan.hops) {
462
+ if (parent !== 'row') empty.push(Cond.and([Cond.isNotNull(col(parent, 'id')), emptyReference(parent, hop)]))
427
463
  path += `/${hop.field}`
428
464
  let alias = joins.get(path)
429
465
  if (!alias) {
@@ -434,7 +470,7 @@ export function compileRoot(kernel: KernelRegistry, scope: Scope, query: QueryIn
434
470
  }
435
471
  expression = new LabelObject(plan.entity, parent, plan.display, !!plan.display && needsDisplayParts(kernel.config, plan.entity, plan.display))
436
472
  }
437
- source = source.field(expression, labelAlias(key))
473
+ source = source.field(new NullableLabel(Cond.or(empty), expression), labelAlias(key))
438
474
  }
439
475
  // Compute the key once from the authorized label, then seek/order/limit over it.
440
476
  let labeled = Q.select().from(source, 'labels').field('labels.*')
@@ -69,7 +69,7 @@ export function expressionInfo(config: Config, entity: string, field: string, wi
69
69
  clause?: 'SELECT' | 'WHERE' | 'JOIN ON' | 'ORDER BY'; selectAggregate?: boolean;
70
70
  aggregate?: string; aggregates?: { found: boolean }; outerAliases?: Set<string>; outerReferences?: Set<string>;
71
71
  aggregateReferences?: { aliases: Set<string>; references: Set<string> }[] }
72
- const root: Context = { aliases: new Map([['self', entity]]), aliasContexts: new Map(), current: entity, query: false }
72
+ const root: Context = { aliases: new Map([['self', entity]]), aliasContexts: new Map(), current: entity, query: false, rawRefs: config.entities[entity].fields[field]?.type === 'ref' }
73
73
  const reference = (column: string, context: Context): Kind => {
74
74
  if (column.includes('*') || !/^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)*$/.test(column)) fail(`Unknown field: ${column}`)
75
75
  const parts = column.split('.'); let source = context.current ?? entity; let qualifier: string | undefined
@@ -89,7 +89,7 @@ export function expressionInfo(config: Config, entity: string, field: string, wi
89
89
  let name = parts[0]
90
90
  const spec = config.entities[source] && Object.hasOwn(config.entities[source].fields, name) ? config.entities[source].fields[name] : undefined
91
91
  if (!spec && !Object.hasOwn(base, name)) fail(`Unknown schema field: ${source}.${name}`, 'Choose a field returned by inspect_schema.')
92
- // A bare to-one ref means the target display value, never its physical FK.
92
+ // Descriptive expressions consume the display value; computed refs consume IDs.
93
93
  if (spec?.type === 'ref' && !context.rawRefs) {
94
94
  if (qualifier && qualifier !== 'self') fail('Ref paths inside subqueries require an explicit schema join')
95
95
  hops.push({ source, field: name, target: spec!.entity! }); source = spec!.entity!