@zmdb/compiler 1.0.0-beta.1

package/dist/reflect/index.js

@@ -0,0 +1,1421 @@
+// Reflection: a TypeScript type → `@zmdb/schema/ir`.
+//
+// This is the front-end that makes type-first declaration possible, and since the
+// builder DSL was deleted it is the only one (PRD §6.7, REQ-TF-4 … REQ-TF-7). It reads
+// a checker `Type` and produces plain serialisable data; from there the back-ends —
+// validator emission, JSON Schema, DDL, the schema value itself — are written against
+// the IR and know nothing about where it came from. `PLAN-type-first.md` Phase 4.
+//
+// Three rules govern everything below, and each one is a reaction to a specific bug:
+//
+//  1. **Total.** `typeIR` never throws. Every input produces a node, and anything the
+//     reflection cannot model produces `{ kind: 'unsupported', reason }`. The
+//     alternative — throwing — makes one bad property abort a whole file, and the
+//     silent alternative is worse: `f70186c6` was a transformer that inlined a
+//     *partial* parse of a type it only half understood, and a partial answer is
+//     indistinguishable from a correct one until production.
+//
+//  2. **Refusals are named.** `unsupported.reason` is prose a human can act on, not
+//     `'unknown'`. The emitter turns an `unsupported` node into a build error (plan
+//     D4), so the reason is the error message, and a vague one wastes the reader's
+//     afternoon.
+//
+//  3. **Budgeted.** Depth, node count and helper count are capped. A recursive type
+//     or a 4000-property union should degrade to a named refusal, not hang the build.
+//     Exceeding a cap is an `unsupported` node like any other, so a budget overrun
+//     stops the build the same way an unmodellable type does; two mechanisms for one
+//     outcome would only be two things to keep in sync.
+//
+// What the checker actually gives us, and what it does not, was measured rather than
+// assumed — `typescript@7` is the Go compiler behind a thin marshalling client, and
+// several `Type` members that exist in the `.d.ts` come back `undefined` over the
+// wire. The comments at each such site say which, and what is done instead.
+import {} from '@zmdb/schema';
+import { KNOWN_CONSTRAINT_KINDS, PROTO_SCALARS, RELATION_KINDS, SQL_TYPES, TAG_NAMES, } from '@zmdb/schema/ir';
+import {} from '@zmdb/schema/naming';
+import { SignatureKind, SymbolFlags } from 'typescript/unstable/sync';
+export { apiInstanceCount, projectSourceFileNames, ReflectSession, withSession } from './session.js';
+/**
+ * Deliberately generous. These are a guard against pathological input, not a style
+ * guide: a legitimate 30-deep nested JSON payload is unusual but not wrong, and a
+ * cap that fires on real code trains people to raise it rather than to read it.
+ */
+export const DEFAULT_LIMITS = { maxDepth: 32, maxNodes: 20_000, maxHelpers: 512 };
+export {} from '@zmdb/schema/naming';
+// ---------------------------------------------------------------------------
+// Tag reading
+// ---------------------------------------------------------------------------
+/**
+ * The checker reports a `unique symbol` property as `__@<name>@<symbolId>`. The id
+ * suffix is what makes plan D5 detectable: two installed copies of
+ * `@zmdb/schema` declare `zmdbSerial` twice, the two are distinct types, and the
+ * escaped names differ only in that number.
+ */
+const TAG_PATTERN = /^__@(\w+?)@?(\d*)$/;
+const PHYSICAL_TAG_NAME = 'zmdbPhysical';
+/**
+ * The tag vocabulary read the other way round: escaped symbol name → IR field.
+ *
+ * boundary: `TAG_NAMES` is keyed by `TagField`, but `Object.entries` types its keys as
+ * `string` — there is no form of it that keeps them. The assertion restores what the
+ * declaration of `TAG_NAMES` already says, and if a key were ever added that is not a
+ * `TagField`, `TAG_NAMES`' own type annotation is where that fails, not here.
+ */
+const TAG_FIELD_BY_NAME = new Map(Object.entries(TAG_NAMES).map(([field, symbolName]) => [symbolName, field]));
+/**
+ * Normalise both tag encodings without importing the type-only vocabulary.
+ *
+ * Most tags are unique-symbol properties (`__@zmdbSerial@1`). `Ext` is the single
+ * structural marker frozen by the IR contract, and the exact `__zmdbExt` spelling is
+ * recognised as the same `zmdbExt` vocabulary entry.
+ */
+function recognizedTag(symbol) {
+    const match = TAG_PATTERN.exec(symbol.escapedName);
+    const uniqueName = match?.[1];
+    if (uniqueName === PHYSICAL_TAG_NAME) {
+        return { name: uniqueName, identity: symbol.escapedName };
+    }
+    if (uniqueName !== undefined && TAG_FIELD_BY_NAME.has(uniqueName)) {
+        return { name: uniqueName, identity: symbol.escapedName };
+    }
+    // `Ext` contributes an optional structural property. A required application
+    // column with the same spelling is ordinary data and must not disappear.
+    if (symbol.name === `__${TAG_NAMES.extension}` && (symbol.flags & SymbolFlags.Optional) !== 0) {
+        return { name: TAG_NAMES.extension };
+    }
+    return undefined;
+}
+// Both vocabularies as sets, behind predicates rather than `has` plus a cast. The tags fix
+// each of these to a literal, but the checker hands them back as `string`, so this is the
+// one place the narrowing has to be earned — and a predicate earns it for every caller.
+const SQL_TYPE_SET = new Set(SQL_TYPES);
+const RELATION_KIND_SET = new Set(RELATION_KINDS);
+const PROTO_SCALAR_SET = new Set(PROTO_SCALARS);
+const REFERENTIAL_ACTION_SET = new Set([
+    'cascade',
+    'restrict',
+    'set null',
+    'set default',
+    'no action',
+]);
+const SQL_IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_]*$/;
+function isSqlType(value) {
+    return SQL_TYPE_SET.has(value);
+}
+function isRelationKind(value) {
+    return RELATION_KIND_SET.has(value);
+}
+function isProtoScalar(value) {
+    return PROTO_SCALAR_SET.has(value);
+}
+function isReferentialAction(value) {
+    return REFERENTIAL_ACTION_SET.has(value);
+}
+/** Whether a property symbol is one of our tag slots rather than real data. */
+function isTagProperty(symbol) {
+    return recognizedTag(symbol) !== undefined;
+}
+/**
+ * Whether a property is a phantom slot — keyed by a `unique symbol` — rather than data.
+ * A superset of `isTagProperty`: it also covers brands from
+ * `aot-validator/src/advanced`, `io-ts`-style nominal markers, and anyone else's
+ * phantom parameter.
+ *
+ * Treating those as data rather than as phantom is what made `Brand<number, 'UserId'>`
+ * refuse: the brand object looked like a second data part of the intersection. And a
+ * symbol-keyed property is never data in a checked position anyway — it cannot cross a
+ * JSON boundary, so there is nothing to check and nothing lost by ignoring it.
+ */
+function isPhantomProperty(symbol) {
+    return isTagProperty(symbol) || symbol.escapedName.startsWith('__@');
+}
+const OPTIONAL = SymbolFlags.Optional;
+/**
+ * One reflector per file, not per type: the budget, the helper names and the
+ * duplicate-tag detector are all whole-program facts, and splitting them per type
+ * would let a 200-type file blow past every cap one type at a time.
+ */
+export class Reflector {
+    diagnostics = [];
+    #checker;
+    #location;
+    #limits;
+    #naming;
+    #nodes = 0;
+    /** Types currently being walked, innermost last. The cycle guard. */
+    #stack = [];
+    /** Name → the type id that claimed it, so two `User`s do not share a helper. */
+    #names = new Map();
+    #anonymous = 0;
+    /** Tag basename → the full escaped name first seen for it. Plan D5. */
+    #tagIdentity = new Map();
+    constructor(checker, location, options = {}) {
+        this.#checker = checker;
+        this.#location = location;
+        this.#limits = { ...DEFAULT_LIMITS, ...options.limits };
+        this.#naming = options.naming ?? {};
+    }
+    // -------------------------------------------------------------------------
+    // Public surface
+    // -------------------------------------------------------------------------
+    /** The structural IR of a type. Total: always returns a node. */
+    typeIR(type, path = '') {
+        return this.#type(type, path, 0);
+    }
+    /**
+     * The structural IR of a protobuf message, with field-number validation enabled.
+     *
+     * Ordinary validators may reflect an object whose properties have no protobuf
+     * numbers; only a protobuf call makes complete numbering mandatory. Keeping that
+     * decision here means every protobuf back-end receives the same checked IR.
+     */
+    protobufIR(type) {
+        const name = typeName(type) ?? 'message';
+        const node = this.#type(type, name, 0);
+        this.#validateProtoNumbers(node, name, new Set());
+        return node;
+    }
+    /**
+     * Reflect a gRPC service while keeping every message on the protobuf path.
+     *
+     * The service shell is not a protobuf message: its properties are methods,
+     * and each method owns two message roots. Reflecting those roots here keeps
+     * field-number validation and every downstream codec on the one TypeIR walk.
+     */
+    grpcServiceIR(type) {
+        const methods = [];
+        for (const methodSymbol of this.#checker.getPropertiesOfType(type)) {
+            if (isTagProperty(methodSymbol))
+                continue;
+            const method = methodSymbol.name;
+            const methodType = this.#typeOf(methodSymbol);
+            if (methodType === undefined) {
+                this.#refuse(method, 'the checker did not resolve a type for this gRPC method');
+                continue;
+            }
+            const requestType = this.#grpcMember(methodType, method, 'request');
+            const responseType = this.#grpcMember(methodType, method, 'response');
+            if (requestType === undefined || responseType === undefined)
+                continue;
+            const requestName = typeName(requestType) ?? `${pascalIdentifier(method)}Request`;
+            const responseName = typeName(responseType) ?? `${pascalIdentifier(method)}Response`;
+            const request = this.#type(requestType, requestName, 0);
+            const response = this.#type(responseType, responseName, 0);
+            this.#validateProtoNumbers(request, requestName, new Set());
+            this.#validateProtoNumbers(response, responseName, new Set());
+            methods.push({
+                name: method,
+                request,
+                requestName,
+                response,
+                responseName,
+                requestStream: this.#grpcStreamFlag(methodType, method, 'requestStream'),
+                responseStream: this.#grpcStreamFlag(methodType, method, 'responseStream'),
+            });
+        }
+        if (methods.length === 0) {
+            this.#refuse(typeName(type) ?? 'service', 'a gRPC service must declare at least one method');
+        }
+        return { methods };
+    }
+    /**
+     * The schema IR of a *tagged entity* type: the only way a table's IR is produced.
+     *
+     * There used to be a second producer that read the same document back out of a builder
+     * value, and for the length of the migration the two had to agree node for node. Now this
+     * is it, so every SQL snapshot, DDL golden and JSON Schema contract in the repository is
+     * downstream of what this returns (REQ-TF-7, REQ-TF-12). `reflect.spec.ts` writes out the
+     * answer for the two-table corpus, which is what stands in for that differential.
+     */
+    schemaIR(type, fallbackTable) {
+        const tags = this.#readTags(type);
+        const table = literalOf(this.#nonNullable(tags.get('table')));
+        const name = typeName(type);
+        const tableName = typeof table === 'string' ? table : (fallbackTable ?? name ?? 'unknown');
+        const explicitPhysicalTable = this.#physicalNameOf(type);
+        const physicalTable = explicitPhysicalTable ?? (this.#naming.table === undefined ? tableName : this.#naming.table(tableName));
+        if (typeof table !== 'string') {
+            this.#refuse(name ?? 'entity', "no Table<'name'> tag; the table name cannot be guessed from the type name");
+        }
+        const columns = [];
+        const relations = [];
+        for (const symbol of this.#checker.getPropertiesOfType(type)) {
+            if (isTagProperty(symbol))
+                continue;
+            const property = symbol.name;
+            const propertyType = this.#typeOf(symbol);
+            if (!propertyType) {
+                this.#refuse(property, 'the checker did not resolve a type for this property');
+                continue;
+            }
+            // Nullability is TypeScript's job, not a tag's (REQ-TF-2). Splitting it off
+            // first is not cosmetic: `getPropertiesOfType` on `(string & Min<3>) | null`
+            // returns NOTHING, because a union only has the properties every member has and
+            // `null` has none. Reading tags off the whole property type would therefore find
+            // none, and the column would come back untagged and unconstrained.
+            const split = this.#splitNullable(propertyType);
+            const propertyTags = this.#mergeTags(split.rest);
+            const relation = this.#relationOf(property, propertyTags);
+            if (relation) {
+                relations.push(relation);
+                continue;
+            }
+            columns.push(this.#column(property, split, propertyTags, tableName));
+        }
+        const fts = literalOf(this.#nonNullable(tags.get('ftsTable')));
+        const shardKey = this.#tableColumnList('ShardKey', tags.get('shardKey'));
+        const sortKey = this.#tableColumnList('SortKey', tags.get('sortKey'));
+        const rowstore = tags.has('rowstore');
+        const softDeleteTag = this.#nonNullable(tags.get('softDelete'));
+        const softDeleteName = literalOf(softDeleteTag);
+        const primaryKey = columns.filter(c => c.primaryKey).map(c => c.name);
+        if (primaryKey.length > 1) {
+            const serialKey = columns.find(column => column.primaryKey && column.serial);
+            if (serialKey) {
+                this.#refuse(tableName, `${tableName}.${serialKey.name}: a \`Serial\` column cannot be part of a composite primary key ` +
+                    `(key is (${primaryKey.join(', ')})); give the table a single-column surrogate key or drop \`Serial\``);
+            }
+        }
+        const foreignKeys = this.#foreignKeysOf(tableName, tags, columns);
+        const columnNames = new Set(columns.map(column => column.name));
+        for (const [label, names] of [
+            ['ShardKey', shardKey],
+            ['SortKey', sortKey],
+        ]) {
+            for (const column of names ?? []) {
+                if (!columnNames.has(column)) {
+                    this.#refuse(tableName, `${label} names unknown column "${column}" on "${tableName}"`);
+                }
+            }
+        }
+        const physicalColumns = new Map();
+        for (const column of columns) {
+            const previous = physicalColumns.get(column.physicalName);
+            if (previous === undefined) {
+                physicalColumns.set(column.physicalName, column.name);
+                continue;
+            }
+            this.#refuse(tableName, `\`${previous}\` and \`${column.name}\` both map to the column \`${column.physicalName}\`; ` +
+                "rename one property or give one an explicit Physical<'…'>");
+        }
+        // A table with no primary key is refused rather than accepted with an empty one. This is
+        // the one rule `defineSchema` enforced that has no other home: it threw a `SchemaError`,
+        // synchronously, on a column map with no `primaryKey()` in it. The reason outlives the
+        // function — `findById`, `update` and `delete` all build their `WHERE` out of
+        // `primaryKey`, so an empty one compiles a statement with no conditions. `delete(1)` on a
+        // key-less table is `DELETE FROM users`.
+        if (typeof table === 'string' && primaryKey.length === 0) {
+            this.#refuse(tableName, 'no PrimaryKey column. Every table needs one: findById, update and delete build their ' +
+                'WHERE clause from it, and an empty key compiles to a statement with no conditions.');
+        }
+        const tableOptions = shardKey === undefined && sortKey === undefined && !rowstore
+            ? undefined
+            : {
+                ...(shardKey === undefined ? {} : { shardKey }),
+                ...(sortKey === undefined ? {} : { sortKey }),
+                ...(rowstore ? { rowstore: true } : {}),
+            };
+        let softDelete;
+        if (softDeleteTag !== undefined) {
+            if (typeof softDeleteName !== 'string') {
+                this.#refuse(tableName, "SoftDelete<'column'> needs a string literal column name");
+            }
+            else {
+                const column = columns.find(candidate => candidate.name === softDeleteName);
+                if (column === undefined) {
+                    this.#refuse(tableName, `SoftDelete<'${softDeleteName}'> names a column that does not exist on ${tableName}`);
+                }
+                else {
+                    if (!column.nullable) {
+                        this.#refuse(tableName, `${tableName}: SoftDelete<'${softDeleteName}'> names a non-nullable column; ` +
+                            'a soft-delete column must be nullable because IS NULL is what "live" means');
+                    }
+                    if (column.sql !== 'timestamp') {
+                        this.#refuse(tableName, `${tableName}: SoftDelete<'${softDeleteName}'> names a ${String(column.sql)} column; ` +
+                            "a soft-delete column must use Sql<'timestamp'>");
+                    }
+                    if (column.nullable && column.sql === 'timestamp')
+                        softDelete = { column: softDeleteName };
+                }
+            }
+        }
+        return {
+            table: tableName,
+            physicalTable,
+            columns,
+            primaryKey,
+            relations,
+            foreignKeys,
+            ...(typeof fts === 'string' || fts === true ? { ftsTable: fts } : {}),
+            ...(tableOptions === undefined ? {} : { tableOptions }),
+            ...(softDelete === undefined ? {} : { softDelete }),
+        };
+    }
+    /**
+     * The columns of any object type, each with its own optionality — what the JSON
+     * Schema back-end consumes (`jsonSchemaFromShape`).
+     *
+     * `schemaIR` above is for a tagged *entity*: it wants a `Table<'name'>` tag, reads
+     * relations, and computes a primary key. A document is generated from something
+     * weaker and more general — `CreateDTO<User>`, `ReadDTO<User>`, or a `Pick` of either
+     * — and none of those carry a table name, because a mapped type drops the
+     * symbol-keyed entity tags along with everything else non-string. Demanding one would
+     * make the type-driven `toJsonSchema<T>()` work on exactly one shape per table.
+     *
+     * The optionality is the type's own, read off the property symbol. That is the whole
+     * reason this is not `schemaIR` with a flag: `CreateDTO<User>` has already applied the
+     * "a column with a default may be omitted" rule that the `'create'` variant applies by
+     * hand, and reading it back off the type is what makes the two paths agree by
+     * construction rather than by a rule written twice.
+     *
+     * Relations are skipped, as they are in `schemaIR`: a join target is not a column and
+     * has no place in a column's document. `toJsonSchemaWithRelations` adds `$ref`s on top.
+     */
+    shapeIR(type) {
+        const shape = [];
+        for (const symbol of this.#checker.getPropertiesOfType(type)) {
+            if (isTagProperty(symbol))
+                continue;
+            const property = symbol.name;
+            const propertyType = this.#typeOf(symbol);
+            if (!propertyType) {
+                this.#refuse(property, 'the checker did not resolve a type for this property');
+                continue;
+            }
+            // Same order as `schemaIR`, and for the same reason: reading tags off
+            // `(string & Min<3>) | null` finds none, because a union only has the properties
+            // every member has and `null` has none.
+            const split = this.#splitNullable(propertyType);
+            const propertyTags = this.#mergeTags(split.rest);
+            if (this.#relationOf(property, propertyTags))
+                continue;
+            shape.push({
+                column: this.#column(property, split, propertyTags),
+                optional: (symbol.flags & OPTIONAL) !== 0,
+            });
+        }
+        return shape;
+    }
+    // -------------------------------------------------------------------------
+    // Structural walk
+    // -------------------------------------------------------------------------
+    #type(type, path, depth) {
+        if (depth > this.#limits.maxDepth) {
+            return this.#unsupported(path, `nesting deeper than ${this.#limits.maxDepth} levels`);
+        }
+        if (++this.#nodes > this.#limits.maxNodes) {
+            return this.#unsupported(path, `more than ${this.#limits.maxNodes} IR nodes in one file`);
+        }
+        // A type parameter is not a type yet. Reflecting `T` would produce a check for
+        // whatever constraint it happens to have, which is a check for the wrong thing,
+        // so it is refused where it is written rather than at the instantiation site.
+        if (type.isTypeParameter()) {
+            return this.#unsupported(path, 'a generic type parameter has no shape to reflect', this.#print(type));
+        }
+        if (type.isErrorType()) {
+            return this.#unsupported(path, 'the checker could not resolve this type', this.#print(type));
+        }
+        const intrinsic = this.#intrinsic(type, path);
+        if (intrinsic)
+            return intrinsic;
+        const literal = this.#literal(type, path);
+        if (literal)
+            return literal;
+        const template = this.#template(type, path);
+        if (template)
+            return template;
+        if (type.isUnionType())
+            return this.#union(type.getTypes(), path, depth);
+        if (type.isIntersectionType())
+            return this.#intersection(type, path, depth);
+        return this.#object(type, path, depth, this.#readTags(type));
+    }
+    /** `string`, `number`, `null`, `never`, … — everything with an `intrinsicName`. */
+    #intrinsic(type, path) {
+        if (!type.isIntrinsicType())
+            return undefined;
+        switch (type.intrinsicName) {
+            case 'string':
+                return { kind: 'scalar', scalar: 'string' };
+            case 'number':
+                return { kind: 'scalar', scalar: 'number' };
+            case 'boolean':
+                return { kind: 'scalar', scalar: 'boolean' };
+            case 'bigint':
+                return { kind: 'scalar', scalar: 'bigint' };
+            case 'null':
+                return { kind: 'null' };
+            case 'undefined':
+            case 'void':
+                return { kind: 'undefined' };
+            // `any` and `unknown` are refused rather than mapped to `UnknownIR`. That node
+            // means "a `json` column whose payload shape was not declared", where accepting
+            // anything is the documented contract. In a validated position it would mean a
+            // validator that always passes, which is a hole with a green test beside it.
+            case 'any':
+                return this.#unsupported(path, '`any` disables the check it would have to emit; declare the shape');
+            case 'unknown':
+                return this.#unsupported(path, '`unknown` has no shape to check; declare the shape or use a `json` payload');
+            case 'never':
+                return this.#unsupported(path, '`never` has no values, so no check can succeed');
+            case 'object':
+                return this.#unsupported(path, 'bare `object` has no properties to check; declare them');
+            case 'symbol':
+                return this.#unsupported(path, 'a symbol cannot cross a JSON boundary');
+            default:
+                return this.#unsupported(path, `unhandled primitive \`${type.intrinsicName}\``);
+        }
+    }
+    #literal(type, path) {
+        if (type.isStringLiteralType() || type.isNumberLiteralType() || type.isBooleanLiteralType()) {
+            return { kind: 'literal', value: type.value };
+        }
+        // A bigint literal has no JSON spelling and `LiteralIR.value` deliberately does
+        // not admit one — a `bigint` column is a string on the wire (plan D3), and a
+        // *literal* bigint would have to pick a side.
+        if (type.isBigIntLiteralType()) {
+            return this.#unsupported(path, 'a bigint literal type has no wire representation', this.#print(type));
+        }
+        return undefined;
+    }
+    /**
+     * `` `${string}@${string}` `` → a `string` with a derived `pattern`. Needed for its
+     * own sake, and needed because without it a template literal type falls through to
+     * `#object`: `string` carries a numeric index signature, so the refusal it would
+     * collect is "`Record<string, T>` cannot be modelled", which is true of neither the
+     * type nor the problem.
+     *
+     * Only placeholders with an exact character class are derivable. `Uppercase<string>`
+     * is not one, and guessing `[\s\S]*` for it would produce a pattern that accepts
+     * strings the type rejects — a validator that is wrong in the permissive direction.
+     */
+    #template(type, path) {
+        if (type.isStringMappingType()) {
+            return this.#unsupported(path, 'a string-mapping type (`Uppercase`, `Capitalize`, …) has no equivalent pattern; spell the constraint with `Pattern<…>`', this.#print(type));
+        }
+        if (!type.isTemplateLiteralType())
+            return undefined;
+        const spans = type.getTypes();
+        const parts = [];
+        for (const [index, text] of type.texts.entries()) {
+            parts.push(escapeRegExp(text));
+            const span = spans[index];
+            if (span === undefined)
+                continue;
+            const source = placeholderPattern(span);
+            if (source === undefined) {
+                return this.#unsupported(path, `the placeholder \`${this.#print(span)}\` in this template literal type has no equivalent pattern; spell the constraint with \`Pattern<…>\``, this.#print(type));
+            }
+            parts.push(source);
+        }
+        return { kind: 'scalar', scalar: 'string', constraints: { pattern: `^${parts.join('')}$` } };
+    }
+    #union(members, path, depth) {
+        // `boolean` is `true | false` in the checker, not an intrinsic. Recognising it
+        // here is load-bearing: without it the walk falls through to the object branch
+        // and emits a property check for a primitive.
+        //
+        // The data part, not the member itself: `boolean & Sql<'boolean'>` is normalised by
+        // the checker into `(false & Sql<'boolean'>) | (true & Sql<'boolean'>)` — the same
+        // distribution that makes `(T | null) & Unique` a trap — so a tagged boolean column
+        // arrives here as two *intersections*. Reading through them is what stops a tagged
+        // boolean column emitting two literal comparisons where a `typeof` check is meant.
+        if (members.length === 2 && members.every(m => this.#dataPart(m).isBooleanLiteralType())) {
+            return this.#applyConstraints({ kind: 'scalar', scalar: 'boolean' }, this.#mergeTags(members));
+        }
+        // The checker sorts `null` and `undefined` to the FRONT of a union. `../ir`'s
+        // `withNull` puts them at the back, and the IR has to say one of the two — a union
+        // whose member order depends on which producer built it turns every golden into
+        // `[null, string]` in one place and `[string, null]` in another.
+        const nullish = (m) => m.isIntrinsicType() && (m.intrinsicName === 'null' || m.intrinsicName === 'undefined');
+        const ordered = [...members.filter(m => !nullish(m)), ...members.filter(nullish)];
+        return { kind: 'union', members: ordered.map(m => this.#type(m, path, depth + 1)) };
+    }
+    /**
+     * `number & Min<18>` is an intersection of one data part and one tag part. The tags
+     * were already collected by the caller's `#readTags` over the whole intersection —
+     * they are just properties — so this only has to find the part that carries data.
+     */
+    // Typed `IntersectionType` rather than `Type`: `getTypes()` only exists on the
+    // narrowed form, and the `isIntersectionType()` guard at the call site is what
+    // establishes it. Widening the parameter here would throw the narrowing away.
+    #intersection(type, path, depth) {
+        const tags = this.#readTags(type);
+        const parts = type.getTypes().filter(part => !this.#isTagOnly(part));
+        if (parts.length === 0) {
+            return this.#unsupported(path, 'a tags-only intersection carries no value', this.#print(type));
+        }
+        const [sole] = parts;
+        if (parts.length === 1 && sole !== undefined) {
+            return this.#applyConstraints(this.#type(sole, path, depth), tags);
+        }
+        // Several data parts: only an intersection of object types has a meaning we can
+        // check (merge the properties). Anything else — `string & number` — is `never` in
+        // practice and a mistake in the declaration.
+        if (parts.every(part => this.#isPlainObject(part))) {
+            return this.#object(type, path, depth, tags);
+        }
+        return this.#unsupported(path, 'an intersection of unrelated non-object types cannot be checked', this.#print(type));
+    }
+    #object(type, path, depth, tags) {
+        const checker = this.#checker;
+        // Order matters here, and it is not arbitrary. Arrays and tuples have a numeric
+        // index signature, so they must be recognised before the index-signature refusal;
+        // `Date` is an interface, so it must be recognised before the property walk.
+        if (checker.isArrayType(type)) {
+            const element = this.#typeArguments(type)[0];
+            if (!element)
+                return this.#unsupported(path, 'an array type with no element type', this.#print(type));
+            return this.#applyConstraints({ kind: 'array', element: this.#type(element, `${path}[]`, depth + 1) }, tags);
+        }
+        if (checker.isTupleType(type))
+            return this.#tuple(type, path, depth);
+        const symbol = type.getSymbol();
+        if (symbol?.name === 'Date')
+            return this.#applyConstraints({ kind: 'scalar', scalar: 'date' }, tags);
+        // A class instance is refused for a reason that is easy to miss: its *declared*
+        // shape is checkable, but a validated value that passes it is a plain object, not
+        // an instance, so private state, prototype methods and `instanceof` are all
+        // silently absent. Naming the refusal is honest; pretending is not.
+        if (symbol && (symbol.flags & SymbolFlags.Class) !== 0) {
+            return this.#unsupported(path, `\`${symbol.name}\` is a class; a checked value is a plain object, not an instance`);
+        }
+        if (checker.getSignaturesOfType(type, SignatureKind.Call).length > 0) {
+            return this.#unsupported(path, 'a function cannot be validated or serialised', this.#print(type));
+        }
+        if (checker.getSignaturesOfType(type, SignatureKind.Construct).length > 0) {
+            return this.#unsupported(path, 'a constructor cannot be validated or serialised', this.#print(type));
+        }
+        if (this.#hasIndexSignature(type)) {
+            // Measured, not assumed: `getPropertiesOfType` does not surface index
+            // signatures at all, and `getIndexInfosOfType` returns entries whose `keyType`
+            // the client fails to marshal. So an index signature is *detectable* but not
+            // *readable*, and a `Record<string, T>` would otherwise reflect as an object
+            // with zero properties — a validator that accepts `{}` and everything else.
+            return this.#unsupported(path, 'an index signature is not readable through the checker API, so `Record<string, T>` cannot be modelled', this.#print(type));
+        }
+        const properties = checker
+            .getPropertiesOfType(type)
+            .filter(s => !isPhantomProperty(s))
+            .map(member => ({ member, type: this.#typeOf(member) }));
+        if (properties.length === 0) {
+            return this.#unsupported(path, 'an object type with no properties admits every object', this.#print(type));
+        }
+        // A method makes this a behavioural type rather than a data type, and refusing it
+        // here — naming the type — is what rules out `Map`, `Set`, `Promise`, a typed array
+        // and any class with a prototype method. One rule instead of a list of special
+        // cases, and the message points at the property that gave it away.
+        const method = properties.find(p => p.type !== undefined && checker.getSignaturesOfType(p.type, SignatureKind.Call).length > 0);
+        if (method) {
+            return this.#unsupported(path, `\`${this.#print(type)}\` has a method (\`${method.member.name}\`); only data types can be checked`);
+        }
+        const cycle = this.#stack.find(frame => frame.id === type.id);
+        if (cycle) {
+            cycle.referenced = true;
+            cycle.name ??= this.#claimName(`Anonymous${++this.#anonymous}`, type.id);
+            return { kind: 'ref', name: cycle.name };
+        }
+        const declared = typeName(type);
+        const frame = {
+            id: type.id,
+            name: declared === undefined ? undefined : this.#claimName(declared, type.id),
+            referenced: false,
+        };
+        this.#stack.push(frame);
+        const members = [];
+        for (const { member, type: propertyType } of properties) {
+            const childPath = path === '' ? member.name : `${path}.${member.name}`;
+            const propertyTags = propertyType === undefined
+                ? new Map()
+                : this.#mergeTags(this.#splitNullable(propertyType).rest);
+            const protoFieldType = this.#nonNullable(propertyTags.get('protoField'));
+            const protoField = numberOf(protoFieldType);
+            if (protoFieldType !== undefined && protoField === undefined) {
+                this.#refuse(childPath, 'ProtoField<N> needs a number literal argument', this.#print(protoFieldType));
+            }
+            members.push({
+                name: member.name,
+                type: propertyType
+                    ? this.#type(propertyType, childPath, depth + 1)
+                    : this.#unsupported(childPath, 'the checker did not resolve a type for this property'),
+                // An optional property's type does NOT carry `| undefined` here, even under
+                // `exactOptionalPropertyTypes` — the checker reports `nickname?: string` as
+                // `string`. So `optional` is the only record of absence being allowed, and an
+                // emitter that ignores it produces a validator that rejects every value the
+                // type accepts.
+                optional: (member.flags & OPTIONAL) !== 0,
+                // `readonly` is not marshalled onto the symbol, and it is not a runtime
+                // distinction anyway: it constrains writes, and validation reads. Recorded as
+                // `false` rather than guessed at.
+                readonly: false,
+                ...(protoField === undefined ? {} : { protoField }),
+            });
+        }
+        this.#stack.pop();
+        if (frame.name !== undefined && this.#names.size > this.#limits.maxHelpers) {
+            return this.#unsupported(path, `more than ${this.#limits.maxHelpers} named object types in one file`);
+        }
+        return { kind: 'object', ...(frame.name === undefined ? {} : { name: frame.name }), properties: members };
+    }
+    #tuple(type, path, depth) {
+        // `TupleType.elementFlags` is in the `.d.ts` but comes back `undefined` over the
+        // client, so optional and rest elements are not distinguishable structurally.
+        // They ARE visible in the printed form, and refusing on that is better than
+        // emitting a fixed-length check for a variadic tuple.
+        const printed = this.#print(type);
+        if (/[?.]/.test(printed.slice(printed.indexOf('[')))) {
+            return this.#unsupported(path, 'a tuple with optional or rest elements is not modelled', printed);
+        }
+        const elements = this.#typeArguments(type);
+        return { kind: 'tuple', elements: elements.map((el, i) => this.#type(el, `${path}[${i}]`, depth + 1)) };
+    }
+    // -------------------------------------------------------------------------
+    // Tags
+    // -------------------------------------------------------------------------
+    /**
+     * Every tag slot on a type, keyed by the IR field it sets. Reads the whole type
+     * rather than an intersection part, because a tag *is* a property and the checker
+     * already merged them.
+     */
+    #readTags(type) {
+        const found = new Map();
+        for (const symbol of this.#checker.getPropertiesOfType(type)) {
+            const tag = recognizedTag(symbol);
+            if (tag === undefined)
+                continue;
+            this.#rememberTagIdentity(symbol, tag);
+            const field = TAG_FIELD_BY_NAME.get(tag.name);
+            if (field === undefined)
+                continue;
+            const value = this.#typeOf(symbol);
+            if (value)
+                found.set(field, value);
+        }
+        return found;
+    }
+    /** The public `Physical<Name>` tag's dedicated table-or-column reader. */
+    #physicalNameOf(type) {
+        for (const symbol of this.#checker.getPropertiesOfType(type)) {
+            const tag = recognizedTag(symbol);
+            if (tag?.name !== PHYSICAL_TAG_NAME)
+                continue;
+            this.#rememberTagIdentity(symbol, tag);
+            const value = this.#typeOf(symbol);
+            const physical = value === undefined ? undefined : literalOf(this.#nonNullable(value));
+            if (typeof physical === 'string')
+                return physical;
+            this.#refuse(symbol.name, 'Physical<Name> needs a string literal argument');
+        }
+        return undefined;
+    }
+    #physicalNameFrom(members) {
+        let physical;
+        for (const member of members)
+            physical = this.#physicalNameOf(member) ?? physical;
+        return physical;
+    }
+    #rememberTagIdentity(symbol, tag) {
+        if (tag.identity === undefined)
+            return;
+        const first = this.#tagIdentity.get(tag.name);
+        if (first === undefined) {
+            this.#tagIdentity.set(tag.name, tag.identity);
+            return;
+        }
+        if (first === tag.identity)
+            return;
+        this.#refuse(symbol.name, `the tag \`${tag.name}\` resolves to two different declarations (\`${first}\` and \`${tag.identity}\`), ` +
+            'which means two copies of @zmdb/schema are installed; deduplicate them');
+    }
+    /** Union members, minus `null` and `undefined`, plus whether either was there. */
+    #splitNullable(type) {
+        const members = type.isUnionType() ? type.getTypes() : [type];
+        const isNullish = (m) => m.isIntrinsicType() && (m.intrinsicName === 'null' || m.intrinsicName === 'undefined');
+        return {
+            nullable: members.some(m => m.isIntrinsicType() && m.intrinsicName === 'null'),
+            optional: members.some(m => m.isIntrinsicType() && m.intrinsicName === 'undefined'),
+            rest: members.filter(m => !isNullish(m)),
+        };
+    }
+    /** Tags from every member of a union. A tag on one arm is a tag on the column. */
+    #mergeTags(members) {
+        const [only] = members;
+        if (members.length === 1 && only !== undefined)
+            return this.#readTags(only);
+        const merged = new Map();
+        for (const member of members)
+            for (const [field, value] of this.#readTags(member))
+                merged.set(field, value);
+        return merged;
+    }
+    /** `string & Length<64>` → `string`. A type with no tag parts is its own data part. */
+    #dataPart(type) {
+        // Written as a positive branch rather than an early return on the negation: the
+        // `this is IntersectionType` predicate does not survive `if (!…) return`, and
+        // without it `getTypes()` is not in scope.
+        if (type.isIntersectionType()) {
+            const parts = type.getTypes().filter(part => !this.#isTagOnly(part));
+            const [sole] = parts;
+            return parts.length === 1 && sole !== undefined ? sole : type;
+        }
+        return type;
+    }
+    /**
+     * A type whose every property is a phantom slot: `Min<18>`, `Serial`, `Table<'t'>`,
+     * and equally `{ readonly [__brand]: 'UserId' }`. Deliberately not restricted to
+     * *our* tags — see `isPhantomProperty`.
+     */
+    #isTagOnly(type) {
+        const properties = this.#checker.getPropertiesOfType(type);
+        return properties.length > 0 && properties.every(isPhantomProperty);
+    }
+    #isPlainObject(type) {
+        return (type.isObjectType() &&
+            !this.#checker.isArrayType(type) &&
+            !this.#checker.isTupleType(type) &&
+            this.#checker.getSignaturesOfType(type, SignatureKind.Call).length === 0);
+    }
+    /** Fold `Min`/`Max`/`MinLength`/`MaxLength`/`Pattern` into a scalar or array node. */
+    #applyConstraints(node, tags) {
+        if (node.kind !== 'scalar' && node.kind !== 'array')
+            return node;
+        // The node may already carry constraints its *structure* implied — a template
+        // literal type derives a `pattern`. Tags win per keyword, so an explicit
+        // `Pattern<…>` overrides the derived one, but a `MinLength<3>` beside a template
+        // literal type does not silently erase it.
+        const constraints = { ...node.constraints, ...this.#constraintsFromTags(tags) };
+        // `Sql<'integer'>` on a `number` narrows the scalar: the emitter's integrality
+        // check comes from the SQL type, never from a `Min<1>` that happens to be there.
+        let scalar = node.kind === 'scalar' ? node.scalar : undefined;
+        const sql = this.#sqlOf(tags);
+        if (scalar === 'number' && (sql === 'integer' || sql === 'serial'))
+            scalar = 'integer';
+        // `Length<N>` is `varchar(N)`; it is also a maximum, and the explicit
+        // `MaxLength<N>` wins when both are present.
+        const length = numberOf(this.#nonNullable(tags.get('length')));
+        if (length !== undefined && constraints.maxLength === undefined)
+            constraints.maxLength = length;
+        if (node.kind === 'array') {
+            return Object.keys(constraints).length === 0 ? node : { ...node, constraints };
+        }
+        const proto = this.#protoScalarOf(tags);
+        return {
+            ...node,
+            ...(scalar === undefined ? {} : { scalar }),
+            ...(proto === undefined ? {} : { proto }),
+            ...(Object.keys(constraints).length === 0 ? {} : { constraints }),
+        };
+    }
+    #constraintsFromTags(tags) {
+        const out = {};
+        for (const kind of KNOWN_CONSTRAINT_KINDS) {
+            const value = this.#nonNullable(tags.get(kind));
+            if (!value)
+                continue;
+            if (kind === 'pattern') {
+                const pattern = literalOf(value);
+                if (typeof pattern === 'string')
+                    out.pattern = pattern;
+                else
+                    this.#refuse(kind, 'Pattern<S> needs a string literal argument', this.#print(value));
+                continue;
+            }
+            const bound = numberOf(value);
+            if (bound !== undefined)
+                out[kind] = bound;
+            else
+                this.#refuse(kind, `${kind} needs a number literal argument`, this.#print(value));
+        }
+        return out;
+    }
+    #sqlOf(tags) {
+        const declared = literalOf(this.#nonNullable(tags.get('sql')));
+        if (typeof declared !== 'string')
+            return undefined;
+        if (!isSqlType(declared)) {
+            this.#refuse('sql', `\`${declared}\` is not a SQL type; expected one of ${SQL_TYPES.join(', ')}`);
+            return undefined;
+        }
+        return declared;
+    }
+    #extensionOf(property, tags) {
+        const spec = this.#nonNullable(tags.get('extension'));
+        if (spec === undefined)
+            return undefined;
+        if (!this.#checker.isTupleType(spec)) {
+            this.#refuse(property, 'Ext<E, N, A> needs an extension name, type name and argument tuple', this.#print(spec));
+            return undefined;
+        }
+        const [extensionType, nameType, argsType] = this.#typeArguments(spec);
+        const extension = literalOf(extensionType);
+        const name = literalOf(nameType);
+        if (typeof extension !== 'string' || typeof name !== 'string' || argsType === undefined) {
+            this.#refuse(property, 'Ext<E, N, A> needs literal extension and type names plus an argument tuple', this.#print(spec));
+            return undefined;
+        }
+        if (!SQL_IDENTIFIER.test(name)) {
+            this.#refuse(property, `extension type name \`${name}\` is not a SQL identifier`, name);
+            return undefined;
+        }
+        if (!this.#checker.isTupleType(argsType)) {
+            this.#refuse(property, 'Ext<E, N, A> arguments must be a tuple of string or number literals', this.#print(argsType));
+            return undefined;
+        }
+        const args = [];
+        for (const argumentType of this.#typeArguments(argsType)) {
+            const argument = literalOf(argumentType);
+            if (typeof argument === 'number' && Number.isFinite(argument)) {
+                args.push(argument);
+                continue;
+            }
+            if (typeof argument === 'string' && SQL_IDENTIFIER.test(argument)) {
+                args.push(argument);
+                continue;
+            }
+            this.#refuse(property, 'extension type arguments must be finite number literals or SQL identifiers', this.#print(argumentType));
+            return undefined;
+        }
+        return { extension, name, ...(args.length === 0 ? {} : { args }) };
+    }
+    #protoScalarOf(tags) {
+        const tagged = this.#nonNullable(tags.get('protoScalar'));
+        const declared = literalOf(tagged);
+        if (declared === undefined)
+            return undefined;
+        if (typeof declared === 'string' && isProtoScalar(declared))
+            return declared;
+        this.#refuse('protoScalar', `Proto<K> needs one protobuf scalar literal; expected one of ${PROTO_SCALARS.join(', ')}`, tagged === undefined ? undefined : this.#print(tagged));
+        return undefined;
+    }
+    // -------------------------------------------------------------------------
+    // Protobuf field numbering
+    // -------------------------------------------------------------------------
+    #validateProtoNumbers(node, path, seen) {
+        switch (node.kind) {
+            case 'object': {
+                if (seen.has(node))
+                    return;
+                seen.add(node);
+                const message = node.name ?? path;
+                const numbered = new Map();
+                for (const property of node.properties) {
+                    const propertyPath = `${message}.${property.name}`;
+                    const number = property.protoField;
+                    if (number === undefined) {
+                        this.#refuse(propertyPath, `protobuf message \`${message}\` property \`${property.name}\` has no ProtoField<N> field number`);
+                    }
+                    else if (!Number.isInteger(number) || number < 1 || number > 536_870_911) {
+                        this.#refuse(propertyPath, `protobuf field number ${number} on \`${message}.${property.name}\` is outside the valid range 1 … 536870911`);
+                    }
+                    else if (number >= 19_000 && number <= 19_999) {
+                        this.#refuse(propertyPath, `protobuf field number ${number} on \`${message}.${property.name}\` is in the reserved range 19000 … 19999`);
+                    }
+                    else {
+                        const group = numbered.get(number);
+                        if (group)
+                            group.push(property);
+                        else
+                            numbered.set(number, [property]);
+                    }
+                    this.#validateProtoNumbers(property.type, propertyPath, seen);
+                }
+                for (const [number, properties] of numbered) {
+                    if (properties.length < 2)
+                        continue;
+                    const names = properties.map(property => `\`${property.name}\``).join(', ');
+                    for (const property of properties) {
+                        this.#refuse(`${message}.${property.name}`, `protobuf field number ${number} is duplicated by properties ${names} in message \`${message}\``);
+                    }
+                }
+                return;
+            }
+            case 'array':
+                this.#validateProtoNumbers(node.element, `${path}[]`, seen);
+                return;
+            case 'tuple':
+                for (const [index, element] of node.elements.entries()) {
+                    this.#validateProtoNumbers(element, `${path}[${index}]`, seen);
+                }
+                return;
+            case 'union':
+                for (const member of node.members)
+                    this.#validateProtoNumbers(member, path, seen);
+                return;
+            default:
+                return;
+        }
+    }
+    // -------------------------------------------------------------------------
+    // Columns and relations
+    // -------------------------------------------------------------------------
+    #relationOf(property, tags) {
+        const spec = this.#nonNullable(tags.get('relation'));
+        if (!spec)
+            return undefined;
+        const read = (name) => {
+            const symbol = this.#checker.getPropertyOfType(spec, name);
+            if (!symbol)
+                return undefined;
+            const type = this.#typeOf(symbol);
+            return type ? literalOf(type) : undefined;
+        };
+        const kind = read('kind');
+        const target = read('target');
+        // `manyToMany` carries a join table, the other three carry a foreign key. One IR
+        // field (`via`) covers both, because every back-end wants "the thing that joins".
+        const via = read('fk') ?? read('through');
+        if (typeof kind !== 'string' || typeof target !== 'string' || typeof via !== 'string') {
+            this.#refuse(property, 'a relation tag needs literal target and foreign-key arguments', this.#print(spec));
+            return undefined;
+        }
+        // Each of the four tags fixes `kind` to a literal, so reaching this refusal means a
+        // hand-written `[zmdbRelation]` payload. Checked anyway, for the reason `#sqlOf` checks:
+        // an unrecognised cardinality would otherwise reach the SQL back-ends as one, and be
+        // read there as whichever branch fell through.
+        if (!isRelationKind(kind)) {
+            this.#refuse(property, `\`${kind}\` is not a relation kind; expected one of ${RELATION_KINDS.join(', ')}`);
+            return undefined;
+        }
+        return { name: property, relation: kind, target, via };
+    }
+    #foreignKeysOf(table, tags, columns) {
+        const spec = this.#nonNullable(tags.get('foreignKeys'));
+        if (!spec)
+            return [];
+        const read = (name) => {
+            const symbol = this.#checker.getPropertyOfType(spec, name);
+            if (!symbol)
+                return undefined;
+            const type = this.#typeOf(symbol);
+            return type ? literalOf(type) : undefined;
+        };
+        const local = read('columns');
+        const targetTable = read('targetTable');
+        const target = read('targetColumns');
+        if (typeof local !== 'string' || typeof targetTable !== 'string' || typeof target !== 'string') {
+            this.#refuse(table, 'ForeignKey<LocalColumns, TargetTable, TargetColumns> needs three string-literal arguments', this.#print(spec));
+            return [];
+        }
+        const split = (value) => value.split(',').map(column => column.trim());
+        const localColumns = split(local);
+        const targetColumns = split(target);
+        if (localColumns.length !== targetColumns.length ||
+            localColumns.some(column => column.length === 0) ||
+            targetColumns.some(column => column.length === 0)) {
+            this.#refuse(table, `ForeignKey declares ${localColumns.length} local ${localColumns.length === 1 ? 'column' : 'columns'} ` +
+                `and ${targetColumns.length} target ${targetColumns.length === 1 ? 'column' : 'columns'}; ` +
+                'the lists must be positionally paired and have equal lengths');
+            return [];
+        }
+        const declared = new Set(columns.map(column => column.name));
+        const missing = localColumns.filter(column => !declared.has(column));
+        if (missing.length > 0) {
+            this.#refuse(table, `ForeignKey names ${missing.map(column => `\`${column}\``).join(', ')}, ` +
+                `${missing.length === 1 ? 'which is not a column' : 'which are not columns'} on \`${table}\``);
+            return [];
+        }
+        return [{ columns: localColumns, targetTable, targetColumns }];
+    }
+    #referentialAction(property, tag, declared) {
+        const spec = this.#nonNullable(declared);
+        if (!spec)
+            return undefined;
+        const value = literalOf(spec);
+        if (typeof value === 'string' && isReferentialAction(value))
+            return value;
+        this.#refuse(property, `${tag}<Action> needs one of ${[...REFERENTIAL_ACTION_SET].map(action => `'${action}'`).join(', ')}`, this.#print(spec));
+        return undefined;
+    }
+    #column(property, split, tags, declaredTable) {
+        const { nullable, rest } = split;
+        const explicitPhysicalName = this.#physicalNameFrom(rest);
+        const physicalName = explicitPhysicalName ??
+            (declaredTable === undefined || this.#naming.column === undefined
+                ? property
+                : this.#naming.column(property, { table: declaredTable }));
+        // `('admin' | 'viewer') & Sql<'jsonEnum'>` does not stay written that way: an
+        // intersection containing a union normalises to a union of intersections, so each
+        // member arrives with the tag attached. Stripping the tag parts is what makes the
+        // literal union visible again.
+        const data = rest.map(member => this.#dataPart(member));
+        // A column whose data part is nothing but tags. Worth its own message because the
+        // way a reader gets here is not by writing `Sql<'json'>` on its own — it is by
+        // writing `unknown & Sql<'json'>` and not knowing that `unknown & X` *is* `X`, so
+        // the type they think they declared is gone before the reflection ever sees it.
+        const [first] = data;
+        if (first !== undefined && data.every(member => this.#isTagOnly(member))) {
+            this.#refuse(property, "the tags carry no type: `unknown & X` collapses to `X` — an unshaped JSON payload is `object & Sql<'json'>`", this.#print(first));
+        }
+        const enumValues = literalUnion(data);
+        const declaredSql = this.#sqlOf(tags);
+        const extension = this.#extensionOf(property, tags);
+        if (declaredSql !== undefined && extension !== undefined) {
+            this.#refuse(property, 'a column cannot carry both Sql<…> and Ext<…>; choose one database type');
+        }
+        const constraints = this.#constraintsFromTags(tags);
+        const length = numberOf(this.#nonNullable(tags.get('length')));
+        const precision = this.#precisionOf(tags);
+        const references = literalOf(this.#nonNullable(tags.get('references')));
+        const onDelete = this.#referentialAction(property, 'OnDelete', tags.get('onDelete'));
+        const onUpdate = this.#referentialAction(property, 'OnUpdate', tags.get('onUpdate'));
+        const codec = literalOf(this.#nonNullable(tags.get('codec')));
+        const wire = this.#nonNullable(tags.get('wire'));
+        // `Serial` implies a database default. Not an inference for convenience: a generated
+        // column *does* have one, and `hasDefault` is what keeps it out of `CreateDTO` — so a
+        // `Serial` that only set `serial` would demand the key the database is about to make.
+        const serial = tags.has('serial');
+        const hasDefault = serial || tags.has('hasDefault');
+        if (serial && extension !== undefined) {
+            this.#refuse(property, 'Serial cannot be combined with an extension-backed column type');
+        }
+        for (const [tag, action] of [
+            ['OnDelete', onDelete],
+            ['OnUpdate', onUpdate],
+        ]) {
+            if (action === 'set null' && !nullable) {
+                this.#refuse(property, `${tag}<'set null'> on a NOT NULL column; a referential action would have to write NULL into ` +
+                    "a column that forbids it — make the column nullable, or use 'cascade' or 'restrict'");
+            }
+            if (action === 'set default' && !hasDefault) {
+                this.#refuse(property, `${tag}<'set default'> on a column with no default; add HasDefault or choose an action ` +
+                    'that does not write a missing default');
+            }
+        }
+        if ((onDelete !== undefined || onUpdate !== undefined) && typeof references !== 'string') {
+            this.#refuse(property, 'OnDelete and OnUpdate require References<…> on the same foreign-key column');
+        }
+        // A generated `integer` is what `serial` means, and the declaration says it in two tags
+        // rather than one because the old `Sql<'serial'>` made a serial key's value unassignable
+        // to an `integer` foreign key — see `ColumnSqlType` in `@zmdb/schema/tags`. The IR
+        // keeps the one-word spelling, because that is the word two of the three dialects want
+        // in the DDL and every renderer reads it.
+        const coreSql = declaredSql ?? (extension === undefined ? this.#inferSql(property, data, enumValues) : undefined);
+        const sql = extension ??
+            (serial && coreSql === 'integer' ? 'serial' : (coreSql ?? this.#inferSql(property, data, enumValues)));
+        const payload = this.#declaredApp(property, data, sql, typeof codec === 'string');
+        return {
+            name: property,
+            physicalName,
+            sql,
+            nullable,
+            primaryKey: tags.has('primaryKey'),
+            serial,
+            unique: tags.has('unique'),
+            hasDefault,
+            sensitive: tags.has('sensitive'),
+            ...(length === undefined ? {} : { length }),
+            ...(precision === undefined ? {} : { precision }),
+            ...(sql === 'jsonEnum' && enumValues !== undefined ? { enum: enumValues } : {}),
+            ...(typeof references === 'string' ? { references } : {}),
+            ...(onDelete === undefined ? {} : { onDelete }),
+            ...(onUpdate === undefined ? {} : { onUpdate }),
+            ...(typeof codec === 'string' ? { codec } : {}),
+            // `WireAs<W>` is the one tag whose payload is a type rather than a literal, so it
+            // is reflected like data instead of read with `literalOf`. Only the declaration
+            // can say what a codec puts on the wire — see `wireTypeOf`, which refuses a codec
+            // column without it rather than assuming the app type crosses unchanged.
+            ...(wire === undefined ? {} : { wire: this.#type(wire, property, 1) }),
+            constraints,
+            rules: this.#rulesOf(tags),
+            ...(payload === undefined ? {} : { payload }),
+        };
+    }
+    /**
+     * The app type, where only a tagged declaration can say it.
+     *
+     * Two cases, one IR field. A `json` column's payload shape: `ColumnMeta` records
+     * `sql: 'json'` and has nowhere to put the shape, so a consumer reading the column map
+     * gets "an object, unspecified". And the type behind a codec: `Money & Sql<'integer'> &
+     * Codec<'Money'>` is an integer in the database and a `Money` in the app, and a
+     * validator that checked `integer` would reject every valid value. Both are facts only
+     * the declaration has, and both are why `CoreSchema` carries its IR.
+     *
+     * A codec over a *scalar* is left alone deliberately. `string & Sql<'text'> &
+     * Length<80> & Codec<'currency'>` is a string on both sides, and recording the bare
+     * data part would drop the constraints the tags carry, which `appTypeOf` reads off the
+     * column instead. So the field is set only where the app type is a shape the SQL type
+     * cannot describe at all.
+     *
+     * `object & Sql<'json'>` is the declared spelling of a payload-free `json()`, so it
+     * leaves the field unset like `unknown` does. That is not a shortcut: `object` means
+     * "not a primitive", which is precisely the check an unshaped `json` column emits, so
+     * the type and the validator say the same thing rather than one of them saying more.
+     */
+    #declaredApp(property, data, sql, codec) {
+        if (typeof sql !== 'string') {
+            const [only] = data;
+            if (data.length !== 1 || only === undefined || isUnknown(only) || isNonPrimitive(only))
+                return undefined;
+            return this.#type(only, property, 1);
+        }
+        if (!codec && sql !== 'json')
+            return undefined;
+        const [only] = data;
+        if (data.length !== 1 || only === undefined || isUnknown(only) || isNonPrimitive(only))
+            return undefined;
+        const node = this.#type(only, property, 1);
+        if (sql === 'json')
+            return node;
+        return node.kind === 'scalar' || node.kind === 'literal' ? undefined : node;
+    }
+    /**
+     * `Sql<T>` is required only where TypeScript is genuinely ambiguous. That is `number`,
+     * which is both `integer` and `numeric`, and `string`, which is both `text` and
+     * `varchar` — and for `string` there is a defensible default, so only `number` is
+     * refused outright. Everywhere else the type says it, and asking for a second spelling
+     * would be asking for two sources of truth (REQ-TF-2).
+     */
+    #inferSql(property, members, enumValues) {
+        if (enumValues !== undefined)
+            return 'jsonEnum';
+        const only = members.length === 1 ? members[0] : undefined;
+        if (!only)
+            return 'json';
+        if (only.isIntrinsicType()) {
+            switch (only.intrinsicName) {
+                case 'string':
+                    return 'text';
+                case 'boolean':
+                    return 'boolean';
+                case 'bigint':
+                    return 'bigint';
+                case 'number':
+                    this.#refuse(property, "a `number` column needs Sql<'integer'> or Sql<'numeric'> — TypeScript spells both `number`");
+                    return 'numeric';
+                default:
+                    break;
+            }
+        }
+        if (only.isBooleanLiteralType())
+            return 'boolean';
+        if (only.getSymbol()?.name === 'Date')
+            return 'timestamp';
+        return 'json';
+    }
+    #precisionOf(tags) {
+        const spec = this.#nonNullable(tags.get('precision'));
+        if (!spec)
+            return undefined;
+        const parts = this.#checker.isTupleType(spec) ? this.#typeArguments(spec) : [];
+        const [p, s] = parts.map(part => numberOf(part));
+        if (p === undefined || s === undefined) {
+            this.#refuse('precision', 'Numeric<P, S> needs two number literals', this.#print(spec));
+            return undefined;
+        }
+        return [p, s];
+    }
+    #tableColumnList(label, tagged) {
+        const spec = this.#nonNullable(tagged);
+        if (!spec)
+            return undefined;
+        const parts = this.#checker.isTupleType(spec) ? this.#typeArguments(spec) : [];
+        const columns = parts.map(part => literalOf(part));
+        if (columns.length === 0 || columns.some(column => typeof column !== 'string')) {
+            this.#refuse(label, `${label}<Columns> needs a non-empty tuple of string literals`, this.#print(spec));
+            return undefined;
+        }
+        const names = columns.filter((column) => typeof column === 'string');
+        if (new Set(names).size !== names.length) {
+            this.#refuse(label, `${label}<Columns> names each column once`, this.#print(spec));
+            return undefined;
+        }
+        return names;
+    }
+    /**
+     * `Rule<'luhn'>`, or `Rule<'luhn' | 'checksum'>` for more than one. A second
+     * `Rule<>` in the same intersection would reuse the same symbol slot and intersect
+     * the arguments to `never`, so the union is the spelling — hence a union is read
+     * here rather than refused.
+     */
+    #rulesOf(tags) {
+        const spec = this.#nonNullable(tags.get('rules'));
+        if (!spec)
+            return [];
+        const members = spec.isUnionType() ? spec.getTypes() : [spec];
+        const names = literalUnion(members);
+        if (names === undefined) {
+            this.#refuse('rules', "Rule<Name> needs a string literal, or a union of them: Rule<'a' | 'b'>", this.#print(spec));
+            return [];
+        }
+        return names;
+    }
+    // -------------------------------------------------------------------------
+    // Checker helpers
+    // -------------------------------------------------------------------------
+    #typeOf(symbol) {
+        return this.#checker.getTypeOfSymbolAtLocation(symbol, this.#location);
+    }
+    #grpcMember(type, method, member) {
+        const symbol = this.#checker.getPropertyOfType(type, member);
+        if (symbol === undefined) {
+            this.#refuse(`${method}.${member}`, `a gRPC method must declare its ${member} type`);
+            return undefined;
+        }
+        const value = this.#typeOf(symbol);
+        if (value === undefined) {
+            this.#refuse(`${method}.${member}`, `the checker did not resolve this gRPC ${member} type`);
+        }
+        return value;
+    }
+    #grpcStreamFlag(type, method, member) {
+        const symbol = this.#checker.getPropertyOfType(type, member);
+        if (symbol === undefined)
+            return false;
+        const value = this.#typeOf(symbol);
+        if (value === undefined || literalOf(this.#nonNullable(value)) !== true) {
+            this.#refuse(`${method}.${member}`, `a gRPC stream flag must be the literal type \`true\` when present`);
+        }
+        return true;
+    }
+    /**
+     * The type arguments of an array, tuple or other generic reference.
+     *
+     * boundary: `getTypeArguments` takes a `TypeReference`, but `isArrayType` and
+     * `isTupleType` answer with a plain `boolean` rather than a predicate, so the check that
+     * makes the call sound cannot narrow the argument. Every caller runs one of those two
+     * first; the cast lives here, once, instead of at each of them. A reference this is
+     * called on wrongly answers with an empty list, and each caller already handles that —
+     * an array with no element type is a refusal, and a tuple with none is an empty tuple.
+     */
+    #typeArguments(type) {
+        return this.#checker.getTypeArguments(type);
+    }
+    /** Strips `| undefined` off an optional tag slot's type. */
+    #nonNullable(type) {
+        if (!type)
+            return undefined;
+        return this.#checker.getNonNullableType(type) ?? type;
+    }
+    #hasIndexSignature(type) {
+        try {
+            return this.#checker.getIndexInfosOfType(type).length > 0;
+        }
+        catch {
+            // The client throws while marshalling an `IndexInfo` whose `keyType` it cannot
+            // resolve. It only gets that far when there IS one, so a throw is a positive
+            // answer, not an error to swallow.
+            return true;
+        }
+    }
+    #print(type) {
+        return this.#checker.typeToString(type);
+    }
+    #refuse(path, reason, source) {
+        this.diagnostics.push({ path, reason, ...(source === undefined ? {} : { source }) });
+    }
+    #unsupported(path, reason, source) {
+        this.#refuse(path, reason, source);
+        return { kind: 'unsupported', reason, ...(source === undefined ? {} : { source }) };
+    }
+    #claimName(preferred, id) {
+        const owner = this.#names.get(preferred);
+        if (owner === undefined) {
+            this.#names.set(preferred, id);
+            return preferred;
+        }
+        if (owner === id)
+            return preferred;
+        // Two declarations, one name. Suffixing keeps the emitted helpers distinct; the
+        // alternative is one helper silently checking the other's shape.
+        let n = 2;
+        while (this.#names.has(`${preferred}_${n}`) && this.#names.get(`${preferred}_${n}`) !== id)
+            n++;
+        this.#names.set(`${preferred}_${n}`, id);
+        return `${preferred}_${n}`;
+    }
+}
+/** One type, one IR, plus whatever the reflection had to refuse along the way. */
+export function irFromType(checker, type, location, options) {
+    const reflector = new Reflector(checker, location, options);
+    return { ir: reflector.typeIR(type), diagnostics: reflector.diagnostics };
+}
+/** A tagged entity type, read to the `SchemaIR` every back-end takes. */
+export function schemaIrFromType(checker, type, location, options) {
+    const reflector = new Reflector(checker, location, options);
+    return { ir: reflector.schemaIR(type), diagnostics: reflector.diagnostics };
+}
+// ---------------------------------------------------------------------------
+// Small pure helpers
+// ---------------------------------------------------------------------------
+function isUnknown(type) {
+    return type.isIntrinsicType() && (type.intrinsicName === 'unknown' || type.intrinsicName === 'any');
+}
+/** The `object` keyword: any non-primitive, which is any JSON object or array. */
+function isNonPrimitive(type) {
+    return type.isIntrinsicType() && type.intrinsicName === 'object';
+}
+function literalOf(type) {
+    if (!type)
+        return undefined;
+    if (type.isStringLiteralType() || type.isNumberLiteralType() || type.isBooleanLiteralType())
+        return type.value;
+    // `Fts<true>` and a bare `PrimaryKey` both carry the `true` type, which the checker
+    // may report as the `boolean` union rather than a literal depending on how it was
+    // written; treat that as `true` because `false` is not a spelling any tag admits.
+    if (type.isIntrinsicType() && type.intrinsicName === 'true')
+        return true;
+    return undefined;
+}
+function numberOf(type) {
+    const value = literalOf(type);
+    return typeof value === 'number' ? value : undefined;
+}
+/**
+ * `'a' | 'b'` → `['a', 'b']`, sorted; anything else → `undefined`.
+ *
+ * Sorted because the order we are handed is not the order the author wrote. The checker
+ * normalises union members, so `'free' | 'pro' | 'enterprise'` arrives as `enterprise`,
+ * `free`, `pro`. Sorting is what makes the answer stable across an edit that only reorders
+ * the union, which is not a change to the table. See `ColumnIR.enum`.
+ */
+function literalUnion(members) {
+    if (members.length === 0)
+        return undefined;
+    const values = [];
+    for (const member of members) {
+        if (!member.isStringLiteralType())
+            return undefined;
+        values.push(member.value);
+    }
+    return values.toSorted();
+}
+function escapeRegExp(text) {
+    return text.replaceAll(/[$()*+.?[\\\]^{|}]/g, String.raw `\$&`);
+}
+function pascalIdentifier(text) {
+    const words = text.split(/[^A-Za-z0-9]+/).filter(word => word.length > 0);
+    if (words.length === 0)
+        return 'Method';
+    return words.map(word => `${word.slice(0, 1).toUpperCase()}${word.slice(1)}`).join('');
+}
+/**
+ * The regex source for one `${…}` span of a template literal type, or `undefined` when
+ * there is no *exact* equivalent.
+ *
+ * `${number}` is deliberately not derivable. TypeScript's own rule for what text is
+ * assignable to it covers exponents, `Infinity` and leading signs, so any regex short
+ * enough to write here is either stricter than the type — rejecting values the type
+ * accepts — or looser. Refusing and asking for an explicit `Pattern<…>` lets the author
+ * pick the numeric grammar they actually mean.
+ *
+ * There is no union case because the checker never leaves one here: `` `v${1 | 2}` ``
+ * is normalised to two template literal types before we see it.
+ */
+function placeholderPattern(span) {
+    if (span.isStringLiteralType() || span.isNumberLiteralType())
+        return escapeRegExp(String(span.value));
+    if (span.isIntrinsicType() && span.intrinsicName === 'string')
+        return String.raw `[\s\S]*`;
+    return undefined;
+}
+/**
+ * The declared name of a type, or `undefined` for an anonymous one. `__type` and
+ * `__object` are the checker's placeholders for a type literal, not names.
+ */
+function typeName(type) {
+    const name = type.getAliasSymbol()?.name ?? type.getSymbol()?.name;
+    if (name === undefined || name.startsWith('__'))
+        return undefined;
+    return name;
+}
+//# sourceMappingURL=index.js.map