Skip to content

Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS

43.4 KB
Raw Blame
/**
 * Creative-production pipeline Zod schemas (split out of validation.js,
 * issue #1831).
 *
 * Covers the Writers Room (works, folders, live-mode, drafts, snapshots,
 * exercises, analyses), the story-bible character/place/object schemas (+ the
 * kind-neutral Pipeline re-exports), registry-driven editorial checks, storyboard
 * shot/scene shapes, the prompt-stage config, and the pipeline issue-list query.
 * validation.js re-exports everything here (flat) so existing deep imports keep
 * working; the barrel surfaces it as the `pipelineValidation` namespace.
 */
import { z } from 'zod';
import { partialWithoutDefaults } from './zodCompat.js';
import { WORK_KINDS, WORK_STATUSES, ANALYSIS_KINDS } from './writersRoomPresets.js';
import { ALL_STYLE_IDS, STYLE_ID } from './writersRoomStylePresets.js';
import {
  BIBLE_LIMITS, RELATIONSHIP_LINK_TYPES, RELATIONSHIP_OPPOSITION_AXES,
  ATTACHMENT_ROLES, VOICE_CANON_SOURCE_POLICIES, IDENTITY_ASSET_ROLES,
} from './storyBible.js';
import {
  CHARACTER_ARC_TYPES,
  CHARACTER_FRAMEWORK_LIMITS,
  CHARACTER_PSYCHOLOGY_LIMITS,
  CHARACTER_PSYCHOLOGY_TEXT_FIELDS,
  CHARACTER_SLIDER_AXES,
  PSYCHOLOGY_ASSESSMENTS,
  PSYCHOLOGY_DRIVE_AXES,
} from './characterFramework.js';
import { MIN_TIMEOUT as STAGE_TIMEOUT_MIN_MS, MAX_TIMEOUT as STAGE_TIMEOUT_MAX_MS } from './aiToolkit/constants.js';
import { EFFORT_LEVELS } from './providerModels.js';
import { CHECK_SCOPES, CHECK_SEVERITIES } from './editorial/checkInfra/taxonomy.js';
import { SHOT_TYPES, SCREEN_DIRECTIONS } from './shotGrammar.js';
import { characterEvolutionSchema } from './characterEvolutionValidation.js';

export const pipelineStageRecoverySchema = z.object({ revision: z.string().regex(/^[a-f0-9]{64}$/) });

// =============================================================================
// WRITERS ROOM SCHEMAS
// =============================================================================

export const writersRoomWorkKindSchema = z.enum(WORK_KINDS);
export const writersRoomWorkStatusSchema = z.enum(WORK_STATUSES);

// IDs are either null (unfiled / unattached) or a non-empty trimmed string.
// Zod runs chain steps in declared order, so .trim() MUST come before .min(1)
// — otherwise a whitespace-only string passes min(1), then trim() collapses
// it to '' after the guard already accepted it. Same gotcha applies to all
// the .min(1).trim() pairs below.
const wrIdNullable = z.string().trim().min(1).max(100).nullable();

export const writersRoomFolderCreateSchema = z.object({
  name: z.string().trim().min(1).max(200),
  parentId: wrIdNullable.optional(),
  sortOrder: z.number().int().optional()
}).strict();

export const writersRoomWorkCreateSchema = z.object({
  title: z.string().trim().min(1).max(300),
  kind: writersRoomWorkKindSchema.optional().default('short-story'),
  folderId: wrIdNullable.optional()
}).strict();

export const writersRoomImageStyleSchema = z.object({
  // 'none' (no style applied), 'custom' (user-authored prompt with no preset),
  // or one of the curated preset ids. The resolved prompt text lives on the
  // work — picking a preset later doesn't retroactively change historical
  // works' rendering.
  presetId: z.enum(ALL_STYLE_IDS).default(STYLE_ID.NONE),
  prompt: z.string().max(2000).default(''),
  negativePrompt: z.string().max(2000).default(''),
}).strict();

// Phase 5 live-mode opt-in (per work). `enabled` gates the editor's
// background continuation suggestions; `debounceMs` is the client's
// idle-after-typing throttle before it asks; `dailyCallBudget` caps how many
// suggest calls the server will run per UTC day (0 = unlimited);
// `dailyRenderBudget` is the distinct cap on live render previews (renders cost
// materially more than text, so they get their own knob). The server-tracked
// `usage` / `renderUsage` counters are NOT user-editable — they're bumped by
// the suggest / render-reserve paths and reset on a new day — so they live
// outside this update schema (mirrors how `pipelineSeriesId` is set by
// linkToPipeline, not updateWork).
export const writersRoomLiveModeSchema = z.object({
  enabled: z.boolean().default(false),
  debounceMs: z.number().int().min(800).max(30_000).default(2500),
  dailyCallBudget: z.number().int().min(0).max(10_000).default(100),
  dailyRenderBudget: z.number().int().min(0).max(10_000).default(20),
}).strict();

// Voice exemplar / anti-exemplar passages on a Writers Room work (#2179 Writers
// Room parity). Same shape + caps as the series style guide's voice fields
// (STYLE_GUIDE_LIMITS in styleGuide.js) — `passage` is the concrete prose
// anchor ("the tuning fork"), `note` a one-line gloss of what it demonstrates
// (exemplar) or what's wrong with it (anti-exemplar). `note` is optional; the
// service sanitizer (sanitizeVoiceExemplars) drops empty passages, trims to the
// caps, and caps the list at 3 — this wire gate just bounds the shape so a
// crafted PATCH can't ship an unbounded blob. An explicit `[]` clears the list.
const writersRoomVoiceExemplarSchema = z.object({
  passage: z.string().max(2000),
  note: z.string().max(200).optional(),
}).strict();
const writersRoomVoiceExemplarsSchema = z.array(writersRoomVoiceExemplarSchema).max(3);

