@owlmeans/viable-common 0.0.44 → 0.0.46

package/src/integrity/verify.ts

@@ -1,219 +1,215 @@
 import { IntegrityRule, TARGET_FORBIDDEN_SCRIPTS, TARGET_SLUG_PATTERN } from './consts.js'
-import { detectTargetLayout, targetManifest, targetPackageName, targetRequiredDeps } from './utils.js'
+import { targetLayoutHelper } from './layout.js'
 import type { IntegrityViolation, TargetFileMap, TargetIntegrityReport } from './types.js'
-
-/**
- * Decide whether a tree is the generated application, from its files alone.
- *
- * Pure and IO-free on purpose. The publisher reads the sandbox and calls this; a test reads
- * the template and calls this; both then agree by construction. It is also why the check is
- * cheap enough to sit in front of every spawn rather than only at the moments someone
- * remembered to guard.
- *
- * The tree picks the manifest it is verified against. A slot holds the layout it was
- * initialized with for the life of the project and nothing migrates it, so asserting the
- * current layout unconditionally does not make the check stricter — it aims it at a tree that
- * was never there, and every legacy slot answers with one `missing` violation per file it was
- * never supposed to have. That refuses the application the platform itself generated.
- *
- * Every rule collects rather than short-circuits: a tree that fails is usually a person's
- * repository, and telling them one thing at a time turns a fix into a dozen round trips
- * through a pull that reverts itself each time.
- */
-export const verifyTargetShape = (files: TargetFileMap): TargetIntegrityReport => {
-  const violations: IntegrityViolation[] = []
-  const layout = detectTargetLayout(files)
-  const manifest = targetManifest(layout)
-
-  // Only this layout's files. The caller reads the union of every layout's list so that the
-  // probes are in hand before the layout is known — reporting the other layout's paths as
-  // missing would refuse both trees at once.
-  for (const path of manifest.files) {
-    if (files[path] == null) {
-      violations.push({
-        path, rule: IntegrityRule.Missing,
-        detail: `${path} is missing — a Viable project always has it.`
-      })
+import type { TargetIntegrityHelper } from './verify/types.js'
+
+export const createTargetIntegrityHelper = (): TargetIntegrityHelper => {
+  const verifyTargetShape = (files: TargetFileMap): TargetIntegrityReport => {
+    const violations: IntegrityViolation[] = []
+    const layout = targetLayoutHelper.detectTargetLayout(files)
+    const manifest = targetLayoutHelper.targetManifest(layout)
+
+    // Only this layout's files. The caller reads the union of every layout's list so that the
+    // probes are in hand before the layout is known — reporting the other layout's paths as
+    // missing would refuse both trees at once.
+    for (const path of manifest.files) {
+      if (files[path] == null) {
+        violations.push({
+          path, rule: IntegrityRule.Missing,
+          detail: `${path} is missing — a Viable project always has it.`
+        })
+      }
     }
-  }
-
-  // The slug is read once, from the root, and every package name is checked against it. A
-  // project the user renamed is still the project; a package that does not carry the root's
-  // name is a different tree wearing the workspace layout.
-  const slug = checkRoot()
-  checkInstallConfig()
-  for (const pkg of manifest.packages) {
-    checkPackage(pkg, slug)
-  }
-  checkMarkers()
 
-  return { ok: violations.length === 0, violations, layout }
+    // The slug is read once, from the root, and every package name is checked against it. A
+    // project the user renamed is still the project; a package that does not carry the root's
+    // name is a different tree wearing the workspace layout.
+    const slug = checkRoot()
+    checkInstallConfig()
+    for (const pkg of manifest.packages) {
+      checkPackage(pkg, slug)
+    }
+    checkMarkers()
 
-  function checkRoot(): string | null {
-    const found = readJson('package.json')
-    if (found == null) return null
+    return { ok: violations.length === 0, violations, layout }
 
-    const name = typeof found.name === 'string' ? found.name : ''
-    if (!TARGET_SLUG_PATTERN.test(name)) {
-      violations.push({
-        path: 'package.json', rule: IntegrityRule.PackageName,
-        detail: `The root package name "${String(found.name)}" is not a project slug`
-          + ` — lowercase letters, digits and inner hyphens, up to 32 characters.`
-      })
-    }
-    if (found.type !== 'module') {
-      violations.push({
-        path: 'package.json', rule: IntegrityRule.ModuleType,
-        detail: 'The root package must declare "type": "module".'
-      })
-    }
+    function checkRoot(): string | null {
+      const found = readJson('package.json')
+      if (found == null) return null
 
-    // The workspace list is what makes the packages resolve to each other. Both spellings are
-    // the same tree: the glob `create-app` emits, or the entries written out.
-    const declared = Array.isArray(found.workspaces) ? found.workspaces as string[] : []
-    const isGlob = declared.length === 1 && declared[0] === manifest.workspaceGlob
-    const isExplicit = declared.length === manifest.workspaceEntries.length
-      && manifest.workspaceEntries.every(entry => declared.includes(entry))
-    if (!isGlob && !isExplicit) {
-      violations.push({
-        path: 'package.json', rule: IntegrityRule.Workspaces,
-        detail: `The root package must declare the workspaces as ["${manifest.workspaceGlob}"]`
-          + ` or as exactly ${manifest.workspaceEntries.join(', ')}.`
-      })
-    }
+      const name = typeof found.name === 'string' ? found.name : ''
+      if (!TARGET_SLUG_PATTERN.test(name)) {
+        violations.push({
+          path: 'package.json', rule: IntegrityRule.PackageName,
+          detail: `The root package name "${String(found.name)}" is not a project slug`
+            + ` — lowercase letters, digits and inner hyphens, up to 32 characters.`
+        })
+      }
+      if (found.type !== 'module') {
+        violations.push({
+          path: 'package.json', rule: IntegrityRule.ModuleType,
+          detail: 'The root package must declare "type": "module".'
+        })
+      }
 
-    checkScripts('package.json', found)
+      // The workspace list is what makes the packages resolve to each other. Both spellings are
+      // the same tree: the glob `create-app` emits, or the entries written out.
+      const declared = Array.isArray(found.workspaces) ? found.workspaces as string[] : []
+      const isGlob = declared.length === 1 && declared[0] === manifest.workspaceGlob
+      const isExplicit = declared.length === manifest.workspaceEntries.length
+        && manifest.workspaceEntries.every(entry => declared.includes(entry))
+      if (!isGlob && !isExplicit) {
+        violations.push({
+          path: 'package.json', rule: IntegrityRule.Workspaces,
+          detail: `The root package must declare the workspaces as ["${manifest.workspaceGlob}"]`
+            + ` or as exactly ${manifest.workspaceEntries.join(', ')}.`
+        })
+      }
 
-    return TARGET_SLUG_PATTERN.test(name) ? name : null
-  }
+      checkScripts('package.json', found)
 
-  /**
-   * `bunfig.toml` decides where `bun install` fetches from and how it links.
-   *
-   * A registry line pointed elsewhere makes every dependency in the tree arbitrary code
-   * regardless of how well-formed the manifests are, so it is checked as a shape rather than
-   * a marker: nothing but the hoisted-linker install block belongs in it.
-   */
-  function checkInstallConfig(): void {
-    const content = files['bunfig.toml']
-    if (content == null) return
-
-    const offending = content.split('\n')
-      .map(line => line.trim())
-      .filter(line => line.length > 0 && !line.startsWith('#'))
-      .filter(line => !/^\[install\]$/.test(line) && !/^linker\s*=/.test(line))
-
-    if (offending.length > 0) {
-      violations.push({
-        path: 'bunfig.toml', rule: IntegrityRule.InstallConfig,
-        detail: 'bunfig.toml may only declare the hoisted install linker.'
-      })
+      return TARGET_SLUG_PATTERN.test(name) ? name : null
     }
-  }
 
-  function checkPackage(pkg: string, slug: string | null): void {
-    const path = `${manifest.dir}/${pkg}/package.json`
-    const found = readJson(path)
-    if (found == null) return
-
-    // With no readable slug the name and the workspace dependencies have nothing to be checked
-    // against; the root violation already says why, and repeating it per package is noise.
-    if (slug != null) {
-      const expected = targetPackageName(slug, pkg)
-      if (found.name !== expected) {
+    /**
+     * `bunfig.toml` decides where `bun install` fetches from and how it links.
+     *
+     * A registry line pointed elsewhere makes every dependency in the tree arbitrary code
+     * regardless of how well-formed the manifests are, so it is checked as a shape rather than
+     * a marker: nothing but the hoisted-linker install block belongs in it.
+     */
+    function checkInstallConfig(): void {
+      const content = files['bunfig.toml']
+      if (content == null) return
+
+      const offending = content.split('\n')
+        .map(line => line.trim())
+        .filter(line => line.length > 0 && !line.startsWith('#'))
+        .filter(line => !/^\[install\]$/.test(line) && !/^linker\s*=/.test(line))
+
+      if (offending.length > 0) {
         violations.push({
-          path, rule: IntegrityRule.PackageName,
-          detail: `Package must be named "${expected}", not "${String(found.name)}".`
+          path: 'bunfig.toml', rule: IntegrityRule.InstallConfig,
+          detail: 'bunfig.toml may only declare the hoisted install linker.'
         })
       }
     }
-    if (found.type !== 'module') {
-      violations.push({
-        path, rule: IntegrityRule.ModuleType,
-        detail: `Package "${pkg}" must declare "type": "module".`
-      })
-    }
-
-    const scripts = asRecord(found.scripts)
-    if (scripts.build !== manifest.buildScripts[pkg]) {
-      // The one the platform actually spawns.
-      violations.push({
-        path, rule: IntegrityRule.BuildScript,
-        detail: `The build script of "${pkg}" must be exactly \`${manifest.buildScripts[pkg]}\`.`
-      })
-    }
-    checkScripts(path, found)
 
-    if (slug == null) return
-
-    const deps = { ...asRecord(found.dependencies), ...asRecord(found.devDependencies) }
-    for (const dep of targetRequiredDeps(slug, pkg, layout)) {
-      if (deps[dep] == null) {
+    function checkPackage(pkg: string, slug: string | null): void {
+      const path = `${manifest.dir}/${pkg}/package.json`
+      const found = readJson(path)
+      if (found == null) return
+
+      // With no readable slug the name and the workspace dependencies have nothing to be checked
+      // against; the root violation already says why, and repeating it per package is noise.
+      if (slug != null) {
+        const expected = targetLayoutHelper.targetPackageName(slug, pkg)
+        if (found.name !== expected) {
+          violations.push({
+            path, rule: IntegrityRule.PackageName,
+            detail: `Package must be named "${expected}", not "${String(found.name)}".`
+          })
+        }
+      }
+      if (found.type !== 'module') {
         violations.push({
-          path, rule: IntegrityRule.RequiredDependency,
-          detail: `Package "${pkg}" must depend on ${dep}.`
+          path, rule: IntegrityRule.ModuleType,
+          detail: `Package "${pkg}" must declare "type": "module".`
         })
       }
-    }
-  }
 
-  /** Lifecycle hooks run on `bun install`, before anything else has a chance to refuse. */
-  function checkScripts(path: string, found: Record<string, unknown>): void {
-    const scripts = asRecord(found.scripts)
-    for (const hook of TARGET_FORBIDDEN_SCRIPTS) {
-      if (scripts[hook] != null) {
+      const scripts = asRecord(found.scripts)
+      if (scripts.build !== manifest.buildScripts[pkg]) {
+        // The one the platform actually spawns.
         violations.push({
-          path, rule: IntegrityRule.LifecycleScript,
-          detail: `Lifecycle script "${hook}" is not allowed in a target project.`
+          path, rule: IntegrityRule.BuildScript,
+          detail: `The build script of "${pkg}" must be exactly \`${manifest.buildScripts[pkg]}\`.`
         })
       }
+      checkScripts(path, found)
+
+      if (slug == null) return
+
+      const deps = { ...asRecord(found.dependencies), ...asRecord(found.devDependencies) }
+      for (const dep of targetLayoutHelper.targetRequiredDeps(slug, pkg, layout)) {
+        if (deps[dep] == null) {
+          violations.push({
+            path, rule: IntegrityRule.RequiredDependency,
+            detail: `Package "${pkg}" must depend on ${dep}.`
+          })
+        }
+      }
     }
-  }
 
-  function checkMarkers(): void {
-    for (const [path, markers] of Object.entries(manifest.markers)) {
-      const content = files[path]
-      if (content == null) continue
+    /** Lifecycle hooks run on `bun install`, before anything else has a chance to refuse. */
+    function checkScripts(path: string, found: Record<string, unknown>): void {
+      const scripts = asRecord(found.scripts)
+      for (const hook of TARGET_FORBIDDEN_SCRIPTS) {
+        if (scripts[hook] != null) {
+          violations.push({
+            path, rule: IntegrityRule.LifecycleScript,
+            detail: `Lifecycle script "${hook}" is not allowed in a target project.`
+          })
+        }
+      }
+    }
 
-      const absent = markers.filter(marker => !content.includes(marker))
-      if (absent.length > 0) {
-        violations.push({
-          path, rule: IntegrityRule.EntryMarker,
-          detail: `${path} does not look like the generated app's entry: ${absent.join(', ')} not found.`
-        })
+    function checkMarkers(): void {
+      for (const [path, markers] of Object.entries(manifest.markers)) {
+        const content = files[path]
+        if (content == null) continue
+
+        const absent = markers.filter(marker => !content.includes(marker))
+        if (absent.length > 0) {
+          violations.push({
+            path, rule: IntegrityRule.EntryMarker,
+            detail: `${path} does not look like the generated app's entry: ${absent.join(', ')} not found.`
+          })
+        }
       }
     }
-  }
 
-  function readJson(path: string): Record<string, unknown> | null {
-    const content = files[path]
-    if (content == null) return null
-    try {
-      const parsed: unknown = JSON.parse(content)
-
-      return typeof parsed === 'object' && parsed !== null
-        ? parsed as Record<string, unknown>
-        : reportUnreadable(path)
-    } catch {
-      return reportUnreadable(path)
+    function readJson(path: string): Record<string, unknown> | null {
+      const content = files[path]
+      if (content == null) return null
+      try {
+        const parsed: unknown = JSON.parse(content)
+
+        return typeof parsed === 'object' && parsed !== null
+          ? parsed as Record<string, unknown>
+          : reportUnreadable(path)
+      } catch {
+        return reportUnreadable(path)
+      }
     }
-  }
 
-  function reportUnreadable(path: string): null {
-    violations.push({
-      path, rule: IntegrityRule.Unreadable, detail: `${path} is not a readable JSON object.`
-    })
+    function reportUnreadable(path: string): null {
+      violations.push({
+        path, rule: IntegrityRule.Unreadable, detail: `${path} is not a readable JSON object.`
+      })
+
+      return null
+    }
 
-    return null
+    function asRecord(value: unknown): Record<string, string> {
+      return typeof value === 'object' && value !== null
+        ? value as Record<string, string>
+        : {}
+    }
   }
 
-  function asRecord(value: unknown): Record<string, string> {
-    return typeof value === 'object' && value !== null
-      ? value as Record<string, string>
-      : {}
-  }
+  const formatIntegrityReport = (report: TargetIntegrityReport): string =>
+    report.violations.map(violation => `${violation.path}: ${violation.detail}`).join('\n')
+
+  return { verifyTargetShape, formatIntegrityReport }
 }
 
-/** One line per violation — what goes into a log, `slot.lastError`, or a build diagnostic. */
+export const targetIntegrityHelper = createTargetIntegrityHelper()
+
+/** @deprecated compat:factory-refactor — use `targetIntegrityHelper.verifyTargetShape(…)` */
+export const verifyTargetShape = (files: TargetFileMap): TargetIntegrityReport =>
+  targetIntegrityHelper.verifyTargetShape(files)
+
+/** @deprecated compat:factory-refactor — use `targetIntegrityHelper.formatIntegrityReport(…)` */
 export const formatIntegrityReport = (report: TargetIntegrityReport): string =>
-  report.violations.map(violation => `${violation.path}: ${violation.detail}`).join('\n')
+  targetIntegrityHelper.formatIntegrityReport(report)

package/src/intent/consts.ts

@@ -12,6 +12,10 @@
  * read the same declarations, and none of them may reinvent a name the others parse.
  */
 
+import { DISPATCHER } from '@owlmeans/auth'
+import { HOME } from '@owlmeans/context'
+import type { ShallowFlow } from '@owlmeans/flow'
+
 /** Every address of the hand-off. API routes are guest routes; the landing is a screen. */
 export const intent = Object.freeze({
   base: 'viable:manager-api:intent:base',
@@ -64,3 +68,66 @@ export enum IntentFlowStep {
   /** The platform's home screen, where the draft is offered back. */
   Review = 'review',
 }
+
+const payloadMap = { [INTENT_PAYLOAD_REF]: 0 }
+
+/**
+ * The hand-off flow both sides walk.
+ *
+ * `compose` runs on the public site: the prompt is stashed and `handoff` carries the reference to
+ * `land`, whose module is the platform's landing screen — so the site redirects to
+ * `land`'s address with the payload as query. The landing then enters at `land` FRESH (the
+ * reference arrives as `?ref=`, never as a serialized token, which the platform's own sign-in
+ * parses from `?flow=` on every page), and either goes on to `review` (signed in) or parks the flow
+ * with `suspendFlow` at `sign-in`, whose non-explicit way forward is `review` — the home screen —
+ * so whichever sign-in method finishes lands there.
+ *
+ * The steps address CONCRETE entrypoint aliases, never `$`-prefixed references: this flow is never
+ * the live `FlowService` model and nothing here needs `configureFlows`.
+ */
+export const intentFlow: ShallowFlow = {
+  flow: INTENT_FLOW,
+  initialStep: IntentFlowStep.Compose,
+  steps: {
+    [IntentFlowStep.Compose]: {
+      index: 0,
+      step: IntentFlowStep.Compose,
+      service: '',
+      initial: true,
+      payloadMap,
+      transitions: {
+        handoff: { transition: 'handoff', step: IntentFlowStep.Land },
+      },
+    },
+    [IntentFlowStep.Land]: {
+      index: 1,
+      step: IntentFlowStep.Land,
+      service: '',
+      module: intent.landing,
+      initial: true,
+      payloadMap,
+      transitions: {
+        review: { transition: 'review', step: IntentFlowStep.Review },
+        'sign-in': { transition: 'sign-in', step: IntentFlowStep.SignIn, explicit: true },
+      },
+    },
+    [IntentFlowStep.SignIn]: {
+      index: 2,
+      step: IntentFlowStep.SignIn,
+      service: '',
+      module: DISPATCHER,
+      payloadMap,
+      transitions: {
+        next: { transition: 'next', step: IntentFlowStep.Review },
+      },
+    },
+    [IntentFlowStep.Review]: {
+      index: 3,
+      step: IntentFlowStep.Review,
+      service: '',
+      module: HOME,
+      payloadMap,
+      transitions: {},
+    },
+  },
+}

package/src/intent/entrypoints.ts

@@ -3,7 +3,7 @@ import { frontend, route, RouteMethod } from '@owlmeans/route'
 import { INTENT_API_PATH, INTENT_LANDING_PATH, intent } from './consts.js'
 import { IntentPickupBodySchema, IntentStashBodySchema } from './schemas.js'
 import type {
-  IntentPickupBody, IntentPickupResult, IntentProtocolOptions, IntentStashBody, IntentStashResult,
+  IntentPickupBody, IntentPickupResult, IntentProtocolOptions, IntentProtocols, IntentStashBody, IntentStashResult,
 } from './types.js'
 
 /**
@@ -20,7 +20,7 @@ import type {
  * The landing screen is `sticky`, like the OAuth consent screens: it is an ordinary in-app screen
  * that a visitor arrives at directly from another origin.
  */
-export const makeIntentProtocols = (opts: IntentProtocolOptions = {}) => {
+export const makeIntentProtocols = (opts: IntentProtocolOptions = {}): IntentProtocols => {
   const base = openProtocol(route(intent.base, opts.path ?? INTENT_API_PATH))
 
   return {

package/src/intent/index.ts

@@ -2,5 +2,4 @@ export * from './consts.js'
 export * from './schemas.js'
 export * from './errors.js'
 export * from './entrypoints.js'
-export * from './flow.js'
 export type * from './types.js'

package/src/intent/types.ts

@@ -1,5 +1,5 @@
+import type { EntrypointProtocol, OpenRequest, OpenValue } from '@owlmeans/entrypoint'
 import type { ResourceRecord } from '@owlmeans/resource'
-import { makeIntentProtocols } from './entrypoints.js'
 
 /** What the public site sends: the prompt and the person's confirmation of its processing. */
 export interface IntentStashBody {
@@ -45,4 +45,11 @@ export interface IntentProtocolOptions {
   landing?: string
 }
 
-export type IntentProtocols = ReturnType<typeof makeIntentProtocols>
+/** The intent-first hand-off tree {@link makeIntentProtocols} declares. */
+export interface IntentProtocols {
+  base: EntrypointProtocol<OpenRequest, OpenValue>
+  stash: EntrypointProtocol<{ body: IntentStashBody }, IntentStashResult>
+  pickup: EntrypointProtocol<{ body: IntentPickupBody }, IntentPickupResult>
+  /** The landing screen — `sticky`, an in-app screen a visitor reaches from another origin. */
+  landing: EntrypointProtocol<OpenRequest, OpenValue>
+}

package/src/legal/consts.ts

@@ -0,0 +1,17 @@
+import type { LegalDocumentDates, LegalDocumentKey } from './types.js'
+
+/**
+ * The shared dates for the platform's legal acceptance and the public site's legal pages.
+ * Changing terms/privacy/billing/product updated dates requires renewed terms acceptance;
+ * privacy.updated also revises marketing consent. The other documents are display-only.
+ */
+export const OWLMEANS_LEGAL_DATES = {
+  terms: { effective: '2026-05-30', updated: '2026-05-30' },
+  privacy: { effective: '2026-05-30', updated: '2026-05-30' },
+  cookies: { effective: '2026-09-24', updated: '2026-09-25' },
+  'services-agreement': { effective: '2026-10-04', updated: '2026-10-04' },
+  'platform-license': { effective: '2026-10-04', updated: '2026-10-04' },
+  // These documents date the platform's sign-in terms line without public-site pages yet.
+  billing: { effective: '2026-05-30', updated: '2026-05-30' },
+  product: { effective: '2026-05-30', updated: '2026-05-30' },
+} as const satisfies Record<LegalDocumentKey, LegalDocumentDates>

package/src/legal/index.ts

@@ -0,0 +1,2 @@
+export * from './consts.js'
+export type * from './types.js'

package/src/legal/types.ts

@@ -0,0 +1,11 @@
+/** ISO YYYY-MM-DD dates, formatted for the reader's locale by the consumer. */
+export interface LegalDocumentDates {
+  /** The day this version of the document takes effect. */
+  effective: string
+  /** The day this version of the document was last edited. */
+  updated: string
+}
+
+/** The complete document set; the date table must cover every key. */
+// Kept as a type: a union of the document keys.
+export type LegalDocumentKey = 'terms' | 'privacy' | 'cookies' | 'services-agreement' | 'platform-license' | 'billing' | 'product'

package/src/moderation/index.ts

@@ -1,4 +1,6 @@
 export * from './consts.js'
 export * from './schemas.js'
+export * from './verdict.js'
 export * from './utils.js'
 export type * from './types.js'
+export type * from './verdict/types.js'

package/src/moderation/utils.ts

@@ -1,35 +1,12 @@
-import { ModerationCategory } from './consts.js'
+import type { ModerationCategory } from './consts.js'
 import type { ModerationAction, ModerationPolicy, ModerationVerdict } from './types.js'
+import { moderationVerdictHelper } from './verdict.js'
 
-/**
- * Narrow whatever the model put in `category` to a real one, or to nothing.
- *
- * The wire field is a free string on purpose — see {@link ModerationVerdictSchema}. A model
- * that is allowing has nothing to categorise and still fills the field, so anything
- * unrecognized is treated as absent rather than as a failure.
- */
-export const normalizeCategory = (category?: string): ModerationCategory | undefined => {
-  const values = Object.values(ModerationCategory) as string[]
+/** @deprecated compat:factory-refactor — use `moderationVerdictHelper.normalizeCategory(…)` */
+export const normalizeCategory = (category?: string): ModerationCategory | undefined =>
+  moderationVerdictHelper.normalizeCategory(category)
 
-  return category != null && values.includes(category)
-    ? category as ModerationCategory
-    : undefined
-}
-
-/**
- * What to do about a verdict.
- *
- * Pure, because this is the part with the operational levers on it and the part most likely
- * to be wrong in a hurry: `enforce` turns the whole gate into an observer without a deploy,
- * and `bypassEntities` releases one entity when a real customer is wrongly refused.
- */
+/** @deprecated compat:factory-refactor — use `moderationVerdictHelper.decideModeration(…)` */
 export const decideModeration = (
   verdict: ModerationVerdict, policy: ModerationPolicy & { entityId?: string } = {}
-): ModerationAction => {
-  if (verdict.allowed) return 'allow'
-  if (policy.entityId != null && policy.bypassEntities?.includes(policy.entityId) === true) return 'allow'
-
-  // Defaults to ON: a gate that has to be switched on is a gate that is off in every
-  // environment nobody remembered to configure.
-  return policy.enforce !== false ? 'refuse' : 'shadow'
-}
+): ModerationAction => moderationVerdictHelper.decideModeration(verdict, policy)

package/src/moderation/verdict/types.ts

@@ -0,0 +1,22 @@
+import type { ModerationCategory } from '../consts.js'
+import type { ModerationAction, ModerationPolicy, ModerationVerdict } from '../types.js'
+
+/** Reading a moderation verdict: its category, and what to do about it. */
+export interface ModerationVerdictHelper {
+  /**
+   * Narrow whatever the model put in `category` to a real one, or to nothing.
+   *
+   * The wire field is a free string on purpose — see {@link ModerationVerdictSchema}. A model
+   * that is allowing has nothing to categorise and still fills the field, so anything
+   * unrecognized is treated as absent rather than as a failure.
+   */
+  normalizeCategory: (category?: string) => ModerationCategory | undefined
+  /**
+   * What to do about a verdict.
+   *
+   * Pure, because this is the part with the operational levers on it and the part most likely
+   * to be wrong in a hurry: `enforce` turns the whole gate into an observer without a deploy,
+   * and `bypassEntities` releases one entity when a real customer is wrongly refused.
+   */
+  decideModeration: (verdict: ModerationVerdict, policy?: ModerationPolicy & { entityId?: string }) => ModerationAction
+}