@syncular/typegen 0.1.3 → 0.2.1

package/dist/init.js

@@ -0,0 +1,85 @@
+/**
+ * `syncular init` — drop a starter `syncular.json` + `migrations/0001_initial`
+ * into an existing project (the "add syncular to my app" path). Writes nothing
+ * that would clobber an existing manifest or migration; fails loud instead.
+ *
+ * The starter mirrors the `create-app` minimal template's schema shape so the
+ * two on-ramps agree. Kept dependency-free and pure of process concerns.
+ */
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { MANIFEST_FILENAME } from './manifest.js';
+const STARTER_MANIFEST = `{
+  "manifestVersion": 1,
+  "migrations": "./migrations",
+  "queries": "./queries",
+  "output": {
+    "ir": "./syncular.ir.json",
+    "module": "./src/syncular.generated.ts",
+    "queries": "./src/syncular.queries.ts"
+  },
+  "schemaVersions": [{ "version": 1, "through": "0001_initial" }],
+  "tables": [{ "name": "notes", "scopes": ["list:{list_id}"] }],
+  "subscriptions": [
+    {
+      "name": "notesInList",
+      "table": "notes",
+      "scopes": { "list_id": ["{listId}"] }
+    }
+  ]
+}
+`;
+const STARTER_MIGRATION = `-- Your first table. typegen reads this for the schema SHAPE (column types,
+-- primary key); the server manages its own sync_* tables and never runs it.
+CREATE TABLE notes (
+  id TEXT PRIMARY KEY,
+  list_id TEXT NOT NULL,
+  body TEXT NOT NULL,
+  updated_at_ms INTEGER NOT NULL
+);
+`;
+// A starter NAMED query (the typed .sql read tier). typegen type-checks it
+// against the schema via SQLite and emits a typed \`notesInList(client, listId)\`
+// + \`NotesInListRow\` into src/syncular.queries.ts. :listId infers to TEXT
+// (compared against notes.list_id).
+const STARTER_QUERY = `-- Every note in a list, id-ordered. Typed by SQLite against your schema.
+SELECT id, list_id, body, updated_at_ms
+FROM notes
+WHERE list_id = :listId
+ORDER BY id
+`;
+/** Errors that carry a friendly, actionable message for the CLI. */
+export class InitError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'InitError';
+    }
+}
+/**
+ * Create the starter files under `dir`. Refuses to overwrite an existing
+ * manifest or `migrations/0001_initial/up.sql`.
+ */
+export function initProject(dir) {
+    const root = resolve(dir);
+    const manifestPath = join(root, MANIFEST_FILENAME);
+    const migrationDir = join(root, 'migrations', '0001_initial');
+    const migrationPath = join(migrationDir, 'up.sql');
+    const queriesDir = join(root, 'queries');
+    const queryPath = join(queriesDir, 'notes-in-list.sql');
+    if (existsSync(manifestPath)) {
+        throw new InitError(`${manifestPath} already exists — refusing to overwrite. ` +
+            'Edit it directly, or run `syncular generate`.');
+    }
+    if (existsSync(migrationPath)) {
+        throw new InitError(`${migrationPath} already exists — refusing to overwrite.`);
+    }
+    if (existsSync(queryPath)) {
+        throw new InitError(`${queryPath} already exists — refusing to overwrite.`);
+    }
+    mkdirSync(migrationDir, { recursive: true });
+    mkdirSync(queriesDir, { recursive: true });
+    writeFileSync(manifestPath, STARTER_MANIFEST, 'utf8');
+    writeFileSync(migrationPath, STARTER_MIGRATION, 'utf8');
+    writeFileSync(queryPath, STARTER_QUERY, 'utf8');
+    return { written: [manifestPath, migrationPath, queryPath] };
+}

package/dist/ir.d.ts