export const writersRoomWorkUpdateSchema = z.object({
  title: z.string().trim().min(1).max(300).optional(),
  kind: writersRoomWorkKindSchema.optional(),
  status: writersRoomWorkStatusSchema.optional(),
  folderId: wrIdNullable.optional(),
  imageStyle: writersRoomImageStyleSchema.optional(),
  // partialWithoutDefaults (not .partial()) so a single-knob PATCH doesn't inject
  // the other knobs' defaults and clobber their stored values (Zod 4 .partial()
  // keeps inner defaults — see zodCompat.js). The service field-merges each knob.
  liveMode: partialWithoutDefaults(writersRoomLiveModeSchema).optional(),
  voiceExemplars: writersRoomVoiceExemplarsSchema.optional(),
  voiceAntiExemplars: writersRoomVoiceExemplarsSchema.optional(),
}).strict();

// Cursor-context payload for the live continuation suggest route. The three
// prose slices are bounded so a runaway editor can't ship a multi-MB body on
// every keystroke — the server only needs a window around the cursor, not the
// whole manuscript.
export const writersRoomLiveSuggestSchema = z.object({
  before: z.string().max(12_000).optional().default(''),
  after: z.string().max(12_000).optional().default(''),
  selection: z.string().max(8_000).optional().default(''),
}).strict();

// Live render-preview reservation takes no body — the work id is in the path
// and the budget is server-owned. A strict empty object rejects any crafted
// payload (e.g. an attempt to smuggle a usage counter) instead of ignoring it.
export const writersRoomLiveRenderPreviewSchema = z.object({}).strict();

// =============================================================================
// EDITORIAL CHECKS (#1284) — registry-driven editorial review
// =============================================================================
// Per-check enable/config. `config` is a free-form blob validated a second time
// against the check's own Zod `configSchema` in the registry (resolveCheckConfig)
// — this gate just bounds the wire shape so a malformed PATCH can't write junk.
export const editorialCheckConfigSchema = z.object({
  enabled: z.boolean().optional(),
  config: z.record(z.unknown()).optional(),
  // Optional per-check severity override (#1596). Absent falls through to the
  // check's registry `severityDefault`; an explicit `null` CLEARS a previously
  // stored override (so the catalog "Default" option resets to the registry
  // value rather than pinning a level). Bounded to the registry's own severity
  // enum so the wire gate can't drift from resolveCheckState.
  severity: z.enum([...CHECK_SEVERITIES]).nullable().optional(),
}).strict();

// POST .../editorial/checks/run — run all enabled checks, or a named subset.
// providerId/model are optional overrides forwarded to LLM-kind checks.
export const editorialChecksRunSchema = z.object({
  checkIds: z.array(z.string().trim().min(1).max(120)).max(50).optional(),
  providerId: z.string().trim().max(80).optional(),
  model: z.string().trim().max(200).optional(),
}).strict();

// User-defined editorial check (#1346). The base authored-field shapes carry NO
// `.default()` so the UPDATE schema (a `.partial()` of them) leaves an omitted
// field unchanged — a defaulted optional would silently RESET the stored value
// on a field-specific PATCH (Zod's `.partial()` keeps the inner `.default()`,
// which still fires when the key is absent). `scope`/`severityDefault` reuse the
// registry's own enums so the wire gate can't drift from `buildCustomCheck`.
const editorialCustomCheckShape = {
  label: z.string().trim().min(1).max(120),
  description: z.string().trim().max(500),
  prompt: z.string().trim().min(1).max(8_000),
  scope: z.enum([...CHECK_SCOPES]),
  category: z.string().trim().max(60),
  severityDefault: z.enum([...CHECK_SEVERITIES]),
};

// Create: label + prompt required; the rest optional with sensible defaults (so
// a new check is fully-formed). The JSON output contract is enforced server-side
// (buildCustomCheckPrompt), so no schema field captures it.
export const editorialCustomCheckCreateSchema = z.object({
  ...editorialCustomCheckShape,
  description: editorialCustomCheckShape.description.optional().default(''),
  scope: editorialCustomCheckShape.scope.optional().default('issue'),
  category: editorialCustomCheckShape.category.optional().default('custom'),
  severityDefault: editorialCustomCheckShape.severityDefault.optional().default('medium'),
}).strict();

// Edit (the id is in the URL): every field optional, NO defaults, so an omitted
// field is left unchanged rather than reset.
export const editorialCustomCheckUpdateSchema = z.object(editorialCustomCheckShape).partial().strict();

// Dry-run preview (#1607): run an UNSAVED draft check against a series and return
// sample findings without persisting. Same authored fields as create (so the
// draft synthesizes into a runnable check), plus an optional per-run cap and the
// provider/model overrides the run route accepts.
export const editorialCustomCheckPreviewSchema = z.object({
  ...editorialCustomCheckShape,
  description: editorialCustomCheckShape.description.optional().default(''),
  scope: editorialCustomCheckShape.scope.optional().default('issue'),
  category: editorialCustomCheckShape.category.optional().default('custom'),
  severityDefault: editorialCustomCheckShape.severityDefault.optional().default('medium'),
  maxFindings: z.number().int().min(1).max(50).optional(),
  providerId: z.string().trim().max(80).optional(),
  model: z.string().trim().max(200).optional(),
}).strict();

