prisma-generator-express 1.66.0 → 1.68.0

package/src/generators/generateRouterPartsHono.ts

@@ -0,0 +1,220 @@
+import type { DMMF } from '@prisma/generator-helper'
+import { generateRouteConfigType } from './generateRouteConfigType'
+import type { ImportStyle } from '../utils/resolveImportStyle'
+import { importExt } from '../utils/importExt'
+import type { WriteStrategy } from '../constants'
+import { modelPathSegment, type PathCase } from '../utils/pathCasing'
+import { OPERATION_METADATA } from '../copy/operationDefinitions'
+
+function opKindFor(opName: string): string {
+  switch (opName) {
+    case 'findUnique':
+    case 'findUniqueOrThrow':
+      return 'readUnique'
+    case 'findMany':
+    case 'findFirst':
+    case 'findFirstOrThrow':
+    case 'findManyPaginated':
+    case 'count':
+    case 'aggregate':
+    case 'groupBy':
+      return 'read'
+    case 'create':
+      return 'create'
+    case 'createMany':
+    case 'createManyAndReturn':
+      return 'createMany'
+    case 'update':
+      return 'update'
+    case 'updateMany':
+    case 'updateManyAndReturn':
+      return 'updateMany'
+    case 'upsert':
+      return 'upsert'
+    case 'delete':
+      return 'delete'
+    case 'deleteMany':
+      return 'deleteMany'
+    default:
+      return 'noop'
+  }
+}
+
+/**
+ * The phase 9 static assembly boundary, emitted side: one named factory per
+ * operation, each returning a Hono sub-app with exactly that route. A consumer
+ * imports only the parts it serves; everything not imported is absent from the
+ * bundle — which `enableAll` at runtime can never do, because route
+ * configuration is runtime data. Heavy features are referenced only by their
+ * own parts (`userOpenApi` is the sole static referencer of the OpenAPI
+ * renderer and `yaml`).
+ */
+export function generateHonoRouterParts({
+  model,
+  enums,
+  guardShapesImport,
+  clientImport,
+  importStyle,
+  writeStrategy,
+  dropGuard,
+  pathCase,
+}: {
+  model: DMMF.Model
+  enums: DMMF.DatamodelEnum[]
+  guardShapesImport: string | null
+  clientImport?: string
+  importStyle: ImportStyle
+  writeStrategy: WriteStrategy
+  dropGuard: boolean
+  pathCase: PathCase
+}): string {
+  const ext = importExt(importStyle)
+  const modelName = model.name
+  const modelSegment = modelPathSegment(modelName, pathCase)
+  const lower = modelName.charAt(0).toLowerCase() + modelName.slice(1)
+  const cap = (s: string) => s.charAt(0).toUpperCase() + s.slice(1)
+
+  const handlerImports = OPERATION_METADATA.map(
+    (m) => `  ${modelName}${cap(m.name)},`,
+  ).join('\n')
+
+  const readOps = OPERATION_METADATA.filter((m) => m.kind === 'read')
+  const writeOps = OPERATION_METADATA.filter(
+    (m) => m.kind === 'write' || m.kind === 'batch',
+  ).filter((m) => m.name !== 'updateEach')
+
+  const pathExpr = (suffix: string) =>
+    !suffix ? `setup.basePath || '/'` : `\`\${setup.basePath}${suffix}\``
+
+  const readFactories = readOps
+    .map((meta) => {
+      const fn = `${lower}${cap(meta.name)}`
+      const handler = `${modelName}${cap(meta.name)}`
+      const opKind = opKindFor(meta.name)
+      const pathValue = pathExpr(meta.pathSuffix)
+      const postPathValue =
+        meta.name === 'findMany'
+          ? `setup.basePath ? \`\${setup.basePath}/read\` : '/read'`
+          : pathExpr(meta.pathSuffix)
+      return `
+export function ${fn}<TCtx = unknown, TPrisma extends PrismaClientLike = PrismaClientLike, TEnv extends HonoEnvBase = HonoEnvBase>(config: ${modelName}RouteConfig<TCtx, TPrisma, TEnv> = {}): Hono<GeneratedHonoEnv<TEnv>> {
+  const setup = ${lower}PartsSetup(config)
+  const opConfig = setup.opFor('${meta.configKey}')
+  const app = new Hono<GeneratedHonoEnv<TEnv>>()
+  app.get(${pathValue}, createReadRoute<TCtx, TPrisma, TEnv>({ config, opConfig, opKind: '${opKind}', handler: ${handler}, parse: 'query', dropGuard: setup.dropGuard, settleBeforeHooks: setup.settleBeforeHooks }))
+  return app
+}
+
+export function ${fn}PostRead<TCtx = unknown, TPrisma extends PrismaClientLike = PrismaClientLike, TEnv extends HonoEnvBase = HonoEnvBase>(config: ${modelName}RouteConfig<TCtx, TPrisma, TEnv> = {}): Hono<GeneratedHonoEnv<TEnv>> {
+  const setup = ${lower}PartsSetup(config)
+  const opConfig = setup.opFor('${meta.configKey}')
+  const app = new Hono<GeneratedHonoEnv<TEnv>>()
+  app.post(${postPathValue}, createReadRoute<TCtx, TPrisma, TEnv>({ config, opConfig, opKind: '${opKind}', handler: ${handler}, parse: 'body', dropGuard: setup.dropGuard, settleBeforeHooks: setup.settleBeforeHooks }))
+  return app
+}
+`
+    })
+    .join('\n')
+
+  const writeFactories = writeOps
+    .map((meta) => {
+      const fn = `${lower}${cap(meta.name)}`
+      const handler = `${modelName}${cap(meta.name)}`
+      const opKind = opKindFor(meta.name)
+      const pathValue = pathExpr(meta.pathSuffix)
+      return `
+export function ${fn}<TCtx = unknown, TPrisma extends PrismaClientLike = PrismaClientLike, TEnv extends HonoEnvBase = HonoEnvBase>(config: ${modelName}RouteConfig<TCtx, TPrisma, TEnv> = {}): Hono<GeneratedHonoEnv<TEnv>> {
+  const setup = ${lower}PartsSetup(config)
+  const opConfig = setup.opFor('${meta.configKey}')
+  const app = new Hono<GeneratedHonoEnv<TEnv>>()
+  app.${meta.method}(${pathValue}, createWriteRoute<TCtx, TPrisma, TEnv>({ config, opConfig, opKind: '${opKind}', handler: ${handler}, dropGuard: setup.dropGuard, settleBeforeHooks: setup.settleBeforeHooks }))
+  return app
+}
+`
+    })
+    .join('\n')
+
+  return `import { Hono } from 'hono'
+import {
+${handlerImports}
+} from './${modelName}Handlers${ext}'
+import type {
+  RouteConfig,
+  HonoEnvBase,
+  GeneratedHonoEnv,
+  PrismaClientLike,
+} from '../routeConfig.target${ext}'
+import { normalizePrefix, getEnv, resolveDropGuardEnv } from '../misc${ext}'
+import {
+  resolveGuardPolicy,
+  validateCountSourceWhere,
+  warnIfUnguardedRoutes,
+} from '../routeConfig${ext}'
+import {
+  createReadRoute,
+  createWriteRoute,
+  createUpdateEachRoute,
+  opConfigFor,
+  normalizeHonoOperation,
+  type HonoOpConfig,
+} from '../routerParts${ext}'
+import { MODEL_FIELDS, MODEL_ENUMS } from './${modelName}Metadata${ext}'
+
+${generateRouteConfigType(modelName, 'HonoBeforeHook', guardShapesImport, importStyle, 'hono', clientImport)}
+
+// Fixed at generation time, identical to the legacy router factory.
+const DROP_GUARD = ${dropGuard}
+
+// No module-level side effects: this file must be tree-shakeable, so unused
+// per-op exports — and everything only they reference, down to the OpenAPI
+// renderer and yaml — drop out of a bundler's output. The environment is read
+// inside the functions that need it.
+
+function ${lower}PartsSetup<TCtx = unknown, TPrisma extends PrismaClientLike = PrismaClientLike, TEnv extends HonoEnvBase = HonoEnvBase>(config: ${modelName}RouteConfig<TCtx, TPrisma, TEnv>) {
+  validateCountSourceWhere(config.pagination?.countSource, '${modelName} pagination')
+  validateCountSourceWhere(
+    (config.findManyPaginated && typeof config.findManyPaginated === 'object' ? config.findManyPaginated : undefined)?.pagination?.countSource,
+    '${modelName} findManyPaginated pagination',
+  )
+
+  const isEnabled = (value: unknown): boolean => value !== false && !!(config.enableAll || value)
+  warnIfUnguardedRoutes('${modelName}', ['findMany', 'findUnique', 'findUniqueOrThrow', 'findFirst', 'findFirstOrThrow', 'findManyPaginated', 'count', 'aggregate', 'groupBy', 'create', 'createMany', 'createManyAndReturn', 'update', 'updateMany', 'updateManyAndReturn', 'upsert', 'delete', 'deleteMany'], config, isEnabled)
+
+  const customPrefix = normalizePrefix(config.customUrlPrefix || '')
+  const modelPrefix = config.addModelPrefix !== false ? '/${modelSegment}' : ''
+  const basePath = customPrefix + modelPrefix
+
+  const POLICY = resolveGuardPolicy(config)
+  const dropGuard =
+    DROP_GUARD || (POLICY.allowE2EGuardBypass && resolveDropGuardEnv(getEnv()))
+  const settleBeforeHooks = POLICY.guardResolutionOrder === 'before-hooks'
+
+  const opFor = <K extends keyof ${modelName}RouteConfig<TCtx, TPrisma, TEnv>>(
+    key: K,
+  ): HonoOpConfig<TEnv> => {
+    const raw = config[key] as unknown as Parameters<typeof normalizeHonoOperation<TEnv>>[0]
+    return opConfigFor<TEnv>(raw, '${modelName}.' + String(key), POLICY)
+  }
+
+  return { basePath, POLICY, dropGuard, settleBeforeHooks, opFor }
+}
+${readFactories}
+${writeFactories}
+export function ${lower}UpdateEach<TCtx = unknown, TPrisma extends PrismaClientLike = PrismaClientLike, TEnv extends HonoEnvBase = HonoEnvBase>(config: ${modelName}RouteConfig<TCtx, TPrisma, TEnv> = {}): Hono<GeneratedHonoEnv<TEnv>> {
+  const setup = ${lower}PartsSetup(config)
+  if (!setup.POLICY.enableUpdateEach) {
+    throw new Error(
+      '${modelName}.updateEach: enableUpdateEach is false, so this part ' +
+      'is not available. It bypasses guard shapes entirely, so there is no ' +
+      'configuration that makes it safe to expose.',
+    )
+  }
+  const raw = config.updateEach as unknown as Parameters<typeof normalizeHonoOperation<TEnv>>[0]
+  const opConfig = normalizeHonoOperation<TEnv>(raw)
+  const app = new Hono<GeneratedHonoEnv<TEnv>>()
+  app.post(setup.basePath ? \`\${setup.basePath}/each\` : '/each', createUpdateEachRoute<TCtx, TPrisma, TEnv>({ config, opConfig, handler: ${modelName}UpdateEach, dropGuard: setup.dropGuard }))
+  return app
+}
+
+`
+}