@@ -0,0 +1,90 @@
+export declare const IR_VERSION = 1;
+/** The §2.4 column types (wire tags 1..8, in this order; tag 7 = blob_ref,
+ * §5.9; tag 8 = crdt, §5.10). */
+export type IrColumnType = 'string' | 'integer' | 'float' | 'boolean' | 'json' | 'bytes' | 'blob_ref' | 'crdt';
+export interface IrColumn {
+    readonly name: string;
+    readonly type: IrColumnType;
+    readonly nullable: boolean;
+    /** For a `crdt` column (§5.10.1): the merger name (default `yjs-doc`).
+     * Present only for `crdt`; serialized after `nullable` when set. */
+    readonly crdtType?: string;
+    /** §5.11: this column is encrypted end-to-end. When set, `type` is `bytes`
+     * (the wire type) and `declaredType` is the pre-flip app type. Both are IR
+     * metadata (never on the wire, like `crdtType`). Present only for encrypted
+     * columns, so non-encrypted columns stay byte-identical in the IR. */
+    readonly encrypted?: boolean;
+    /** §5.11: the app-side type of an encrypted column. Present iff `encrypted`. */
+    readonly declaredType?: IrColumnType;
+}
+/** One §3.1 scope pattern, fully resolved (no re-parsing downstream). */
+export interface IrScope {
+    readonly pattern: string;
+    readonly variable: string;
+    readonly column: string;
+}
+/**
+ * One local secondary index declared by a `CREATE [UNIQUE] INDEX` migration.
+ * Applied on BOTH sides: the client materializes it in its local SQLite, and
+ * the server creates it on the relational per-app row table
+ * (DESIGN-relational-server-storage.md "user indexes"; the sync read path
+ * itself still uses the scope inverted-index). `columns` preserves declared
+ * order (a compound index is order-sensitive). Index order within a table is
+ * declaration order.
+ */
+export interface IrIndex {
+    readonly name: string;
+    readonly columns: readonly string[];
+    readonly unique: boolean;
+}
+export interface IrTable {
+    readonly name: string;
+    readonly primaryKey: string;
+    /** Declaration order — this IS the §2.4 row-codec positional order. */
+    readonly columns: readonly IrColumn[];
+    readonly scopes: readonly IrScope[];
+    /** Local secondary indexes (§migration subset), in declaration order.
+     * Additive under irVersion 1: absent/empty for tables that declare none. */
+    readonly indexes: readonly IrIndex[];
+    /** Reserved per-table hook slot (WP-49); empty object for now. */
+    readonly extensions: Readonly<Record<string, unknown>>;
+}
+export type IrScopeValue = {
+    readonly kind: 'literal';
+    readonly value: string;
+} | {
+    readonly kind: 'parameter';
+    readonly name: string;
+};
+export interface IrSubscriptionScope {
+    readonly variable: string;
+    readonly values: readonly IrScopeValue[];
+}
+export interface IrSubscription {
+    readonly name: string;
+    readonly table: string;
+    /** Sorted by variable for stable diffs. */
+    readonly scopes: readonly IrSubscriptionScope[];
+}
+export interface IrSchemaVersion {
+    readonly version: number;
+    /** Migration names this version added, in application order. */
+    readonly migrations: readonly string[];
+}
+export interface IrDocument {
+    readonly irVersion: number;
+    /** The current (latest) generated schema version (§1.5). */
+    readonly schemaVersion: number;
+    readonly schemaVersions: readonly IrSchemaVersion[];
+    /** Manifest order — the handler-declared bootstrap order (§4.7). */
+    readonly tables: readonly IrTable[];
+    readonly subscriptions: readonly IrSubscription[];
+    /** Reserved document-level hook slot (WP-49); empty object for now. */
+    readonly extensions: Readonly<Record<string, unknown>>;
+}
+/** Recursively sort object keys so extension payloads serialize stably. */
+export declare function canonicalizeExtensions(value: unknown): unknown;
+/** Serialize with a fixed key order — byte-deterministic for equal IRs. */
+export declare function serializeIr(ir: IrDocument): string;
+/** Hash of the exact IR file bytes; stamped into generated modules. */
+export declare function irHash(irJson: string): string;

package/dist/ir.js