// settings.pipelineEditorialChecks slice (validated on PUT /api/settings when
// present). `checks` maps a checkId → its persisted enable/config; `customChecks`
// holds the user-defined check definitions (#1346).
//
// `customChecks` items are gated LENIENTLY (any object, unknown keys preserved):
// the authoring CRUD routes (editorialCustomCheck{Create,Update}Schema) are the
// strict input gate, while this wholesale-settings path must stay forward/older-
// peer compatible — a def carrying a future field (or a newer scope value) must
// not 400 an unrelated settings save. `buildCustomCheck`/`isValidCustomCheckDef`
// decide at read time which stored defs are actually runnable.
// `readinessGate` (#1316) is the editorial health convergence gate the autopilot
// loop + UI read as "manuscript clean": 'noOpenHigh' (default), the stricter
// 'noOpenHighOrMedium', or 'none' (disable). Optional + additive, so older peers
// and a never-configured install fall through to the service default.
// `maxArcVerifyRounds` / `maxEditorialRounds` bound the autopilot's verify→resolve
// convergence loops before it pauses for human review (0 = skip that gate
// entirely). Persisted defaults the autopilot reads when a run doesn't pass a
// per-run override; raised cap so a stubborn arc can be given more rounds. The
// cap is exported so the autopilot route schema (and any UI) share one ceiling
// instead of re-hardcoding it and drifting.
export const MAX_CONVERGENCE_ROUNDS = 20;
export const pipelineEditorialChecksSettingsSchema = z.object({
  checks: z.record(editorialCheckConfigSchema).optional(),
  customChecks: z.array(z.object({}).passthrough()).optional(),
  readinessGate: z.enum(['noOpenHigh', 'noOpenHighOrMedium', 'none']).optional(),
  maxArcVerifyRounds: z.number().int().min(0).max(MAX_CONVERGENCE_ROUNDS).optional(),
  maxEditorialRounds: z.number().int().min(0).max(MAX_CONVERGENCE_ROUNDS).optional(),
  // Whole-manuscript beat-continuity convergence (#1510) — same bound + 0-skip
  // semantics. Optional + additive so older peers fall through to the default.
  maxBeatContinuityRounds: z.number().int().min(0).max(MAX_CONVERGENCE_ROUNDS).optional(),
  // Foundation-quality gate (#2176, CWQE Phase 11). Before drafting, the
  // autopilot judges the whole foundation (world/characters/arc) against a
  // weighted rubric and iterates on the weakest dimension until it clears
  // `foundationThreshold` (a weighted [0,10] score), bounded by
  // `maxFoundationRounds` (0 = skip the gate). `foundationGate` toggles the gate
  // (defaults ON — the point of the phase). All three optional + additive so
  // older peers fall through to the defaults.
  foundationGate: z.boolean().optional(),
  foundationThreshold: z.number().min(0).max(10).optional(),
  maxFoundationRounds: z.number().int().min(0).max(MAX_CONVERGENCE_ROUNDS).optional(),
  // Editorial-checks pause threshold (#1613). When the registry-driven editorial
  // checks pass surfaces ≥ N high-severity findings, the autopilot pauses the run
  // for human review instead of silently proceeding (the downstream health gate is
  // a backstop, but the per-step signal was misleading — a 50-high-finding pass
  // looked "complete"). 0 = off (default), so the behavior is opt-in and existing
  // installs are unchanged. Optional + additive so older peers fall through to off.
  // No upper bound mirrors the round caps — a large N just means "effectively off".
  checkFindingsPauseThreshold: z.number().int().min(0).optional(),
  // Pause-notification escalation (#1615). When an autopilot run pauses, post an
  // in-app notification (reason + resume link) so a paused run isn't missed until
  // the user opens the status page. Defaults ON (true) when unset — a zero-cost
  // informational signal — so this is the one autopilot setting that's opt-OUT.
  // Optional + additive so older peers fall through to the default.
  notifyOnPause: z.boolean().optional(),
  // Autopilot → CD teaser deliverable (CDO Phase 3, #2185). When on, once a comic
  // issue is text-ready + drafted the autopilot OPTIONALLY mints + starts a
  // Creative Director teaser/trailer video project seeded from it. Defaults OFF
  // (opt-in) — producing video is a fresh burst of LLM + render spend. Optional +
  // additive so older peers fall through to off.
  produceTeaser: z.boolean().optional(),
  // Iterate-to-quality revision loop (CWQE Phase 7, #2171). When on, the autopilot
  // cycles the weakest drafted issue through adversarial cuts + a judge-gated
  // keep/revert after the editorial-health gate, stopping on plateau /
  // hedged-convergence / maxCycles. Defaults OFF (opt-in) — a fresh burst of judge
  // + cut LLM spend. `revisionMaxCycles` is the cost ceiling; `revisionMinCycles`
  // floors the plateau/hedge stops; `revisionPlateauDelta` is the mean-score
  // movement below which the series counts as converged. All optional + additive.
  revisionEnabled: z.boolean().optional(),
  revisionMinCycles: z.number().int().min(1).max(MAX_CONVERGENCE_ROUNDS).optional(),
  revisionMaxCycles: z.number().int().min(1).max(MAX_CONVERGENCE_ROUNDS).optional(),
  revisionPlateauDelta: z.number().min(0).max(10).optional(),
  // NOTE: the autopilot's `unlockForRun` option is deliberately NOT stored here.
  // Every knob in this slice is a spend/quality default that is harmless to
  // reuse unattended; unlocking rewrites protection state the user set by hand,
  // and `seriesAutopilotScheduler` reads this slice — so a saved default would
  // arm lock-clearing for every scheduled run of every series. It is a per-run
  // option only (see seriesAutopilot/config.js#resolveAutopilotUnlockForRun).
  // Pipeline self-improvement. When on, a run that ends badly (or finishes with
  // unhealthy telemetry) spends ONE extra LLM call diagnosing whether the
  // AUTOMATION is at fault — a missing editorial step earlier in the pipeline, a
  // prompt producing unusable output, a runner swallowing a failure — and files
  // a CoS task against PortOS itself to fix it. Defaults OFF (opt-in): it is
  // fresh LLM spend AND it queues work that changes PortOS's own code.
  // The filed task always awaits human approval, runs in a worktree and opens a
  // PR — that is not configurable, matching every other autonomously generated
  // code-editing task in PortOS. Optional + additive so older peers fall
  // through to off.
  selfImprove: z.boolean().optional(),
  // Observing orchestrator — the continuous, self-dispatching sibling of
  // selfImprove. When on, an autopilot run watches its own telemetry step by
  // step and dispatches AUTO-APPROVED PortOS fix tasks (worktree + PR + review
  // loop + merge, no human gate) as pipeline defects surface, so unattended
  // runs continuously harden the pipeline itself. Defaults OFF (opt-in): it is
  // fresh LLM spend AND standing consent for unattended changes to PortOS's own
  // code — enabling it is that consent (see seriesAutopilot/observer.js for the
  // structural guards: execute-mode only, budget-gated, pass-capped, raised
  // confidence bar, full PR review loop). Persistable deliberately, unlike
  // unlockForRun: a scheduled unattended run is exactly where the user wants
  // the pipeline improving itself. Optional + additive so older peers fall
  // through to off.
  observer: z.boolean().optional(),
  // Evidence-based Series Autopilot routing. Metrics are collected regardless;
  // this opt-in permits sufficiently sampled recommendations to become the
  // run's soft provider/model/effort defaults. Explicit run/stage pins win.
  autoSelectModels: z.boolean().optional(),
  // Series Autopilot: run the whole pipeline on ONE provider/model/effort by
  // ignoring the per-stage pins set on the Prompts page. Defaults OFF (opt-in),
  // and persistable unlike unlockForRun — it re-routes spend but mutates
  // nothing, and an unattended scheduled run is exactly where "always use my
  // one provider" belongs. Optional + additive so older peers fall through to
  // off. See seriesAutopilot/config.js#resolveAutopilotOverrideStagePins and
  // lib/stagePinPolicy.js.
  overrideStagePins: z.boolean().optional(),
}).strict();