package/src/generators/generateUnifiedDocs.ts

@@ -4,18 +4,21 @@ import type { Target } from '../constants'
 
 export function generateUnifiedDocs(
   modelNames: string[],
+  pathSegments: Record<string, string>,
   target: Target,
   importStyle: ImportStyle,
 ): string {
   const ext = importExt(importStyle)
-  if (target === 'fastify') return generateFastify(modelNames, ext)
-  if (target === 'hono') return generateHono(modelNames, ext)
-  return generateExpress(modelNames, ext)
+  if (target === 'fastify')
+    return generateFastify(modelNames, pathSegments, ext)
+  if (target === 'hono') return generateHono(modelNames, pathSegments, ext)
+  return generateExpress(modelNames, pathSegments, ext)
 }
 
 const renderIndexFn = `function renderIndex(title: string, modelNames: string[], basePath: string): string {
+  const segments = MODEL_PATH_SEGMENTS as Record<string, string>
   const links = modelNames
-    .map((n) => '<li><a href="' + basePath + '/' + n.toLowerCase() + '">' + n + '</a></li>')
+    .map((n) => '<li><a href="' + basePath + '/' + (segments[n] ?? n.toLowerCase()) + '">' + n + '</a></li>')
     .join('')
 
   return '<!DOCTYPE html><html><head><meta charset="utf-8" /><title>' + title +
@@ -27,7 +30,11 @@ const renderIndexFn = `function renderIndex(title: string, modelNames: string[],
     '</div></body></html>'
 }`
 
-function generateExpress(modelNames: string[], ext: string): string {
+function generateExpress(
+  modelNames: string[],
+  pathSegments: Record<string, string>,
+  ext: string,
+): string {
   return `import type { Router } from 'express'
 import { getEnv, removeTrailingSlash } from './misc${ext}'
 