@@ -0,0 +1,94 @@
+/**
+ * Neutral schema IR (REVISE B5).
+ *
+ * The IR is a versioned, language-neutral JSON document: tables with the
+ * SPEC §2.4 column types (+ nullability + primary key), scope patterns
+ * (§3.1), the schema-version history (§1.5 gating), subscription templates,
+ * and a reserved `extensions` slot (the WP-49 apply/read-model hooks home —
+ * empty today, present in the schema so later emitters share one shape).
+ * Serialization is deterministic: fixed key order, sorted extension keys,
+ * 2-space indent, trailing newline — so the IR file diffs cleanly and the
+ * Swift/Kotlin emitters can hash it the same way the TS emitter does.
+ */
+import { createHash } from 'node:crypto';
+export const IR_VERSION = 1;
+/** Recursively sort object keys so extension payloads serialize stably. */
+export function canonicalizeExtensions(value) {
+    if (Array.isArray(value))
+        return value.map(canonicalizeExtensions);
+    if (value !== null && typeof value === 'object') {
+        const entries = Object.entries(value).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+        const out = {};
+        for (const [key, entry] of entries) {
+            out[key] = canonicalizeExtensions(entry);
+        }
+        return out;
+    }
+    return value;
+}
+function canonicalScopeValue(value) {
+    return value.kind === 'literal'
+        ? { kind: 'literal', value: value.value }
+        : { kind: 'parameter', name: value.name };
+}
+/** Serialize with a fixed key order — byte-deterministic for equal IRs. */
+export function serializeIr(ir) {
+    const doc = {
+        irVersion: ir.irVersion,
+        schemaVersion: ir.schemaVersion,
+        schemaVersions: ir.schemaVersions.map((v) => ({
+            version: v.version,
+            migrations: v.migrations,
+        })),
+        tables: ir.tables.map((table) => ({
+            name: table.name,
+            primaryKey: table.primaryKey,
+            columns: table.columns.map((column) => ({
+                name: column.name,
+                type: column.type,
+                nullable: column.nullable,
+                // §5.10.1: crdtType is IR metadata (never on the wire); emitted only
+                // for crdt columns so non-crdt column diffs stay byte-identical.
+                ...(column.crdtType !== undefined ? { crdtType: column.crdtType } : {}),
+                // §5.11: encrypted/declaredType are IR metadata (never on the wire);
+                // emitted only for encrypted columns so non-encrypted diffs stay
+                // byte-identical.
+                ...(column.encrypted === true
+                    ? { encrypted: true, declaredType: column.declaredType }
+                    : {}),
+            })),
+            scopes: table.scopes.map((scope) => ({
+                pattern: scope.pattern,
+                variable: scope.variable,
+                column: scope.column,
+            })),
+            // Indexes are additive under irVersion 1: emitted only when the table
+            // declares at least one, so index-free tables (every pre-index manifest)
+            // stay byte-identical and --check fresh. Declaration order preserved.
+            ...(table.indexes.length > 0
+                ? {
+                    indexes: table.indexes.map((index) => ({
+                        name: index.name,
+                        columns: index.columns,
+                        unique: index.unique,
+                    })),
+                }
+                : {}),
+            extensions: canonicalizeExtensions(table.extensions),
+        })),
+        subscriptions: ir.subscriptions.map((sub) => ({
+            name: sub.name,
+            table: sub.table,
+            scopes: sub.scopes.map((scope) => ({
+                variable: scope.variable,
+                values: scope.values.map(canonicalScopeValue),
+            })),
+        })),
+        extensions: canonicalizeExtensions(ir.extensions),
+    };
+    return `${JSON.stringify(doc, null, 2)}\n`;
+}
+/** Hash of the exact IR file bytes; stamped into generated modules. */
+export function irHash(irJson) {
+    return `sha256:${createHash('sha256').update(irJson, 'utf8').digest('hex')}`;
+}

package/dist/manifest.d.ts