// Cursor-context payload for the CD-bridge suggest route — identical shape to
// the live continuation suggest (the server only needs a window around the
// cursor, not the whole manuscript).
export const writersRoomCdBridgeSuggestSchema = z.object({
  before: z.string().max(12_000).optional().default(''),
  after: z.string().max(12_000).optional().default(''),
  selection: z.string().max(8_000).optional().default(''),
}).strict();

// The reviewed CD-bridge proposal the writer sends into a new Creative Director
// project. Caps align with creativeDirectorTreatmentSchema / creativeDirectorSceneSchema
// so a gate-passing proposal always validates again at setTreatment time. The
// scene shape here is the PROPOSAL subset (intent/prompt/duration); the service
// assigns sceneId/order/useContinuationFromPrior before calling setTreatment.
export const writersRoomCdBridgeSendSchema = z.object({
  proposal: z.object({
    logline: z.string().trim().min(1).max(500),
    synopsis: z.string().trim().min(1).max(5000),
    styleSpec: z.string().max(5000).optional().default(''),
    scenes: z.array(z.object({
      intent: z.string().trim().min(1).max(1000),
      prompt: z.string().trim().min(1).max(8000),
      durationSeconds: z.number().int().min(1).max(10),
    }).strict()).min(1).max(120),
  }).strict(),
}).strict();

export const writersRoomDraftSaveSchema = z.object({
  body: z.string().max(5_000_000), // 5 MB ceiling — well over a long novel in plain text
  // Catalog ingredient ids this draft version references. Optional: when
  // absent the server scans the prose against the work's linked cast and
  // derives the list itself; when present (e.g. a client that already knows
  // the set) it's trusted as the snapshot. Bounded so a malformed body can't
  // balloon the manifest.
  referencedIngredientIds: z.array(z.string().trim().min(1).max(128)).max(500).optional(),
}).strict();

export const writersRoomSnapshotSchema = z.object({
  label: z.string().trim().min(1).max(100).optional()
}).strict();

// A single storyboard shot within `stages.storyboards.scenes[].shots[]` (#1315).
// Validates the known shot fields and the new film-grammar enums (`shotType`,
// `screenDirection`) — each nullable + tolerant of the UI's "not captured"
// sentinel (null) and an empty-string clear (preprocessed to undefined). It is
// `.passthrough()` (NOT strip) because render-time hooks stamp extra fields onto
// a shot (`startFrameJobId`) that must survive a re-PATCH of the scenes array;
// the load-bearing normalization still happens in `sanitizeShot`
// (sceneExtractor.js) on the auto-extract path, but the route validates the
// enums up front so an invalid framing/direction is rejected, not silently kept.
export const storyboardShotSchema = z.object({
  // id / description are optional here (not at the sanitizer) so the route stays
  // as tolerant as `sanitizeShot`, which synthesizes a missing id and drops a
  // description-less shot — the route's job is only to reject a bad enum, not to
  // tighten the existing client contract.
  id: z.string().trim().max(80).optional(),
  // Bound loosely to the UI's textarea limit (maxLength=4000), NOT the
  // sanitizer's SHOT_DESCRIPTION_MAX (2000). The sanitizer truncates a long
  // description to 2000 downstream; the route must not REJECT one the UI lets a
  // user type (2001–4000) — that would turn the previously-passthrough scenes
  // contract into a 400. The route's job here is only to reject a bad enum.
  description: z.string().max(4000).optional(),
  durationSeconds: z.number().int().min(1).max(30).optional(),
  continuityFromShotId: z.string().trim().max(80).nullable().optional(),
  shotType: z.preprocess(
    (v) => (v === '' ? null : v),
    z.enum(SHOT_TYPES).nullable().optional(),
  ),
  screenDirection: z.preprocess(
    (v) => (v === '' ? null : v),
    z.enum(SCREEN_DIRECTIONS).nullable().optional(),
  ),
}).passthrough();

// A storyboard scene as submitted through the visual-stage PATCH. Kept
// `.passthrough()` so the rich, evolving scene shape (heading, slugline,
// dialogue, sceneVideoJobId, …) flows through untouched — only `shots[]` is
// validated (through storyboardShotSchema) so a bad shotType/screenDirection
// is caught at the route instead of persisting unnormalized.
export const storyboardSceneSchema = z.object({
  shots: z.array(storyboardShotSchema).max(64).optional(),
}).passthrough();

