@cosmicdrift/kumiko-framework 0.328.0 → 0.328.1

package/src/engine/feature-ast/pattern-change-schema.ts

@@ -1,1411 +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 — 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 { type LifecycleHookType, LifecycleHookTypes } from "../constants";
-import type {
-  ConfigKeyDefinition,
-  ConfigKeyType,
-  JobDefinition,
-  ReferenceDataDef,
-  RunIn,
-  TranslationKeys,
-} from "../types/config";
-import type { MetricOptions, SecretOptions } from "../types/feature";
-import type { EntityDefinition } from "../types/fields";
-import type { AgentRisk, ClaimKeyType, RateLimitPer } from "../types/handlers";
-import type { HookPhase } from "../types/hooks";
-import type { HttpRouteMethod } from "../types/http-route";
-import type { NavDefinition } from "../types/nav";
-import type { RelationDefinition } from "../types/relations";
-import type { ScreenDefinition } from "../types/screen";
-import type { TreeActionDef } from "../types/tree-node";
-import type { WorkspaceDefinition } from "../types/workspace";
-import { describeUnknownFieldType, findUnknownEntityFieldTypes } from "./entity-field-types";
-import { AGENT_RISK_VALUES } from "./extractors/handlers";
-import { isPlainObject, isRawRefSentinel } from "./extractors/shared";
-import type {
-  PatternChange,
-  PatternId,
-  QueryHandlerHeaderKey,
-  StreamHandlerHeaderKey,
-  WriteHandlerHeaderKey,
-} from "./patch";
-import { SYNTHETIC_LOC } from "./patcher";
-import type { FeaturePatternKind } from "./patterns";
-import type { SourceLocation, SourcePosition } from "./source-location";
-
-// 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<T extends string>(flags: Record<T, true>): readonly T[] {
-  return Object.keys(flags) as T[];
-}
-
-// =============================================================================
-// Result types
-// =============================================================================
-
-export type PatternChangeIssue = {
-  readonly path: string;
-  readonly message: string;
-};
-
-export type PatternChangesParseResult =
-  | { readonly ok: true; readonly changes: readonly PatternChange[] }
-  | { readonly ok: false; readonly issues: readonly PatternChangeIssue[] };
-
-// =============================================================================
-// Shared primitives
-// =============================================================================
-
-function isPlainObjectOrSentinel(value: unknown): boolean {
-  return isRawRefSentinel(value) || isPlainObject(value);
-}
-
-const sourcePositionSchema: z.ZodType<SourcePosition> = z
-  .object({ line: z.number(), column: z.number() })
-  .strict();
-
-const fullSourceLocationSchema: z.ZodType<SourceLocation> = 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): SourceLocation => ({ ...SYNTHETIC_LOC, raw: value.raw }));
-
-const stringSourceLocationSchema = z
-  .string()
-  .transform((raw): SourceLocation => ({ ...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.ZodType<SourceLocation> = 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: z.ZodType<SourceLocation> = 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.ZodType<readonly string[]> = z.custom<readonly string[]>(
-  (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,
-) as readonly LifecycleHookType[];
-
-const hookTypeSchema = z.enum([...LIFECYCLE_HOOK_TYPE_VALUES, "validation"] as const);
-const hookPhaseSchema = z.enum(keysOf<HookPhase>({ inTransaction: true, afterCommit: true }));
-const httpRouteMethodSchema = z.enum(
-  keysOf<HttpRouteMethod>({
-    GET: true,
-    POST: true,
-    PUT: true,
-    PATCH: true,
-    DELETE: true,
-    HEAD: true,
-    OPTIONS: true,
-  }),
-);
-const runInSchema = z.enum(keysOf<RunIn>({ api: true, worker: true, both: true }));
-const claimKeyTypeSchema = z.enum(
-  keysOf<ClaimKeyType>({
-    string: true,
-    number: true,
-    boolean: true,
-    "string[]": true,
-    object: true,
-  }),
-);
-const agentRiskSchema = z.enum(AGENT_RISK_VALUES as [AgentRisk, ...AgentRisk[]]);
-const rateLimitPerSchema = z.enum(
-  keysOf<RateLimitPer>({
-    user: true,
-    tenant: true,
-    ip: true,
-    "user+handler": true,
-    "tenant+handler": true,
-    "ip+handler": true,
-  }),
-);
-const mspDeliverySchema = z.enum(
-  keysOf<"shared" | "per-instance">({ 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<T extends z.ZodTypeAny>(schema: T) {
-  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,
-} satisfies Record<WriteHandlerHeaderKey, z.ZodTypeAny>;
-const QUERY_HANDLER_HEADER_SHAPE = {
-  access: accessRuleSchema,
-  description: z.string(),
-  agent: agentHandlerHintsSchema,
-  rateLimit: rateLimitOptionSchema,
-  escapeHatch: escapeHatchSchema,
-} satisfies Record<QueryHandlerHeaderKey, z.ZodTypeAny>;
-const STREAM_HANDLER_HEADER_SHAPE = {
-  access: accessRuleSchema,
-  rateLimit: rateLimitOptionSchema,
-  escapeHatch: escapeHatchSchema,
-} satisfies Record<StreamHandlerHeaderKey, z.ZodTypeAny>;
-
-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: {
-    readonly handlerName?: string;
-    readonly schemaSource?: SourceLocation;
-    readonly handlerBody?: SourceLocation;
-    readonly source: SourceLocation;
-    readonly [headerKey: string]: unknown;
-  },
-  ctx: z.RefinementCtx,
-  headerKeys: readonly string[],
-): void {
-  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<T>(): z.ZodType<T> {
-  return z.custom<T>(isPlainObjectOrSentinel, {
-    message: "must be a plain object or unresolved reference",
-  });
-}
-
-const entityDefinitionSchema = passthroughSchema<EntityDefinition>().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<RelationDefinition>(),
-  })
-  .strict();
-
-const navSchema = z
-  .object({
-    kind: z.literal("nav"),
-    source: sourceFieldSchema,
-    definition: passthroughSchema<NavDefinition>(),
-  })
-  .strict();
-
-const workspaceSchema = z
-  .object({
-    kind: z.literal("workspace"),
-    source: sourceFieldSchema,
-    definition: passthroughSchema<WorkspaceDefinition>(),
-  })
-  .strict();
-
-const configSchema = z
-  .object({
-    kind: z.literal("config"),
-    source: sourceFieldSchema,
-    keys: passthroughSchema<Readonly<Record<string, ConfigKeyDefinition<ConfigKeyType>>>>(),
-  })
-  .strict();
-
-const translationsSchema = z
-  .object({
-    kind: z.literal("translations"),
-    source: sourceFieldSchema,
-    keys: passthroughSchema<TranslationKeys>(),
-  })
-  .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<MetricOptions>(),
-  })
-  .strict();
-
-const secretSchema = z
-  .object({
-    kind: z.literal("secret"),
-    source: sourceFieldSchema,
-    shortName: z.string(),
-    options: passthroughSchema<SecretOptions>(),
-  })
-  .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<ReferenceDataDef["data"]>(
-      (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<Readonly<Record<string, unknown>>>().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<Readonly<Record<string, TreeActionDef>>>(),
-  })
-  .strict();
-
-// =============================================================================
-// Mixed patterns
-// =============================================================================
-
-const screenSchema = z
-  .object({
-    kind: z.literal("screen"),
-    source: sourceFieldSchema,
-    definition: passthroughSchema<ScreenDefinition>(),
-    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<Omit<JobDefinition, "name" | "handler">>(),
-    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<{ readonly __raw: string }>(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<Record<string, unknown>>(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,
-} satisfies Record<FeaturePatternKind, z.ZodTypeAny>;
-
-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,
-} satisfies Record<PatternId["kind"], z.ZodTypeAny>;
-
-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: readonly z.core.$ZodIssue[],
-  prefix: PropertyKey,
-): z.core.$ZodIssue[] {
-  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: string,
-  j: number,
-  index: number,
-  setKeys: ReadonlySet<string>,
-): PatternChangeIssue | undefined {
-  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 extends z.ZodType<Record<string, unknown>>,
-  UnsetKey extends string,
->(
-  setSchema: SetSchema,
-  unsetEnum: z.ZodType<UnsetKey>,
-  kindLabel: string,
-  value: z.output<typeof updateChangeSchema>,
-  index: number,
-  rawItem: unknown,
-):
-  | { readonly ok: true; readonly set: z.output<SetSchema>; readonly unset: readonly UnsetKey[] }
-  | { readonly ok: false; readonly issues: readonly PatternChangeIssue[] } {
-  const issues: PatternChangeIssue[] = [];
-  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: UnsetKey[] = [];
-  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: z.output<typeof updateChangeSchema>,
-  index: number,
-  rawItem: unknown,
-): { readonly change?: PatternChange; readonly issues: readonly PatternChangeIssue[] } {
-  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: PatternChange = {
-        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: PatternChange = {
-        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: PatternChange = {
-        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: number, path: readonly PropertyKey[]): string {
-  let out = `changes[${index}]`;
-  for (const segment of path) {
-    out += typeof segment === "number" ? `[${segment}]` : `.${String(segment)}`;
-  }
-  return out;
-}
-
-function getAtPath(root: unknown, path: readonly PropertyKey[]): unknown {
-  let current: unknown = 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: unknown): boolean {
-  return kind === "writeHandler" || kind === "queryHandler" || kind === "streamHandler";
-}
-
-function formatZodIssues(
-  issues: readonly z.core.$ZodIssue[],
-  index: number,
-  rawItem: unknown,
-): PatternChangeIssue[] {
-  const out: PatternChangeIssue[] = [];
-  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: unknown): PatternChangesParseResult {
-  if (!Array.isArray(input)) {
-    return { ok: false, issues: [{ path: "changes", message: "must be an array" }] };
-  }
-
-  const issues: PatternChangeIssue[] = [];
-  const changes: PatternChange[] = [];
-
-  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 };
-}