@@ -0,0 +1,76 @@
+export declare const MANIFEST_FILENAME = "syncular.json";
+/** Same shorthand the server schema accepts (§3.1). */
+export type ManifestScopeSpec = string | {
+    pattern: string;
+    column: string;
+};
+export interface ManifestTable {
+    readonly name: string;
+    readonly scopes: readonly ManifestScopeSpec[];
+    readonly extensions: Readonly<Record<string, unknown>>;
+    /**
+     * §5.11: columns to encrypt end-to-end. App config (not DDL): the IR flips
+     * each named column's wire type to `bytes` and records `encrypted` +
+     * `declaredType`. Absent/empty for tables with no encryption (byte-identical
+     * IR to before this rung). Hard errors (encrypted scope/crdt/pk column, or
+     * an unknown column) are enforced at generate time.
+     */
+    readonly encryptedColumns: readonly string[];
+}
+export interface ManifestSubscription {
+    readonly name: string;
+    readonly table: string;
+    readonly scopes: Readonly<Record<string, readonly string[]>>;
+}
+export interface ManifestSchemaVersion {
+    readonly version: number;
+    readonly through: string;
+}
+/** Swift emitter output: a `.swift` path plus optional options. */
+export interface SwiftOutput {
+    readonly path: string;
+    /** The generated enum namespace (default `SyncularSchema`). */
+    readonly enumName: string;
+    /** Opt-in named-queries output path (a sibling `.swift` file). */
+    readonly queriesPath?: string;
+}
+/** Kotlin emitter output: a `.kt` path plus its package declaration. */
+export interface KotlinOutput {
+    readonly path: string;
+    /** The Kotlin package declaration (default `syncular.generated`). */
+    readonly package: string;
+    /** The generated top-level object name (default `SyncularSchema`). */
+    readonly objectName: string;
+    /** Opt-in named-queries output path (a sibling `.kt` file). */
+    readonly queriesPath?: string;
+}
+/** Dart emitter output: a `.dart` path plus optional options. */
+export interface DartOutput {
+    readonly path: string;
+    /** Opt-in named-queries output path (a sibling `.dart` file). */
+    readonly queriesPath?: string;
+}
+export interface ManifestOutput {
+    readonly ir: string;
+    readonly module: string;
+    /** Opt-in TS named-queries output path (a sibling `.ts` file). Undefined →
+     * named queries are not generated for TS. */
+    readonly queries?: string;
+    /** Opt-in native emitters; undefined → that language is not generated. */
+    readonly swift?: SwiftOutput;
+    readonly kotlin?: KotlinOutput;
+    readonly dart?: DartOutput;
+}
+export interface Manifest {
+    readonly manifestVersion: 1;
+    readonly migrations: string;
+    /** Directory of `.sql` named-query files (default `./queries`). Only read
+     * when at least one output requests a named-queries file. */
+    readonly queries: string;
+    readonly output: ManifestOutput;
+    readonly schemaVersions: readonly ManifestSchemaVersion[];
+    readonly tables: readonly ManifestTable[];
+    readonly subscriptions: readonly ManifestSubscription[];
+    readonly extensions: Readonly<Record<string, unknown>>;
+}
+export declare function parseManifest(raw: unknown): Manifest;

package/dist/manifest.js