export const writersRoomExerciseCreateSchema = z.object({
  workId: wrIdNullable.optional(),
  prompt: z.string().max(2000).optional().default(''),
  durationSeconds: z.number().int().min(60).max(3600).default(600),
  startingWords: z.number().int().min(0).default(0)
}).strict();

export const writersRoomExerciseFinishSchema = z.object({
  endingWords: z.number().int().min(0).optional(),
  appendedText: z.string().max(100000).nullable().optional()
}).strict();

export const writersRoomAnalysisCreateSchema = z.object({
  kind: z.enum(ANALYSIS_KINDS)
}).strict();

// Start options for the autonomous Polish loop (#2173). All bounds mirror the
// polish.js runtime clamps so a direct API call can't request an out-of-range
// run; the runner clamps again defensively.
export const writersRoomPolishStartSchema = z.object({
  cycles: z.number().int().min(1).max(3).optional(),
  plateauThreshold: z.number().min(0).max(100).optional(),
  cutTargetPercent: z.number().int().min(5).max(20).optional(),
  minCuts: z.number().int().min(1).max(50).optional(),
  maxCuts: z.number().int().min(1).max(50).optional(),
}).strict();

// Manual revert of a work body to an immutable Polish snapshot (#2173).
export const writersRoomPolishRevertSchema = z.object({
  snapshotId: z.string().trim().regex(/^wr-snap-[0-9a-f-]+$/i, 'Invalid snapshot id'),
}).strict();