@@ -35,6 +42,8 @@ const _env = getEnv()
 
 const MODELS = ${JSON.stringify(modelNames)} as const
 
+const MODEL_PATH_SEGMENTS = ${JSON.stringify(pathSegments)} as const
+
 interface UnifiedDocsConfig {
   title?: string
   basePath?: string
@@ -62,7 +71,11 @@ export default registerUnifiedDocs
 `
 }
 
-function generateFastify(modelNames: string[], ext: string): string {
+function generateFastify(
+  modelNames: string[],
+  pathSegments: Record<string, string>,
+  ext: string,
+): string {
   return `import type { FastifyInstance } from 'fastify'
 import { getEnv, removeTrailingSlash } from './misc${ext}'
 
@@ -70,6 +83,8 @@ const _env = getEnv()
 
 const MODELS = ${JSON.stringify(modelNames)} as const
 
+const MODEL_PATH_SEGMENTS = ${JSON.stringify(pathSegments)} as const
+
 interface UnifiedDocsConfig {
   title?: string
   basePath?: string
@@ -100,7 +115,11 @@ export default registerUnifiedDocs
 `
 }
 
-function generateHono(modelNames: string[], ext: string): string {
+function generateHono(
+  modelNames: string[],
+  pathSegments: Record<string, string>,
+  ext: string,
+): string {
   return `import type { Hono } from 'hono'
 import { getEnv, removeTrailingSlash } from './misc${ext}'
 
@@ -108,6 +127,8 @@ const _env = getEnv()
 
 const MODELS = ${JSON.stringify(modelNames)} as const
 
+const MODEL_PATH_SEGMENTS = ${JSON.stringify(pathSegments)} as const
+
 interface UnifiedDocsConfig {
   title?: string
   basePath?: string
@@ -133,4 +154,4 @@ ${renderIndexFn}
 
 export default registerUnifiedDocs
 `
-}
+}

package/src/generators/generateUnifiedHandler.ts

@@ -1,5 +1,5 @@
-import { DMMF } from '@prisma/generator-helper'
-import { ImportStyle } from '../utils/resolveImportStyle'
+import type { DMMF } from '@prisma/generator-helper'
+import type { ImportStyle } from '../utils/resolveImportStyle'
 import { importExt } from '../utils/importExt'
 import { OPERATION_METADATA } from '../copy/operationDefinitions'
 
@@ -11,31 +11,53 @@ export interface UnifiedHandlerOptions {
 export function generateUnifiedHandler(options: UnifiedHandlerOptions): string {
   const ext = importExt(options.importStyle)
   const modelName = options.model.name
-
   const dispatchOps = OPERATION_METADATA.filter((m) => m.name !== 'updateEach')
 
-  const handlers = dispatchOps.map((meta) => {
-    const exportName = `${modelName}${meta.name.charAt(0).toUpperCase() + meta.name.slice(1)}`
+  const handlers = dispatchOps
+    .map((meta) => {
+      const exportName = `${modelName}${meta.name.charAt(0).toUpperCase() + meta.name.slice(1)}`
 
-    return `
+      return `
 export async function ${exportName}(
   req: Request,
   res: Response,
   next: NextFunction,
 ) {
   try {
-    ;(res.locals as LocalsBag).data = await core.${meta.coreName}(buildContext(req, res))
+    const locals = readLocals(res)
+    ;locals.data = await executeOperation(
+      { variantKey: locals.guardVariantKey, caller: locals.guardCaller },
+      { guardShape: locals.guardShape },
+      {
+        core: core.${meta.coreName},
+        args: queryChannel(res),
+        body: req.body,
+        prisma: requirePrisma((req as ExtendedRequest).prisma),
+        postgres: (req as ExtendedRequest).postgres,
+        sqlite: (req as ExtendedRequest).sqlite,
+        pagination: locals.routeConfig?.pagination,
+        override: locals.operationOverride,
+        getContext: locals.getContext,
+      },
+    )
     next()
   } catch (error: unknown) {
-    next(mapError(error))
+    next(classifyError(error))
   }
 }`
-  }).join('\n')
+    })
+    .join('\n')
 
   return `import type { Request, Response, NextFunction } from 'express'
 import * as core from './${modelName}Core${ext}'
-import { OperationContext } from '../operationRuntime${ext}'
-import { mapError } from '../errorMapper${ext}'
+import type { RuntimeOperationOverride } from '../operationRuntime${ext}'
+import type { PaginationConfig } from '../routeConfig${ext}'
+import {
+  executeOperation,
+  classifyError,
+  requirePrisma,
+  type ArgsChannel,
+} from '../operationPipeline${ext}'
 
 type ExtendedRequest = Request & {
   prisma?: unknown
@@ -45,26 +67,27 @@ type ExtendedRequest = Request & {
 
 type LocalsBag = {
   parsedQuery?: Record<string, unknown>
-  routeConfig?: { pagination?: unknown }
+  routeConfig?: { pagination?: PaginationConfig }
   guardShape?: Record<string, unknown>
   guardCaller?: string
+  guardVariantKey?: string
+  operationOverride?: RuntimeOperationOverride
+  getContext?: () => Promise<unknown>
   data?: unknown
 }
 
-function buildContext(req: Request, res: Response): OperationContext {
-  const extReq = req as ExtendedRequest
-  const locals = res.locals as LocalsBag
+function readLocals(res: Response): LocalsBag {
+  return res.locals as LocalsBag
+}
+
+function queryChannel(res: Response): ArgsChannel {
   return {
-    prisma: extReq.prisma,
-    postgres: extReq.postgres,
-    sqlite: extReq.sqlite,
-    parsedQuery: locals.parsedQuery,
-    body: req.body,
-    guardShape: locals.guardShape,
-    guardCaller: locals.guardCaller,
-    paginationConfig: (locals.routeConfig?.pagination) as OperationContext['paginationConfig'],
+    read: () => readLocals(res).parsedQuery,
+    write: (next) => {
+      readLocals(res).parsedQuery = next
+    },
   }
 }
 ${handlers}
 `
