@cosmicdrift/kumiko-framework 0.388.0 → 0.390.0

package/dist/engine/feature-ast/pattern-change-schema.js

@@ -1,1226 +0,0 @@
-// Runtime validator for the `unknown → PatternChange[]` boundary. An AI
-// tool (or any external caller) hands us JSON; before it ever reaches
-// `applyChanges` it must pass through here. Every rejection carries an
-// exact dotted/bracketed path so the caller (frequently an LLM) can
-// self-correct without a human in the loop.
-//
-// **Zod v4 constraint driving this file's shape:** every discriminated-
-// union member below stays a plain `z.object(...)` (or `.superRefine`
-// wrapper around one) — never `.transform()` at the object level. A
-// whole-object transform would erase the "which member matched" signal
-// `discriminatedUnion` needs to attribute a nested field error to the
-// right member, and it would blur per-member `.strict()` unrecognized-key
-// detection. Transforms only ever touch a single field (`sourceBody`,
-// below) — never the object they live on.
-//
-// **Deep definitions stay opaque.** EntityDefinition, ScreenDefinition,
-// NavDefinition, WorkspaceDefinition, JobDefinition-options, MetricOptions,
-// etc. are NOT hand-modeled here — that would fork a second, driftable
-// catalogue of their shape. They're accepted via `z.custom` (plain object,
-// or a RawRefSentinel/AiStepOpaqueArgs — the extractor's own "couldn't
-// resolve this statically" markers) and, for EntityDefinition only,
-// additionally checked for field-type membership via the shared
-// `findUnknownEntityFieldTypes` helper (kept in sync with `extractEntity`).
-import { ESCAPE_HATCH_GRANTS } from "@cosmicdrift/kumiko-types/handlers";
-import * as z from "zod";
-import { LifecycleHookTypes } from "../constants.js";
-import { describeUnknownFieldType, findUnknownEntityFieldTypes } from "./entity-field-types.js";
-import { AGENT_RISK_VALUES } from "./extractors/handlers.js";
-import { isPlainObject, isRawRefSentinel } from "./extractors/shared.js";
-import { SYNTHETIC_LOC } from "./patcher.js";
-// Derives an exhaustive literal-value array from a `Record<T, true>` flag
-// map: an added/removed union member fails to compile here instead of
-// silently producing a schema narrower than the runtime type — same
-// rationale as kumiko-types's `NO_WIDGET_FIELD_TYPES`/`FIELD_TYPE_NAMES`.
-function keysOf(flags) {
-    return Object.keys(flags);
-}
-// =============================================================================
-// Shared primitives
-// =============================================================================
-function isPlainObjectOrSentinel(value) {
-    return isRawRefSentinel(value) || isPlainObject(value);
-}
-const sourcePositionSchema = z
-    .object({ line: z.number(), column: z.number() })
-    .strict();
-const fullSourceLocationSchema = z
-    .object({
-    file: z.string(),
-    start: sourcePositionSchema,
-    end: sourcePositionSchema,
-    raw: z.string(),
-})
-    .strict();
-// Partial object form — only `raw` is meaningful, `file`/`start`/`end` (if
-// present) are accepted but discarded: a wire producer sending a
-// half-populated location is telling us "this came from generated code, not
-// a real file span" and `rawLoc` is exactly that contract.
-const partialSourceLocationSchema = z
-    .object({
-    raw: z.string(),
-    file: z.string().optional(),
-    start: sourcePositionSchema.optional(),
-    end: sourcePositionSchema.optional(),
-})
-    .strict()
-    .transform((value) => ({ ...SYNTHETIC_LOC, raw: value.raw }));
-const stringSourceLocationSchema = z
-    .string()
-    .transform((raw) => ({ ...SYNTHETIC_LOC, raw }));
-// `sourceBody`: string | {raw, file?, start?, end?} | full SourceLocation.
-// Order matters — a fully-populated object must match `fullSourceLocationSchema`
-// first so it round-trips unchanged; only a partial object falls through to
-// the raw-collapsing variant.
-const sourceBodySchema = z.union([
-    fullSourceLocationSchema,
-    partialSourceLocationSchema,
-    stringSourceLocationSchema,
-]);
-const nonEmptySourceBodySchema = sourceBodySchema.refine((loc) => loc.raw.trim().length > 0, {
-    message: "source.raw must be non-empty",
-});
-// The pattern-level `source` field: optional on the wire, defaults to the
-// patcher's own synthetic placeholder (mirrors createFeaturePatcher's
-// add{Kind} methods, which never have a real file span either).
-const sourceFieldSchema = sourceBodySchema
-    .optional()
-    .default(SYNTHETIC_LOC);
-// `readVarargsOrArrayProp` (extractors/shared.ts) already types a mixed
-// string/sentinel array as `readonly string[]` at its own extraction
-// boundary (requires.featureNames, readsConfig.qualifiedKeys); mirror that
-// same typed lie here instead of re-deriving a wider array type only to
-// cast it back down.
-const stringOrRawRefListSchema = z.custom((value) => Array.isArray(value) && value.every((el) => typeof el === "string" || isRawRefSentinel(el)), { message: "must be an array of strings or unresolved references" });
-// Runtime source of truth for the lifecycle-hook-type literals: the
-// engine's own `LifecycleHookTypes` const object (engine/constants.ts) —
-// `hook`'s `hookType` is that union plus the AST-only "validation" pseudo-
-// type (r.hook(type: "validation", ...) has no runtime LifecycleHookType
-// counterpart, it maps to a different registrar call).
-const LIFECYCLE_HOOK_TYPE_VALUES = Object.values(LifecycleHookTypes);
-const hookTypeSchema = z.enum([...LIFECYCLE_HOOK_TYPE_VALUES, "validation"]);
-const hookPhaseSchema = z.enum(keysOf({ inTransaction: true, afterCommit: true }));
-const httpRouteMethodSchema = z.enum(keysOf({
-    GET: true,
-    POST: true,
-    PUT: true,
-    PATCH: true,
-    DELETE: true,
-    HEAD: true,
-    OPTIONS: true,
-}));
-const runInSchema = z.enum(keysOf({ api: true, worker: true, both: true }));
-const claimKeyTypeSchema = z.enum(keysOf({
-    string: true,
-    number: true,
-    boolean: true,
-    "string[]": true,
-    object: true,
-}));
-const agentRiskSchema = z.enum(AGENT_RISK_VALUES);
-const rateLimitPerSchema = z.enum(keysOf({
-    user: true,
-    tenant: true,
-    ip: true,
-    "user+handler": true,
-    "tenant+handler": true,
-    "ip+handler": true,
-}));
-const mspDeliverySchema = z.enum(keysOf({ shared: true, "per-instance": true }));
-const escapeHatchSchema = z
-    .object({
-    reason: z.string().refine((s) => s.trim().length > 0, {
-        message: "reason must be non-empty",
-    }),
-    grants: z.array(z.enum(ESCAPE_HATCH_GRANTS)).min(1).optional(),
-})
-    .strict();
-const rawRefSentinelSchema = z.object({ __raw: z.string() }).strict();
-// Adds the raw-ref-sentinel branch a handler header field accepts when the
-// extractor couldn't resolve it to a literal (see extractors/hooks.ts).
-function orRawRef(schema) {
-    return z.union([schema, rawRefSentinelSchema]);
-}
-const rateLimitDisabledSchema = z
-    .object({
-    disabled: z.literal(true),
-    reason: z.string().refine((s) => s.trim().length > 0, {
-        message: "reason must be non-empty",
-    }),
-})
-    .strict();
-const rateLimitOptionSchema = z
-    .object({
-    per: rateLimitPerSchema,
-    limit: z.number(),
-    windowSeconds: z.number(),
-    cost: z.number().optional(),
-})
-    .strict();
-const rateLimitOptionListSchema = z.tuple([rateLimitOptionSchema], rateLimitOptionSchema);
-const additionalRateLimitsSchema = z.array(z
-    .object({
-    per: z.object({ payloadField: z.string() }).strict(),
-    limit: z.number(),
-    windowSeconds: z.number(),
-    cost: z.number().optional(),
-    normalize: z.literal("email").optional(),
-})
-    .strict());
-const agentHandlerHintsSchema = z
-    .object({
-    expose: z.boolean().optional(),
-    risk: agentRiskSchema.optional(),
-})
-    .strict();
-// AccessRule — DEFAULT-DENY per its doc in types/handlers.ts; a malformed
-// shape must be rejected, not silently narrowed to "no access" (that would
-// hide the author's mistake instead of reporting it at the boundary).
-const roleAccessRuleSchema = z
-    .object({
-    roles: z.array(z.string()),
-    personalData: z.literal("public-intake").optional(),
-})
-    .strict();
-const openToAllAccessRuleSchema = z
-    .object({
-    openToAll: z
-        .object({
-        reason: z.string().refine((s) => s.trim().length > 0, {
-            message: "openToAll.reason must be non-empty",
-        }),
-        personalData: z.literal("tenant-members").optional(),
-    })
-        .strict(),
-})
-    .strict();
-const accessRuleSchema = z.union([roleAccessRuleSchema, openToAllAccessRuleSchema]);
-// Header keys per handler kind — drift pin against patch.ts's *HeaderKey
-// types (via `satisfies`), and the source the schemas below derive from.
-const WRITE_HANDLER_HEADER_SHAPE = {
-    access: accessRuleSchema,
-    description: z.string(),
-    agent: agentHandlerHintsSchema,
-    rateLimit: rateLimitOptionSchema,
-    additionalRateLimits: additionalRateLimitsSchema,
-    unsafeSkipTransitionGuard: z.boolean(),
-    escapeHatch: escapeHatchSchema,
-};
-const QUERY_HANDLER_HEADER_SHAPE = {
-    access: accessRuleSchema,
-    description: z.string(),
-    agent: agentHandlerHintsSchema,
-    rateLimit: rateLimitOptionSchema,
-    escapeHatch: escapeHatchSchema,
-};
-const STREAM_HANDLER_HEADER_SHAPE = {
-    access: accessRuleSchema,
-    rateLimit: rateLimitOptionSchema,
-    escapeHatch: escapeHatchSchema,
-};
-const WRITE_HANDLER_HEADER_KEYS = z.object(WRITE_HANDLER_HEADER_SHAPE).keyof().options;
-const QUERY_HANDLER_HEADER_KEYS = z.object(QUERY_HANDLER_HEADER_SHAPE).keyof().options;
-const STREAM_HANDLER_HEADER_KEYS = z.object(STREAM_HANDLER_HEADER_SHAPE).keyof().options;
-// `update`'s set-schema stays exactly as strict as the extractor's own
-// output: Designer/AI-authored values must be structured, never a raw
-// reference or a partially-literal shape — those only ever come from
-// statically parsed source, not from a `set` payload.
-const WRITE_HANDLER_UPDATE_SET_SCHEMA = z.object(WRITE_HANDLER_HEADER_SHAPE).partial().strict();
-const QUERY_HANDLER_UPDATE_SET_SCHEMA = z.object(QUERY_HANDLER_HEADER_SHAPE).partial().strict();
-const STREAM_HANDLER_UPDATE_SET_SCHEMA = z.object(STREAM_HANDLER_HEADER_SHAPE).partial().strict();
-// `unset` may name any header field except `access` (always required).
-const WRITE_HANDLER_UPDATE_UNSET_ENUM = z
-    .object(WRITE_HANDLER_HEADER_SHAPE)
-    .omit({ access: true })
-    .keyof();
-const QUERY_HANDLER_UPDATE_UNSET_ENUM = z
-    .object(QUERY_HANDLER_HEADER_SHAPE)
-    .omit({ access: true })
-    .keyof();
-const STREAM_HANDLER_UPDATE_UNSET_ENUM = z
-    .object(STREAM_HANDLER_HEADER_SHAPE)
-    .omit({ access: true })
-    .keyof();
-// Full patterns (add/replace) carry whatever the extractor parsed, which
-// may be a RawRefSentinel or a disabled-rate-limit shape it can't resolve
-// to a literal; widen only here, not on UPDATE_SET_SCHEMA above.
-const WRITE_HANDLER_PATTERN_HEADER_SHAPE = {
-    ...WRITE_HANDLER_HEADER_SHAPE,
-    access: orRawRef(accessRuleSchema),
-    agent: orRawRef(agentHandlerHintsSchema),
-    rateLimit: orRawRef(z.union([rateLimitOptionSchema, rateLimitOptionListSchema, rateLimitDisabledSchema])),
-    additionalRateLimits: orRawRef(additionalRateLimitsSchema),
-    escapeHatch: orRawRef(escapeHatchSchema),
-};
-const QUERY_HANDLER_PATTERN_HEADER_SHAPE = {
-    ...QUERY_HANDLER_HEADER_SHAPE,
-    access: orRawRef(accessRuleSchema),
-    agent: orRawRef(agentHandlerHintsSchema),
-    rateLimit: orRawRef(z.union([rateLimitOptionSchema, rateLimitOptionListSchema, rateLimitDisabledSchema])),
-    escapeHatch: orRawRef(escapeHatchSchema),
-};
-const STREAM_HANDLER_PATTERN_HEADER_SHAPE = {
-    ...STREAM_HANDLER_HEADER_SHAPE,
-    access: orRawRef(accessRuleSchema),
-    rateLimit: orRawRef(z.union([rateLimitOptionSchema, rateLimitOptionListSchema, rateLimitDisabledSchema])),
-    escapeHatch: orRawRef(escapeHatchSchema),
-};
-function requireHandlerBody(val, ctx, headerKeys) {
-    const hasAny = val.handlerName !== undefined ||
-        val.schemaSource !== undefined ||
-        val.handlerBody !== undefined;
-    if (!hasAny) {
-        if (val.source.raw.trim().length === 0) {
-            ctx.addIssue({
-                code: "custom",
-                path: ["source"],
-                message: "an opaque handler reference (no handlerName/schemaSource/handlerBody) requires a non-empty source.raw",
-            });
-        }
-        for (const key of headerKeys) {
-            if (val[key] !== undefined) {
-                ctx.addIssue({
-                    code: "custom",
-                    path: [key],
-                    message: "not rendered for an opaque handler reference; provide handlerName, schemaSource and handlerBody",
-                });
-            }
-        }
-        // skip: opaque handler reference carries no name/schema/body to require
-        return;
-    }
-    if (val.handlerName === undefined || val.handlerName.trim().length === 0) {
-        ctx.addIssue({
-            code: "custom",
-            path: ["handlerName"],
-            message: "handlerName is required and must be non-empty",
-        });
-    }
-    if (val.schemaSource === undefined) {
-        ctx.addIssue({ code: "custom", path: ["schemaSource"], message: "schemaSource is required" });
-    }
-    if (val.handlerBody === undefined) {
-        ctx.addIssue({ code: "custom", path: ["handlerBody"], message: "handlerBody is required" });
-    }
-}
-// =============================================================================
-// Static patterns
-// =============================================================================
-// Deep-definition passthrough: accepts a plain object OR the extractor's
-// own "couldn't resolve this statically" sentinel (RawRefSentinel), typed
-// as `T` at the boundary — the same "typed lie" the extractors already
-// make (e.g. round2.ts's `definition as EntityDefinition`), because a
-// sentinel-bearing value is never actually shaped like `T` at runtime, but
-// round-trips through `applyChanges`/the renderer unexamined either way.
-function passthroughSchema() {
-    return z.custom(isPlainObjectOrSentinel, {
-        message: "must be a plain object or unresolved reference",
-    });
-}
-const entityDefinitionSchema = passthroughSchema().superRefine((value, ctx) => {
-    for (const entry of findUnknownEntityFieldTypes(value)) {
-        ctx.addIssue({
-            code: "custom",
-            path: ["fields", entry.fieldName, "type"],
-            message: describeUnknownFieldType(entry),
-        });
-    }
-});
-const entitySchema = z
-    .object({
-    kind: z.literal("entity"),
-    source: sourceFieldSchema,
-    entityName: z.string(),
-    definition: entityDefinitionSchema,
-    backingTable: passthroughSchema().optional(),
-})
-    .strict();
-const relationSchema = z
-    .object({
-    kind: z.literal("relation"),
-    source: sourceFieldSchema,
-    entityName: z.string(),
-    relationName: z.string(),
-    definition: passthroughSchema(),
-})
-    .strict();
-const navSchema = z
-    .object({
-    kind: z.literal("nav"),
-    source: sourceFieldSchema,
-    definition: passthroughSchema(),
-})
-    .strict();
-const workspaceSchema = z
-    .object({
-    kind: z.literal("workspace"),
-    source: sourceFieldSchema,
-    definition: passthroughSchema(),
-})
-    .strict();
-const configSchema = z
-    .object({
-    kind: z.literal("config"),
-    source: sourceFieldSchema,
-    keys: passthroughSchema(),
-})
-    .strict();
-const translationsSchema = z
-    .object({
-    kind: z.literal("translations"),
-    source: sourceFieldSchema,
-    keys: passthroughSchema(),
-})
-    .strict();
-const requiresSchema = z
-    .object({
-    kind: z.literal("requires"),
-    source: sourceFieldSchema,
-    featureNames: stringOrRawRefListSchema,
-})
-    .strict();
-const optionalRequiresSchema = z
-    .object({
-    kind: z.literal("optionalRequires"),
-    source: sourceFieldSchema,
-    featureNames: stringOrRawRefListSchema,
-})
-    .strict();
-const systemScopeSchema = z
-    .object({
-    kind: z.literal("systemScope"),
-    source: sourceFieldSchema,
-})
-    .strict();
-const toggleableSchema = z
-    .object({
-    kind: z.literal("toggleable"),
-    source: sourceFieldSchema,
-    default: z.boolean(),
-})
-    .strict();
-const describeSchema = z
-    .object({
-    kind: z.literal("describe"),
-    source: sourceFieldSchema,
-    text: z.string().refine((s) => s.trim().length > 0, { message: "text must be non-empty" }),
-})
-    .strict();
-const uiHintsSchema = z
-    .object({
-    kind: z.literal("uiHints"),
-    source: nonEmptySourceBodySchema,
-})
-    .strict();
-const metricSchema = z
-    .object({
-    kind: z.literal("metric"),
-    source: sourceFieldSchema,
-    shortName: z.string(),
-    options: passthroughSchema(),
-})
-    .strict();
-const secretSchema = z
-    .object({
-    kind: z.literal("secret"),
-    source: sourceFieldSchema,
-    shortName: z.string(),
-    options: passthroughSchema(),
-})
-    .strict();
-const secretNamespaceSchema = z
-    .object({
-    kind: z.literal("secretNamespace"),
-    source: sourceFieldSchema,
-    shortName: z.string(),
-    options: passthroughSchema(),
-})
-    .strict();
-const claimKeySchema = z
-    .object({
-    kind: z.literal("claimKey"),
-    source: sourceFieldSchema,
-    shortName: z.string(),
-    claimType: claimKeyTypeSchema,
-})
-    .strict();
-const referenceDataSchema = z
-    .object({
-    kind: z.literal("referenceData"),
-    source: sourceFieldSchema,
-    entityName: z.string(),
-    data: z.custom((value) => Array.isArray(value) || isRawRefSentinel(value), { message: "data must be an array or unresolved reference" }),
-    upsertKey: z.string().optional(),
-})
-    .strict();
-const readsConfigSchema = z
-    .object({
-    kind: z.literal("readsConfig"),
-    source: sourceFieldSchema,
-    qualifiedKeys: stringOrRawRefListSchema,
-})
-    .strict();
-const useExtensionSchema = z
-    .object({
-    kind: z.literal("useExtension"),
-    source: sourceFieldSchema,
-    extensionName: z.string(),
-    extensionNameRaw: z.string().optional(),
-    entityName: z.string(),
-    options: passthroughSchema().optional(),
-})
-    .strict();
-const usesApiSchema = z
-    .object({
-    kind: z.literal("usesApi"),
-    source: sourceFieldSchema,
-    apiName: z.string(),
-})
-    .strict();
-const exposesApiSchema = z
-    .object({
-    kind: z.literal("exposesApi"),
-    source: sourceFieldSchema,
-    apiName: z.string(),
-})
-    .strict();
-const treeActionsSchema = z
-    .object({
-    kind: z.literal("treeActions"),
-    source: sourceFieldSchema,
-    definitions: passthroughSchema(),
-})
-    .strict();
-// =============================================================================
-// Mixed patterns
-// =============================================================================
-const screenSchema = z
-    .object({
-    kind: z.literal("screen"),
-    source: sourceFieldSchema,
-    definition: passthroughSchema(),
-    opaqueProps: z.record(z.string(), sourceBodySchema).optional().default({}),
-})
-    .strict();
-const writeHandlerSchema = z
-    .object({
-    kind: z.literal("writeHandler"),
-    source: sourceFieldSchema,
-    handlerName: z.string().optional(),
-    schemaSource: sourceBodySchema.optional(),
-    handlerBody: sourceBodySchema.optional(),
-    ...z.object(WRITE_HANDLER_PATTERN_HEADER_SHAPE).partial().shape,
-})
-    .strict()
-    .superRefine((val, ctx) => requireHandlerBody(val, ctx, WRITE_HANDLER_HEADER_KEYS));
-const queryHandlerSchema = z
-    .object({
-    kind: z.literal("queryHandler"),
-    source: sourceFieldSchema,
-    handlerName: z.string().optional(),
-    schemaSource: sourceBodySchema.optional(),
-    handlerBody: sourceBodySchema.optional(),
-    ...z.object(QUERY_HANDLER_PATTERN_HEADER_SHAPE).partial().shape,
-})
-    .strict()
-    .superRefine((val, ctx) => requireHandlerBody(val, ctx, QUERY_HANDLER_HEADER_KEYS));
-const streamHandlerSchema = z
-    .object({
-    kind: z.literal("streamHandler"),
-    source: sourceFieldSchema,
-    handlerName: z.string().optional(),
-    schemaSource: sourceBodySchema.optional(),
-    handlerBody: sourceBodySchema.optional(),
-    ...z.object(STREAM_HANDLER_PATTERN_HEADER_SHAPE).partial().shape,
-})
-    .strict()
-    .superRefine((val, ctx) => requireHandlerBody(val, ctx, STREAM_HANDLER_HEADER_KEYS));
-const hookTargetSchema = z.union([
-    z.string(),
-    z.array(z.string()),
-    z.object({ allOf: z.string() }).strict(),
-]);
-const hookSchema = z
-    .object({
-    kind: z.literal("hook"),
-    source: sourceFieldSchema,
-    hookType: hookTypeSchema,
-    target: hookTargetSchema,
-    fnBody: sourceBodySchema,
-    phase: hookPhaseSchema.optional(),
-    escapeHatch: orRawRef(escapeHatchSchema).optional(),
-})
-    .strict();
-const jobSchema = z
-    .object({
-    kind: z.literal("job"),
-    source: sourceFieldSchema,
-    jobName: z.string(),
-    options: passthroughSchema(),
-    handlerBody: sourceBodySchema,
-})
-    .strict();
-const notificationSchema = z
-    .object({
-    kind: z.literal("notification"),
-    source: sourceFieldSchema,
-    notificationName: z.string(),
-    trigger: z.object({ on: z.string() }).strict().optional(),
-    recipientBody: sourceBodySchema.optional(),
-    dataBody: sourceBodySchema.optional(),
-    templates: z.record(z.string(), sourceBodySchema).optional(),
-})
-    .strict();
-const authClaimsSchema = z
-    .object({
-    kind: z.literal("authClaims"),
-    source: sourceFieldSchema,
-    fnBody: sourceBodySchema,
-})
-    .strict();
-const httpRouteSchema = z
-    .object({
-    kind: z.literal("httpRoute"),
-    source: sourceFieldSchema,
-    method: httpRouteMethodSchema,
-    path: z.string(),
-    anonymous: z.boolean(),
-    handlerBody: sourceBodySchema,
-})
-    .strict();
-const projectionSchema = z
-    .object({
-    kind: z.literal("projection"),
-    source: sourceFieldSchema,
-    name: z.string(),
-    sourceEntity: z.union([z.string(), z.array(z.string())]),
-    applyBodies: z.record(z.string(), sourceBodySchema),
-})
-    .strict();
-const mspErrorPolicySchema = z.object({ skipApplyErrors: z.boolean().optional() }).strict();
-const mspErrorModeSchema = z
-    .object({
-    continuous: mspErrorPolicySchema.optional(),
-    rebuild: mspErrorPolicySchema.optional(),
-})
-    .strict();
-const multiStreamProjectionSchema = z
-    .object({
-    kind: z.literal("multiStreamProjection"),
-    source: sourceFieldSchema,
-    name: z.string(),
-    applyBodies: z.record(z.string(), sourceBodySchema),
-    errorMode: mspErrorModeSchema.optional(),
-    runIn: runInSchema.optional(),
-    delivery: mspDeliverySchema.optional(),
-})
-    .strict();
-const defineEventSchema = z
-    .object({
-    kind: z.literal("defineEvent"),
-    source: sourceFieldSchema,
-    eventName: z.string(),
-    eventNameRaw: z.string().optional(),
-    schemaSource: sourceBodySchema,
-    version: z.number().optional(),
-    piiFields: sourceBodySchema,
-    migrations: z.record(z.string(), sourceBodySchema).optional(),
-})
-    .strict();
-const extendsRegistrarSchema = z
-    .object({
-    kind: z.literal("extendsRegistrar"),
-    source: sourceFieldSchema,
-    extensionName: z.string(),
-    extensionNameRaw: z.string().optional(),
-    defBody: sourceBodySchema,
-})
-    .strict();
-const envSchemaSchema = z
-    .object({
-    kind: z.literal("envSchema"),
-    source: sourceFieldSchema,
-    schemaBody: sourceBodySchema,
-})
-    .strict();
-const aiStepOpaqueArgsSchema = z.custom(isRawRefSentinel, {
-    message: "must be an unresolved reference ({ __raw })",
-});
-const aiStepPolicySchema = z
-    .object({
-    enabled: z.boolean(),
-    providerId: z.string().optional(),
-    model: z.string().optional(),
-    params: z.custom(isPlainObject, {
-        message: "params must be a plain object",
-    }),
-})
-    .strict();
-const stringOrAiOpaqueSchema = z.union([z.string(), aiStepOpaqueArgsSchema]);
-const aiStepPolicyOrOpaqueSchema = z.union([aiStepPolicySchema, aiStepOpaqueArgsSchema]);
-const aiGenerateSchema = z
-    .object({
-    kind: z.literal("ai.generate"),
-    source: sourceFieldSchema,
-    argsSource: aiStepOpaqueArgsSchema.optional(),
-    stepKey: stringOrAiOpaqueSchema.optional(),
-    promptKey: stringOrAiOpaqueSchema.optional(),
-    promptFallback: stringOrAiOpaqueSchema.optional(),
-    defaults: aiStepPolicyOrOpaqueSchema.optional(),
-    paramsSchemaSource: sourceBodySchema.optional(),
-    inputBody: sourceBodySchema.optional(),
-})
-    .strict();
-const aiExtractSchema = z
-    .object({
-    kind: z.literal("ai.extract"),
-    source: sourceFieldSchema,
-    argsSource: aiStepOpaqueArgsSchema.optional(),
-    stepKey: stringOrAiOpaqueSchema.optional(),
-    promptKey: stringOrAiOpaqueSchema.optional(),
-    promptFallback: stringOrAiOpaqueSchema.optional(),
-    defaults: aiStepPolicyOrOpaqueSchema.optional(),
-    paramsSchemaSource: sourceBodySchema.optional(),
-    outputSchemaSource: sourceBodySchema.optional(),
-    instructionsBody: sourceBodySchema.optional(),
-    documentBody: sourceBodySchema.optional(),
-})
-    .strict();
-const aiClassifySchema = z
-    .object({
-    kind: z.literal("ai.classify"),
-    source: sourceFieldSchema,
-    argsSource: aiStepOpaqueArgsSchema.optional(),
-    stepKey: stringOrAiOpaqueSchema.optional(),
-    promptKey: stringOrAiOpaqueSchema.optional(),
-    promptFallback: stringOrAiOpaqueSchema.optional(),
-    defaults: aiStepPolicyOrOpaqueSchema.optional(),
-    paramsSchemaSource: sourceBodySchema.optional(),
-    actions: z.array(z.object({ type: z.string(), description: z.string() }).strict()).optional(),
-    inputBody: sourceBodySchema.optional(),
-})
-    .strict();
-// =============================================================================
-// Catch-all
-// =============================================================================
-const unknownPatternSchema = z
-    .object({
-    kind: z.literal("unknown"),
-    source: nonEmptySourceBodySchema,
-    methodName: z.string(),
-})
-    .strict();
-// =============================================================================
-// Pattern union — Record keyed by kind doubles as the exhaustiveness pin
-// consumed by the compile-time typtest (a missing/renamed kind fails to
-// compile here, same contract as patterns.ts's own switch statements).
-// =============================================================================
-export const PATTERN_SCHEMAS_BY_KIND = {
-    entity: entitySchema,
-    relation: relationSchema,
-    nav: navSchema,
-    workspace: workspaceSchema,
-    config: configSchema,
-    translations: translationsSchema,
-    requires: requiresSchema,
-    optionalRequires: optionalRequiresSchema,
-    systemScope: systemScopeSchema,
-    toggleable: toggleableSchema,
-    describe: describeSchema,
-    uiHints: uiHintsSchema,
-    metric: metricSchema,
-    secret: secretSchema,
-    secretNamespace: secretNamespaceSchema,
-    claimKey: claimKeySchema,
-    referenceData: referenceDataSchema,
-    readsConfig: readsConfigSchema,
-    useExtension: useExtensionSchema,
-    usesApi: usesApiSchema,
-    exposesApi: exposesApiSchema,
-    treeActions: treeActionsSchema,
-    screen: screenSchema,
-    writeHandler: writeHandlerSchema,
-    queryHandler: queryHandlerSchema,
-    streamHandler: streamHandlerSchema,
-    hook: hookSchema,
-    job: jobSchema,
-    notification: notificationSchema,
-    authClaims: authClaimsSchema,
-    httpRoute: httpRouteSchema,
-    projection: projectionSchema,
-    multiStreamProjection: multiStreamProjectionSchema,
-    defineEvent: defineEventSchema,
-    extendsRegistrar: extendsRegistrarSchema,
-    envSchema: envSchemaSchema,
-    "ai.generate": aiGenerateSchema,
-    "ai.extract": aiExtractSchema,
-    "ai.classify": aiClassifySchema,
-    unknown: unknownPatternSchema,
-};
-export const patternSchema = z.discriminatedUnion("kind", [
-    entitySchema,
-    relationSchema,
-    navSchema,
-    workspaceSchema,
-    configSchema,
-    translationsSchema,
-    requiresSchema,
-    optionalRequiresSchema,
-    systemScopeSchema,
-    toggleableSchema,
-    describeSchema,
-    uiHintsSchema,
-    metricSchema,
-    secretSchema,
-    secretNamespaceSchema,
-    claimKeySchema,
-    referenceDataSchema,
-    readsConfigSchema,
-    useExtensionSchema,
-    usesApiSchema,
-    exposesApiSchema,
-    treeActionsSchema,
-    screenSchema,
-    writeHandlerSchema,
-    queryHandlerSchema,
-    streamHandlerSchema,
-    hookSchema,
-    jobSchema,
-    notificationSchema,
-    authClaimsSchema,
-    httpRouteSchema,
-    projectionSchema,
-    multiStreamProjectionSchema,
-    defineEventSchema,
-    extendsRegistrarSchema,
-    envSchemaSchema,
-    aiGenerateSchema,
-    aiExtractSchema,
-    aiClassifySchema,
-    unknownPatternSchema,
-]);
-// =============================================================================
-// PatternId union
-// =============================================================================
-const patternIdEntitySchema = z
-    .object({ kind: z.literal("entity"), entityName: z.string() })
-    .strict();
-const patternIdRelationSchema = z
-    .object({ kind: z.literal("relation"), entityName: z.string(), relationName: z.string() })
-    .strict();
-const patternIdNavSchema = z.object({ kind: z.literal("nav"), id: z.string() }).strict();
-const patternIdWorkspaceSchema = z
-    .object({ kind: z.literal("workspace"), id: z.string() })
-    .strict();
-const patternIdScreenSchema = z.object({ kind: z.literal("screen"), id: z.string() }).strict();
-const patternIdWriteHandlerSchema = z
-    .object({ kind: z.literal("writeHandler"), handlerName: z.string() })
-    .strict();
-const patternIdQueryHandlerSchema = z
-    .object({ kind: z.literal("queryHandler"), handlerName: z.string() })
-    .strict();
-const patternIdStreamHandlerSchema = z
-    .object({ kind: z.literal("streamHandler"), handlerName: z.string() })
-    .strict();
-const patternIdHookSchema = z
-    .object({
-    kind: z.literal("hook"),
-    hookType: z.string(),
-    target: z.union([z.string(), z.object({ allOf: z.string() }).strict()]),
-})
-    .strict();
-const patternIdMetricSchema = z
-    .object({ kind: z.literal("metric"), shortName: z.string() })
-    .strict();
-const patternIdSecretSchema = z
-    .object({ kind: z.literal("secret"), shortName: z.string() })
-    .strict();
-const patternIdSecretNamespaceSchema = z
-    .object({ kind: z.literal("secretNamespace"), shortName: z.string() })
-    .strict();
-const patternIdClaimKeySchema = z
-    .object({ kind: z.literal("claimKey"), shortName: z.string() })
-    .strict();
-const patternIdReferenceDataSchema = z
-    .object({ kind: z.literal("referenceData"), entityName: z.string() })
-    .strict();
-const patternIdUseExtensionSchema = z
-    .object({ kind: z.literal("useExtension"), extensionName: z.string(), entityName: z.string() })
-    .strict();
-const patternIdJobSchema = z.object({ kind: z.literal("job"), jobName: z.string() }).strict();
-const patternIdNotificationSchema = z
-    .object({ kind: z.literal("notification"), notificationName: z.string() })
-    .strict();
-const patternIdHttpRouteSchema = z
-    .object({ kind: z.literal("httpRoute"), method: z.string(), path: z.string() })
-    .strict();
-const patternIdProjectionSchema = z
-    .object({ kind: z.literal("projection"), name: z.string() })
-    .strict();
-const patternIdMultiStreamProjectionSchema = z
-    .object({ kind: z.literal("multiStreamProjection"), name: z.string() })
-    .strict();
-const patternIdDefineEventSchema = z
-    .object({ kind: z.literal("defineEvent"), eventName: z.string() })
-    .strict();
-const patternIdExtendsRegistrarSchema = z
-    .object({ kind: z.literal("extendsRegistrar"), extensionName: z.string() })
-    .strict();
-const patternIdAiGenerateSchema = z
-    .object({ kind: z.literal("ai.generate"), stepKey: z.string() })
-    .strict();
-const patternIdAiExtractSchema = z
-    .object({ kind: z.literal("ai.extract"), stepKey: z.string() })
-    .strict();
-const patternIdAiClassifySchema = z
-    .object({ kind: z.literal("ai.classify"), stepKey: z.string() })
-    .strict();
-const patternIdRequiresSchema = z.object({ kind: z.literal("requires") }).strict();
-const patternIdOptionalRequiresSchema = z.object({ kind: z.literal("optionalRequires") }).strict();
-const patternIdReadsConfigSchema = z.object({ kind: z.literal("readsConfig") }).strict();
-const patternIdSystemScopeSchema = z.object({ kind: z.literal("systemScope") }).strict();
-const patternIdToggleableSchema = z.object({ kind: z.literal("toggleable") }).strict();
-const patternIdDescribeSchema = z.object({ kind: z.literal("describe") }).strict();
-const patternIdUiHintsSchema = z.object({ kind: z.literal("uiHints") }).strict();
-const patternIdConfigSchema = z.object({ kind: z.literal("config") }).strict();
-const patternIdTranslationsSchema = z.object({ kind: z.literal("translations") }).strict();
-const patternIdAuthClaimsSchema = z.object({ kind: z.literal("authClaims") }).strict();
-const patternIdTreeActionsSchema = z.object({ kind: z.literal("treeActions") }).strict();
-export const PATTERN_ID_SCHEMAS_BY_KIND = {
-    entity: patternIdEntitySchema,
-    relation: patternIdRelationSchema,
-    nav: patternIdNavSchema,
-    workspace: patternIdWorkspaceSchema,
-    screen: patternIdScreenSchema,
-    writeHandler: patternIdWriteHandlerSchema,
-    queryHandler: patternIdQueryHandlerSchema,
-    streamHandler: patternIdStreamHandlerSchema,
-    hook: patternIdHookSchema,
-    metric: patternIdMetricSchema,
-    secret: patternIdSecretSchema,
-    secretNamespace: patternIdSecretNamespaceSchema,
-    claimKey: patternIdClaimKeySchema,
-    referenceData: patternIdReferenceDataSchema,
-    useExtension: patternIdUseExtensionSchema,
-    job: patternIdJobSchema,
-    notification: patternIdNotificationSchema,
-    httpRoute: patternIdHttpRouteSchema,
-    projection: patternIdProjectionSchema,
-    multiStreamProjection: patternIdMultiStreamProjectionSchema,
-    defineEvent: patternIdDefineEventSchema,
-    extendsRegistrar: patternIdExtendsRegistrarSchema,
-    "ai.generate": patternIdAiGenerateSchema,
-    "ai.extract": patternIdAiExtractSchema,
-    "ai.classify": patternIdAiClassifySchema,
-    requires: patternIdRequiresSchema,
-    optionalRequires: patternIdOptionalRequiresSchema,
-    readsConfig: patternIdReadsConfigSchema,
-    systemScope: patternIdSystemScopeSchema,
-    toggleable: patternIdToggleableSchema,
-    describe: patternIdDescribeSchema,
-    uiHints: patternIdUiHintsSchema,
-    config: patternIdConfigSchema,
-    translations: patternIdTranslationsSchema,
-    authClaims: patternIdAuthClaimsSchema,
-    treeActions: patternIdTreeActionsSchema,
-};
-export const patternIdSchema = z.discriminatedUnion("kind", [
-    patternIdEntitySchema,
-    patternIdRelationSchema,
-    patternIdNavSchema,
-    patternIdWorkspaceSchema,
-    patternIdScreenSchema,
-    patternIdWriteHandlerSchema,
-    patternIdQueryHandlerSchema,
-    patternIdStreamHandlerSchema,
-    patternIdHookSchema,
-    patternIdMetricSchema,
-    patternIdSecretSchema,
-    patternIdSecretNamespaceSchema,
-    patternIdClaimKeySchema,
-    patternIdReferenceDataSchema,
-    patternIdUseExtensionSchema,
-    patternIdJobSchema,
-    patternIdNotificationSchema,
-    patternIdHttpRouteSchema,
-    patternIdProjectionSchema,
-    patternIdMultiStreamProjectionSchema,
-    patternIdDefineEventSchema,
-    patternIdExtendsRegistrarSchema,
-    patternIdAiGenerateSchema,
-    patternIdAiExtractSchema,
-    patternIdAiClassifySchema,
-    patternIdRequiresSchema,
-    patternIdOptionalRequiresSchema,
-    patternIdReadsConfigSchema,
-    patternIdSystemScopeSchema,
-    patternIdToggleableSchema,
-    patternIdDescribeSchema,
-    patternIdUiHintsSchema,
-    patternIdConfigSchema,
-    patternIdTranslationsSchema,
-    patternIdAuthClaimsSchema,
-    patternIdTreeActionsSchema,
-]);
-// =============================================================================
-// Change union — `rationale` is accepted (optional, on every member) and
-// dropped when the final PatternChange is assembled below (plain field
-// selection, not a schema-level transform — see file-header rationale).
-// =============================================================================
-const addChangeSchema = z
-    .object({
-    op: z.literal("add"),
-    pattern: patternSchema,
-    rationale: z.string().optional(),
-})
-    .strict();
-const replaceChangeSchema = z
-    .object({
-    op: z.literal("replace"),
-    id: patternIdSchema,
-    pattern: patternSchema,
-    rationale: z.string().optional(),
-})
-    .strict();
-const removeChangeSchema = z
-    .object({
-    op: z.literal("remove"),
-    id: patternIdSchema,
-    rationale: z.string().optional(),
-})
-    .strict();
-// `set`/`unset` are validated loosely here; the real per-kind check happens
-// in a second pass once `id.kind` is known (see parseUpdateChange).
-const updateChangeSchema = z
-    .object({
-    op: z.literal("update"),
-    id: patternIdSchema,
-    set: z.record(z.string(), z.unknown()).optional(),
-    unset: z.array(z.string()).optional(),
-    rationale: z.string().optional(),
-})
-    .strict();
-const changeSchema = z.discriminatedUnion("op", [
-    addChangeSchema,
-    replaceChangeSchema,
-    removeChangeSchema,
-    updateChangeSchema,
-]);
-function prefixIssuePath(issues, prefix) {
-    return issues.map((issue) => ({ ...issue, path: [prefix, ...issue.path] }));
-}
-// Shared per-`unset[j]` checks ("access" is fixed-required, overlap with
-// `set`) ahead of the kind-specific enum parse in parseHeaderSetAndUnset.
-function unsetElementIssue(key, j, index, setKeys) {
-    if (key === "access") {
-        return {
-            path: `changes[${index}].unset[${j}]`,
-            message: "access is required and cannot be unset",
-        };
-    }
-    if (setKeys.has(key)) {
-        return { path: `changes[${index}].unset[${j}]`, message: "key is also in set" };
-    }
-    return undefined;
-}
-// Shared set/unset validation for one handler kind's Set-schema/Unset-enum —
-// the only thing that differs per kind (see the switch below).
-function parseHeaderSetAndUnset(setSchema, unsetEnum, kindLabel, value, index, rawItem) {
-    const issues = [];
-    const setResult = setSchema.safeParse(value.set ?? {});
-    if (!setResult.success) {
-        issues.push(...formatZodIssues(prefixIssuePath(setResult.error.issues, "set"), index, rawItem));
-    }
-    const setKeys = new Set(Object.keys(value.set ?? {}));
-    const unsetInput = value.unset ?? [];
-    const validatedUnset = [];
-    unsetInput.forEach((key, j) => {
-        const preIssue = unsetElementIssue(key, j, index, setKeys);
-        if (preIssue) {
-            issues.push(preIssue);
-            // skip: already reported, no further checks apply to this element
-            return;
-        }
-        const parsed = unsetEnum.safeParse(key);
-        if (!parsed.success) {
-            issues.push({
-                path: `changes[${index}].unset[${j}]`,
-                message: `"${key}" is not a header field of ${kindLabel}`,
-            });
-            // skip: already reported, no further checks apply to this element
-            return;
-        }
-        validatedUnset.push(parsed.data);
-    });
-    const hasSet = value.set !== undefined && Object.keys(value.set).length > 0;
-    if (!hasSet && unsetInput.length === 0) {
-        issues.push({
-            path: `changes[${index}].set`,
-            message: "update needs at least one key in set or unset",
-        });
-    }
-    if (!setResult.success || issues.length > 0)
-        return { ok: false, issues };
-    return { ok: true, set: setResult.data, unset: validatedUnset };
-}
-// Per-kind switch so `value.id` narrows and `change` needs no cast.
-function parseUpdateChange(value, index, rawItem) {
-    switch (value.id.kind) {
-        case "writeHandler": {
-            const result = parseHeaderSetAndUnset(WRITE_HANDLER_UPDATE_SET_SCHEMA, WRITE_HANDLER_UPDATE_UNSET_ENUM, "writeHandler", value, index, rawItem);
-            if (!result.ok)
-                return { issues: result.issues };
-            const change = {
-                op: "update",
-                id: value.id,
-                set: result.set,
-                ...(result.unset.length > 0 ? { unset: result.unset } : {}),
-            };
-            return { change, issues: [] };
-        }
-        case "queryHandler": {
-            const result = parseHeaderSetAndUnset(QUERY_HANDLER_UPDATE_SET_SCHEMA, QUERY_HANDLER_UPDATE_UNSET_ENUM, "queryHandler", value, index, rawItem);
-            if (!result.ok)
-                return { issues: result.issues };
-            const change = {
-                op: "update",
-                id: value.id,
-                set: result.set,
-                ...(result.unset.length > 0 ? { unset: result.unset } : {}),
-            };
-            return { change, issues: [] };
-        }
-        case "streamHandler": {
-            const result = parseHeaderSetAndUnset(STREAM_HANDLER_UPDATE_SET_SCHEMA, STREAM_HANDLER_UPDATE_UNSET_ENUM, "streamHandler", value, index, rawItem);
-            if (!result.ok)
-                return { issues: result.issues };
-            const change = {
-                op: "update",
-                id: value.id,
-                set: result.set,
-                ...(result.unset.length > 0 ? { unset: result.unset } : {}),
-            };
-            return { change, issues: [] };
-        }
-        default:
-            return {
-                issues: [
-                    {
-                        path: `changes[${index}].id.kind`,
-                        message: `update is not supported for kind "${value.id.kind}"; use replace`,
-                    },
-                ],
-            };
-    }
-}
-// =============================================================================
-// Issue formatting
-// =============================================================================
-function formatPath(index, path) {
-    let out = `changes[${index}]`;
-    for (const segment of path) {
-        out += typeof segment === "number" ? `[${segment}]` : `.${String(segment)}`;
-    }
-    return out;
-}
-function getAtPath(root, path) {
-    let current = root;
-    for (const segment of path) {
-        if (isPlainObject(current)) {
-            current = current[String(segment)];
-        }
-        else if (Array.isArray(current) && typeof segment === "number") {
-            current = current[segment];
-        }
-        else {
-            return undefined;
-        }
-    }
-    return current;
-}
-// zod v4 reports `.strict()` violations as a single `unrecognized_keys`
-// issue per offending object, carrying all extra key names at once. We
-// split it into one PatternChangeIssue per key so each unexpected key gets
-// its own actionable path — except `definition` on a handler-kind pattern
-// nesting an `access` sub-key, which gets the more specific message the
-// spec calls for (a caller who nests `access` under a stray `definition`
-// key is making one specific, common mistake, not an arbitrary unknown key).
-// Only these kinds render a top-level `access`; on any other kind the hint
-// would send the caller into a second rejection.
-function isKindWithTopLevelAccess(kind) {
-    return kind === "writeHandler" || kind === "queryHandler" || kind === "streamHandler";
-}
-function formatZodIssues(issues, index, rawItem) {
-    const out = [];
-    for (const issue of issues) {
-        if (issue.code === "unrecognized_keys") {
-            const parentValue = getAtPath(rawItem, issue.path);
-            for (const key of issue.keys) {
-                const keyValue = isPlainObject(parentValue) ? parentValue[key] : undefined;
-                if (key === "definition" &&
-                    isPlainObject(parentValue) &&
-                    isKindWithTopLevelAccess(parentValue["kind"]) &&
-                    isPlainObject(keyValue) &&
-                    "access" in keyValue) {
-                    out.push({
-                        path: `${formatPath(index, issue.path)}.definition.access`,
-                        message: "unexpected key; access belongs at top level of the pattern",
-                    });
-                    continue;
-                }
-                out.push({
-                    path: `${formatPath(index, issue.path)}.${key}`,
-                    message: "unexpected key",
-                });
-            }
-            continue;
-        }
-        out.push({ path: formatPath(index, issue.path), message: issue.message });
-    }
-    return out;
-}
-// =============================================================================
-// Public API
-// =============================================================================
-export function parsePatternChanges(input) {
-    if (!Array.isArray(input)) {
-        return { ok: false, issues: [{ path: "changes", message: "must be an array" }] };
-    }
-    const issues = [];
-    const changes = [];
-    input.forEach((item, index) => {
-        const result = changeSchema.safeParse(item);
-        if (!result.success) {
-            issues.push(...formatZodIssues(result.error.issues, index, item));
-            // skip: schema violations already reported as issues
-            return;
-        }
-        const value = result.data;
-        if (value.op === "replace" && value.id.kind !== value.pattern.kind) {
-            issues.push({
-                path: `changes[${index}].pattern.kind`,
-                message: `pattern.kind "${value.pattern.kind}" does not match id.kind "${value.id.kind}"`,
-            });
-            // skip: id/pattern kind mismatch already reported as an issue
-            return;
-        }
-        if (value.op === "add") {
-            changes.push({ op: "add", pattern: value.pattern });
-        }
-        else if (value.op === "replace") {
-            changes.push({ op: "replace", id: value.id, pattern: value.pattern });
-        }
-        else if (value.op === "remove") {
-            changes.push({ op: "remove", id: value.id });
-        }
-        else {
-            const outcome = parseUpdateChange(value, index, item);
-            issues.push(...outcome.issues);
-            if (outcome.change)
-                changes.push(outcome.change);
-        }
-    });
-    if (issues.length > 0)
-        return { ok: false, issues };
-    return { ok: true, changes };
-}