// Character profile fields are all optional on update so the UI can PATCH
// one field at a time. `name` accepts trimmed non-empty when present; all
// other text fields tolerate '' so the writer can deliberately blank a field
// out and have the next analysis re-fill it.
const wrCharTextField = z.string().max(2000);
// Voice id namespace shared by writers-room + pipeline character routes:
// `engine:voiceName` (e.g. `kokoro:af_heart`). Nullable so a UI clear path
// can null it explicitly.
const wrVoiceIdField = z.string().trim().max(200).nullable();
// Portable production metadata. The nested schemas intentionally contain no
// provider/profile/path fields: those are machine-local voice/media concerns,
// not Universe canon and not wire-safe record data.
const voiceCanonField = z.object({
  version: z.number().int().min(1).max(BIBLE_LIMITS.VOICE_CANON_VERSION_MAX).optional(),
  description: z.string().max(BIBLE_LIMITS.VOICE_CANON_DESCRIPTION_MAX).optional(),
  defaultDelivery: z.string().max(BIBLE_LIMITS.VOICE_CANON_DELIVERY_MAX).optional(),
  emotionalRange: z.array(z.string().trim().min(1).max(BIBLE_LIMITS.VOICE_CANON_RANGE_ITEM_MAX)).max(BIBLE_LIMITS.VOICE_CANON_RANGE_MAX).optional(),
  avoid: z.array(z.string().trim().min(1).max(BIBLE_LIMITS.VOICE_CANON_AVOID_ITEM_MAX)).max(BIBLE_LIMITS.VOICE_CANON_AVOID_MAX).optional(),
  pronunciations: z.array(z.object({
    term: z.string().trim().min(1).max(BIBLE_LIMITS.VOICE_CANON_PRONUNCIATION_TERM_MAX),
    pronunciation: z.string().trim().min(1).max(BIBLE_LIMITS.VOICE_CANON_PRONUNCIATION_VALUE_MAX),
  }).strict()).max(BIBLE_LIMITS.VOICE_CANON_PRONUNCIATIONS_MAX).optional(),
  sourcePolicy: z.enum(VOICE_CANON_SOURCE_POLICIES).nullable().optional(),
  approved: z.boolean().optional(),
}).strict();
const identityPackField = z.object({
  assets: z.array(z.object({
    role: z.enum(IDENTITY_ASSET_ROLES),
    imageRef: z.string().trim().min(1).max(BIBLE_LIMITS.IMAGE_REF_MAX),
    approved: z.boolean().optional(),
  }).strict()).max(BIBLE_LIMITS.IDENTITY_PACK_ASSETS_MAX).optional(),
  avoid: z.array(z.string().trim().min(1).max(BIBLE_LIMITS.IDENTITY_PACK_AVOID_ITEM_MAX)).max(BIBLE_LIMITS.IDENTITY_PACK_AVOID_MAX).optional(),
}).strict();
// Wardrobe array (A2). `id` is omitted on POSTs by the UI — the sanitizer
// fills it from the server-side UUID factory. Limits sourced from
// BIBLE_LIMITS so bumping the constant updates Zod automatically.
const wrWardrobeField = z.array(z.object({
  id: z.string().trim().max(64).optional(),
  name: z.string().trim().min(1).max(BIBLE_LIMITS.WARDROBE_NAME_MAX),
  description: z.string().max(BIBLE_LIMITS.WARDROBE_DESCRIPTION_MAX).optional(),
  createdAt: z.string().optional(),
  updatedAt: z.string().optional(),
}).strict()).max(BIBLE_LIMITS.WARDROBES_PER_CHARACTER_MAX);
// Structured relationship links (#1287). `id` is omitted on POSTs — the
// sanitizer mints it. `type` / `opposition.axis` accept the known enum tokens;
// an unrecognized value (legacy/peer payload) is coerced to `custom` by the
// sanitizer, not rejected here, so older clients never 400. Limits sourced
// from BIBLE_LIMITS so bumping a constant updates Zod automatically.
const wrOppositionField = z.object({
  axis: z.enum(RELATIONSHIP_OPPOSITION_AXES).or(z.string().trim().max(BIBLE_LIMITS.RELATIONSHIP_OPPOSITION_AXIS_MAX)),
  thisRole: z.string().max(BIBLE_LIMITS.RELATIONSHIP_OPPOSITION_ROLE_MAX).optional(),
  targetRole: z.string().max(BIBLE_LIMITS.RELATIONSHIP_OPPOSITION_ROLE_MAX).optional(),
  note: z.string().max(BIBLE_LIMITS.RELATIONSHIP_OPPOSITION_NOTE_MAX).optional(),
}).strict();
const wrRelationshipLinksField = z.array(z.object({
  id: z.string().trim().max(64).optional(),
  targetCharacterId: z.string().trim().min(1).max(BIBLE_LIMITS.RELATIONSHIP_TARGET_ID_MAX),
  type: z.enum(RELATIONSHIP_LINK_TYPES).or(z.string().trim().max(BIBLE_LIMITS.RELATIONSHIP_TYPE_MAX)).optional(),
  description: z.string().max(BIBLE_LIMITS.RELATIONSHIP_DESCRIPTION_MAX).optional(),
  opposition: wrOppositionField.nullable().optional(),
  locked: z.boolean().optional(),
}).strict()).max(BIBLE_LIMITS.RELATIONSHIP_LINKS_PER_CHARACTER_MAX);
// Optional psychology profile (#6414) and the Three Sliders (#2175) — the two
// structured surfaces the Universe cast editor already authors. Both are
// clearable: `psychology: null` (or an all-blank object) drops the profile so a
// character reads as unassessed again rather than keeping an empty husk, and a
// slider axis set to null un-rates it without disturbing the other two.
const wrPsychologyDriveField = z.object({
  desire: z.string().max(CHARACTER_PSYCHOLOGY_LIMITS.drive).nullable().optional(),
  fear: z.string().max(CHARACTER_PSYCHOLOGY_LIMITS.drive).nullable().optional(),
}).strict();
const wrPsychologyField = z.object({
  ...Object.fromEntries(CHARACTER_PSYCHOLOGY_TEXT_FIELDS.map((field) => [
    field, z.string().max(CHARACTER_PSYCHOLOGY_LIMITS[field]).nullable().optional(),
  ])),
  // '' and null both unset the assessment; the sanitizer's trimEnum maps an
  // unrecognized token to null rather than rejecting it.
  assessment: z.enum(PSYCHOLOGY_ASSESSMENTS).or(z.literal('')).nullable().optional(),
  assessmentNote: z.string().max(CHARACTER_PSYCHOLOGY_LIMITS.assessmentNote).nullable().optional(),
  drives: z.object(Object.fromEntries(
    PSYCHOLOGY_DRIVE_AXES.map((axis) => [axis, wrPsychologyDriveField.nullable().optional()]),
  )).strict().nullable().optional(),
}).strict();
const wrSlidersField = z.object(Object.fromEntries(CHARACTER_SLIDER_AXES.map((axis) => [
  axis,
  z.number().int().min(BIBLE_LIMITS.SLIDER_MIN).max(BIBLE_LIMITS.SLIDER_MAX).nullable().optional(),
]))).strict();
// Narrative character framework (#6417) — parity with what the Universe cast
// editor already authors and `sanitizeCharacter` already persists. Every field
// is optional AND tolerates its empty value ('' / [] / null) so a writer can
// deliberately clear one; absence leaves the stored value untouched, which is
// the absent-vs-intentionally-empty split the store relies on.
const wrCharFrameworkFields = Object.freeze({
  motivations: z.string().max(CHARACTER_FRAMEWORK_LIMITS.motivations).optional(),
  ghost: z.string().max(CHARACTER_FRAMEWORK_LIMITS.ghost).optional(),
  wound: z.string().max(CHARACTER_FRAMEWORK_LIMITS.wound).optional(),
  lie: z.string().max(CHARACTER_FRAMEWORK_LIMITS.lie).optional(),
  need: z.string().max(CHARACTER_FRAMEWORK_LIMITS.need).optional(),
  want: z.string().max(CHARACTER_FRAMEWORK_LIMITS.want).optional(),
  // '' and null both clear the declared arc; the sanitizer's trimEnum maps
  // anything it doesn't recognize to null rather than rejecting.
  arcType: z.enum(CHARACTER_ARC_TYPES).or(z.literal('')).nullable().optional(),
  secrets: z.array(z.string().trim().min(1).max(BIBLE_LIMITS.SECRET_MAX))
    .max(BIBLE_LIMITS.SECRETS_PER_CHARACTER_MAX).optional(),
  psychology: wrPsychologyField.nullable().optional(),
  sliders: wrSlidersField.nullable().optional(),
  // The optional five-stage evolution lens (#6445), reusing the SAME schema the
  // Pipeline series arc and the FableLoom plan validate against — a second
  // definition here would drift the stage vocabulary the moment one moved.
  // `null` (or an all-blank lens) is a real clear: `sanitizeCharacterEvolution`
  // collapses it to absent so the character reads as un-authored again.
  // Anything this object accepts must also appear in `editableFields` in
  // services/writersRoom/characters.js or the write is validated and dropped.
  evolution: characterEvolutionSchema.nullable().optional(),
});
// Shared between create and update — the two differ only in whether `name` is
// required, and drifting them apart is how `relationshipLinks` ended up
// accepted on one path and dropped on the other.
const wrCharacterFields = Object.freeze({
  aliases: z.array(z.string().trim().min(1).max(200)).max(20).optional(),
  role: wrCharTextField.optional(),
  physicalDescription: wrCharTextField.optional(),
  personality: wrCharTextField.optional(),
  background: wrCharTextField.optional(),
  notes: wrCharTextField.optional(),
  voiceId: wrVoiceIdField.optional(),
  voiceCanon: voiceCanonField.optional(),
  identityPack: identityPackField.optional(),
  wardrobes: wrWardrobeField.optional(),
  relationshipLinks: wrRelationshipLinksField.optional(),
  ...wrCharFrameworkFields,
});
export const writersRoomCharacterCreateSchema = z.object({
  name: z.string().trim().min(1).max(200),
  ...wrCharacterFields,
}).strict();
export const writersRoomCharacterUpdateSchema = z.object({
  name: z.string().trim().min(1).max(200).optional(),
  ...wrCharacterFields,
}).strict();

