@cosmicdrift/kumiko-framework 0.328.0 → 0.328.1

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

@@ -0,0 +1,1196 @@
+// 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 — see kumiko-framework#3137.
+//
+// **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 * 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",
+    }),
+})
+    .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 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,
+    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, rateLimitDisabledSchema])),
+    escapeHatch: orRawRef(escapeHatchSchema),
+};
+const QUERY_HANDLER_PATTERN_HEADER_SHAPE = {
+    ...QUERY_HANDLER_HEADER_SHAPE,
+    access: orRawRef(accessRuleSchema),
+    agent: orRawRef(agentHandlerHintsSchema),
+    rateLimit: orRawRef(z.union([rateLimitOptionSchema, rateLimitDisabledSchema])),
+    escapeHatch: orRawRef(escapeHatchSchema),
+};
+const STREAM_HANDLER_PATTERN_HEADER_SHAPE = {
+    ...STREAM_HANDLER_HEADER_SHAPE,
+    access: orRawRef(accessRuleSchema),
+    rateLimit: orRawRef(z.union([rateLimitOptionSchema, 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,
+})
+    .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 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(),
+    recipientBody: sourceBodySchema,
+    dataBody: sourceBodySchema,
+    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,
+    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,
+};
+const patternSchema = z.discriminatedUnion("kind", [
+    entitySchema,
+    relationSchema,
+    navSchema,
+    workspaceSchema,
+    configSchema,
+    translationsSchema,
+    requiresSchema,
+    optionalRequiresSchema,
+    systemScopeSchema,
+    toggleableSchema,
+    describeSchema,
+    uiHintsSchema,
+    metricSchema,
+    secretSchema,
+    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 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,
+    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,
+};
+const patternIdSchema = z.discriminatedUnion("kind", [
+    patternIdEntitySchema,
+    patternIdRelationSchema,
+    patternIdNavSchema,
+    patternIdWorkspaceSchema,
+    patternIdScreenSchema,
+    patternIdWriteHandlerSchema,
+    patternIdQueryHandlerSchema,
+    patternIdStreamHandlerSchema,
+    patternIdHookSchema,
+    patternIdMetricSchema,
+    patternIdSecretSchema,
+    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 };
+}