@syncular/typegen 0.15.40 → 0.15.43

package/dist/generate.d.ts

@@ -11,8 +11,10 @@ export interface MigrationInput {
     /** Contents of its `up.sql`. */
     readonly sql: string;
 }
-/** Pure IR construction — the testable heart of the generator. */
-export declare function buildIr(manifest: Manifest, migrations: readonly MigrationInput[]): IrDocument;
+/** Pure IR construction — the testable heart of the generator. Migrations
+ * named in `lockedNames` replay as immutable deployed history: rules that
+ * only appended migrations must satisfy are skipped for them. */
+export declare function buildIr(manifest: Manifest, migrations: readonly MigrationInput[], lockedNames?: ReadonlySet<string>): IrDocument;
 /** Load `NNNN_name/up.sql` migrations, ordered by numeric prefix. */
 export declare function loadMigrations(migrationsDir: string): MigrationInput[];
 /** One named-query file (`.sql` — the compatibility floor — or `.syql`, the

package/dist/generate.js

@@ -17,7 +17,7 @@ import { emitSwiftModule } from './emit-swift.js';
 import { TypegenError } from './errors.js';
 import { canonicalizeExtensions, IR_VERSION, irHash, serializeIr, } from './ir.js';
 import { MANIFEST_FILENAME, parseManifest, } from './manifest.js';
-import { buildMigrationLock, LEGACY_MIGRATION_LOCK_FORMAT_VERSION, MIGRATION_LOCK_FILENAME, readMigrationLock, serializeMigrationLock, updateMigrationLock, } from './migration-lock.js';
+import { buildMigrationLock, LEGACY_MIGRATION_LOCK_FORMAT_VERSION, lockedMigrationNames, MIGRATION_LOCK_FILENAME, readMigrationLock, serializeMigrationLock, updateMigrationLock, } from './migration-lock.js';
 import { buildNamingMap } from './naming.js';
 import { analyzeQueryFile, synthesizeDdl, } from './query.js';
 import { serializeQueryIr } from './query-ir.js';
@@ -149,15 +149,17 @@ function buildSchemaVersions(manifest, migrations) {
     }
     return out;
 }
-/** Pure IR construction — the testable heart of the generator. */
-export function buildIr(manifest, migrations) {
+/** Pure IR construction — the testable heart of the generator. Migrations
+ * named in `lockedNames` replay as immutable deployed history: rules that
+ * only appended migrations must satisfy are skipped for them. */
+export function buildIr(manifest, migrations, lockedNames) {
     if (migrations.length === 0) {
         throw new TypegenError(MANIFEST_FILENAME, 'no migrations found');
     }
     const parsedTables = new Map();
     const droppedTables = new Set();
     for (const migration of migrations) {
-        applyMigrationSql(parsedTables, migration.sql, `${migration.name}/up.sql`, droppedTables);
+        applyMigrationSql(parsedTables, migration.sql, `${migration.name}/up.sql`, droppedTables, { lockedHistory: lockedNames?.has(migration.name) === true });
     }
     validateFinalSchemaIdentifiers(parsedTables);
     const schemaVersions = buildSchemaVersions(manifest, migrations);
@@ -366,17 +368,29 @@ export function upgradeMigrationHistory(manifestDir) {
     }
     // Validate the immutable prefix before replacing its representation.
     updateMigrationLock(locked, migrations);
-    buildIr(manifest, migrations);
+    // upgrade-lock converts the committed representation of history that is
+    // already locked. Extending the lock over appended migrations is its own
+    // reviewable act, so unlocked migrations stop the conversion here.
+    if (migrations.length > locked.migrations.length) {
+        const appended = migrations
+            .slice(locked.migrations.length)
+            .map((migration) => migration.name)
+            .join(', ');
+        throw new TypegenError(MIGRATION_LOCK_FILENAME, `migrations ${appended} are appended beyond the locked history — run generate to extend the lock over them, commit the extended lock, then rerun \`migrations upgrade-lock\``);
+    }
+    const lockedNames = lockedMigrationNames(locked);
+    buildIr(manifest, migrations, lockedNames);
     return {
         path: resolve(manifestDir, MIGRATION_LOCK_FILENAME),
-        content: serializeMigrationLock(buildMigrationLock(migrations)),
+        content: serializeMigrationLock(buildMigrationLock(migrations, undefined, lockedNames)),
     };
 }
 /** Fast CI check for migration history without emitting/query analysis. */
 export function checkMigrationHistory(manifestDir) {
     const { manifest, migrations } = loadProjectInputs(manifestDir);
-    const current = updateMigrationLock(readMigrationLock(manifestDir), migrations);
-    buildIr(manifest, migrations);
+    const locked = readMigrationLock(manifestDir);
+    const current = updateMigrationLock(locked, migrations);
+    buildIr(manifest, migrations, lockedMigrationNames(locked));
     const output = {
         path: resolve(manifestDir, MIGRATION_LOCK_FILENAME),
         content: serializeMigrationLock(current),
@@ -391,8 +405,9 @@ export function checkMigrationHistory(manifestDir) {
 /** Read `syncular.json` + migrations under `manifestDir`; build outputs. */
 export function generate(manifestDir) {
     const { manifest, migrations } = loadProjectInputs(manifestDir);
-    const migrationLock = updateMigrationLock(readMigrationLock(manifestDir), migrations);
-    const ir = buildIr(manifest, migrations);
+    const locked = readMigrationLock(manifestDir);
+    const migrationLock = updateMigrationLock(locked, migrations);
+    const ir = buildIr(manifest, migrations, lockedMigrationNames(locked));
     // §5/§12 naming: the emitter targets this run generates (keyword hazards
     // are only real on targets that exist), and the per-table collision check
     // for the generated row types.

package/dist/lsp.js

@@ -6,6 +6,7 @@ import { TypegenError } from './errors.js';
 import { formatSyql } from './fmt.js';
 import { buildIr, loadMigrations, loadQueries, makeQueryDb } from './generate.js';
 import { MANIFEST_FILENAME, parseManifest } from './manifest.js';
+import { lockedMigrationNames, readMigrationLock } from './migration-lock.js';
 import { SyqlFrontendError } from './syql-lexer.js';
 import { lowerSyqlQuery } from './syql-lowering.js';
 import { buildSyqlModuleGraph } from './syql-modules.js';
@@ -177,7 +178,16 @@ export class SyqlLanguageServer {
             return cached;
         try {
             const manifest = parseManifest(JSON.parse(readFileSync(resolve(manifestDir, MANIFEST_FILENAME), 'utf8')));
-            const ir = buildIr(manifest, loadMigrations(resolve(manifestDir, manifest.migrations)));
+            // Tolerate locked history exactly like generation does; a project with
+            // no readable lock builds strictly.
+            let lockedNames;
+            try {
+                lockedNames = lockedMigrationNames(readMigrationLock(manifestDir));
+            }
+            catch {
+                lockedNames = undefined;
+            }
+            const ir = buildIr(manifest, loadMigrations(resolve(manifestDir, manifest.migrations)), lockedNames);
             const { db } = makeQueryDb(ir);
             const targets = ['ts'];
             if (manifest.output.swift !== undefined)

package/dist/migration-lock.d.ts

@@ -33,8 +33,10 @@ export interface MigrationLockV2 {
     };
 }
 export type MigrationLock = LegacyMigrationLock | MigrationLockV2;
+/** The names of every migration a committed lock has made immutable. */
+export declare function lockedMigrationNames(lock: MigrationLock): ReadonlySet<string>;
 /** Build a deterministic lock document for a complete migration sequence. */
-export declare function buildMigrationLock(migrations: readonly MigrationInput[], formatVersion?: typeof LEGACY_MIGRATION_LOCK_FORMAT_VERSION | typeof MIGRATION_LOCK_FORMAT_VERSION): MigrationLock;
+export declare function buildMigrationLock(migrations: readonly MigrationInput[], formatVersion?: typeof LEGACY_MIGRATION_LOCK_FORMAT_VERSION | typeof MIGRATION_LOCK_FORMAT_VERSION, lockedNames?: ReadonlySet<string>): MigrationLock;
 /** Fixed-order, byte-deterministic serialization for clean code review. */
 export declare function serializeMigrationLock(lock: MigrationLock): string;
 /** Parse and structurally validate a committed lock document. */

package/dist/migration-lock.js

@@ -31,21 +31,28 @@ function snapshotColumn(column) {
     };
 }
 function snapshotTables(tables) {
-    return [...tables.values()]
-        .sort((a, b) => a.name.localeCompare(b.name))
+    return ([...tables.values()]
+        // Code-point order keeps the serialization byte-identical across locales.
+        .sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0))
         .map((table) => ({
         name: table.name,
         primaryKey: table.primaryKey,
         columns: table.columns.map(snapshotColumn),
-    }));
+    })));
 }
