primitive-admin 1.0.54 → 1.0.55

package/dist/src/lib/db-codegen/dbGenerator.js

@@ -6,605 +6,142 @@
  * then either (a) writes them, or (b) compares them against on-disk for
  * `--check`. No commander dependency, no `process.exit`.
  *
- * Reuses the codegen-v2 machinery:
- *   - `loadSchemaFromTomlString` (the shared `[models.*]` parser) for record
- *     interfaces — the database-type `[models.*]` blocks round-trip through
- *     the same loader and the same `FieldType` vocabulary.
- *   - The banner + fingerprint header pattern and stale-output cleanup.
- *
- * Adds the OPERATIONS half (op-params interfaces + per-op result aliases)
- * that codegen-v2 has no analog for. A result alias is derived from `op.type`
- * and, where the shape is derivable, the op's parsed `definition`: a query op's
- * `projection` (#1439), a mutation op's step kinds (#1438), and a pipeline op's
- * `return` step (#1437). This file resolves those into the small descriptors
- * the templates consume; the templates stay pure string-emitters.
+ * The op/record RESOLUTION (parse, schema load, required-ness inference, op
+ * params, and per-op result descriptors) lives in the shared, naming-neutral
+ * `describeDbType` IR (`dbTypeIR.ts`) — the SAME source the Swift renderer
+ * (`swift-codegen/dbGenerator.ts`) consumes (issue #1547 binding 5). This file
+ * is now purely the TS *rendering* half: it applies TS identifier naming
+ * (`resolveRecordInterfaceName`, `opParamsInterfaceName`, …) to that IR and
+ * emits `*.generated.ts` via the pure `dbTemplates` string-emitters. The
+ * emitted bytes are unchanged from the former inline implementation.
  */
 import * as path from "path";
-import { parseConfigToml, stringifyConfigToml } from "../config-toml.js";
-import { loadSchemaFromTomlString } from "js-bao";
-import { parseDatabaseTypeToml } from "../../commands/sync.js";
 import { writeOrCheckGeneratedFiles, } from "../codegen-shared/generatedFiles.js";
-import { fingerprintToml } from "./dbFingerprint.js";
-import { tsTypeForDbFieldType } from "./dbTsTypes.js";
-import { resolveRecordInterfaceName, opParamsInterfaceName, opResultAliasName, opsFactoryName, opPropertyKey, } from "./dbNaming.js";
-import { renderHeader, renderRecordInterface, renderOpParamsInterface, renderOpResultAlias, renderOpsFactory, RESULT_ALIASES_BLOCK, } from "./dbTemplates.js";
+import { describeDbType, } from "./dbTypeIR.js";
+import { resolveRecordInterfaceName, opParamsInterfaceName, opResultAliasName, opsFactoryName, subscriptionsFactoryName, objectPropertyKey, } from "./dbNaming.js";
+import { renderHeader, renderRecordInterface, renderOpParamsInterface, renderOpResultAlias, renderFactories, RESULT_ALIASES_BLOCK, } from "./dbTemplates.js";
+export { inferArrayParamElementTypes, inferRequiredRecordFields, } from "./dbTypeIR.js";
 const GENERATED_FILE_SUFFIX = ".generated.ts";
 /**
- * Op-param types that declare a scalar value (#1488). A param carrying one of
- * these explicit declarations is validated by the runtime as that scalar, so
- * array-element inference must not rewrite it to an array type in the generated
- * interface. Keep in step with the runtime's scalar coercion list
- * (`MODEL_PARAM_SCALAR_TYPES` in `database-operations-controller.ts`).
+ * Map the naming-neutral pipeline-return IR to the interface-named descriptor
+ * the TS `renderOpResultAlias` template consumes.
  */
-const SCALAR_PARAM_TYPES = new Set(["string", "number", "boolean", "integer"]);
+function mapPipelineReturn(ir, recordInterfaceByModel) {
+    switch (ir.kind) {
+        case "query":
+            return {
+                kind: "query",
+                recordInterfaceName: ir.modelName
+                    ? recordInterfaceByModel[ir.modelName] ?? null
+                    : null,
+                projection: ir.projection,
+            };
+        case "count":
+            return { kind: "count" };
+        case "aggregate":
+            return { kind: "aggregate" };
+        case "opaque":
+        default:
+            return { kind: "opaque" };
+    }
+}
 /**
  * Render the in-memory `.generated.ts` content for a single database-type
  * TOML. Exported so tests can assert on the rendered string directly.
  */
 export function renderDbTypeFile(input) {
-    const { tomlContent } = input;
-    const fingerprint = fingerprintToml(tomlContent);
-    // Parse the raw TOML once for the [type] / [[operations]] data, and route
-    // the [models.*] subtree through the shared js-bao loader (same path the
-    // server uses to validate the schema).
-    const tomlData = parseConfigToml(tomlContent);
-    const { typeConfig, operations } = parseDatabaseTypeToml(tomlData);
-    // 1. Record interfaces (read shape) from [models.*].
-    const schemas = tomlData.models
-        ? loadSchemaFromTomlString(stringifyConfigToml({ models: tomlData.models }), {
-            strict: false,
-        })
-        : [];
-    const stampedFields = collectStampedFields(typeConfig);
-    // model name → set of record fields the operation params prove are always
-    // supplied at create time (every `save` op that sets the field binds it to a
-    // `required: true` param). OR'd with the schema-level `required` flag below;
-    // inference only ever ADDS requiredness, never removes it. (#842)
-    const inferredRequired = inferRequiredRecordFields(operations);
-    // model name → resolved record interface name (used by query result aliases).
+    const ir = describeDbType(input);
+    // model name → resolved record interface name (used by query result aliases),
+    // with the same collision guard the inline implementation had.
     const recordInterfaceByModel = {};
-    // model name → the field names that appear on its record interface (declared
-    // fields + server-stamped fields). Used to guard projection `Pick`
-    // against keys that are not members of the interface (#1439).
-    const recordFieldsByModel = new Map();
-    // model name → declared field name → field type. Feeds the `$in`/`$nin`
-    // array-param element-type inference (#1488) below.
-    const fieldTypesByModel = new Map();
-    for (const schema of schemas) {
-        const ftypes = new Map();
-        for (const [fname, fopts] of Object.entries(schema.fields)) {
-            const t = fopts?.type;
-            if (typeof t === "string")
-                ftypes.set(fname, t);
-        }
-        fieldTypesByModel.set(schema.name, ftypes);
-    }
     const seenInterfaceNames = new Map(); // interfaceName → modelName
-    for (const schema of schemas) {
-        const ifaceName = resolveRecordInterfaceName(schema.name, schema.options?.className);
+    for (const rec of ir.records) {
+        const ifaceName = resolveRecordInterfaceName(rec.modelName, rec.className);
         const prior = seenInterfaceNames.get(ifaceName);
-        if (prior !== undefined && prior !== schema.name) {
+        if (prior !== undefined && prior !== rec.modelName) {
             throw new Error(`Record-interface name collision: models "${prior}" and ` +
-                `"${schema.name}" both produce interface "${ifaceName}". Add a ` +
+                `"${rec.modelName}" both produce interface "${ifaceName}". Add a ` +
                 `class_name override to one of them.`);
         }
-        seenInterfaceNames.set(ifaceName, schema.name);
-        recordInterfaceByModel[schema.name] = ifaceName;
-        const memberNames = new Set(Object.keys(schema.fields));
-        for (const stamped of stampedFields)
-            memberNames.add(stamped);
-        recordFieldsByModel.set(schema.name, memberNames);
+        seenInterfaceNames.set(ifaceName, rec.modelName);
+        recordInterfaceByModel[rec.modelName] = ifaceName;
     }
     const blocks = [];
-    blocks.push(renderHeader(fingerprint));
+    blocks.push(renderHeader(ir.fingerprint));
     blocks.push(RESULT_ALIASES_BLOCK.trimEnd());
     // Record interfaces, sorted by interface name for deterministic output.
-    const sortedSchemas = [...schemas].sort((a, b) => recordInterfaceByModel[a.name].localeCompare(recordInterfaceByModel[b.name]));
-    for (const schema of sortedSchemas) {
-        const inferredForModel = inferredRequired.get(schema.name)?.fields;
-        const fields = Object.entries(schema.fields).map(([name, opts]) => ({
-            name,
-            type: opts.type,
-            required: opts.required === true ||
-                (opts.autoAssign === true && name === "id") ||
-                inferredForModel?.has(name) === true,
-            // Allowed-value set for string fields → string-literal union (#843).
-            // Threaded through the shared loader's FieldOptions.enum; validated
-            // (non-empty, all-string, string-only) by parseFieldOptions upstream.
-            enum: opts.enum,
-        }));
+    const sortedRecords = [...ir.records].sort((a, b) => recordInterfaceByModel[a.modelName].localeCompare(recordInterfaceByModel[b.modelName]));
+    for (const rec of sortedRecords) {
         blocks.push(renderRecordInterface({
-            interfaceName: recordInterfaceByModel[schema.name],
-            modelName: schema.name,
-            fields,
-            stampedFields,
+            interfaceName: recordInterfaceByModel[rec.modelName],
+            modelName: rec.modelName,
+            fields: rec.fields,
+            stampedFields: ir.stampedFields,
         }));
     }
-    // Operation interfaces + result aliases, sorted by op name.
-    const sortedOps = [...operations]
-        .filter((op) => op && typeof op.name === "string")
-        .sort((a, b) => a.name.localeCompare(b.name));
-    // Descriptors for the typed-ops factory (#1441), collected in the same
-    // name-sorted order so the factory's methods are deterministic.
+    // Operation interfaces + result aliases, already sorted by op name in the IR.
+    // Descriptors for the typed-ops factory (#1441), collected in the same order.
     const factoryOps = [];
-    for (const op of sortedOps) {
-        const inferredArrays = inferArrayParamElementTypes(op, fieldTypesByModel);
-        const params = paramsToFields(op.params, inferredArrays);
+    for (const op of ir.ops) {
         blocks.push(renderOpParamsInterface({
-            interfaceName: opParamsInterfaceName(op.name),
-            opName: op.name,
-            params,
+            interfaceName: opParamsInterfaceName(op.opName),
+            opName: op.opName,
+            params: op.params,
         }));
         factoryOps.push({
-            propertyKey: opPropertyKey(op.name),
-            opName: op.name,
-            paramsInterfaceName: opParamsInterfaceName(op.name),
-            resultAliasName: opResultAliasName(op.name),
-            hasParams: params.length > 0,
+            propertyKey: objectPropertyKey(op.opName),
+            opName: op.opName,
+            paramsInterfaceName: opParamsInterfaceName(op.opName),
+            resultAliasName: opResultAliasName(op.opName),
+            hasParams: op.hasParams,
         });
-        const recordInterfaceName = op.type === "query" && op.modelName
-            ? recordInterfaceByModel[op.modelName] ?? null
+        const recordInterfaceName = op.resultModelName
+            ? recordInterfaceByModel[op.resultModelName] ?? null
             : null;
-        // Query ops: narrow the record type by the op's static projection (#1439).
-        const projection = op.type === "query"
-            ? classifyProjection(op.definition?.projection, (op.modelName && recordFieldsByModel.get(op.modelName)) ||
-                new Set())
-            : undefined;
-        // Pipeline ops: resolve the `return`-step result shape (#1437).
-        const pipelineReturn = op.type === "pipeline"
-            ? resolvePipelineReturn(op.definition, recordInterfaceByModel, recordFieldsByModel)
+        const pipelineReturn = op.pipelineReturn
+            ? mapPipelineReturn(op.pipelineReturn, recordInterfaceByModel)
             : undefined;
         blocks.push(renderOpResultAlias({
-            aliasName: opResultAliasName(op.name),
-            opName: op.name,
-            opType: op.type,
+            aliasName: opResultAliasName(op.opName),
+            opName: op.opName,
+            opType: op.opType,
             recordInterfaceName,
-            projection,
+            projection: op.projection,
             pipelineReturn,
         }));
     }
-    // Typed-ops factory (#1441): one method per op pairing `<Op>Params` in with
-    // `<Op>Result` out. Omitted entirely for a type with no operations.
-    if (factoryOps.length > 0) {
-        blocks.push(renderOpsFactory({
-            factoryName: opsFactoryName(input.databaseType),
+    // Typed-subscriptions descriptors (#1544 Phase 2): map each subscription's
+    // model to its record interface (or a `Pick` when it declares `select`). The
+    // IR already validated that every model resolves and every select field is a
+    // known member, so this mapping never fails.
+    const factorySubscriptions = ir.subscriptions.map((sub) => {
+        const interfaceName = recordInterfaceByModel[sub.modelName];
+        const eventType = sub.select && sub.select.length > 0
+            ? `Pick<${interfaceName}, ${sub.select
+                .map((f) => JSON.stringify(f))
+                .join(" | ")}>`
+            : interfaceName;
+        return {
+            propertyKey: objectPropertyKey(sub.subscriptionKey),
+            subscriptionKey: sub.subscriptionKey,
+            eventType,
+        };
+    });
+    // Typed-ops factory (#1441) + typed-subscriptions factory (#1544 Phase 2),
+    // sharing one structural client interface. Omitted entirely for a type with
+    // neither ops nor subscriptions.
+    if (factoryOps.length > 0 || factorySubscriptions.length > 0) {
+        blocks.push(renderFactories({
             databaseType: input.databaseType,
+            opsFactoryName: opsFactoryName(input.databaseType),
+            subscriptionsFactoryName: subscriptionsFactoryName(input.databaseType),
             ops: factoryOps,
+            subscriptions: factorySubscriptions,
         }));
     }
     // Single trailing newline; blocks separated by a blank line.
     return blocks.join("\n\n") + "\n";
 }
-/**
- * Classify a query op's static `projection` into how it narrows the record type
- * (#1439). Kept private to the generator: the returned `{ kind, fields }` shape
- * is what the template needs, and the field-guard / `id`-folding / sorting live
- * here so the template stays a pure string-emitter.
- *
- * `recordFieldNames` is the set of members on the record interface (declared +
- * stamped). A projected key that is not a member (a nested `"a.b"` path, or a
- * field absent from the schema) makes the whole projection fall back to
- * `Partial<M>` rather than emit an invalid `Pick`. Reused for a pipeline
- * op's returning `query` step (#1437).
- *
- * Rules (projection values are validated server-side to be `1` or `0`, mixing
- * rejected — codegen runs pre-push, so it still guards):
- *   - absent / not an object / empty `{}`      → `full` (whole record `M`).
- *   - all `1` (inclusion), keys all known      → `pick` (with `id` folded in,
- *                                                since inclusion always retains
- *                                                `id` at runtime).
- *   - all `0` (exclusion), keys all known       → `partial`. The DO runtime does
- *                                                not strip excluded fields yet, so
- *                                                an `Omit` would hide fields that
- *                                                are still returned (#1439/Codex-P2).
- *   - mixed / dynamic / non-`1|0` / unknown key → `partial` (honest fallback).
- */
-function classifyProjection(projection, recordFieldNames) {
-    if (!projection ||
-        typeof projection !== "object" ||
-        Array.isArray(projection)) {
-        return { kind: "full" };
-    }
-    const entries = Object.entries(projection);
-    if (entries.length === 0)
-        return { kind: "full" };
-    let allInclude = true;
-    let allExclude = true;
-    const included = [];
-    const excluded = [];
-    for (const [field, val] of entries) {
-        if (val === 1) {
-            included.push(field);
-            allExclude = false;
-        }
-        else if (val === 0) {
-            excluded.push(field);
-            allInclude = false;
-        }
-        else {
-            // A dynamic (`$params.x`) or otherwise non-`1|0` value — can't resolve
-            // statically. Fall back rather than emit garbage.
-            allInclude = false;
-            allExclude = false;
-        }
-    }
-    if (allInclude && included.length > 0) {
-        if (!included.every((f) => recordFieldNames.has(f)))
-            return { kind: "partial" };
-        // Inclusion always retains `id` at runtime (the DO unshifts it), so fold it
-        // into the union when the model has an `id` field.
-        const fields = new Set(included);
-        if (recordFieldNames.has("id"))
-            fields.add("id");
-        return { kind: "pick", fields: [...fields].sort() };
-    }
-    if (allExclude && excluded.length > 0) {
-        // Exclusion projection (e.g. `{ secret: 0 }`). The DO query runtime does
-        // NOT actually strip excluded fields today: `JsonQueryTranslator` selects
-        // `_data` for excludes and `_handleQuery` merges the full row via
-        // `_parseRow`, so the excluded field is still present in the response.
-        // Emitting `Omit<M, ...>` would hide fields that ARE returned and break
-        // existing TS callers after regeneration, so type these as `Partial<M>`
-        // until the runtime filters them (#1439 / Codex-P2).
-        return { kind: "partial" };
-    }
-    return { kind: "partial" };
-}
-/**
- * Resolve a pipeline op's `return`-step result shape (#1437). The runtime
- * flattens a returning pipeline to the returned step's shape, so codegen types
- * it as that step's result. `return: "all"`, no `return`, or any step the
- * generator can't resolve fall back to `opaque` → the generic `PipelineResult`.
- * Never throws — one odd op must not break codegen for the whole file.
- */
-function resolvePipelineReturn(definition, recordInterfaceByModel, recordFieldsByModel) {
-    if (!definition || typeof definition !== "object")
-        return { kind: "opaque" };
-    const def = definition;
-    const ret = def.return ?? "all";
-    if (ret === "all" || typeof ret !== "string")
-        return { kind: "opaque" };
-    if (!Array.isArray(def.steps))
-        return { kind: "opaque" };
-    const step = def.steps.find((s) => s && typeof s === "object" && s.name === ret);
-    if (!step)
-        return { kind: "opaque" };
-    if (step.type === "query") {
-        const modelName = typeof step.modelName === "string" ? step.modelName : undefined;
-        const recordInterfaceName = modelName
-            ? recordInterfaceByModel[modelName] ?? null
-            : null;
-        const fieldNames = (modelName && recordFieldsByModel.get(modelName)) || new Set();
-        const projection = classifyProjection(step.projection, fieldNames);
-        return { kind: "query", recordInterfaceName, projection };
-    }
-    if (step.type === "count")
-        return { kind: "count" };
-    if (step.type === "aggregate")
-        return { kind: "aggregate" };
-    return { kind: "opaque" };
-}
-/**
- * Collect the server-stamped field names from the parsed [type] config:
- * timestamps (`create`/`update` field names) + auto-populated field names
- * (the keys of the `autoPopulatedFields` map). These appear on the READ
- * record interface as OPTIONAL props.
- */
-function collectStampedFields(typeConfig) {
-    const names = [];
-    const ts = typeConfig?.timestamps;
-    if (ts && typeof ts === "object") {
-        if (typeof ts.create === "string")
-            names.push(ts.create);
-        if (typeof ts.update === "string")
-            names.push(ts.update);
-    }
-    const apf = typeConfig?.autoPopulatedFields;
-    if (apf && typeof apf === "object") {
-        for (const key of Object.keys(apf))
-            names.push(key);
-    }
-    // De-dup, preserve first-seen order.
-    return [...new Set(names)];
-}
-/**
- * Convert the normalized op `params` map
- * (`{ name: { type, required, enum?, items? } }`) into a sorted list of
- * `ParamField`. Sorted by name for deterministic output. A string param's
- * `enum` (#861) is carried through so the emitter can render a string-literal
- * union.
- *
- * `inferredArrayElements` (#1488, Phase 1) maps a param bound to a `$in`/`$nin`
- * filter operator to its inferred scalar element TS type (or the `"unknown"`
- * sentinel → `unknown[]`). Inference only ever NARROWS a param the emitter
- * would otherwise widen: an explicit `type = "array"` declaration (Phase 2)
- * always wins, and a param absent from the map keeps its declared-type mapping.
- */
-function paramsToFields(params, inferredArrayElements) {
-    if (!params || typeof params !== "object")
-        return [];
-    return Object.entries(params)
-        .map(([name, def]) => {
-        const rawType = def?.type;
-        const declaredType = rawType ?? "object";
-        const declaredItems = def?.items;
-        let type = declaredType;
-        let items = declaredItems;
-        // Apply inference only to untyped/`object` params — the declaration is
-        // otherwise authoritative (behavior 8). A param explicitly declared as a
-        // scalar (`string`/`number`/`boolean`/`integer`) is validated by runtime
-        // `execute` against that scalar type; a param declared with a model type
-        // is treated as model-typed by the runtime `coerceParam`, which rejects
-        // arrays with "must be an object"; and an explicit `array` already has its
-        // element type. Rewriting any of those to an inferred array would emit a
-        // type the server is guaranteed to reject. Only untyped/`object` params
-        // (which the emitter would otherwise widen to `Record<string, unknown>`)
-        // are eligible. Since `declaredType = rawType ?? "object"`, `=== "object"`
-        // matches both a missing `type` and an explicit `object` declaration.
-        const inferred = inferredArrayElements?.get(name);
-        if (declaredType === "object" && inferred !== undefined) {
-            type = "array";
-            // The `"unknown"` sentinel means "array, element unresolved": leave
-            // `items` undefined so the emitter renders `unknown[]`.
-            items = inferred === "unknown" ? undefined : inferred;
-        }
-        return {
-            name,
-            type,
-            required: def?.required === true,
-            // Allowed-value set for a string param → string-literal union (#861).
-            // `normalizeOperationFromToml` preserves `enum` upstream via its
-            // `...rest` spread; carry it through here so it reaches the emitter.
-            enum: def?.enum,
-            items,
-        };
-    })
-        .sort((a, b) => a.name.localeCompare(b.name));
-}
-/**
- * Infer the scalar element TS type for op params consumed by a `$in`/`$nin`
- * filter operator (#1488, Phase 1). Codegen-only: a param compared with
- * `$in`/`$nin` against a model field is definitionally an array, so the
- * typed-ops factory (#1441) should emit `<elem>[]` rather than widening an
- * untyped/object param to `Record<string, unknown>` (which `string[]` is not
- * assignable to).
- *
- * Kept a small local helper next to {@link inferRequiredRecordFields} rather
- * than a shared cross-runtime analysis pass (sponsor decision on #1488).
- *
- * Returns a map of param name → element TS type. The `"unknown"` sentinel means
- * "emit `unknown[]`" — used when the compared field is missing from the model
- * schema (or the op has no resolvable model), when the same param is bound to
- * fields of differing element types, or when the param is also used as a scalar
- * elsewhere (conservative widen, mirroring #845's disagreement rule / #1488
- * Fork 4). A param absent from the map is not consumed by any array operator
- * and keeps its declared-type mapping (inference never widens such a param).
- */
-export function inferArrayParamElementTypes(op, fieldTypesByModel) {
-    const result = new Map();
-    if (!op || typeof op !== "object")
-        return result;
-    const def = op.definition;
-    if (!def || typeof def !== "object")
-        return result;
-    // Element TS types seen for each param via `$in`/`$nin` (deduped). A param
-    // also seen as a scalar reference is widened to `unknown[]`.
-    const arrayElems = new Map();
-    const scalarRefs = new Set();
-    const addArrayElem = (param, elem) => {
-        let s = arrayElems.get(param);
-        if (!s) {
-            s = new Set();
-            arrayElems.set(param, s);
-        }
-        s.add(elem);
-    };
-    // A bare `$params.<name>` string → the param name, else null.
-    const paramRef = (v) => {
-        if (typeof v !== "string")
-            return null;
-        const m = v.match(/^\$params\.([A-Za-z0-9_]+)$/);
-        return m ? m[1] : null;
-    };
-    // Scalar element TS type for `field` of the current model, or `"unknown"`.
-    // A `stringset` field's ELEMENT is a string (#1488, e7) — do NOT reuse
-    // `tsTypeForDbFieldType`, which maps `stringset → string[]` and would emit
-    // `string[][]` for the param.
-    const elemTypeForField = (field, fields) => {
-        const ftype = fields?.get(field);
-        if (ftype === undefined)
-            return "unknown"; // missing field / no schema (e2)
-        if (ftype === "stringset")
-            return "string";
-        const ts = tsTypeForDbFieldType(ftype);
-        return ts === "string" || ts === "number" || ts === "boolean"
-            ? ts
-            : "unknown";
-    };
-    const modelFields = (name) => typeof name === "string" ? fieldTypesByModel.get(name) : undefined;
-    // Walk a filter object, resolving field conditions against `fields`.
-    const walkFilter = (filter, fields) => {
-        if (!filter || typeof filter !== "object" || Array.isArray(filter))
-            return;
-        for (const [key, value] of Object.entries(filter)) {
-            if (key === "$and" || key === "$or") {
-                if (Array.isArray(value)) {
-                    for (const sub of value)
-                        walkFilter(sub, fields);
-                }
-                continue;
-            }
-            // `$not` is a logical operator too, but (unlike `$and`/`$or`) it wraps a
-            // SINGLE nested condition object rather than an array — recurse into it so
-            // an `$in`/`$nin` inside a negated filter still infers its element type.
-            // Mirrors the operation grammar walker in
-            // `src/app-api/services/walk-operation.ts` (`walkFilterFields`), which
-            // treats `$and`/`$or`/`$not` as the recursing logical operators; the two
-            // walk the same op-definition filter grammar and must agree.
-            if (key === "$not") {
-                walkFilter(value, fields);
-                continue;
-            }
-            // Field condition: `key` is a field name; `value` is a scalar (shorthand
-            // equality) or an operator map (`{ $in: ..., $eq: ... }`).
-            if (value && typeof value === "object" && !Array.isArray(value)) {
-                for (const [operator, opVal] of Object.entries(value)) {
-                    const p = paramRef(opVal);
-                    if (!p)
-                        continue;
-                    if (operator === "$in" || operator === "$nin") {
-                        addArrayElem(p, elemTypeForField(key, fields));
-                    }
-                    else {
-                        // A scalar operator ($eq/$ne/$gt/…) binds a scalar param.
-                        scalarRefs.add(p);
-                    }
-                }
-            }
-            else {
-                const p = paramRef(value);
-                if (p)
-                    scalarRefs.add(p);
-            }
-        }
-    };
-    // Top-level query filter.
-    walkFilter(def.filter, modelFields(op.modelName));
-    // `applyToQuery` ops hold their matching query under `definition.source`
-    // (`source.filter`), which resolves against the op's own model unless the
-    // source names a different one. Without this walk, an `$in`/`$nin` against an
-    // object/untyped param inside `source.filter` stays widened to
-    // `Record<string, unknown>` — the original array-param bug (#1488).
-    if (def.source && typeof def.source === "object") {
-        walkFilter(def.source.filter, modelFields(def.source.modelName ?? op.modelName));
-    }
-    // Mutation inner operations — each may carry its own filter + modelName.
-    if (Array.isArray(def.operations)) {
-        for (const inner of def.operations) {
-            if (inner && typeof inner === "object") {
-                walkFilter(inner.filter, modelFields(inner.modelName ?? op.modelName));
-            }
-        }
-    }
-    // Pipeline steps — each may carry its own filter + modelName.
-    if (Array.isArray(def.steps)) {
-        for (const step of def.steps) {
-            if (step && typeof step === "object") {
-                walkFilter(step.filter, modelFields(step.modelName ?? op.modelName));
-            }
-        }
-    }
-    for (const [param, elems] of arrayElems) {
-        if (scalarRefs.has(param) || elems.size !== 1) {
-            // Used as both array and scalar, or bound to differing element types.
-            result.set(param, "unknown");
-        }
-        else {
-            result.set(param, [...elems][0]);
-        }
-    }
-    return result;
-}
-/**
- * Infer which record fields are always supplied at create time, by reading the
- * `save` operation params (issue #842).
- *
- * A field is promoted to required for a model only if:
- *   - at least one `save` (create) op writes it from a bare `$params.X`
- *     binding, AND
- *   - EVERY `save` op that writes the field binds it to a param declared
- *     `required: true` (the "ALL writers agree" rule).
- *
- * Deliberately conservative:
- *   - `patch` (and every non-`save` inner op) is excluded — partial updates
- *     don't guarantee creation-time presence.
- *   - whole-object saves (`data = "$params.X"`, a string rather than a
- *     per-field map) carry no field-level mapping, so no field can be promoted
- *     from them (Q4 skip).
- *   - only an EXACT top-level bare `$params.X` value counts (the whole binding
- *     value must match `^\$params\.X$`, and `X` must be a declared top-level
- *     param). A literal, computed, partially-interpolated value, or a nested
- *     path (`$params.obj.sub`) never promotes a field — a nested sub-property
- *     may be absent even when the top-level object param is required. This is
- *     deliberately stricter than the CLI's lenient `collectParamRefs`
- *     first-segment rule, which is fine for its validation use but would
- *     wrongly promote nested bindings here.
- *   - inner ops are matched to the record model by the inner op's own
- *     `modelName` when present, falling back to the enclosing operation's
- *     `modelName`.
- *
- * Pure: no I/O, no mutation of the input. The caller OR's the result with the
- * schema-level `required` flag, so inference only ever ADDS requiredness.
- */
-export function inferRequiredRecordFields(operations) {
-    // model → field → running verdict. `true` = every save op seen so far that
-    // sets the field bound it to a required param; `false` = at least one save op
-    // set it from an optional/absent param (sticky — never recovers).
-    const verdicts = new Map();
-    for (const op of operations ?? []) {
-        if (!op || op.type !== "mutation")
-            continue;
-        const innerOps = op.definition?.operations;
-        if (!Array.isArray(innerOps))
-            continue;
-        const params = op.params && typeof op.params === "object" ? op.params : {};
-        for (const inner of innerOps) {
-            if (!inner || inner.op !== "save")
-                continue;
-            // Whole-object save (`data` is a string $params ref) has no per-field
-            // map — skip (Q4).
-            const data = inner.data;
-            if (!data || typeof data !== "object" || Array.isArray(data))
-                continue;
-            const modelName = inner.modelName ?? op.modelName;
-            if (typeof modelName !== "string" || modelName === "")
-                continue;
-            let fieldVerdicts = verdicts.get(modelName);
-            if (!fieldVerdicts) {
-                fieldVerdicts = new Map();
-                verdicts.set(modelName, fieldVerdicts);
-            }
-            for (const [field, value] of Object.entries(data)) {
-                // Only an EXACT top-level bare binding (`$params.X`, no further `.sub`
-                // path) counts. `collectParamRefs` is intentionally lenient — it
-                // returns the FIRST dotted segment, so `$params.profile.name` yields
-                // `["profile"]` and would wrongly promote a field that actually reads
-                // a nested sub-property that may be absent. We match the whole value
-                // against `^\$params\.X$` here instead, leaving `collectParamRefs`
-                // untouched for its validation use. Partial interpolation
-                // (`prefix-$params.X`), literals, and nested paths all fail this match
-                // and therefore never promote a field.
-                const match = typeof value === "string"
-                    ? value.match(/^\$params\.([A-Za-z0-9_]+)$/)
-                    : null;
-                if (!match) {
-                    // Not an exact top-level bare param binding — this save op cannot
-                    // prove the field required. Mark it not-required for this writer.
-                    fieldVerdicts.set(field, false);
-                    continue;
-                }
-                const paramName = match[1];
-                // The matched name must resolve to a declared top-level param.
-                const required = params[paramName]?.required === true;
-                const prior = fieldVerdicts.get(field);
-                // ALL-writers semantics: stays `true` only while every save writer
-                // agrees; one disagreeing writer flips it to `false` permanently.
-                fieldVerdicts.set(field, prior === false ? false : required);
-            }
-        }
-    }
-    const result = new Map();
-    for (const [modelName, fieldVerdicts] of verdicts) {
-        const fields = new Set();
-        for (const [field, verdict] of fieldVerdicts) {
-            if (verdict)
-                fields.add(field);
-        }
-        if (fields.size > 0)
-            result.set(modelName, { fields });
-    }
-    return result;
-}
 /**
  * Run codegen end-to-end across one or more database-type TOML inputs. The
  * disk lifecycle (write / `--check` / stale cleanup) is delegated to the