const wrPlaceTextField = z.string().max(2000);
// Inner ZodObject (without refine) — exposed so the Pipeline can `.extend()`
// it; `.refine()` returns a ZodEffects which has no `.extend()`.
const writersRoomPlaceCreateObject = z.object({
  name: z.string().trim().max(200).optional(),
  slugline: z.string().trim().max(200).optional(),
  description: wrPlaceTextField.optional(),
  palette: wrPlaceTextField.optional(),
  era: wrPlaceTextField.optional(),
  weather: wrPlaceTextField.optional(),
  recurringDetails: wrPlaceTextField.optional(),
  notes: wrPlaceTextField.optional(),
  // Cluster A — INT/EXT + time-of-day taxonomy. Case-insensitive accept
  // mirrors the sanitizer (`INT`/`int` both normalize to `INT`).
  intExt: z.preprocess(
    (v) => (typeof v === 'string' ? v.trim().toUpperCase() : v),
    z.enum(['INT', 'EXT']),
  ).nullable().optional(),
  timeOfDay: z.preprocess(
    (v) => (typeof v === 'string' ? v.trim().toLowerCase() : v),
    z.enum(['dawn', 'day', 'dusk', 'night']),
  ).nullable().optional(),
}).strict();
const placeHasIdentifier = (v) =>
  (v.name && v.name.trim()) || (v.slugline && v.slugline.trim());
export const writersRoomPlaceCreateSchema = writersRoomPlaceCreateObject.refine(
  placeHasIdentifier,
  { message: 'Place requires either a slugline or a name' },
);
export const writersRoomPlaceUpdateSchema = z.object({
  name: z.string().trim().max(200).optional(),
  slugline: z.string().trim().max(200).optional(),
  description: wrPlaceTextField.optional(),
  palette: wrPlaceTextField.optional(),
  era: wrPlaceTextField.optional(),
  weather: wrPlaceTextField.optional(),
  recurringDetails: wrPlaceTextField.optional(),
  notes: wrPlaceTextField.optional(),
  // Cluster A — INT/EXT + time-of-day taxonomy. Case-insensitive accept
  // mirrors the sanitizer (`INT`/`int` both normalize to `INT`).
  intExt: z.preprocess(
    (v) => (typeof v === 'string' ? v.trim().toUpperCase() : v),
    z.enum(['INT', 'EXT']),
  ).nullable().optional(),
  timeOfDay: z.preprocess(
    (v) => (typeof v === 'string' ? v.trim().toLowerCase() : v),
    z.enum(['dawn', 'day', 'dusk', 'night']),
  ).nullable().optional(),
}).strict();

const wrObjectTextField = z.string().max(2000);
// Structured object↔character attachment links (#1288). `id` is omitted on
// POSTs — the sanitizer mints it. `role` accepts the known archetype tokens; an
// unrecognized value (legacy/peer payload) is coerced to `custom` by the
// sanitizer, not rejected here, so older clients never 400. Limits sourced from
// BIBLE_LIMITS so bumping a constant updates Zod automatically.
const wrAttachmentsField = z.array(z.object({
  id: z.string().trim().max(64).optional(),
  characterId: z.string().trim().min(1).max(BIBLE_LIMITS.ATTACHMENT_CHARACTER_ID_MAX),
  emotion: z.string().max(BIBLE_LIMITS.ATTACHMENT_EMOTION_MAX).optional(),
  significance: z.string().max(BIBLE_LIMITS.ATTACHMENT_SIGNIFICANCE_MAX).optional(),
  origin: z.string().max(BIBLE_LIMITS.ATTACHMENT_ORIGIN_MAX).optional(),
  role: z.enum(ATTACHMENT_ROLES).or(z.string().trim().max(60)).optional(),
  locked: z.boolean().optional(),
}).strict()).max(BIBLE_LIMITS.ATTACHMENTS_PER_OBJECT_MAX);
export const writersRoomObjectCreateSchema = z.object({
  name: z.string().trim().min(1).max(200),
  aliases: z.array(z.string().trim().min(1).max(200)).max(20).optional(),
  description: wrObjectTextField.optional(),
  significance: wrObjectTextField.optional(),
  attachments: wrAttachmentsField.optional(),
  notes: wrObjectTextField.optional(),
}).strict();
export const writersRoomObjectUpdateSchema = z.object({
  name: z.string().trim().min(1).max(200).optional(),
  aliases: z.array(z.string().trim().min(1).max(200)).max(20).optional(),
  description: wrObjectTextField.optional(),
  significance: wrObjectTextField.optional(),
  attachments: wrAttachmentsField.optional(),
  notes: wrObjectTextField.optional(),
}).strict();

// Every story-bible route validates through the `writersRoom*` schemas above;
// there are no kind-neutral `*Bible*Schema` aliases beside them (#5730). If a
// Pipeline route needs one, add it next to that caller —
// `writersRoomPlaceCreateObject` is the un-refined ZodObject to `.extend()`.

// =============================================================================
// PROMPT STAGE CONFIG (server/routes/prompts.js PUT /:stage body)
// =============================================================================

// Per-call timeout bounds: STAGE_TIMEOUT_MIN_MS / STAGE_TIMEOUT_MAX_MS are
// imported (aliased) from aiToolkit/constants.js at the top of this file so
// the route validator, the runner (server/services/stageRunner.js), and the
// toolkit's own provider/run validation all share one source of truth. The
// client mirror in client/src/utils/formatters.js can't import across the
// server boundary — comments on both sides flag the requirement to keep
// them in lockstep.

