@zmdb/schema 1.0.0-beta.1

package/dist/ir/index.js

@@ -0,0 +1,735 @@
+// @zmdb/schema/ir — the intermediate representation every walker consumes.
+//
+// This module exists because the repo grew four independent walkers over the same
+// column metadata (`PLAN-type-first.md` §1): the AOT's `emitCheck`, its runtime
+// `matches`/`collectIssues`, `openapi`'s `scalarSchema`, and the repository's
+// `valueMatchesColumn`. Each had its own vocabulary and its own gaps, and they
+// disagreed with each other. Adding a fifth for tagged types would have made it
+// worse, so the tags land on top of one IR instead.
+//
+//   FRONT-END                   IR                       BACK-ENDS
+//                                            ┌── predicate JS   (is)
+//   tagged type ────▶ SchemaIR / TypeIR ─────┼── JSON Schema    (openapi/llm/web)
+//                         (pure data)        ├── runtime walker (fallback, repository)
+//                                            ├── schema value   (schemaFromIR)
+//                                            └── SQL / DDL      (query-compiler)
+//
+// There used to be a second front-end — `irFromSchema`, which read the IR back out of a
+// `defineSchema` value — and its whole purpose was to be the thing the tagged front-end
+// was proved equal to. It went when `defineSchema` did. `schemaFromIR` is what remains,
+// and it points the other way: the value is now a projection of the IR, not a source of it.
+//
+// Two hard constraints on everything below:
+//
+//  1. **The IR is serialisable JSON.** No symbols, no functions, no class
+//     instances. That is what lets the codegen CLI write it to disk, lets golden
+//     tests snapshot it, and keeps `typescript` out of every runtime bundle.
+//  2. **`sql` stays abstract.** A `timestamp` column carries `'timestamp'`, never
+//     `'timestamptz'`. A column has three types — wire, app and db — and each
+//     layer renders the one it owns (plan D3). Rendering a dialect's spelling is
+//     the dialect's job; baking one in here would force every other back-end to
+//     parse it back out.
+import {} from '../index.js';
+import { KNOWN_CONSTRAINT_KINDS } from './vocabulary.js';
+export { KNOWN_CONSTRAINT_KINDS, TAG_NAMES } from './vocabulary.js';
+/**
+ * The four cardinalities, as data so a reader can check a string against them.
+ *
+ * Written this way round — the list first, the type derived — because `../tags` fixes
+ * `kind` to a literal per tag, but the reflection reads it back off the checker as a
+ * `string`. Deriving the type from the list is what lets that read be a check rather than
+ * an assertion, and keeps the two from drifting.
+ */
+export const RELATION_KINDS = ['manyToOne', 'oneToMany', 'oneToOne', 'manyToMany'];
+// ---------------------------------------------------------------------------
+// Vocabulary coverage (REQ-TF-1)
+// ---------------------------------------------------------------------------
+/** Every `SqlType`, as data. `sql-types.type-test.ts` asserts exhaustiveness. */
+export const SQL_TYPES = [
+    'serial',
+    'integer',
+    'bigint',
+    'numeric',
+    'text',
+    'varchar',
+    'boolean',
+    'timestamp',
+    'json',
+    'jsonEnum',
+];
+/** The closed protobuf scalar vocabulary carried by {@link ScalarIR}. */
+export const PROTO_SCALARS = [
+    'int32',
+    'int64',
+    'uint32',
+    'uint64',
+    'sint32',
+    'sint64',
+    'fixed32',
+    'fixed64',
+    'sfixed32',
+    'sfixed64',
+    'float',
+    'double',
+    'bool',
+    'string',
+    'bytes',
+];
+// ---------------------------------------------------------------------------
+// Back-end: IR → schema value (REQ-TF-10)
+// ---------------------------------------------------------------------------
+/**
+ * The constraints, in the spelling `ColumnMeta.validation` uses.
+ *
+ * Emitted in `KNOWN_CONSTRAINT_KINDS` order rather than any order they arrived in: the
+ * IR holds them in a record, which has none to preserve, so a fixed order is the only
+ * one that makes the output a function of the input. Named custom rules keep their name
+ * and lose their arguments, because `ColumnIR.rules` only ever held the name.
+ */
+function validationFromIR(col) {
+    const rules = [];
+    for (const kind of KNOWN_CONSTRAINT_KINDS) {
+        const value = col.constraints[kind];
+        if (value !== undefined)
+            rules.push({ kind, value });
+    }
+    for (const kind of col.rules)
+        rules.push({ kind });
+    return rules;
+}
+/**
+ * A column's metadata. Flags are written only when set — a plain `text` column gives
+ * `{ nullable: false }` and nothing else — so the generated literal stays as small as
+ * the declaration it came from.
+ */
+function columnMetaFromIR(col) {
+    const validation = validationFromIR(col);
+    return {
+        type: col.sql,
+        flags: {
+            nullable: col.nullable,
+            ...(col.primaryKey ? { primaryKey: true } : {}),
+            ...(col.serial ? { autoIncrement: true } : {}),
+            ...(col.unique ? { unique: true } : {}),
+            ...(col.hasDefault ? { hasDefault: true } : {}),
+            ...(col.sensitive ? { sensitive: true } : {}),
+            ...(col.length === undefined ? {} : { length: col.length }),
+            ...(col.enum === undefined ? {} : { enum: col.enum }),
+        },
+        ...(col.default === undefined ? {} : { default: col.default }),
+        ...(col.references === undefined ? {} : { references: { target: col.references } }),
+        ...(validation.length === 0 ? {} : { validation }),
+    };
+}
+/**
+ * The schema value, from the IR — and the only way to get one (REQ-TF-10).
+ *
+ * The query compiler wants the table name and the column types as *data*, and this is
+ * data. `@zmdb/compiler` emits the result of this function as a frozen literal, so
+ * `schemaOf<T>()` costs nothing at runtime and the tagged type stays the only place the
+ * schema is written.
+ *
+ * The IR itself is carried through on `ir` rather than left behind. Three things a
+ * `ColumnMeta` has no field for — `Numeric<P, S>` precision, a `Codec<'Name'>`, a `json`
+ * payload shape — used to be dropped here and were unrecoverable afterwards, because the
+ * only way back to an IR was to walk the flags. Keeping the IR makes the value a superset
+ * of what it projects rather than a lossy copy, and it is what let `irFromSchema` go: no
+ * consumer has to reconstruct from `columns` what the declaration already said.
+ *
+ * Nothing is registered. A generated literal is not a call and has nowhere to do that,
+ * and a global "which schema was that?" lookup is for code that has lost track of its own
+ * schema — which type-first code, by construction, has not.
+ */
+export function schemaFromIR(ir) {
+    const key = new Set(ir.primaryKey);
+    const columnNames = new Set(ir.columns.map(column => column.name));
+    const missing = ir.primaryKey.filter(column => !columnNames.has(column));
+    if (missing.length > 0) {
+        throw new Error(`${ir.table}: primary key names ${missing.map(column => `"${column}"`).join(', ')}, ` +
+            `${missing.length === 1 ? 'a column' : 'columns'} the table does not have`);
+    }
+    const normalizedColumns = ir.columns.map(column => {
+        const primaryKey = key.has(column.name);
+        return column.primaryKey === primaryKey ? column : { ...column, primaryKey };
+    });
+    const normalizedIr = normalizedColumns.every((column, index) => column === ir.columns[index])
+        ? ir
+        : { ...ir, columns: normalizedColumns };
+    const physicalNames = new Map();
+    for (const column of normalizedIr.columns) {
+        const previous = physicalNames.get(column.physicalName);
+        if (previous !== undefined) {
+            throw new Error(`${normalizedIr.table}: \`${previous}\` and \`${column.name}\` both map to the column ` +
+                `\`${column.physicalName}\``);
+        }
+        physicalNames.set(column.physicalName, column.name);
+    }
+    const physicalByProperty = new Map(normalizedIr.columns.map(column => [column.name, column.physicalName]));
+    const columns = {};
+    for (const col of normalizedIr.columns)
+        columns[col.physicalName] = columnMetaFromIR(col);
+    return {
+        table: normalizedIr.physicalTable,
+        columns,
+        primaryKey: normalizedIr.primaryKey.map(column => physicalByProperty.get(column) ?? column),
+        references: normalizedIr.columns.flatMap(col => col.references === undefined ? [] : [{ column: col.physicalName, target: col.references }]),
+        ...(normalizedIr.ftsTable === undefined ? {} : { ftsTable: normalizedIr.ftsTable }),
+        ir: normalizedIr,
+    };
+}
+// ---------------------------------------------------------------------------
+// The three types of a column (plan D3 / REQ-TF-13)
+// ---------------------------------------------------------------------------
+function withNull(type, nullable) {
+    return nullable ? { kind: 'union', members: [type, { kind: 'null' }] } : type;
+}
+function constrained(scalar, col, format) {
+    const withLength = col.length !== undefined && col.constraints.maxLength === undefined
+        ? { ...col.constraints, maxLength: col.length }
+        : col.constraints;
+    const derived = format === undefined ? undefined : FORMAT_PATTERNS[format];
+    const constraints = derived !== undefined && withLength.pattern === undefined ? { ...withLength, pattern: derived } : withLength;
+    return {
+        kind: 'scalar',
+        scalar,
+        ...(format === undefined ? {} : { format }),
+        ...(Object.keys(constraints).length === 0 ? {} : { constraints }),
+    };
+}
+function extensionDimension(type) {
+    if (type.name !== 'vector')
+        return undefined;
+    const dimension = type.args?.[0];
+    return typeof dimension === 'number' && Number.isInteger(dimension) && dimension >= 0 ? dimension : undefined;
+}
+function extensionAppBase(col, type) {
+    if (type.name === 'vector') {
+        const dimension = extensionDimension(type);
+        return {
+            kind: 'array',
+            element: { kind: 'scalar', scalar: 'number' },
+            ...(dimension === undefined ? {} : { constraints: { minLength: dimension, maxLength: dimension } }),
+        };
+    }
+    if (type.name === 'citext')
+        return constrained('string', col);
+    return {
+        kind: 'unsupported',
+        reason: `extension type "${type.name}" on column "${col.name}" needs its declared application shape ` +
+            'carried in the IR',
+    };
+}
+/**
+ * The **app** type: what handler code sees. A `timestamp` is a `Date` here, and
+ * a `bigint` is a `bigint`.
+ */
+export function appTypeOf(col) {
+    return withNull(appBaseOf(col), col.nullable);
+}
+function appBaseOf(col) {
+    if (typeof col.sql !== 'string') {
+        if (col.sql.name === 'vector' || col.sql.name === 'citext')
+            return extensionAppBase(col, col.sql);
+        if (col.payload !== undefined)
+            return col.payload;
+        return extensionAppBase(col, col.sql);
+    }
+    // A declared app type wins over the SQL type it is stored as. `amount: Money &
+    // Sql<'integer'> & Codec<'Money'>` is an integer in the database and a `Money` in the
+    // app, and a validator that checked `integer` here would reject every valid value.
+    if (col.payload !== undefined)
+        return col.payload;
+    switch (col.sql) {
+        case 'serial':
+        case 'integer':
+            return constrained('integer', col);
+        case 'bigint':
+            return constrained('bigint', col);
+        case 'numeric':
+            return constrained('number', col);
+        case 'text':
+        case 'varchar':
+            return constrained('string', col);
+        case 'boolean':
+            return { kind: 'scalar', scalar: 'boolean' };
+        case 'timestamp':
+            return { kind: 'scalar', scalar: 'date' };
+        case 'jsonEnum':
+            return col.enum === undefined || col.enum.length === 0
+                ? constrained('string', col)
+                : { kind: 'union', members: col.enum.map(value => ({ kind: 'literal', value })) };
+        case 'json':
+            return JSON_CONTAINER;
+    }
+}
+/**
+ * A `json` column whose payload shape is not known: anything JSON puts in a column, and
+ * nothing else. An object with no declared properties accepts any record, and an array of
+ * `unknown` accepts any array, so together they are "not a primitive".
+ *
+ * Not `{ kind: 'unknown' }`, which accepts `123`. A declaration that says what the payload
+ * is — `lines: Line[] & Sql<'json'>` — gets that type instead, via `ColumnIR.payload`; this
+ * is the answer for a bare `object & Sql<'json'>`, which really does permit any record. It
+ * is the weakest true statement rather than no statement, which is the difference between a
+ * validator that rejects `settings: 123` and one that does not.
+ */
+const JSON_CONTAINER = {
+    kind: 'union',
+    members: [
+        { kind: 'object', properties: [] },
+        { kind: 'array', element: { kind: 'unknown' } },
+    ],
+};
+/**
+ * The assertion behind a `format`, as a `pattern`.
+ *
+ * `format` is an annotation in JSON Schema, not an assertion — a document may say
+ * `date-time` and a conforming validator may check nothing. Neither the runtime walk nor the
+ * emitter reads `format` at all, so a wire type that only said `{scalar:'string',
+ * format:'date-time'}` accepted `"tomorrow"`, and plan D3's claim that a `Wire<T>` validator
+ * checks the ISO string was not true of any validator. Lowering it to a `pattern` makes it
+ * true through machinery that already exists in both walks, which is the reason it is spelled
+ * this way rather than as a sixth constraint kind: a new keyword would need the emitter, the
+ * walker and their equivalence test, and would then check exactly what a pattern checks.
+ *
+ * `date-time` is RFC 3339, so the offset is **required**. `2020-01-01T00:00:00` is a valid
+ * ISO-8601 string and `new Date()` reads it as local time, which is the same lost-offset bug
+ * `TIMESTAMPTZ` exists to prevent — the wire is where that has to be refused, because by the
+ * time it is a `Date` the offset it was read at is gone.
+ *
+ * `int64` is `asBigInt`'s own `DECIMAL`, so what the wire validator accepts and what the
+ * decoder can convert are one expression rather than two that agree today.
+ */
+/** What `asBigInt` will convert. Declared here so the wire pattern is not a second copy. */
+const DECIMAL = /^-?\d+$/;
+const FORMAT_PATTERNS = {
+    'date-time': '^\\d{4}-\\d{2}-\\d{2}[Tt ]\\d{2}:\\d{2}:\\d{2}(?:\\.\\d+)?(?:[Zz]|[+-]\\d{2}:\\d{2})$',
+    int64: DECIMAL.source,
+};
+/**
+ * The **wire** type: what a JSON body actually contains. A `timestamp` is an
+ * ISO-8601 string, because a `Date` cannot survive JSON, and a `bigint` is a
+ * string for the same reason. Anything else matches the app type.
+ */
+export function wireTypeOf(col) {
+    if (col.wire !== undefined)
+        return withNull(col.wire, col.nullable);
+    if (col.codec !== undefined) {
+        // A gap, and gaps are visible (plan D4). A codec exists because the app type is not
+        // the stored type; what it puts on the wire is a third choice that nothing but the
+        // declaration knows, and guessing "the same as the app type" is how a `Money`
+        // instance reaches `JSON.stringify`.
+        return {
+            kind: 'unsupported',
+            reason: `the codec "${col.codec}" does not say what column "${col.name}" looks like on the wire; add WireAs<…> to the declaration`,
+        };
+    }
+    if (typeof col.sql !== 'string')
+        return appTypeOf(col);
+    if (col.sql === 'timestamp')
+        return withNull(constrained('string', col, 'date-time'), col.nullable);
+    if (col.sql === 'bigint')
+        return withNull(constrained('string', col, 'int64'), col.nullable);
+    return appTypeOf(col);
+}
+/**
+ * A single column's JSON Schema. Emitted from the **wire** type, which is why a
+ * `timestamp` becomes `{type:'string',format:'date-time'}` here and a `Date` in
+ * `Entity<T>` — one column, two correct answers, each in its own layer.
+ */
+export function jsonSchemaForColumn(col) {
+    const base = {};
+    const declared = declaredWireKeywords(col);
+    if (declared)
+        return nullableType(declared, col.nullable);
+    if (typeof col.sql !== 'string')
+        return nullableType(extensionJsonSchema(col, col.sql), col.nullable);
+    switch (col.sql) {
+        case 'serial':
+        case 'integer':
+            base.type = 'integer';
+            break;
+        case 'bigint':
+            base.type = 'integer';
+            base.format = 'int64';
+            break;
+        case 'numeric':
+            base.type = 'number';
+            break;
+        case 'text':
+        case 'varchar':
+            base.type = 'string';
+            if (col.length !== undefined)
+                base.maxLength = col.length;
+            break;
+        case 'boolean':
+            base.type = 'boolean';
+            break;
+        case 'timestamp':
+            base.type = 'string';
+            base.format = 'date-time';
+            break;
+        case 'jsonEnum':
+            base.type = 'string';
+            base.enum = [...(col.enum ?? [])];
+            break;
+        case 'json':
+            break;
+    }
+    const c = col.constraints;
+    if (c.minimum !== undefined)
+        base.minimum = c.minimum;
+    if (c.maximum !== undefined)
+        base.maximum = c.maximum;
+    if (c.minLength !== undefined)
+        base.minLength = c.minLength;
+    if (c.maxLength !== undefined)
+        base.maxLength = c.maxLength;
+    if (c.pattern !== undefined)
+        base.pattern = c.pattern;
+    // Nullable widens the `type` keyword. A `json` column has no `type` to widen,
+    // which is the pre-existing behaviour and is preserved deliberately.
+    return nullableType(base, col.nullable);
+}
+function extensionJsonSchema(col, type) {
+    if (type.name === 'vector') {
+        const dimension = extensionDimension(type);
+        return {
+            type: 'array',
+            items: { type: 'number' },
+            ...(dimension === undefined ? {} : { minItems: dimension, maxItems: dimension }),
+        };
+    }
+    if (type.name === 'citext')
+        return jsonSchemaFromTypeIR(constrained('string', col));
+    return col.payload === undefined ? {} : jsonSchemaFromTypeIR(col.payload);
+}
+/**
+ * The JSON Schema projection of one structural type.
+ *
+ * HTTP contracts, validators and other build-time consumers call this after the
+ * existing reflector has produced TypeIR. Keeping the projection here prevents a
+ * second consumer from interpreting TypeScript types or re-walking schema metadata.
+ */
+export function jsonSchemaFromTypeIR(type) {
+    switch (type.kind) {
+        case 'scalar': {
+            const scalar = JSON_SCALAR_TYPES[type.scalar];
+            if (scalar === undefined)
+                return {};
+            return {
+                type: scalar,
+                ...(type.format === undefined ? {} : { format: type.format }),
+                ...(type.constraints?.minimum === undefined ? {} : { minimum: type.constraints.minimum }),
+                ...(type.constraints?.maximum === undefined ? {} : { maximum: type.constraints.maximum }),
+                ...(type.constraints?.minLength === undefined ? {} : { minLength: type.constraints.minLength }),
+                ...(type.constraints?.maxLength === undefined ? {} : { maxLength: type.constraints.maxLength }),
+                ...(type.constraints?.pattern === undefined ? {} : { pattern: type.constraints.pattern }),
+            };
+        }
+        case 'literal':
+            return { const: type.value };
+        case 'null':
+            return { type: 'null' };
+        case 'array':
+            return {
+                type: 'array',
+                items: jsonSchemaFromTypeIR(type.element),
+                ...(type.constraints?.minLength === undefined ? {} : { minItems: type.constraints.minLength }),
+                ...(type.constraints?.maxLength === undefined ? {} : { maxItems: type.constraints.maxLength }),
+            };
+        case 'tuple':
+            return {
+                type: 'array',
+                prefixItems: type.elements.map(jsonSchemaFromTypeIR),
+                minItems: type.elements.length,
+                maxItems: type.elements.length,
+            };
+        case 'object': {
+            const properties = {};
+            const required = [];
+            for (const property of type.properties) {
+                properties[property.name] = jsonSchemaFromTypeIR(property.type);
+                if (!property.optional)
+                    required.push(property.name);
+            }
+            return { type: 'object', properties, required };
+        }
+        case 'union':
+            return { anyOf: type.members.map(jsonSchemaFromTypeIR) };
+        case 'undefined':
+        case 'unknown':
+        case 'ref':
+        case 'unsupported':
+            return {};
+    }
+}
+function nullableType(schema, nullable) {
+    if (nullable && typeof schema.type === 'string')
+        return { ...schema, type: [schema.type, 'null'] };
+    return schema;
+}
+/**
+ * The keywords for a `WireAs<W>` column, when `W` is something JSON Schema has keywords
+ * for. A scalar and a union of string literals cover every wire form seen so far — cents
+ * as a decimal string, a UUID, an enum.
+ *
+ * Anything richer (a tuple, an object) gets no `type` keyword rather than a wrong one:
+ * the same "widest true statement" a `json` column has always produced, for the same
+ * reason. It is a smaller document, not a false one.
+ */
+function declaredWireKeywords(col) {
+    if (col.wire === undefined)
+        return undefined;
+    const node = col.wire;
+    if (node.kind === 'scalar') {
+        const type = JSON_SCALAR_TYPES[node.scalar];
+        if (type === undefined)
+            return {};
+        return { type, ...(node.format === undefined ? {} : { format: node.format }) };
+    }
+    if (node.kind === 'union' && node.members.every(member => member.kind === 'literal')) {
+        // boundary: `every` proves the predicate for every member but returns a `boolean`, so
+        // the narrowing does not reach the `map` that follows. Re-testing `kind` inside the map
+        // would be the same check twice for a branch that cannot be taken.
+        return { enum: node.members.map(member => member.value) };
+    }
+    return {};
+}
+/** The JSON Schema `type` for a scalar the wire can carry. `date` and `bigint` cannot. */
+const JSON_SCALAR_TYPES = {
+    string: 'string',
+    number: 'number',
+    integer: 'integer',
+    boolean: 'boolean',
+};
+/**
+ * A variant, rewritten as a shape.
+ *
+ * The three rules the variants used to spell out inline: an input variant has no
+ * database-generated columns at all, a patch requires nothing, and an input column with
+ * a default may be left out. Each is exactly what the corresponding derived type does to
+ * `Entity<T>`, which is the reason this translation exists rather than a coincidence.
+ *
+ * `update` also drops the primary key, which is what `UpdateDTO<T>` does and what this
+ * function did not: a patch body identifies its row in the URL, so a key in the body is
+ * either redundant or an attempt to move the row. It only ever showed for a *non-serial*
+ * key, since a serial one was already gone, which is why no existing document changes.
+ */
+export function shapeOfVariant(ir, variant) {
+    const isResponse = variant === 'entity' || variant === 'get' || variant === 'list' || variant === 'search';
+    return ir.columns
+        .filter(col => isResponse || (!col.serial && col.name !== ir.softDelete?.column))
+        .filter(col => variant !== 'update' || !col.primaryKey)
+        .map(col => ({
+        column: col,
+        // Nullable is optional on the way in, for the reason `CreateDTO`'s comment gives:
+        // omitting the key inserts `NULL`, so requiring it buys nothing. On the way out it
+        // is not — a row that came back has every column, `null` included.
+        optional: variant === 'update' || (!isResponse && (col.hasDefault || col.nullable)),
+    }));
+}
+/**
+ * The document for a shape.
+ *
+ * `required` is "not optional and not nullable", which is the single rule the three
+ * variants were three cases of. A nullable column is never required because the value
+ * `null` is admissible for it, so demanding the key adds nothing a validator can act on
+ * — that is pre-existing behaviour, preserved deliberately.
+ *
+ * Sensitive columns are dropped here, in the emitter, and not in the shape. A generated
+ * document is published, `Sensitive` means "must not be", and putting the filter at the
+ * last step is what makes that unconditional (REQ-TF-6): no variant, and no derived type
+ * a caller invents, can route around it. `CreateDTO<User>` deliberately *keeps* a
+ * sensitive column — you have to be able to send a password — and its document still
+ * must not name it.
+ */
+export function jsonSchemaFromShape(shape) {
+    const visible = shape
+        .filter(entry => !entry.column.sensitive)
+        .toSorted((a, b) => a.column.name.localeCompare(b.column.name));
+    const properties = {};
+    const required = [];
+    for (const { column, optional } of visible) {
+        properties[column.name] = jsonSchemaForColumn(column);
+        if (!optional && !column.nullable)
+            required.push(column.name);
+    }
+    return { type: 'object', properties, required: required.toSorted() };
+}
+/**
+ * The document for a variant. Byte-for-byte the contract `toJsonSchema` already
+ * publishes; the point is that it is a pure function of IR, so naming a variant and
+ * naming a derived type cannot produce different documents (REQ-TF-7). That AC stops
+ * being a test to chase and becomes the only thing the code can do.
+ */
+export function jsonSchemaFromIR(ir, variant = 'entity') {
+    return jsonSchemaFromShape(shapeOfVariant(ir, variant));
+}
+/**
+ * A shape as the object type a validator checks against.
+ *
+ * Unlike the JSON Schema back-end this keeps sensitive columns: a payload validator that
+ * silently ignored `passwordHash` would reject every legitimate `create`. REQ-TF-6 is
+ * about what gets *published*, and nothing here is published.
+ *
+ * Column order is preserved rather than sorted, because a `TypeIR` is not a contract
+ * anybody serialises — the JSON Schema back-end sorts because a document is published
+ * and key order is part of it.
+ */
+export function objectTypeFromShape(shape, layer = 'app') {
+    return {
+        kind: 'object',
+        properties: shape.map(({ column, optional }) => ({
+            name: column.name,
+            type: layer === 'wire' ? wireTypeOf(column) : appTypeOf(column),
+            optional,
+            // A DTO is a plain object the caller just built, so nothing about it is readonly.
+            // `Entity<T>` is `-readonly` for the same reason.
+            readonly: false,
+        })),
+    };
+}
+/** The object type of one variant of one table, at one layer. */
+export function objectTypeFromIR(ir, variant = 'entity', layer = 'app') {
+    return objectTypeFromShape(shapeOfVariant(ir, variant), layer);
+}
+/** An ISO-8601 string, if that is what this is and it parses. */
+function asDate(value) {
+    if (typeof value !== 'string')
+        return value;
+    const parsed = new Date(value);
+    return Number.isNaN(parsed.getTime()) ? value : parsed;
+}
+/**
+ * A decimal string as a `bigint`.
+ *
+ * `DECIMAL` rather than a bare `BigInt()` call in a `try`: `BigInt('0x10')` is 16 and
+ * `BigInt('')` is 0, neither of which is something a caller meant to send.
+ */
+function asBigInt(value) {
+    return typeof value === 'string' && DECIMAL.test(value) ? BigInt(value) : value;
+}
+const VECTOR_COMPONENT = /^[+-]?(?:\d+(?:\.\d*)?|\.\d+)(?:[eE][+-]?\d+)?$/;
+function asVector(value) {
+    if (Array.isArray(value) || typeof value !== 'string' || !value.startsWith('[') || !value.endsWith(']')) {
+        return value;
+    }
+    const body = value.slice(1, -1);
+    if (body === '')
+        return [];
+    const fields = body.split(',');
+    if (fields.some(field => !VECTOR_COMPONENT.test(field.trim())))
+        return value;
+    const vector = fields.map(field => Number(field.trim()));
+    return vector.every(Number.isFinite) ? vector : value;
+}
+function codecFor(col, codecs) {
+    if (col.codec === undefined)
+        return undefined;
+    const codec = codecs[col.codec];
+    if (!codec) {
+        // A named codec with nothing behind it is a gap, and a gap has to be visible (plan
+        // D4). Silently passing the value through would store whatever JSON happened to
+        // carry in a column whose whole point is that it needs converting.
+        throw new Error(`column "${col.name}" names the codec "${col.codec}", which is not in the registry`);
+    }
+    return codec;
+}
+/** One column's value, as the app layer holds it. */
+export function decodeWireValue(col, value, codecs = {}) {
+    if (value === null || value === undefined)
+        return value;
+    const codec = codecFor(col, codecs);
+    if (codec)
+        return codec.decode(value);
+    if (col.sql === 'timestamp')
+        return asDate(value);
+    if (col.sql === 'bigint')
+        return asBigInt(value);
+    return value;
+}
+/** One column's value, as JSON can carry it. */
+export function encodeWireValue(col, value, codecs = {}) {
+    if (value === null || value === undefined)
+        return value;
+    const codec = codecFor(col, codecs);
+    if (codec)
+        return codec.encode(value);
+    if (col.sql === 'timestamp' && value instanceof Date) {
+        return Number.isNaN(value.getTime()) ? value : value.toISOString();
+    }
+    if (col.sql === 'bigint' && typeof value === 'bigint')
+        return value.toString();
+    return value;
+}
+/**
+ * A JSON body as an app-layer payload: the wire→app decode, once, at the boundary.
+ *
+ * Keys the variant does not have are copied through rather than dropped, because dropping
+ * them here would hide them from the repository's excess check — the decoder's job is to
+ * convert, and deciding what a payload may contain belongs to exactly one place.
+ */
+export function decodeWire(ir, variant, body, codecs = {}) {
+    const columns = new Map(shapeOfVariant(ir, variant).map(({ column }) => [column.name, column]));
+    const out = {};
+    for (const key of Object.keys(body)) {
+        const column = columns.get(key);
+        out[key] = column ? decodeWireValue(column, body[key], codecs) : body[key];
+    }
+    return out;
+}
+/**
+ * A value that came out of a database, as the app layer holds it — the third layer's
+ * crossing (plan D3).
+ *
+ * Written in terms of what *arrived* rather than in terms of the dialect, and that is the
+ * whole design: `pg` hands back a `Date` for a `timestamptz` and a string for an `int8`,
+ * SQLite hands back the `TEXT` it stored and a `number` for an `INTEGER`, and a third
+ * driver will do something else again. Asking "is this already the app value?" answers all
+ * of them, and keeps this function out of the dialect's business — which is the constraint
+ * the whole IR is written under.
+ *
+ * `timestamp` and `bigint` are the only core types whose app values need a distinct JSON
+ * wire form. The db crossing also handles extension vectors: their app and wire forms are
+ * both number arrays, but a driver without pgvector's parser can return the database text
+ * form instead.
+ */
+export function decodeDbValue(col, value) {
+    if (value === null || value === undefined)
+        return value;
+    if (typeof col.sql !== 'string')
+        return col.sql.name === 'vector' ? asVector(value) : value;
+    if (col.sql === 'timestamp')
+        return asDate(value);
+    if (col.sql === 'bigint') {
+        // A driver that read an 8-byte integer into a `number`. Safe integers only: past 2^53
+        // the number has already lost digits, and `BigInt(9007199254740993)` would state a
+        // value the database never held — better to hand back the number the driver gave and
+        // let the validator say the app type is not what arrived.
+        if (typeof value === 'number')
+            return Number.isSafeInteger(value) ? BigInt(value) : value;
+        return asBigInt(value);
+    }
+    return value;
+}
+/** Which columns `decodeDbValue` can change — so a read path can skip the walk entirely. */
+export function dbDecodedColumns(ir) {
+    return ir.columns.filter(col => {
+        if (typeof col.sql === 'string')
+            return col.sql === 'timestamp' || col.sql === 'bigint';
+        return col.sql.name === 'vector';
+    });
+}
+/** A row as a JSON body: the app→wire encode, for a response. */
+export function encodeWire(ir, row, codecs = {}) {
+    const columns = new Map(ir.columns.map(column => [column.name, column]));
+    const out = {};
+    for (const key of Object.keys(row)) {
+        const column = columns.get(key);
+        out[key] = column ? encodeWireValue(column, row[key], codecs) : row[key];
+    }
+    return out;
+}
+export { discriminantOf, expectedForConstraint, expectedForDiscriminant, expectedOf, hasExcessCheck, messageFor, } from './validation-shape.js';
+//# sourceMappingURL=index.js.map