@@ -0,0 +1,303 @@
+/**
+ * `syncular.json` manifest (REVISE B5) — designed here, minimal but
+ * forward-extensible:
+ *
+ * ```json
+ * {
+ *   "manifestVersion": 1,
+ *   "migrations": "./migrations",
+ *   "output": { "ir": "./syncular.ir.json",
+ *               "module": "./syncular.generated.ts",
+ *               "swift": "./Sources/App/Syncular.generated.swift",
+ *               "kotlin": { "path": "./Syncular.generated.kt",
+ *                           "package": "dev.example" },
+ *               "dart": "./lib/syncular.generated.dart" },
+ *   "schemaVersions": [{ "version": 1, "through": "0001_initial" }],
+ *   "tables": [{ "name": "tasks", "scopes": ["project:{project_id}"] }],
+ *   "subscriptions": [{ "name": "projectTasks", "table": "tasks",
+ *                       "scopes": { "project_id": ["{projectId}"] } }],
+ *   "extensions": {}
+ * }
+ * ```
+ *
+ * - `tables` is ordered: it is the handler-declared bootstrap order (§4.7).
+ * - `schemaVersions` is the §1.5 version history: strictly increasing
+ *   versions, each naming the last migration it includes (`through`); the
+ *   final entry must cover the final migration.
+ * - Subscription scope values are literals or whole-value `{param}`
+ *   placeholders (partial templates are unsupported).
+ * - `output.ir` / `output.module` are the always-emitted TS defaults.
+ *   `output.swift` / `output.kotlin` / `output.dart` are OPT-IN native
+ *   emitters — a bare string is the output path; an object carries
+ *   language-appropriate options (Kotlin `package`/`objectName`, Swift
+ *   `enumName`; Dart takes `path` only). This is additive within the `output`
+ *   object (the same forward-extension shape `output.ir`/`output.module`
+ *   already use); no `manifestVersion` bump — new *recognized* keys, not
+ *   tolerated-unknown ones. Absent → that language is not generated (TS
+ *   stays the default).
+ * - Unknown keys are hard errors everywhere (fail loud; growth happens by
+ *   bumping `manifestVersion`), except inside `extensions`, the reserved
+ *   WP-49 passthrough slot copied verbatim into the IR.
+ */
+import { TypegenError } from './errors.js';
+export const MANIFEST_FILENAME = 'syncular.json';
+const SOURCE = MANIFEST_FILENAME;
+function fail(message) {
+    throw new TypegenError(SOURCE, message);
+}
+function asObject(value, context) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+        fail(`${context} must be an object`);
+    }
+    return value;
+}
+function asString(value, context) {
+    if (typeof value !== 'string' || value.length === 0) {
+        fail(`${context} must be a non-empty string`);
+    }
+    return value;
+}
+function rejectUnknownKeys(obj, allowed, context) {
+    for (const key of Object.keys(obj)) {
+        if (!allowed.includes(key)) {
+            fail(`${context} has unknown key ${JSON.stringify(key)}`);
+        }
+    }
+}
+function parseExtensions(value, context) {
+    if (value === undefined)
+        return {};
+    return asObject(value, `${context}.extensions`);
+}
+function parseScopeSpec(value, context) {
+    if (typeof value === 'string')
+        return value;
+    const obj = asObject(value, context);
+    rejectUnknownKeys(obj, ['pattern', 'column'], context);
+    return {
+        pattern: asString(obj.pattern, `${context}.pattern`),
+        column: asString(obj.column, `${context}.column`),
+    };
+}
+/** Parse a native-emitter output spec: a bare path string, or an object with
+ * `path` + language options. Returns the resolved output or throws. */
+function parseSwiftOutput(value) {
+    if (typeof value === 'string') {
+        return {
+            path: asString(value, 'output.swift'),
+            enumName: 'SyncularSchema',
+        };
+    }
+    const obj = asObject(value, 'output.swift');
+    rejectUnknownKeys(obj, ['path', 'enumName', 'queriesPath'], 'output.swift');
+    return {
+        path: asString(obj.path, 'output.swift.path'),
+        enumName: obj.enumName === undefined
+            ? 'SyncularSchema'
+            : asString(obj.enumName, 'output.swift.enumName'),
+        ...(obj.queriesPath !== undefined
+            ? { queriesPath: asString(obj.queriesPath, 'output.swift.queriesPath') }
+            : {}),
+    };
+}
+function parseKotlinOutput(value) {
+    if (typeof value === 'string') {
+        return {
+            path: asString(value, 'output.kotlin'),
+            package: 'syncular.generated',
+            objectName: 'SyncularSchema',
+        };
+    }
+    const obj = asObject(value, 'output.kotlin');
+    rejectUnknownKeys(obj, ['path', 'package', 'objectName', 'queriesPath'], 'output.kotlin');
+    return {
+        path: asString(obj.path, 'output.kotlin.path'),
+        package: obj.package === undefined
+            ? 'syncular.generated'
+            : asString(obj.package, 'output.kotlin.package'),
+        objectName: obj.objectName === undefined
+            ? 'SyncularSchema'
+            : asString(obj.objectName, 'output.kotlin.objectName'),
+        ...(obj.queriesPath !== undefined
+            ? { queriesPath: asString(obj.queriesPath, 'output.kotlin.queriesPath') }
+            : {}),
+    };
+}
+function parseDartOutput(value) {
+    if (typeof value === 'string') {
+        return { path: asString(value, 'output.dart') };
+    }
+    const obj = asObject(value, 'output.dart');
+    rejectUnknownKeys(obj, ['path', 'queriesPath'], 'output.dart');
+    return {
+        path: asString(obj.path, 'output.dart.path'),
+        ...(obj.queriesPath !== undefined
+            ? { queriesPath: asString(obj.queriesPath, 'output.dart.queriesPath') }
+            : {}),
+    };
+}
+function parseTable(value, index) {
+    const context = `tables[${index}]`;
+    const obj = asObject(value, context);
+    rejectUnknownKeys(obj, ['name', 'scopes', 'extensions', 'encryptedColumns'], context);
+    const name = asString(obj.name, `${context}.name`);
+    if (!Array.isArray(obj.scopes) || obj.scopes.length === 0) {
+        fail(`table ${name}: scopes must be a non-empty array (§3.1)`);
+    }
+    let encryptedColumns = [];
+    if (obj.encryptedColumns !== undefined) {
+        if (!Array.isArray(obj.encryptedColumns)) {
+            fail(`table ${name}: encryptedColumns must be an array of column names`);
+        }
+        encryptedColumns = obj.encryptedColumns.map((c, i) => asString(c, `table ${name} encryptedColumns[${i}]`));
+        const seen = new Set();
+        for (const col of encryptedColumns) {
+            if (seen.has(col)) {
+                fail(`table ${name}: duplicate encryptedColumns entry ${JSON.stringify(col)}`);
+            }
+            seen.add(col);
+        }
+    }
+    return {
+        name,
+        scopes: obj.scopes.map((spec, i) => parseScopeSpec(spec, `table ${name} scopes[${i}]`)),
+        extensions: parseExtensions(obj.extensions, `table ${name}`),
+        encryptedColumns,
+    };
+}
+const IDENTIFIER_RE = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+function parseSubscription(value, index) {
+    const context = `subscriptions[${index}]`;
+    const obj = asObject(value, context);
+    rejectUnknownKeys(obj, ['name', 'table', 'scopes'], context);
+    const name = asString(obj.name, `${context}.name`);
+    if (!IDENTIFIER_RE.test(name)) {
+        fail(`subscription ${JSON.stringify(name)}: name must be a valid identifier`);
+    }
+    const table = asString(obj.table, `subscription ${name}: table`);
+    const scopesObj = asObject(obj.scopes, `subscription ${name}: scopes`);
+    const scopes = {};
+    for (const [variable, values] of Object.entries(scopesObj)) {
+        if (!Array.isArray(values) || values.length === 0) {
+            fail(`subscription ${name}: scopes.${variable} must be a non-empty array`);
+        }
+        scopes[variable] = values.map((v, i) => asString(v, `subscription ${name}: scopes.${variable}[${i}]`));
+    }
+    if (Object.keys(scopes).length === 0) {
+        fail(`subscription ${name}: scopes must not be empty`);
+    }
+    return { name, table, scopes };
+}
+function parseSchemaVersion(value, index) {
+    const context = `schemaVersions[${index}]`;
+    const obj = asObject(value, context);
+    rejectUnknownKeys(obj, ['version', 'through'], context);
+    const version = obj.version;
+    if (typeof version !== 'number' ||
+        !Number.isInteger(version) ||
+        version < 1) {
+        fail(`${context}.version must be an integer ≥ 1 (§1.5)`);
+    }
+    return {
+        version,
+        through: asString(obj.through, `${context}.through`),
+    };
+}
+export function parseManifest(raw) {
+    const obj = asObject(raw, 'manifest');
+    rejectUnknownKeys(obj, [
+        'manifestVersion',
+        'migrations',
+        'queries',
+        'output',
+        'schemaVersions',
+        'tables',
+        'subscriptions',
+        'extensions',
+    ], 'manifest');
+    if (obj.manifestVersion !== 1) {
+        fail(`manifestVersion must be 1, got ${JSON.stringify(obj.manifestVersion)}`);
+    }
+    const migrations = obj.migrations === undefined
+        ? './migrations'
+        : asString(obj.migrations, 'migrations');
+    const queries = obj.queries === undefined ? './queries' : asString(obj.queries, 'queries');
+    let ir = './syncular.ir.json';
+    let module = './syncular.generated.ts';
+    let queriesOut;
+    let swift;
+    let kotlin;
+    let dart;
+    if (obj.output !== undefined) {
+        const output = asObject(obj.output, 'output');
+        rejectUnknownKeys(output, ['ir', 'module', 'queries', 'swift', 'kotlin', 'dart'], 'output');
+        if (output.ir !== undefined)
+            ir = asString(output.ir, 'output.ir');
+        if (output.module !== undefined) {
+            module = asString(output.module, 'output.module');
+        }
+        if (output.queries !== undefined) {
+            queriesOut = asString(output.queries, 'output.queries');
+        }
+        if (output.swift !== undefined)
+            swift = parseSwiftOutput(output.swift);
+        if (output.kotlin !== undefined)
+            kotlin = parseKotlinOutput(output.kotlin);
+        if (output.dart !== undefined)
+            dart = parseDartOutput(output.dart);
+    }
+    // Build `output` with only the keys that are set — `exactOptionalPropertyTypes`
+    // forbids explicit `undefined` on optional properties.
+    const outputSpec = {
+        ir,
+        module,
+        ...(queriesOut !== undefined ? { queries: queriesOut } : {}),
+        ...(swift !== undefined ? { swift } : {}),
+        ...(kotlin !== undefined ? { kotlin } : {}),
+        ...(dart !== undefined ? { dart } : {}),
+    };
+    if (!Array.isArray(obj.schemaVersions) || obj.schemaVersions.length === 0) {
+        fail('schemaVersions must be a non-empty array (§1.5 version history)');
+    }
+    const schemaVersions = obj.schemaVersions.map(parseSchemaVersion);
+    for (let i = 1; i < schemaVersions.length; i++) {
+        const prev = schemaVersions[i - 1];
+        const next = schemaVersions[i];
+        if (next.version <= prev.version) {
+            fail(`schemaVersions must be strictly increasing (${prev.version} then ${next.version})`);
+        }
+    }
+    if (!Array.isArray(obj.tables) || obj.tables.length === 0) {
+        fail('tables must be a non-empty array');
+    }
+    const tables = obj.tables.map(parseTable);
+    const tableNames = new Set();
+    for (const table of tables) {
+        if (tableNames.has(table.name)) {
+            fail(`duplicate table ${JSON.stringify(table.name)}`);
+        }
+        tableNames.add(table.name);
+    }
+    const subscriptions = Array.isArray(obj.subscriptions)
+        ? obj.subscriptions.map(parseSubscription)
+        : obj.subscriptions === undefined
+            ? []
+            : fail('subscriptions must be an array');
+    const subNames = new Set();
+    for (const sub of subscriptions) {
+        if (subNames.has(sub.name)) {
+            fail(`duplicate subscription ${JSON.stringify(sub.name)}`);
+        }
+        subNames.add(sub.name);
+    }
+    return {
+        manifestVersion: 1,
+        migrations,
+        queries,
+        output: outputSpec,
+        schemaVersions,
+        tables,
+        subscriptions,
+        extensions: parseExtensions(obj.extensions, 'manifest'),
+    };
+}