// Accept either a number or a numeric string (UI inputs frequently serialize
// as strings) and validate the resulting integer. `nullable` lets the client
// clear the override explicitly with `null`; absence leaves it untouched.
export const stageConfigUpdateSchema = z.object({
  name: z.string().optional(),
  description: z.string().optional(),
  model: z.string().nullable().optional(),
  provider: z.string().nullable().optional(),
  // Writer/judge model split (#2167, CWQE Phase 3). A writer stage may pin a
  // DIFFERENT provider/model to grade its own output — `null`/'' clears the pin
  // so the judge falls back to the writer provider (see resolveJudgeForStage).
  // Without these keys the `.strip()` below would silently drop them from the
  // saved config, so schema parity is required in the same change.
  judgeProvider: z.string().nullable().optional(),
  judgeModel: z.string().nullable().optional(),
  // Per-stage reasoning-effort pin (#3641). Optional and opt-in: with no pin the
  // stage inherits a run-level `effortDefault` (Series Autopilot's run effort),
  // then the provider's own config. Validated against the union of every accepted
  // effort value across effort-capable CLIs — the runner clamps a level the chosen
  // provider doesn't offer down its ladder. `null`/'' clears the pin. Without this
  // key the `.strip()` below would silently drop a pin on save.
  effort: z.preprocess(
    (v) => (v === '' ? null : v),
    z.enum(EFFORT_LEVELS).nullable().optional(),
  ),
  // Multi-candidate draft gate (#2169, CWQE Phase 5). Opt-in, DEFAULT OFF
  // (draftAttempts 1 = single generation, no gate) because each extra attempt
  // multiplies generation + judge cost. When > 1, generateStage re-rolls a fresh
  // draft while the composite qualityScore (#2167) is below draftGateThreshold,
  // up to the attempt cap, and keeps the best-scoring attempt. `null`/'' clears
  // the override. Only judgeable stages (prose/comicScript/teleplay) honor it.
  // Coerce digit-only strings (form inputs) the same way `timeout` does.
  draftAttempts: z.preprocess(
    (v) => {
      if (v === '' || v === null) return null;
      if (v === undefined) return undefined;
      if (typeof v === 'number') return v;
      if (typeof v === 'string' && /^\d+$/.test(v.trim())) return Number(v.trim());
      return v;
    },
    z.number().int().min(1).max(3).nullable().optional(),
  ),
  draftGateThreshold: z.preprocess(
    (v) => {
      if (v === '' || v === null) return null;
      if (v === undefined) return undefined;
      if (typeof v === 'number') return v;
      if (typeof v === 'string' && /^\d+(\.\d+)?$/.test(v.trim())) return Number(v.trim());
      return v;
    },
    z.number().min(0).max(10).nullable().optional(),
  ),
  timeout: z.preprocess(
    // Treat empty string as a "clear override" (null). Coerce digit-only
    // strings to numbers so form clients that send "900000" still parse —
    // but reject "1e3" / "1.5" / "0x10" by leaving them as the original
    // string so the inner `.number()` check fails. The digit-only rule
    // (and the `.trim()` before it) mirror `parseTimeoutMs` in
    // client/src/utils/formatters.js and `normalizeTimeout` in
    // server/services/stageRunner.js so all three reject the same shapes.
    (v) => {
      if (v === '' || v === null) return null;
      if (v === undefined) return undefined;
      if (typeof v === 'number') return v;
      if (typeof v === 'string') {
        const trimmed = v.trim();
        if (trimmed === '') return null;
        if (/^\d+$/.test(trimmed)) return Number(trimmed);
      }
      return v;
    },
    z.number().int().min(STAGE_TIMEOUT_MIN_MS).max(STAGE_TIMEOUT_MAX_MS).nullable().optional()
  ),
  returnsJson: z.boolean().optional(),
  variables: z.array(z.string()).optional(),
}).strip();
// `.strip()` (Zod default) silently drops unknown keys instead of letting
// them flow into `updateStageConfig`'s `{...existing, ...updatedConfig}`
// spread. Stripping prevents prototype-pollution shapes (`__proto__`,
// `constructor`, `prototype`) and config-key squatting from a client that
// sends an unmodelled field. If a future stage field is added, extend the
// schema rather than reintroducing `.passthrough()`.

// =============================================================================
// PIPELINE ISSUE QUERY SCHEMAS
// =============================================================================

// Query params for GET /api/pipeline/series/:id/issues — both are optional;
// when either is present the route returns { items, total, offset, limit }
// instead of the legacy raw array so callers can page large series.
export const issuesListQuerySchema = z.object({
  offset: z.preprocess((v) => (v === undefined ? 0 : Number(v)), z.number().int().min(0)).default(0),
  limit: z.preprocess((v) => (v === undefined ? 1000 : Number(v)), z.number().int().min(1).max(1000)).default(1000),
});


// Query-less callers retain the legacy array; limit/offset opt into a snapshot.
export const writersRoomWorksQuerySchema = z.object({
  limit: z.coerce.number().int().min(1).max(100).default(50),
  offset: z.coerce.number().int().min(0).max(Number.MAX_SAFE_INTEGER).default(0),
  cursor: z.string().regex(/^[0-9a-f-]{36}\.[0-9]+$/).max(80).optional(),
});
export const writersRoomWorkSummarySchema = z.object({
  id: z.string(), folderId: z.string().nullable().optional(), title: z.string(),
  kind: z.string(), status: z.string(), activeDraftVersionId: z.string().nullable().optional(),
  wordCount: z.number(), draftCount: z.number(),
  pipelineSeriesId: z.string().nullable(), pipelineIssueId: z.string().nullable(),
  createdAt: z.string(), updatedAt: z.string(),
});
export const writersRoomWorksResponseSchema = z.union([
  z.array(writersRoomWorkSummarySchema),
  z.object({
    items: z.array(writersRoomWorkSummarySchema), total: z.number().int(),
    limit: z.number().int(), offset: z.number().int(), nextCursor: z.string().nullable(),
  }),
]);