@angriff36/manifest 2.18.0

package/dist/manifest/projections/convex/functions.js

@@ -0,0 +1,786 @@
+/**
+ * Convex functions surfaces: `convex.queries` and `convex.mutations`.
+ *
+ * Queries are reactive reads over `ctx.db` (reads are not governed). Mutations
+ * are governed writes: each IR command becomes a Convex `mutation` that runs the
+ * command's policies → guards → constraints (rendered from IR via the
+ * fail-closed expression resolver), applies the command's mutate actions,
+ * appends an event row, and fires matched reactions.
+ *
+ * Governance is rendered FAIL CLOSED: any guard/policy/constraint the resolver
+ * cannot fully map produces a hard diagnostic AND a denying `throw`, never a
+ * silent pass.
+ */
+import { normalizeOptions } from './options.js';
+import { resolveConvexTableName, collectFkTargets, collectReferenceFields, indexEntryToDef, buildValidator, isPersistentEntity, resolveEventsTableName, } from './generator.js';
+import { resolveConvexValidator } from './type-mapping.js';
+import { renderExpression, isNullLiteral } from './expression.js';
+const GENERATED_HEADER = '// GENERATED by the Manifest → Convex projection. DO NOT EDIT.';
+// ---------------------------------------------------------------------------
+// Shared helpers
+// ---------------------------------------------------------------------------
+function persistentEntities(ir) {
+    return ir.entities.filter(e => isPersistentEntity(e, ir));
+}
+/**
+ * Render an IR default value to a TS literal that satisfies a Convex validator.
+ *
+ * Two of the projection's type mappings are *representational*: `int`/`bigint`
+ * map to `v.int64()` (a JS `bigint`) and `decimal`/`money` map to `v.string()`
+ * (lossless decimal transport — Convex has no native Decimal). A structurally
+ * faithful render of an IR `number` default (`1`) is the WRONG runtime type for
+ * those validators — Convex rejects a JS number where it expects a bigint or a
+ * string — so the create-mutation default fill would fail schema validation at
+ * insert time. Coerce numeric leaves to the validator's representation.
+ *
+ * `validator` is the field's resolved expression (possibly `v.optional`/
+ * `v.array`-wrapped); detection is structural so per-property `typeMappings`
+ * overrides are honored. Arrays share their element validator, so it propagates
+ * to elements; objects carry heterogeneous members the field validator does not
+ * describe, so their members are rendered structurally (no coercion).
+ */
+function defaultToTs(value, validator) {
+    switch (value.kind) {
+        case 'string': return JSON.stringify(value.value);
+        case 'number':
+            // int64 wants a bigint literal; a non-integer default on an int field is
+            // an authoring contradiction — surface it as a type error, don't truncate.
+            if (validator && /\bv\.int64\(\)/.test(validator) && Number.isInteger(value.value)) {
+                return `${value.value}n`;
+            }
+            // decimal/money (and stringId FKs) transport as strings.
+            if (validator && /\bv\.string\(\)/.test(validator)) {
+                return JSON.stringify(String(value.value));
+            }
+            return String(value.value);
+        case 'boolean': return String(value.value);
+        case 'null': return 'null';
+        case 'array': return `[${value.elements.map(el => defaultToTs(el, validator)).join(', ')}]`;
+        case 'object': return `{${Object.entries(value.properties).map(([k, v]) => `${JSON.stringify(k)}: ${defaultToTs(v)}`).join(', ')}}`;
+    }
+}
+/**
+ * Render a mutate-action right-hand side, converting a literal-`null` assignment
+ * to a NON-nullable field into `undefined`. Convex rejects `null` for an
+ * `v.optional(T)` column but treats `undefined` as "unset" — so a DSL `= null`
+ * "clear"/"restore" must lower to field omission, not a rejected null write.
+ * Nullable fields (schema `v.union(T, v.null())`) keep `null`.
+ */
+function renderActionValue(entity, target, expression, scope) {
+    const res = renderExpression(expression, scope);
+    if (res.unresolved.length === 0 && target && isNullLiteral(expression)) {
+        const targetProp = entity.properties.find(p => p.name === target);
+        if (targetProp?.type.nullable !== true) {
+            return { code: 'undefined', unresolved: res.unresolved };
+        }
+    }
+    return res;
+}
+/**
+ * Validator expression for a command parameter (no optional wrap). Mirrors the
+ * entity-field `array<T>` handling so an `array`-typed param maps to
+ * `v.array(<element>)` instead of collapsing to a structureless `v.any()`.
+ * Unknown leaf types still fall back to `v.any()` (params are not schema fields,
+ * so an unmapped type is permissive rather than a hard diagnostic).
+ */
+function paramValidator(type) {
+    if (type.name === 'array' && type.generic) {
+        const element = resolveConvexValidator(type.generic.name, undefined, '') ?? 'v.any()';
+        return `v.array(${element})`;
+    }
+    return resolveConvexValidator(type.name, undefined, '') ?? 'v.any()';
+}
+// ---------------------------------------------------------------------------
+// Queries
+// ---------------------------------------------------------------------------
+function capWord(s) {
+    return s.charAt(0).toUpperCase() + s.slice(1);
+}
+/**
+ * The indexes an entity exposes as reads, derived to match EXACTLY what the
+ * schema surface emits (`generator.ts#emitTable`): `indexed`-modifier properties,
+ * the tenant column, every belongsTo/ref FK (in BOTH reference modes), and every
+ * `options.indexes` entry (single-field AND composite). Single-field specs are
+ * deduped by column in schema order; composite specs by index name. The result
+ * guarantees every schema index has a corresponding `list<Entity>By<Field...>`
+ * query — the two surfaces can no longer drift (closing both the stringId-mode
+ * FK gap and the composite-index gap).
+ */
+function collectQueryIndexSpecs(ir, entity, options) {
+    const specs = [];
+    const seenSingle = new Set();
+    const seenName = new Set();
+    // convexId-only targets: present → arg typed `v.id(target)`; absent → `v.string()`.
+    const fkTargets = collectFkTargets(entity, ir, options);
+    const mkField = (name) => ({ name, fkTarget: fkTargets.get(name) });
+    const addSingle = (field, indexName) => {
+        if (field === 'id' || seenSingle.has(field))
+            return;
+        seenSingle.add(field);
+        seenName.add(indexName);
+        specs.push({ fields: [mkField(field)], indexName });
+    };
+    for (const p of entity.properties) {
+        if (p.modifiers.includes('indexed'))
+            addSingle(p.name, `by_${p.name}`);
+    }
+    const tenantProp = ir.tenant?.property;
+    if (tenantProp && entity.properties.some(p => p.name === tenantProp))
+        addSingle(tenantProp, `by_${tenantProp}`);
+    for (const fk of collectReferenceFields(entity, ir, options).keys())
+        addSingle(fk, `by_${fk}`);
+    for (const entry of options.indexes[entity.name] ?? []) {
+        const def = indexEntryToDef(entry);
+        if (def.fields.length === 1) {
+            addSingle(def.fields[0], def.name);
+        }
+        else if (def.fields.length > 1 && !seenName.has(def.name)) {
+            seenName.add(def.name);
+            specs.push({ fields: def.fields.map(mkField), indexName: def.name });
+        }
+    }
+    return specs;
+}
+function resolveReadFilter(ir, entity, options) {
+    const tenantProp = options.tenantIdProperty ?? ir.tenant?.property;
+    const hasTenant = options.includeTenantFilter && !!tenantProp
+        && entity.properties.some(p => p.name === tenantProp);
+    const deletedProp = options.deletedAtProperty;
+    const hasSoftDelete = options.includeSoftDeleteFilter
+        && entity.properties.some(p => p.name === deletedProp);
+    return {
+        hasTenant,
+        tenantProp: hasTenant ? tenantProp : undefined,
+        tenantIndexed: hasTenant && tenantProp === ir.tenant?.property,
+        hasSoftDelete,
+        deletedProp,
+    };
+}
+export function generateQueries(ir, rawOptions) {
+    const options = normalizeOptions(rawOptions);
+    const diagnostics = [];
+    const blocks = [];
+    for (const entity of persistentEntities(ir)) {
+        const table = resolveConvexTableName(entity.name, options);
+        const rf = resolveReadFilter(ir, entity, options);
+        // list<Entity> — tenant-scoped + soft-delete-filtered by default. The tenant
+        // id comes from the authenticated identity (never a client arg), so an
+        // un-scoped list cannot leak rows across tenants.
+        if (!rf.hasTenant && !rf.hasSoftDelete) {
+            blocks.push(`export const list${entity.name} = query({\n` +
+                `  args: {},\n` +
+                `  handler: async (ctx) => {\n` +
+                `    return await ctx.db.query("${table}").collect();\n` +
+                `  },\n});`);
+        }
+        else {
+            const lines = [];
+            if (rf.hasTenant)
+                lines.push(`    const __tenant = (ctx as any).auth?.${rf.tenantProp} ?? null;`);
+            if (rf.hasTenant && rf.tenantIndexed) {
+                lines.push(`    let rows = await ctx.db.query("${table}").withIndex("by_${rf.tenantProp}", (q) => q.eq("${rf.tenantProp}", __tenant)).collect();`);
+            }
+            else {
+                lines.push(`    let rows = await ctx.db.query("${table}").collect();`);
+                if (rf.hasTenant)
+                    lines.push(`    rows = rows.filter((d) => (d as any).${rf.tenantProp} === __tenant);`);
+            }
+            if (rf.hasSoftDelete)
+                lines.push(`    rows = rows.filter((d) => (d as any).${rf.deletedProp} == null);`);
+            lines.push(`    return rows;`);
+            blocks.push(`export const list${entity.name} = query({\n` +
+                `  args: {},\n` +
+                `  handler: async (ctx) => {\n${lines.join('\n')}\n  },\n});`);
+        }
+        // get<Entity> by Convex _id — returns null on tenant mismatch / soft-deleted.
+        if (!rf.hasTenant && !rf.hasSoftDelete) {
+            blocks.push(`export const get${entity.name} = query({\n` +
+                `  args: { id: v.id("${table}") },\n` +
+                `  handler: async (ctx, { id }) => {\n` +
+                `    return await ctx.db.get(id);\n` +
+                `  },\n});`);
+        }
+        else {
+            const lines = [`    const doc = await ctx.db.get(id);`];
+            if (rf.hasTenant) {
+                lines.push(`    const __tenant = (ctx as any).auth?.${rf.tenantProp} ?? null;`);
+                lines.push(`    if (doc && (doc as any).${rf.tenantProp} !== __tenant) return null;`);
+            }
+            if (rf.hasSoftDelete)
+                lines.push(`    if (doc && (doc as any).${rf.deletedProp} != null) return null;`);
+            lines.push(`    return doc;`);
+            blocks.push(`export const get${entity.name} = query({\n` +
+                `  args: { id: v.id("${table}") },\n` +
+                `  handler: async (ctx, { id }) => {\n${lines.join('\n')}\n  },\n});`);
+        }
+        // list<Entity>By<Field...> — one per schema index (indexed, tenant, every
+        // reference FK in both modes, single-field AND composite option indexes).
+        // Soft-delete + (auth-derived) tenant filters apply unless the index itself
+        // already constrains the tenant column.
+        for (const spec of collectQueryIndexSpecs(ir, entity, options)) {
+            const names = spec.fields.map(f => f.name);
+            const suffix = spec.fields.map(f => capWord(f.name)).join('And');
+            const argList = spec.fields.map(f => `${f.name}: ${f.fkTarget ? `v.id("${f.fkTarget}")` : 'v.string()'}`).join(', ');
+            const destructure = `{ ${names.join(', ')} }`;
+            const eqChain = spec.fields.map(f => `.eq("${f.name}", ${f.name})`).join('');
+            const applyTenant = rf.hasTenant && !!rf.tenantProp && !names.includes(rf.tenantProp);
+            if (!applyTenant && !rf.hasSoftDelete) {
+                blocks.push(`export const list${entity.name}By${suffix} = query({\n` +
+                    `  args: { ${argList} },\n` +
+                    `  handler: async (ctx, ${destructure}) => {\n` +
+                    `    return await ctx.db.query("${table}").withIndex("${spec.indexName}", (q) => q${eqChain}).collect();\n` +
+                    `  },\n});`);
+            }
+            else {
+                const lines = [];
+                if (applyTenant)
+                    lines.push(`    const __tenant = (ctx as any).auth?.${rf.tenantProp} ?? null;`);
+                lines.push(`    let rows = await ctx.db.query("${table}").withIndex("${spec.indexName}", (q) => q${eqChain}).collect();`);
+                if (applyTenant)
+                    lines.push(`    rows = rows.filter((d) => (d as any).${rf.tenantProp} === __tenant);`);
+                if (rf.hasSoftDelete)
+                    lines.push(`    rows = rows.filter((d) => (d as any).${rf.deletedProp} == null);`);
+                lines.push(`    return rows;`);
+                blocks.push(`export const list${entity.name}By${suffix} = query({\n` +
+                    `  args: { ${argList} },\n` +
+                    `  handler: async (ctx, ${destructure}) => {\n${lines.join('\n')}\n  },\n});`);
+            }
+        }
+    }
+    // System events table reads (when emitted): recent feed + the three indexed
+    // lookups (by_type / by_entity / by_entityId) the schema declares on it.
+    if (options.emitEventsTable) {
+        const ev = resolveEventsTableName(ir, options);
+        blocks.push(`export const listRecentEvents = query({\n` +
+            `  args: {},\n` +
+            `  handler: async (ctx) => {\n` +
+            `    return await ctx.db.query("${ev}").order("desc").take(50);\n` +
+            `  },\n});`);
+        for (const field of ['type', 'entity', 'entityId']) {
+            blocks.push(`export const listEventsBy${capWord(field)} = query({\n` +
+                `  args: { ${field}: v.string() },\n` +
+                `  handler: async (ctx, { ${field} }) => {\n` +
+                `    return await ctx.db.query("${ev}").withIndex("by_${field}", (q) => q.eq("${field}", ${field})).collect();\n` +
+                `  },\n});`);
+        }
+    }
+    const code = `${GENERATED_HEADER}\n// ${blocks.length} query function(s).\n\n` +
+        `import { query } from "./_generated/server";\n` +
+        `import { v } from "convex/values";\n\n` +
+        `${blocks.join('\n\n')}\n`;
+    return { code, diagnostics };
+}
+// ---------------------------------------------------------------------------
+// Mutations
+// ---------------------------------------------------------------------------
+/** Build the ROLE_PERMISSIONS map literal from IR roles' effective permissions. */
+function roleMapLiteral(ir) {
+    const map = {};
+    for (const role of ir.roles ?? []) {
+        const actions = new Set();
+        for (const perm of role.effectivePermissions ?? [])
+            actions.add(perm.action);
+        map[role.name] = [...actions].sort();
+    }
+    return JSON.stringify(map, null, 2);
+}
+/** Render governance checks fail-closed. Returns TS lines + diagnostics. */
+function renderChecks(entityName, checks, scope) {
+    const lines = [];
+    const diagnostics = [];
+    for (const c of checks) {
+        const { code, unresolved } = renderExpression(c.expr, scope);
+        if (unresolved.length > 0) {
+            diagnostics.push({
+                severity: 'error',
+                code: c.code,
+                entity: entityName,
+                message: `${c.label}: could not resolve expression (${unresolved.join('; ')}). Emitted a denying throw (fail-closed).`,
+            });
+            lines.push(`    throw new Error(${JSON.stringify(`${c.label} unresolved — denied`)});`);
+        }
+        else {
+            lines.push(`    if (!(${code})) throw new Error(${JSON.stringify(c.message)});`);
+        }
+    }
+    return { lines, diagnostics };
+}
+/** Collect the policy/guard/constraint checks for a command, in runtime order. */
+function commandChecks(ir, cmd, policyMode) {
+    const checks = [];
+    if (policyMode !== 'skip') {
+        for (const pName of cmd.policies ?? []) {
+            const policy = ir.policies.find(p => p.name === pName);
+            if (!policy)
+                continue;
+            checks.push({ expr: policy.expression, message: policy.message ?? `Policy ${pName} denied`, code: 'CONVEX_UNRESOLVED_POLICY', label: `policy '${pName}'` });
+        }
+    }
+    for (let i = 0; i < cmd.guards.length; i++) {
+        checks.push({ expr: cmd.guards[i], message: `Guard ${i} failed`, code: 'CONVEX_UNRESOLVED_GUARD', label: `guard[${i}]` });
+    }
+    for (const c of (cmd.constraints ?? [])) {
+        if (c.severity && c.severity !== 'block')
+            continue;
+        checks.push({ expr: c.expression, message: c.message ?? c.messageTemplate ?? `Constraint ${c.code} failed`, code: 'CONVEX_UNRESOLVED_CONSTRAINT', label: `constraint '${c.code}'` });
+    }
+    return checks;
+}
+/** Render reaction fan-out for the events a command emits. */
+function renderReactions(ir, options, emits) {
+    const lines = [];
+    const diagnostics = [];
+    const matched = (ir.reactions ?? []).filter((r) => emits.includes(r.event));
+    if (matched.length === 0)
+        return { lines, diagnostics };
+    lines.push('    // Reactions');
+    const tenantProp = ir.tenant?.property;
+    // Count vars + the shared tenant binding are handler-scoped (one handler per
+    // command, so all matched reactions share a scope); dedupe across reactions.
+    let countCounter = 0;
+    let tenantEmitted = false;
+    /**
+     * Render ONE reaction param. An aggregate-count param lowers to a read block
+     * (preLines) that counts rows of the param's entity matching its ANDed equality
+     * predicates, then binds the param to that count variable. The foreign-key (or
+     * any indexed) predicate drives a `withIndex` read; remaining predicates,
+     * soft-delete, and tenant scope are applied as JS `.filter`s — mirroring the
+     * hardened read surface. Any other param renders as a single expression.
+     * Returns `entry: null` when the value cannot be resolved (caller omits it).
+     */
+    const buildParam = (p, scope, label) => {
+        const e = p.expression;
+        if (e.kind === 'aggregate' && e.op === 'count') {
+            const childEntity = ir.entities.find(en => en.name === e.entity);
+            if (!childEntity) {
+                diagnostics.push({ severity: 'error', code: 'CONVEX_AGGREGATE_UNKNOWN_ENTITY', message: `${label} param '${p.name}' counts unknown entity '${e.entity}'; omitted.` });
+                return { preLines: [], entry: null };
+            }
+            const childTable = resolveConvexTableName(e.entity, options);
+            const rf = resolveReadFilter(ir, childEntity, options);
+            const refFields = collectReferenceFields(childEntity, ir, options);
+            const isIndexedField = (field) => {
+                const prop = childEntity.properties.find(pp => pp.name === field);
+                return !!prop && (prop.modifiers.includes('indexed') || refFields.has(field));
+            };
+            const renderVal = (val) => {
+                const r = renderExpression(val, scope);
+                if (r.unresolved.length) {
+                    diagnostics.push({ severity: 'warning', code: 'CONVEX_UNRESOLVED_AGGREGATE_PREDICATE', message: `${label} param '${p.name}' count predicate value unresolved (${r.unresolved.join('; ')}).` });
+                }
+                return r;
+            };
+            const indexedPred = e.predicates.find(pr => isIndexedField(pr.field));
+            const remaining = indexedPred ? e.predicates.filter(pr => pr !== indexedPred) : e.predicates;
+            const rowsVar = `__count${countCounter}_rows`;
+            const countVar = `__count${countCounter}`;
+            countCounter++;
+            const preLines = [];
+            let queryHead;
+            if (indexedPred) {
+                const v = renderVal(indexedPred.value);
+                queryHead = `ctx.db.query("${childTable}").withIndex("by_${indexedPred.field}", (q) => q.eq("${indexedPred.field}", ${v.code}))`;
+            }
+            else {
+                queryHead = `ctx.db.query("${childTable}")`;
+                diagnostics.push({ severity: 'info', code: 'CONVEX_AGGREGATE_UNINDEXED', message: `${label} param '${p.name}' counts '${e.entity}' with no indexed/foreign-key predicate; rendered a table scan (mark an equality field indexed for speed).` });
+            }
+            preLines.push(`    const ${rowsVar} = await ${queryHead}.collect();`);
+            const filters = [];
+            for (const pr of remaining) {
+                const v = renderVal(pr.value);
+                filters.push(`(d as any).${pr.field} === ${v.code}`);
+            }
+            if (rf.hasSoftDelete)
+                filters.push(`(d as any).${rf.deletedProp} == null`);
+            if (rf.hasTenant && rf.tenantProp) {
+                if (!tenantEmitted) {
+                    preLines.push(`    const __tenant = (ctx as any).auth?.${rf.tenantProp} ?? null;`);
+                    tenantEmitted = true;
+                }
+                filters.push(`(d as any).${rf.tenantProp} === __tenant`);
+            }
+            const chain = filters.length ? filters.map(f => `.filter((d) => ${f})`).join('') : '';
+            preLines.push(`    const ${countVar} = ${rowsVar}${chain}.length;`);
+            return { preLines, entry: `${p.name}: ${countVar}` };
+        }
+        const { code, unresolved } = renderExpression(e, scope);
+        if (unresolved.length) {
+            diagnostics.push({ severity: 'warning', code: 'CONVEX_UNRESOLVED_REACTION_PARAM', message: `${label} param '${p.name}' unresolved (${unresolved.join('; ')}); omitted.` });
+            return { preLines: [], entry: null };
+        }
+        return { preLines: [], entry: `${p.name}: ${code}` };
+    };
+    matched.forEach((reaction, idx) => {
+        const targetTable = resolveConvexTableName(reaction.targetEntity, options);
+        const targetEntity = ir.entities.find(e => e.name === reaction.targetEntity);
+        const label = `reaction ${reaction.event}→${reaction.targetEntity}.${reaction.targetCommand}`;
+        // Fan-out reaction: dispatch the command on every target row where
+        // row.<matchField> == matchSource. matchSource + params resolve against the
+        // event payload (self === payload, matching the reference runtime). Each
+        // match runs the GENERATED target mutation via ctx.runMutation, so the
+        // target command's own governance/actions run — exactly what hand-written
+        // after-emit middleware does. Prefer the schema index (FK/indexed fields
+        // carry by_<field>); fall back to a table-scan filter otherwise.
+        if (reaction.fanOut) {
+            const fanScope = { selfVar: 'payload', globals: ['user', 'context', 'args'] };
+            const src = renderExpression(reaction.fanOut.matchSource, fanScope);
+            if (src.unresolved.length) {
+                diagnostics.push({ severity: 'warning', code: 'CONVEX_UNRESOLVED_REACTION_FANOUT', message: `fan-out ${label} match source unresolved (${src.unresolved.join('; ')}); skipped.` });
+                return;
+            }
+            const fanParams = [];
+            const fanPreLines = [];
+            for (const p of reaction.params ?? []) {
+                const r = buildParam(p, fanScope, label);
+                fanPreLines.push(...r.preLines);
+                if (r.entry)
+                    fanParams.push(r.entry);
+            }
+            const field = reaction.fanOut.matchField;
+            const isFk = !!targetEntity && collectReferenceFields(targetEntity, ir, options).has(field);
+            const targetProp = targetEntity?.properties.find(p => p.name === field);
+            const indexed = !!targetProp && (targetProp.modifiers.includes('indexed') || isFk);
+            if (!indexed) {
+                diagnostics.push({ severity: 'info', code: 'CONVEX_FANOUT_UNINDEXED', message: `fan-out ${label} matches on non-indexed '${field}'; rendered an unindexed filter (mark '${reaction.targetEntity}.${field}' indexed for speed).` });
+            }
+            const queryExpr = indexed
+                ? `ctx.db.query("${targetTable}").withIndex("by_${field}", (q) => q.eq("${field}", ${src.code}))`
+                : `ctx.db.query("${targetTable}").filter((q) => q.eq(q.field("${field}"), ${src.code}))`;
+            const rowsVar = `fanRows${idx}`;
+            for (const pl of fanPreLines)
+                lines.push(pl);
+            lines.push(`    const ${rowsVar} = await ${queryExpr}.collect();`);
+            lines.push(`    for (const __row of ${rowsVar}) {`);
+            lines.push(`      await ctx.runMutation(api.mutations.${reaction.targetEntity}_${reaction.targetCommand}, { docId: (__row as any)._id${fanParams.length ? ', ' + fanParams.join(', ') : ''} } as any);`);
+            lines.push(`    }`);
+            return;
+        }
+        const scope = { selfVar: 'doc', globals: ['payload', 'user', 'context', 'args'] };
+        const paramEntries = [];
+        const paramPreLines = [];
+        const paramNamesSeen = new Set();
+        for (const p of reaction.params ?? []) {
+            const r = buildParam(p, scope, label);
+            paramPreLines.push(...r.preLines);
+            if (r.entry) {
+                paramEntries.push(r.entry);
+                paramNamesSeen.add(p.name);
+            }
+        }
+        // Tenant propagation: a reaction fires within the source entity's tenant, so
+        // when it creates a tenant-scoped target, thread the source tenantId
+        // (available as payload.<tenantProp>) unless an explicit param already set it.
+        const targetIsTenantScoped = !!tenantProp && !!targetEntity?.properties.some(p => p.name === tenantProp);
+        if (reaction.targetCommand === 'create' && targetIsTenantScoped && !paramNamesSeen.has(tenantProp)) {
+            paramEntries.unshift(`${tenantProp}: payload.${tenantProp}`);
+        }
+        for (const pl of paramPreLines)
+            lines.push(pl);
+        if (reaction.targetCommand === 'create') {
+            lines.push(`    await ctx.db.insert("${targetTable}", { ${paramEntries.join(', ')} } as any);`);
+        }
+        else {
+            const resolve = renderExpression(reaction.resolve, { selfVar: 'doc', globals: ['payload', 'user', 'context', 'args'] });
+            const varName = `reactionTarget${idx}`;
+            if (reaction.resolve?.kind === 'literal' && reaction.resolve.value.kind === 'null') {
+                lines.push(`    // reaction ${reaction.event} → ${reaction.targetEntity}.${reaction.targetCommand} (resolve: null — no target id)`);
+            }
+            else if (resolve.unresolved.length) {
+                diagnostics.push({ severity: 'warning', code: 'CONVEX_UNRESOLVED_REACTION_TARGET', message: `${label} target unresolved; skipped.` });
+            }
+            else {
+                lines.push(`    const ${varName} = ${resolve.code};`);
+                lines.push(`    if (${varName}) await ctx.db.patch(${varName} as any, { ${paramEntries.join(', ')} } as any);`);
+            }
+        }
+    });
+    return { lines, diagnostics };
+}
+/**
+ * Render the G7 `emit Event { field: expr }` payload fields declared for ONE
+ * event, evaluated against the post-action instance scope (selfVar = the
+ * affected instance). Mirrors runtime-engine.ts G7 (eventPayload construction
+ * at emit time): declared fields are populated from `self.*` so the emitted
+ * event row — and the reactions/readers that consume it — see real values
+ * instead of `undefined`. Without this, a reaction on a MUTATE command reading
+ * an entity-owned field (e.g. `payload.invoiceId`) is a silent no-op, which is
+ * the gap capsule-pro papers over with hand-written after-emit middleware.
+ *
+ * Non-governance expressions: unresolved fields are omitted with a warning
+ * diagnostic (never a denying throw — that is reserved for guards/policies).
+ */
+function renderEmitPayloadFields(cmd, eventName, scope) {
+    const spec = cmd.emitPayloads?.find(ep => ep.eventName === eventName);
+    if (!spec)
+        return { fields: [], diagnostics: [] };
+    const fields = [];
+    const diagnostics = [];
+    for (const f of spec.fields) {
+        const { code, unresolved } = renderExpression(f.expression, scope);
+        if (unresolved.length) {
+            diagnostics.push({
+                severity: 'warning',
+                code: 'CONVEX_UNRESOLVED_EMIT_PAYLOAD',
+                message: `emit payload field '${cmd.entity}.${eventName}.${f.name}' unresolved (${unresolved.join('; ')}); omitted.`,
+            });
+            continue;
+        }
+        fields.push({ name: f.name, code });
+    }
+    return { fields, diagnostics };
+}
+/**
+ * Union of G7 payload fields across ALL of a command's emits (deduped by field
+ * name), for the shared reaction-payload binding. Per-event rows carry their
+ * own precise fields (see {@link renderEvents}); the shared reaction payload is
+ * a benign superset — a reaction only reads the fields it references, so extra
+ * sibling-event fields are harmless. Correct for the common single-event case.
+ */
+function unionEmitPayloadFields(cmd, scope) {
+    const seen = new Set();
+    const fields = [];
+    const diagnostics = [];
+    for (const ev of cmd.emits ?? []) {
+        const r = renderEmitPayloadFields(cmd, ev, scope);
+        diagnostics.push(...r.diagnostics);
+        for (const f of r.fields) {
+            if (seen.has(f.name))
+                continue;
+            seen.add(f.name);
+            fields.push(f);
+        }
+    }
+    return { fields, diagnostics };
+}
+function payloadObjectLiteral(fields) {
+    return fields.length ? `{ ${fields.map(f => `${f.name}: ${f.code}`).join(', ')} }` : '{}';
+}
+/** Render the event-row inserts for a command's emits, populating G7 payload fields. */
+function renderEvents(eventsTable, cmd, idVar, scope) {
+    const lines = [];
+    const diagnostics = [];
+    for (const ev of cmd.emits ?? []) {
+        const { fields, diagnostics: d } = renderEmitPayloadFields(cmd, ev, scope);
+        diagnostics.push(...d);
+        lines.push(`    await ctx.db.insert("${eventsTable}", { type: ${JSON.stringify(ev)}, entity: ${JSON.stringify(cmd.entity)}, entityId: ${idVar}, payload: ${payloadObjectLiteral(fields)}, createdAt: Date.now() });`);
+    }
+    return { lines, diagnostics };
+}
+/**
+ * Auth/context/payload bindings a handler needs, derived by scanning the body
+ * for the identifiers it actually references (avoids both undefined-name and
+ * unused-var errors). `payloadValue` is the expression `payload` binds to.
+ */
+function authBindings(bodyText) {
+    const lines = [];
+    const refs = (token) => new RegExp(`\\b${token}\\b`).test(bodyText);
+    if (refs('userRole'))
+        lines.push(`    const userRole = (ctx as any).auth?.role ?? "anonymous";`);
+    if (refs('user'))
+        lines.push(`    const user = (ctx as any).auth ?? {};`);
+    if (refs('context'))
+        lines.push(`    const context = (ctx as any);`);
+    return lines;
+}
+function generateMutation(ir, options, cmd) {
+    if (!cmd.entity)
+        return null;
+    const entity = ir.entities.find(e => e.name === cmd.entity);
+    if (!entity || !isPersistentEntity(entity, ir))
+        return null;
+    const diagnostics = [];
+    const table = resolveConvexTableName(entity.name, options);
+    const name = `${entity.name}_${cmd.name}`;
+    const fkTargets = collectFkTargets(entity, ir, options);
+    const isCreate = cmd.name === 'create';
+    const paramNames = (cmd.parameters ?? []).map(p => p.name);
+    if (isCreate) {
+        // Unified create model. Every stored field must be reachable so the insert
+        // satisfies the schema: it is either (a) set by a `mutate` action, (b) filled
+        // from its default, or (c) exposed as a mutation argument the caller provides.
+        // Command parameters that feed actions (and are not themselves fields) are
+        // also exposed as args. All expressions resolve against `args`.
+        const params = cmd.parameters ?? [];
+        const scope = { selfVar: 'args' };
+        const argLines = [];
+        const argNames = new Set();
+        const docLines = [];
+        // Fields set by mutate actions (mapped from params); not exposed as args.
+        const mutates = (cmd.actions ?? []).filter(a => a.kind === 'mutate' && a.target);
+        const targetSet = new Set(mutates.map(a => a.target));
+        // Entity properties → args (unless action-set) + doc lines (with defaults).
+        for (const p of entity.properties) {
+            if (p.name === 'id' || targetSet.has(p.name))
+                continue;
+            const { validator, diagnostics: vd } = buildValidator(entity, p, ir, options, fkTargets.get(p.name));
+            diagnostics.push(...vd);
+            if (!validator)
+                continue;
+            // Required AND no default → required arg; otherwise optional (caller may
+            // omit; default fills in).
+            const required = p.modifiers.includes('required') && !p.defaultValue;
+            if (!argNames.has(p.name)) {
+                argLines.push(`    ${p.name}: ${required ? validator : `v.optional(${validator})`}`);
+                argNames.add(p.name);
+            }
+            docLines.push(`      ${p.name}: args.${p.name}${p.defaultValue ? ` ?? ${defaultToTs(p.defaultValue, validator)}` : ''}`);
+        }
+        // Command params that are not entity fields (they feed actions) → args.
+        for (const p of params) {
+            if (argNames.has(p.name))
+                continue;
+            const validator = paramValidator(p.type);
+            argLines.push(`    ${p.name}: ${p.required ? validator : `v.optional(${validator})`}`);
+            argNames.add(p.name);
+        }
+        // mutate actions → doc fields (param → field mapping).
+        for (const a of mutates) {
+            const { code, unresolved } = renderActionValue(entity, a.target, a.expression, scope);
+            if (unresolved.length) {
+                diagnostics.push({ severity: 'warning', code: 'CONVEX_UNRESOLVED_ACTION', entity: entity.name, message: `create action '${a.target}' unresolved (${unresolved.join('; ')}); omitted.` });
+                continue;
+            }
+            docLines.push(`      ${a.target}: ${code}`);
+        }
+        const checks = renderChecks(entity.name, commandChecks(ir, cmd, options.policyMode), scope);
+        diagnostics.push(...checks.diagnostics);
+        // G7 `emit Event { field: expr }`: populate each event-row payload (and the
+        // shared reaction payload below) with declared fields evaluated against the
+        // post-action instance. `doc` is the created instance, so `self.X` → doc.X.
+        const g7Scope = { selfVar: 'doc' };
+        const g7 = unionEmitPayloadFields(cmd, g7Scope);
+        diagnostics.push(...g7.diagnostics);
+        const events = renderEvents(resolveEventsTableName(ir, options), cmd, '_id', g7Scope);
+        diagnostics.push(...events.diagnostics);
+        const reactions = renderReactions(ir, options, cmd.emits ?? []);
+        diagnostics.push(...reactions.diagnostics);
+        const tail = [...events.lines, ...reactions.lines].join('\n');
+        // Reaction expressions resolve `payload` against the reference-runtime
+        // contract (runtime-engine.ts): the emitted event payload is `{ ...input,
+        // result }` and reactions additionally see `_subject` (the canonical
+        // entity/command/id metadata). `result` is the affected entity, with its
+        // app-level `id` aliased to the Convex `_id` (convexId mode stores no `id`
+        // scalar). Without these keys, IR expressions like `payload.result.id` /
+        // `payload._subject.id` read through `undefined` and crash at runtime.
+        const g7Entries = g7.fields.map(f => `${f.name}: ${f.code}`).join(', ');
+        const subjectLiteral = `_subject: { entity: ${JSON.stringify(entity.name)}, command: ${JSON.stringify(cmd.name)}, id: _id }`;
+        const payloadBinding = /\bpayload\b/.test(tail)
+            ? `    const payload: Record<string, any> = { _id, id: _id, ...doc, result: { _id, id: _id, ...doc }${g7Entries ? `, ${g7Entries}` : ''}, ${subjectLiteral} };\n`
+            : '';
+        const bodyText = [...checks.lines, tail].join('\n');
+        const body = `export const ${name} = mutation({\n` +
+            `  args: {\n${argLines.join(',\n')}\n  },\n` +
+            `  handler: async (ctx, args: any) => {\n` +
+            (authBindings(bodyText).join('\n') ? authBindings(bodyText).join('\n') + '\n' : '') +
+            `    const doc: Record<string, any> = {\n${docLines.join(',\n')}\n    };\n` +
+            (checks.lines.length ? checks.lines.join('\n') + '\n' : '') +
+            `    const _id = await ctx.db.insert("${table}", doc as any);\n` +
+            payloadBinding +
+            (tail ? tail + '\n' : '') +
+            `    return { _id, ...doc };\n` +
+            `  },\n});`;
+        return { code: body, diagnostics };
+    }
+    // Non-create mutation
+    const argLines = [`    docId: v.id("${table}")`];
+    for (const p of cmd.parameters ?? []) {
+        argLines.push(`    ${p.name}: ${p.required ? paramValidator(p.type) : `v.optional(${paramValidator(p.type)})`}`);
+    }
+    // Non-create: command params are destructured locals; self.x → doc.x.
+    const checks = renderChecks(entity.name, commandChecks(ir, cmd, options.policyMode), { selfVar: 'doc', locals: paramNames });
+    diagnostics.push(...checks.diagnostics);
+    const updateLines = [];
+    for (const a of cmd.actions ?? []) {
+        if (a.kind !== 'mutate' || !a.target)
+            continue;
+        const { code, unresolved } = renderActionValue(entity, a.target, a.expression, { selfVar: 'doc', locals: paramNames });
+        if (unresolved.length) {
+            diagnostics.push({ severity: 'warning', code: 'CONVEX_UNRESOLVED_ACTION', entity: entity.name, message: `action mutate '${a.target}' unresolved (${unresolved.join('; ')}); omitted.` });
+            continue;
+        }
+        updateLines.push(`      ${a.target}: ${code}`);
+    }
+    // G7 `emit Event { field: expr }`: declared payload fields are evaluated
+    // against the POST-action instance (fetched doc + applied updates). Introduce
+    // `__after` ONLY when the command actually declares emit fields, so commands
+    // without G7 emit byte-identical output to before (no unused-var, no churn).
+    const hasG7 = !!(cmd.emitPayloads && cmd.emitPayloads.length > 0);
+    const g7Scope = { selfVar: hasG7 ? '__after' : 'doc', locals: paramNames };
+    const g7 = unionEmitPayloadFields(cmd, g7Scope);
+    diagnostics.push(...g7.diagnostics);
+    const useAfter = hasG7 && g7.fields.length > 0;
+    const afterLine = useAfter ? `    const __after: Record<string, any> = { ...doc, ...updates };\n` : '';
+    const events = renderEvents(resolveEventsTableName(ir, options), cmd, 'docId', g7Scope);
+    diagnostics.push(...events.diagnostics);
+    const reactions = renderReactions(ir, options, cmd.emits ?? []);
+    diagnostics.push(...reactions.diagnostics);
+    const tail = [...events.lines, ...reactions.lines].join('\n');
+    // Same reference-runtime payload contract as the create branch: `result` is
+    // the affected entity (post-patch) with `id` aliased to the Convex `_id`, and
+    // `_subject` carries the canonical entity/command/id metadata reactions read.
+    const g7Entries = g7.fields.map(f => `${f.name}: ${f.code}`).join(', ');
+    const subjectLiteral = `_subject: { entity: ${JSON.stringify(entity.name)}, command: ${JSON.stringify(cmd.name)}, id: docId }`;
+    const payloadBinding = /\bpayload\b/.test(tail)
+        ? (useAfter
+            ? `    const payload: Record<string, any> = { id: docId, ...__after, result: { id: docId, ...__after }${g7Entries ? `, ${g7Entries}` : ''}, ${subjectLiteral} };\n`
+            : `    const payload: Record<string, any> = { id: docId, ...doc, ...updates, result: { id: docId, ...doc, ...updates }, ${subjectLiteral} };\n`)
+        : '';
+    const argDestructure = paramNames.length ? `, ${paramNames.join(', ')}` : '';
+    const bodyText = [...checks.lines, ...updateLines, tail].join('\n');
+    const body = `export const ${name} = mutation({\n` +
+        `  args: {\n${argLines.join(',\n')}\n  },\n` +
+        `  handler: async (ctx, { docId${argDestructure} }) => {\n` +
+        (authBindings(bodyText).join('\n') ? authBindings(bodyText).join('\n') + '\n' : '') +
+        `    const doc = await ctx.db.get(docId) as Record<string, any> | null;\n` +
+        `    if (!doc) throw new Error(${JSON.stringify(`${entity.name} not found`)});\n` +
+        (checks.lines.length ? checks.lines.join('\n') + '\n' : '') +
+        `    const updates = {\n${updateLines.join(',\n')}${updateLines.length ? '\n' : ''}    };\n` +
+        `    await ctx.db.patch(docId, updates as any);\n` +
+        afterLine +
+        payloadBinding +
+        (tail ? tail + '\n' : '') +
+        `    return { ...doc, ...updates };\n` +
+        `  },\n});`;
+    return { code: body, diagnostics };
+}
+export function generateMutations(ir, rawOptions) {
+    const options = normalizeOptions(rawOptions);
+    const diagnostics = [];
+    const blocks = [];
+    for (const cmd of ir.commands) {
+        const m = generateMutation(ir, options, cmd);
+        if (!m)
+            continue;
+        blocks.push(m.code);
+        diagnostics.push(...m.diagnostics);
+    }
+    // Emit helpers only when the generated mutations actually reference them
+    // (a policyMode:'skip' build may use neither), so there is no dead code.
+    const body = blocks.join('\n\n');
+    const helpers = [];
+    if (/\bcheckRole\(/.test(body)) {
+        helpers.push(`// Role hierarchy from IR (effective permissions after inheritance).\n` +
+            `const ROLE_PERMISSIONS: Record<string, string[]> = ${roleMapLiteral(ir)};\n\n` +
+            `function checkRole(userRole: string, action: string): boolean {\n` +
+            `  const perms = ROLE_PERMISSIONS[userRole];\n` +
+            `  return perms ? (perms.includes(action) || perms.includes("all")) : false;\n` +
+            `}`);
+    }
+    if (/\bflag\(/.test(body)) {
+        helpers.push(`// Feature toggle (configurable). Not an authorization gate.\nfunction flag(_name?: string): boolean { return true; }`);
+    }
+    const policyNote = options.policyMode === 'skip' ? ' (policyMode: skip — authorization policies omitted)' : '';
+    // Fan-out reactions dispatch sibling mutations via ctx.runMutation, which
+    // needs the generated `api`. Only import it when actually used (no dead import).
+    const needsApi = /\bctx\.runMutation\b/.test(body);
+    const code = `${GENERATED_HEADER}\n// ${blocks.length} mutation(s); roles: ${(ir.roles ?? []).length}; policies: ${ir.policies.length}.${policyNote}\n\n` +
+        `import { mutation } from "./_generated/server";\n` +
+        `import { v } from "convex/values";\n` +
+        (needsApi ? `import { api } from "./_generated/api";\n` : '') +
+        `\n` +
+        (helpers.length ? helpers.join('\n\n') + '\n\n' : '') +
+        `${body}\n`;
+    return { code, diagnostics };
+}
+//# sourceMappingURL=functions.js.map