-/** Replay a complete migration sequence with ephemeral diagnostic snapshots. */
-function buildMigrationHistory(migrations) {
+/** The names of every migration a committed lock has made immutable. */
+export function lockedMigrationNames(lock) {
+    return new Set(lock.migrations.map((migration) => migration.name));
+}
+/** Replay a complete migration sequence with ephemeral diagnostic snapshots.
+ * Migrations named in `lockedNames` replay as deployed history; rules that
+ * only appended migrations must satisfy are skipped for them. */
+function buildMigrationHistory(migrations, lockedNames) {
     const tables = new Map();
     const droppedTables = new Set();
     const entries = [];
     for (const migration of migrations) {
-        applyMigrationSql(tables, migration.sql, `${migration.name}/up.sql`, droppedTables);
+        applyMigrationSql(tables, migration.sql, `${migration.name}/up.sql`, droppedTables, { lockedHistory: lockedNames?.has(migration.name) === true });
         entries.push({
             name: migration.name,
             sha256: checksum(migration.sql),
@@ -75,8 +82,8 @@ function lockFromHistory(history, formatVersion) {
     };
 }
 /** Build a deterministic lock document for a complete migration sequence. */
-export function buildMigrationLock(migrations, formatVersion = MIGRATION_LOCK_FORMAT_VERSION) {
-    return lockFromHistory(buildMigrationHistory(migrations), formatVersion);
+export function buildMigrationLock(migrations, formatVersion = MIGRATION_LOCK_FORMAT_VERSION, lockedNames) {
+    return lockFromHistory(buildMigrationHistory(migrations, lockedNames), formatVersion);
 }
 /** Fixed-order, byte-deterministic serialization for clean code review. */
 export function serializeMigrationLock(lock) {
@@ -329,11 +336,11 @@ function validateMigrationHistory(locked, current) {
  * version-1 lock is always an explicit command.
  */
 export function updateMigrationLock(locked, migrations) {
-    const current = buildMigrationHistory(migrations);
+    const current = buildMigrationHistory(migrations, lockedMigrationNames(locked));
     validateMigrationHistory(locked, current);
     return lockFromHistory(current, locked.formatVersion);
 }
 /** Validate without changing the committed lock format. */
 export function validateMigrationLock(locked, migrations) {
-    validateMigrationHistory(locked, buildMigrationHistory(migrations));
+    validateMigrationHistory(locked, buildMigrationHistory(migrations, lockedMigrationNames(locked)));
 }

package/dist/query.js

@@ -504,6 +504,11 @@ function hasCommaJoinedSchemaTable(sql, ir) {
     ]);
     let depth = 0;
     let cursor = 0;
+    /** The previous significant token: an uppercased word or a single
+     * punctuation character. Distinguishes a table-source group — a `(` after
+     * FROM, JOIN, `,` or another `(` — from a function call or parenthesized
+     * expression, whose `(` follows an identifier or an operator. */
+    let previous;
     const nextIdentifier = (start) => {
         let index = start;
         while (index < cleaned.length &&
@@ -515,20 +520,31 @@ function hasCommaJoinedSchemaTable(sql, ir) {
     };
     while (cursor < cleaned.length) {
         const char = cleaned[cursor];
+        if (/\s/.test(char)) {
+            cursor += 1;
+            continue;
+        }
         if (char === '(') {
+            const opensTableSource = previous === 'FROM' ||
+                previous === 'JOIN' ||
+                previous === ',' ||
+                previous === '(';
             const next = nextIdentifier(cursor + 1);
-            if (activeFromDepths.has(depth) &&
+            if (opensTableSource &&
+                activeFromDepths.has(depth) &&
                 next !== undefined &&
                 known.has(next.toLowerCase())) {
                 activeFromDepths.add(depth + 1);
             }
             depth += 1;
+            previous = '(';
             cursor += 1;
             continue;
         }
         if (char === ')') {
             activeFromDepths.delete(depth);
             depth = Math.max(0, depth - 1);
+            previous = ')';
             cursor += 1;
             continue;
         }
@@ -536,6 +552,7 @@ function hasCommaJoinedSchemaTable(sql, ir) {
             const next = nextIdentifier(cursor + 1);
             if (next !== undefined && known.has(next.toLowerCase()))
                 return true;
+            previous = ',';
             cursor += 1;
             continue;
         }
@@ -550,9 +567,11 @@ function hasCommaJoinedSchemaTable(sql, ir) {
                 activeFromDepths.add(depth);
             else if (clauseEnders.has(word))
                 activeFromDepths.delete(depth);
+            previous = word;
             cursor = end;
             continue;
         }
+        previous = char;
         cursor += 1;
     }
     return false;

package/dist/sql.d.ts

@@ -8,15 +8,25 @@ export interface ParsedTable {
     /** Client-local contentful FTS5 projections. */
     readonly ftsIndexes: IrFtsIndex[];
 }
+/** Options for replaying one migration's SQL. */
+export interface ApplyMigrationSqlOptions {
+    /** True while this migration is part of the locked, immutable history
+     * prefix (`syncular.migrations.lock.json`). Deployed migrations are
+     * immutable, so checks that would require editing them are skipped for the
+     * locked prefix and enforced for appended migrations. */
+    readonly lockedHistory?: boolean;
+}
 /**
  * Validate the accumulated head schema after every migration has been
  * applied. This deliberately permits a locked historical migration to create
  * an invalid identifier when a later forward migration drops it; only final
- * generated objects must be portable.
+ * generated objects must be portable. Objects created by locked migrations
+ * are additionally exempt from the ASCII rule (deployed migrations are
+ * immutable, so the name can only be retired by a forward migration).
  */
 export declare function validateFinalSchemaIdentifiers(tables: ReadonlyMap<string, ParsedTable>): void;
 /**
  * Apply one migration file's SQL to the accumulated table map. Columns
  * accumulate in declaration order — the §2.4 row-codec positional order.
  */
-export declare function applyMigrationSql(tables: Map<string, ParsedTable>, sql: string, source: string, droppedTables?: Set<string>): void;
+export declare function applyMigrationSql(tables: Map<string, ParsedTable>, sql: string, source: string, droppedTables?: Set<string>, options?: ApplyMigrationSqlOptions): void;

package/dist/sql.js

@@ -59,29 +59,48 @@ const DATA_MUTATION_GUIDANCE = 'Syncular migration SQL is schema-only: retain th
 const tableIdentifierSources = new WeakMap();
 const columnIdentifierSources = new WeakMap();
 const indexIdentifierSources = new WeakMap();
-function validateIdentifier(source, kind, identifier) {
+const ftsIndexIdentifierSources = new WeakMap();
+/** Objects created while replaying the locked, immutable history prefix.
+ * Rules adopted while that prefix was already deployed (nullable-only ADD
+ * COLUMN, ASCII-portable identifiers) replay tolerantly for these objects;
+ * every migration beyond the locked prefix enforces them. */
+const lockedHistoryObjects = new WeakSet();
+/** ASCII identifier contract shared with named-query analysis: query
+ * dependency tracking and reactivity resolve identifiers with this shape. */
+const PORTABLE_ASCII_IDENTIFIER_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
+function validateIdentifier(source, kind, identifier, target) {
     try {
         validatePortableRelationalIdentifier(kind, identifier);
     }
     catch (error) {
         throw new TypegenError(source, error instanceof Error ? error.message : 'invalid relational identifier');
     }
+    if (lockedHistoryObjects.has(target))
+        return;
+    if (!PORTABLE_ASCII_IDENTIFIER_RE.test(identifier)) {
+        throw new TypegenError(source, `${kind} name ${JSON.stringify(identifier)} must be an ASCII identifier matching [A-Za-z_][A-Za-z0-9_]* — named-query analysis resolves ASCII identifiers, so a non-ASCII name silently loses dependency tracking and reactivity`);
+    }
 }
 /**
  * Validate the accumulated head schema after every migration has been
  * applied. This deliberately permits a locked historical migration to create
  * an invalid identifier when a later forward migration drops it; only final
- * generated objects must be portable.
+ * generated objects must be portable. Objects created by locked migrations
+ * are additionally exempt from the ASCII rule (deployed migrations are
+ * immutable, so the name can only be retired by a forward migration).
  */
 export function validateFinalSchemaIdentifiers(tables) {
     for (const table of tables.values()) {
         const tableSource = tableIdentifierSources.get(table) ?? 'migrations';
-        validateIdentifier(tableSource, 'table', table.name);
+        validateIdentifier(tableSource, 'table', table.name, table);
         for (const column of table.columns) {
-            validateIdentifier(columnIdentifierSources.get(column) ?? tableSource, `table ${table.name}: column`, column.name);
+            validateIdentifier(columnIdentifierSources.get(column) ?? tableSource, `table ${table.name}: column`, column.name, column);
         }
         for (const index of table.indexes) {
-            validateIdentifier(indexIdentifierSources.get(index) ?? tableSource, `table ${table.name}: index`, index.name);
+            validateIdentifier(indexIdentifierSources.get(index) ?? tableSource, `table ${table.name}: index`, index.name, index);
+        }
+        for (const ftsIndex of table.ftsIndexes) {
+            validateIdentifier(ftsIndexIdentifierSources.get(ftsIndex) ?? tableSource, `table ${table.name}: FTS virtual table`, ftsIndex.name, ftsIndex);
         }
     }
 }
@@ -288,22 +307,22 @@ function parseColumnDef(cursor, allowPrimaryKey) {
  * Dispatch a `CREATE …` statement: `CREATE TABLE`, `CREATE INDEX`, or
  * `CREATE UNIQUE INDEX`. Anything else is a hard error naming the construct.
  */
-function parseCreate(cursor, tables, droppedTables, source) {
+function parseCreate(cursor, tables, droppedTables, source, options) {
     if (cursor.eatWord('VIRTUAL')) {
-        parseCreateVirtualTable(cursor, tables);
+        parseCreateVirtualTable(cursor, tables, source, options);
         return;
     }
     if (cursor.eatWord('TABLE')) {
-        parseCreateTable(cursor, tables, droppedTables, source);
+        parseCreateTable(cursor, tables, droppedTables, source, options);
         return;
     }
     if (cursor.eatWord('UNIQUE')) {
         cursor.expectWord('INDEX', 'after CREATE UNIQUE');
-        parseCreateIndex(cursor, tables, true, source);
+        parseCreateIndex(cursor, tables, true, source, options);
         return;
     }
     if (cursor.eatWord('INDEX')) {
-        parseCreateIndex(cursor, tables, false, source);
+        parseCreateIndex(cursor, tables, false, source, options);
         return;
     }
     const token = cursor.peek();
@@ -320,7 +339,7 @@ const ALLOWED_FTS_TOKENIZERS = new Set([
 /** Parse the deliberately narrow migration-subset v2 FTS5 form documented in
  * RFC 0005. The virtual table is attached to its owning synced
  * table and is not itself a synced table. */
-function parseCreateVirtualTable(cursor, tables) {
+function parseCreateVirtualTable(cursor, tables, source, options) {
     cursor.expectWord('TABLE', 'after CREATE VIRTUAL');
     if (cursor.eatWord('IF')) {
         cursor.expectWord('NOT', 'after IF');
@@ -409,9 +428,13 @@ function parseCreateVirtualTable(cursor, tables) {
             cursor.fail(`FTS virtual table ${name}: column ${JSON.stringify(columnName)} must have TEXT/string type`);
         }
     }
-    table.ftsIndexes.push({ name, columns, tokenize });
+    const ftsIndex = { name, columns, tokenize };
+    table.ftsIndexes.push(ftsIndex);
+    ftsIndexIdentifierSources.set(ftsIndex, source);
+    if (options.lockedHistory === true)
+        lockedHistoryObjects.add(ftsIndex);
 }
-function parseCreateTable(cursor, tables, droppedTables, source) {
+function parseCreateTable(cursor, tables, droppedTables, source, options) {
     if (cursor.eatWord('IF')) {
         cursor.expectWord('NOT', 'after IF');
         cursor.expectWord('EXISTS', 'after IF NOT');
@@ -497,8 +520,12 @@ function parseCreateTable(cursor, tables, droppedTables, source) {
     };
     tables.set(name, table);
     tableIdentifierSources.set(table, source);
+    if (options.lockedHistory === true)
+        lockedHistoryObjects.add(table);
     for (const column of finalColumns) {
         columnIdentifierSources.set(column, source);
+        if (options.lockedHistory === true)
+            lockedHistoryObjects.add(column);
     }
 }
 /**
@@ -509,7 +536,7 @@ function parseCreateTable(cursor, tables, droppedTables, source) {
  * (partial index) clause are hard errors naming the construct. Index names
  * are unique per accumulated schema.
  */
-function parseCreateIndex(cursor, tables, unique, source) {
+function parseCreateIndex(cursor, tables, unique, source, options) {
     // `INDEX` already matched by the dispatcher.
     if (cursor.eatWord('IF')) {
         cursor.expectWord('NOT', 'after IF');
@@ -572,8 +599,10 @@ function parseCreateIndex(cursor, tables, unique, source) {
     const index = { name, columns, unique };
     table.indexes.push(index);
     indexIdentifierSources.set(index, source);
+    if (options.lockedHistory === true)
+        lockedHistoryObjects.add(index);
 }
-function parseAlterTable(cursor, tables, source) {
+function parseAlterTable(cursor, tables, source, options) {
     cursor.expectWord('TABLE', 'after ALTER');
     const name = cursor.identifier('a table name');
     const table = tables.get(name);
@@ -587,7 +616,9 @@ function parseAlterTable(cursor, tables, source) {
     cursor.eatWord('COLUMN');
     const def = parseColumnDef(cursor, false);
     cursor.expectEnd();
-    if (!def.column.nullable) {
+    // A locked migration replays as deployed; the nullable rule applies to
+    // migrations beyond the locked prefix, where the SQL can still change.
+    if (!def.column.nullable && options.lockedHistory !== true) {
         cursor.fail(`ALTER TABLE ${name}: added column ${JSON.stringify(def.column.name)} must be nullable — SQL defaults do not backfill Syncular row payloads; add the column nullable, backfill it through versioned server-authoritative writes, and enforce required values in application validation`);
     }
     if (table.columns.some((c) => c.name === def.column.name)) {
@@ -595,6 +626,8 @@ function parseAlterTable(cursor, tables, source) {
     }
     table.columns.push(def.column);
     columnIdentifierSources.set(def.column, source);
+    if (options.lockedHistory === true)
+        lockedHistoryObjects.add(def.column);
 }
 /** `DROP TABLE [IF EXISTS] name`; table-name reuse remains unsupported. */
 function parseDropTable(cursor, tables, droppedTables) {
@@ -629,6 +662,16 @@ function parseDropIndex(cursor, tables) {
         table.indexes.splice(index, 1);
         return;
     }
+    for (const table of tables.values()) {
+        if (table.ftsIndexes.some((candidate) => candidate.name === name)) {
+            // `DROP INDEX IF EXISTS <fts>` matches SQLite: an FTS5 virtual table is
+            // no regular index, so IF EXISTS resolves to a tolerant no-op (this also
+            // keeps a locked migration carrying the statement replayable).
+            if (ifExists)
+                return;
+            cursor.fail(`DROP INDEX ${name}: ${name} is an FTS5 virtual table (CREATE VIRTUAL TABLE … USING fts5); the migration subset removes an FTS projection together with its owning content table (DROP TABLE ${table.name})`);
+        }
+    }
     if (!ifExists) {
         cursor.fail(`DROP INDEX ${name}: index does not exist at this point`);
     }
@@ -649,16 +692,16 @@ function parseDrop(cursor, tables, droppedTables) {
  * Apply one migration file's SQL to the accumulated table map. Columns
  * accumulate in declaration order — the §2.4 row-codec positional order.
  */
-export function applyMigrationSql(tables, sql, source, droppedTables = new Set()) {
+export function applyMigrationSql(tables, sql, source, droppedTables = new Set(), options = {}) {
     for (const tokens of tokenizeStatements(sql, source)) {
         const cursor = new Cursor(tokens, source);
         const head = cursor.next();
         const word = head.kind === 'word' ? head.text.toUpperCase() : '';
         if (word === 'CREATE') {
-            parseCreate(cursor, tables, droppedTables, source);
+            parseCreate(cursor, tables, droppedTables, source, options);
         }
         else if (word === 'ALTER') {
-            parseAlterTable(cursor, tables, source);
+            parseAlterTable(cursor, tables, source, options);
         }
         else if (word === 'DROP') {
             parseDrop(cursor, tables, droppedTables);

package/dist/syql-validator.js

@@ -868,19 +868,45 @@ class Validator {
             }
             return true;
         };
-        const requiredJoinEqualityAt = (index) => {
+        const joinEqualityContextAt = (index) => {
             const prefix = cleaned.slice(0, index);
             const clauses = [
                 ...prefix.matchAll(/\b(ON|JOIN|WHERE|GROUP\s+BY|ORDER\s+BY|HAVING|LIMIT|UNION|EXCEPT|INTERSECT)\b/gi),
             ];
             const last = clauses.at(-1);
             if (last?.[1]?.toUpperCase() !== 'ON')
-                return false;
+                return undefined;
             const start = (last.index ?? 0) + last[0].length;
             const next = /\b(?:JOIN|WHERE|GROUP\s+BY|ORDER\s+BY|HAVING|LIMIT|UNION|EXCEPT|INTERSECT)\b/i.exec(cleaned.slice(index));
             const end = next === null ? cleaned.length : index + next.index;
             const clause = cleaned.slice(start, end);
-            return !/\b(?:OR|NOT|SELECT|WITH)\b/i.test(clause);
+            if (/\b(?:OR|NOT|SELECT|WITH)\b/i.test(clause))
+                return undefined;
+            const join = clauses.at(-2);
+            if (join?.[1]?.toUpperCase() !== 'JOIN')
+                return undefined;
+            const joinIndex = join.index ?? 0;
+            const outerKind = /\b(LEFT|RIGHT|FULL)(?:\s+OUTER)?\s*$/i
+                .exec(prefix.slice(0, joinIndex))?.[1]
+                ?.toUpperCase();
+            if (outerKind === undefined)
+                return { kind: 'inner' };
+            // A FULL join preserves both operands, so its ON constrains neither.
+            if (outerKind === 'FULL')
+                return undefined;
+            const introducedAlias = (prefix
+                .slice(joinIndex + join[0].length, last.index)
+                .match(new RegExp(IDENT_SOURCE, 'g')) ?? [])
+                .filter((word) => word.toUpperCase() !== 'AS')
+                .at(-1)
+                ?.toLowerCase();
+            if (introducedAlias === undefined)
+                return undefined;
+            return {
+                kind: 'outer',
+                introducedAlias,
+                nullExtended: outerKind === 'LEFT' ? 'introduced' : 'prior',
+            };
         };
         const refByAlias = new Map(refs.map((ref) => [ref.alias.toLowerCase(), ref]));
         const scopeNode = (alias, column) => `${alias.toLowerCase()}\0${column.toLowerCase()}`;
@@ -903,24 +929,93 @@ class Validator {
             if (leftRoot !== rightRoot)
                 parents.set(rightRoot, leftRoot);
         };
+        /** Directed scope inheritance for outer-join ON equalities: `target`
+         * inherits `source`'s proof on every row where target's table actually
+         * contributes (matched rows of the null-extended side). The preserved
+         * side gains nothing from such an equality. */
+        const inheritSources = new Map();
+        const addInheritEdge = (target, source) => {
+            find(target);
+            find(source);
+            const sources = inheritSources.get(target) ?? new Set();
+            sources.add(source);
+            inheritSources.set(target, sources);
+        };
+        /** Every node whose direct proof also constrains `start`: the union
+         * class of `start`, plus everything reachable through directed
+         * inheritance edges (each hop stays sound because a satisfied equality
+         * needs both operands non-NULL, so the source relation contributed the
+         * row). */
+        const reachableProofNodes = (start) => {
+            const seen = new Set();
+            const queue = [start];
+            while (queue.length > 0) {
+                const node = queue.pop();
+                if (seen.has(node))
+                    continue;
+                seen.add(node);
+                const root = find(node);
+                for (const classmate of [...parents.keys()]) {
+                    if (!seen.has(classmate) && find(classmate) === root) {
+                        queue.push(classmate);
+                    }
+                }
+                for (const source of inheritSources.get(node) ?? []) {
+                    if (!seen.has(source))
+                        queue.push(source);
+                }
+            }
+            return seen;
+        };
         const scopeColumn = (alias, column) => {
             const ref = refByAlias.get(alias.toLowerCase());
             const table = this.#ir.tables.find((item) => item.name === ref?.table);
             return (table?.scopes.some((scope) => scope.column.toLowerCase() === column.toLowerCase()) === true);
         };
-        const qualifiedEquality = new RegExp(`(${IDENT_SOURCE})\\.(${IDENT_SOURCE})\\s*(?:=|==|\\bIS\\b)\\s*(${IDENT_SOURCE})\\.(${IDENT_SOURCE})`, 'gi');
+        // Scope inheritance across a join relies on a satisfied predicate proving
+        // both operands non-NULL. `IS` is null-safe (`NULL IS NULL` holds), so it
+        // would let a null-extended row on an outer join's preserved side carry a
+        // scope proof it never satisfies; only `=`/`==` qualify here.
+        const qualifiedEquality = new RegExp(`(${IDENT_SOURCE})\\.(${IDENT_SOURCE})\\s*(?:=|==)\\s*(${IDENT_SOURCE})\\.(${IDENT_SOURCE})`, 'gi');
         for (const match of cleaned.matchAll(qualifiedEquality)) {
             const leftAlias = match[1];
             const leftColumn = match[2];
             const rightAlias = match[3];
             const rightColumn = match[4];
             if (!scopeColumn(leftAlias, leftColumn) ||
-                !scopeColumn(rightAlias, rightColumn) ||
-                (!requiredAt(match.index ?? 0) &&
-                    !requiredJoinEqualityAt(match.index ?? 0))) {
+                !scopeColumn(rightAlias, rightColumn)) {
+                continue;
+            }
+            const index = match.index ?? 0;
+            const leftNode = scopeNode(leftAlias, leftColumn);
+            const rightNode = scopeNode(rightAlias, rightColumn);
+            if (requiredAt(index)) {
+                union(leftNode, rightNode);
+                continue;
+            }
+            const context = joinEqualityContextAt(index);
+            if (context === undefined)
                 continue;
+            if (context.kind === 'inner') {
+                // An inner join's ON filters every result row, so the equality
+                // constrains both operands symmetrically.
+                union(leftNode, rightNode);
+                continue;
+            }
+            const leftIntroduced = leftAlias.toLowerCase() === context.introducedAlias;
+            const rightIntroduced = rightAlias.toLowerCase() === context.introducedAlias;
+            // An equality with both operands on one side of the outer join proves
+            // nothing across it; preserved-side rows appear regardless of the ON.
+            if (leftIntroduced === rightIntroduced)
+                continue;
+            const introducedNode = leftIntroduced ? leftNode : rightNode;
+            const priorNode = leftIntroduced ? rightNode : leftNode;
+            if (context.nullExtended === 'introduced') {
+                addInheritEdge(introducedNode, priorNode);
+            }
+            else {
+                addInheritEdge(priorNode, introducedNode);
             }
-            union(scopeNode(leftAlias, leftColumn), scopeNode(rightAlias, rightColumn));
         }
         const required = new Set([...symbols.values()].flatMap((symbol) => symbol.parameter.kind === 'value' &&
             !symbol.parameter.optional &&
@@ -1002,9 +1097,9 @@ class Validator {
                 const direct = directByVariable.get(scope.variable);
                 if (direct !== undefined)
                     return [direct];
-                const root = find(scopeNode(candidate.ref.alias, scope.column));
+                const reachable = reachableProofNodes(scopeNode(candidate.ref.alias, scope.column));
                 const inherited = [...directScopeEvidence.entries()]
-                    .filter(([node]) => find(node) === root)
+                    .filter(([node]) => reachable.has(node))
                     .map(([, evidence]) => evidence);
                 const params = [
                     ...new Set(inherited.flatMap((evidence) => evidence.binding.params)),
@@ -1133,7 +1228,8 @@ class Validator {
                 fixedScopes,
             };
         });
-        coverage.sort((left, right) => left.table.localeCompare(right.table));
+        // Code-point order keeps emitted metadata byte-identical across locales.
+        coverage.sort((left, right) => left.table < right.table ? -1 : left.table > right.table ? 1 : 0);
         return { dependencies, coverage };
     }
     #validateSort(query, structure, location) {