-}
+}

package/src/generators/generateUnifiedScalarUI.ts

@@ -215,4 +215,4 @@ const MODEL_CONTEXT: DocsModelContext = {
 
 ${docsExport}
 `
-}
+}

package/src/guardOptions.ts

@@ -98,90 +98,94 @@ export type GuardOptionMetadata = {
  * them; declaring them on the shared base made Express and Fastify accept them in
  * TypeScript and ignore them at runtime, which is a false public API.
  */
-export const GUARD_OPTION_METADATA: readonly GuardOptionMetadata[] = Object.freeze([
-  {
-    name: 'requireGuardShape',
-    type: 'boolean',
-    default: UPSTREAM_GUARD_DEFAULTS.requireGuardShape,
-    hardened: HARDENED_GUARD_PROFILE.requireGuardShape,
-    label: 'Require a guard on every enabled operation',
-    description:
-      'Refuses at router construction when an operation defines neither "shape" nor "variants".',
-    warning:
-      "Off, an operation nobody configured passes the caller's own where/select/include straight to Prisma.",
-    target: 'hono',
-  },
-  {
-    name: 'validateGuardShapes',
-    type: 'boolean',
-    default: UPSTREAM_GUARD_DEFAULTS.validateGuardShapes,
-    hardened: HARDENED_GUARD_PROFILE.validateGuardShapes,
-    label: 'Validate guard shapes',
-    description:
-      'Refuses an empty shape, and one mixing guard keys with non-guard keys, at the top level and inside variants.',
-    warning:
-      'Off, "shape: {}" reads as guarded and constrains nothing. On, strict validation may reject existing route configs.',
-    target: 'hono',
-  },
-  {
-    name: 'requireDefaultVariantOptIn',
-    type: 'boolean',
-    default: UPSTREAM_GUARD_DEFAULTS.requireDefaultVariantOptIn,
-    hardened: HARDENED_GUARD_PROFILE.requireDefaultVariantOptIn,
-    label: 'Require confirmation for a "default" variant',
-    description:
-      'A variant named "default" must set allowDefaultVariant: true to be accepted.',
-    warning: 'A "default" variant answers every unrecognised, blank and missing caller.',
-    target: 'hono',
-  },
-  {
-    name: 'enableUpdateEach',
-    type: 'boolean',
-    default: UPSTREAM_GUARD_DEFAULTS.enableUpdateEach,
-    hardened: HARDENED_GUARD_PROFILE.enableUpdateEach,
-    label: 'Register the updateEach batch route',
-    description: 'Mounts POST <base>/each. Set false to refuse it at router construction.',
-    warning:
-      'updateEach bypasses guard shapes entirely; only a development-only warning stands between it and an unguarded mass update.',
-    target: 'hono',
-  },
-  {
-    name: 'guardResolutionOrder',
-    type: 'enum',
-    values: Object.freeze(['after-hooks', 'before-hooks']),
-    default: UPSTREAM_GUARD_DEFAULTS.guardResolutionOrder,
-    hardened: HARDENED_GUARD_PROFILE.guardResolutionOrder,
-    label: 'When guard failures are raised',
-    description:
-      'after-hooks is the upstream behaviour; before-hooks settles variant and shape resolution before any operation hook runs.',
-    warning:
-      'With after-hooks, a hook that returns a Response can answer a request whose guard was never established.',
-    target: 'hono',
-  },
-  {
-    name: 'allowE2EGuardBypass',
-    type: 'boolean',
-    default: UPSTREAM_GUARD_DEFAULTS.allowE2EGuardBypass,
-    hardened: HARDENED_GUARD_PROFILE.allowE2EGuardBypass,
-    label: 'Honour the E2E environment guard bypass',
-    description: 'Treats E2E=true in the environment as a request to drop the guard.',
-    warning:
-      'A runtime variable can weaken a deployed artifact after generation. On an edge runtime this is an ordinary config var.',
-    target: 'hono',
-  },
-  {
-    name: 'validateResolvedShapes',
-    type: 'boolean',
-    default: UPSTREAM_GUARD_DEFAULTS.validateResolvedShapes,
-    hardened: HARDENED_GUARD_PROFILE.validateResolvedShapes,
-    label: 'Validate what a shape function returns',
-    description:
-      'Checks a dynamically resolved shape before use and fails the request with 500 if it is unusable. Also resolves it exactly once.',
-    warning:
-      'Off, a shape function returning {} or undefined runs the operation unguarded, once per request.',
-    target: 'hono',
-  },
-])
+export const GUARD_OPTION_METADATA: readonly GuardOptionMetadata[] =
+  Object.freeze([
+    {
+      name: 'requireGuardShape',
+      type: 'boolean',
+      default: UPSTREAM_GUARD_DEFAULTS.requireGuardShape,
+      hardened: HARDENED_GUARD_PROFILE.requireGuardShape,
+      label: 'Require a guard on every enabled operation',
+      description:
+        'Refuses at router construction when an operation defines neither "shape" nor "variants".',
+      warning:
+        "Off, an operation nobody configured passes the caller's own where/select/include straight to Prisma.",
+      target: 'hono',
+    },
+    {
+      name: 'validateGuardShapes',
+      type: 'boolean',
+      default: UPSTREAM_GUARD_DEFAULTS.validateGuardShapes,
+      hardened: HARDENED_GUARD_PROFILE.validateGuardShapes,
+      label: 'Validate guard shapes',
+      description:
+        'Refuses an empty shape, and one mixing guard keys with non-guard keys, at the top level and inside variants.',
+      warning:
+        'Off, "shape: {}" reads as guarded and constrains nothing. On, strict validation may reject existing route configs.',
+      target: 'hono',
+    },
+    {
+      name: 'requireDefaultVariantOptIn',
+      type: 'boolean',
+      default: UPSTREAM_GUARD_DEFAULTS.requireDefaultVariantOptIn,
+      hardened: HARDENED_GUARD_PROFILE.requireDefaultVariantOptIn,
+      label: 'Require confirmation for a "default" variant',
+      description:
+        'A variant named "default" must set allowDefaultVariant: true to be accepted.',
+      warning:
+        'A "default" variant answers every unrecognised, blank and missing caller.',
+      target: 'hono',
+    },
+    {
+      name: 'enableUpdateEach',
+      type: 'boolean',
+      default: UPSTREAM_GUARD_DEFAULTS.enableUpdateEach,
+      hardened: HARDENED_GUARD_PROFILE.enableUpdateEach,
+      label: 'Register the updateEach batch route',
+      description:
+        'Mounts POST <base>/each. Set false to refuse it at router construction.',
+      warning:
+        'updateEach bypasses guard shapes entirely; only a development-only warning stands between it and an unguarded mass update.',
+      target: 'hono',
+    },
+    {
+      name: 'guardResolutionOrder',
+      type: 'enum',
+      values: Object.freeze(['after-hooks', 'before-hooks']),
+      default: UPSTREAM_GUARD_DEFAULTS.guardResolutionOrder,
+      hardened: HARDENED_GUARD_PROFILE.guardResolutionOrder,
+      label: 'When guard failures are raised',
+      description:
+        'after-hooks is the upstream behaviour; before-hooks settles variant and shape resolution before any operation hook runs.',
+      warning:
+        'With after-hooks, a hook that returns a Response can answer a request whose guard was never established.',
+      target: 'hono',
+    },
+    {
+      name: 'allowE2EGuardBypass',
+      type: 'boolean',
+      default: UPSTREAM_GUARD_DEFAULTS.allowE2EGuardBypass,
+      hardened: HARDENED_GUARD_PROFILE.allowE2EGuardBypass,
+      label: 'Honour the PGE_DROP_GUARD environment guard bypass',
+      description:
+        'Treats PGE_DROP_GUARD=true in the environment as a request to drop the guard. Deprecated alias: E2E=true.',
+      warning:
+        'A runtime variable can weaken a deployed artifact after generation. On an edge runtime this is an ordinary config var.',
+      target: 'hono',
+    },
+    {
+      name: 'validateResolvedShapes',
+      type: 'boolean',
+      default: UPSTREAM_GUARD_DEFAULTS.validateResolvedShapes,
+      hardened: HARDENED_GUARD_PROFILE.validateResolvedShapes,
+      label: 'Validate what a shape function returns',
+      description:
+        'Checks a dynamically resolved shape before use and fails the request with 500 if it is unusable. Also resolves it exactly once.',
+      warning:
+        'Off, a shape function returning {} or undefined runs the operation unguarded, once per request.',
+      target: 'hono',
+    },
+  ])
 
 /**
  * What this metadata does NOT cover.
@@ -208,19 +212,28 @@ export const GUARD_METADATA_SCOPE = Object.freeze({
 })
 
 /** Fill in the defaults. Absent means upstream, never an opinion. */
-export function resolveGuardPolicy(config: Partial<GuardPolicy> | undefined): GuardPolicy {
+export function resolveGuardPolicy(
+  config: Partial<GuardPolicy> | undefined,
+): GuardPolicy {
   return {
-    requireGuardShape: config?.requireGuardShape ?? UPSTREAM_GUARD_DEFAULTS.requireGuardShape,
+    requireGuardShape:
+      config?.requireGuardShape ?? UPSTREAM_GUARD_DEFAULTS.requireGuardShape,
     validateGuardShapes:
-      config?.validateGuardShapes ?? UPSTREAM_GUARD_DEFAULTS.validateGuardShapes,
+      config?.validateGuardShapes ??
+      UPSTREAM_GUARD_DEFAULTS.validateGuardShapes,
     requireDefaultVariantOptIn:
-      config?.requireDefaultVariantOptIn ?? UPSTREAM_GUARD_DEFAULTS.requireDefaultVariantOptIn,
-    enableUpdateEach: config?.enableUpdateEach ?? UPSTREAM_GUARD_DEFAULTS.enableUpdateEach,
+      config?.requireDefaultVariantOptIn ??
+      UPSTREAM_GUARD_DEFAULTS.requireDefaultVariantOptIn,
+    enableUpdateEach:
+      config?.enableUpdateEach ?? UPSTREAM_GUARD_DEFAULTS.enableUpdateEach,
     guardResolutionOrder:
-      config?.guardResolutionOrder ?? UPSTREAM_GUARD_DEFAULTS.guardResolutionOrder,
+      config?.guardResolutionOrder ??
+      UPSTREAM_GUARD_DEFAULTS.guardResolutionOrder,
     allowE2EGuardBypass:
-      config?.allowE2EGuardBypass ?? UPSTREAM_GUARD_DEFAULTS.allowE2EGuardBypass,
+      config?.allowE2EGuardBypass ??
+      UPSTREAM_GUARD_DEFAULTS.allowE2EGuardBypass,
     validateResolvedShapes:
-      config?.validateResolvedShapes ?? UPSTREAM_GUARD_DEFAULTS.validateResolvedShapes,
+      config?.validateResolvedShapes ??
+      UPSTREAM_GUARD_DEFAULTS.validateResolvedShapes,
   }
 }