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

40.1 KB
Raw Blame
import { z } from 'zod';
import { CACHEABLE_TYPES, COGNITIVE_DRILL_TYPES, LLM_DRILL_TYPES, POST_SUPPORTED_MEMORY_TYPES } from './postDrillTypes.js';
import { validateCognitivePair } from './postCognitiveConfig.js';
import { TOPIC_IDS } from './postTopics.js';
import { HHMM_STRICT_RE } from './timezone.js';
import { POST_LLM_MAX_SEMANTIC_CANDIDATES, postLlmEvaluationSchema } from './postLlmContracts.js';
import { EFFORT_LEVELS } from './providerModels.js';
import { RHETORIC_DRILL_TYPES, RHETORIC_MODE_IDS, rhetoricEvaluationSchema } from './postRhetoric.js';
import { POLLUTING_KEYS } from './objects.js';

// Chunk ids and element names index the plain-object mastery maps in
// meatspacePostMemory.js; `__proto__` would resolve to Object.prototype and
// the mastery update would write onto every object in the process.
const masteryKeySchema = z.string().refine((key) => !POLLUTING_KEYS.has(key), 'reserved mastery key');

// =============================================================================
// POST (Power On Self Test) VALIDATION SCHEMAS
// =============================================================================

// Legacy free-text tags for session conditions (sleep, caffeine, stress, etc.).
// Superseded by `postConditionsSchema` below — kept only so historical session
// records (and any client that still sends it) remain valid; the launcher no
// longer writes free-text values here.
export const postTagsSchema = z.record(z.string().max(200));

// Structured session conditions (issue #4442): fixed enums instead of free
// text so values are filterable/comparable across sessions, plus an optional
// note for anything the enums don't capture. Every field is optional — a
// session with no conditions filled in submits `{}`/`undefined`, not a
// placeholder-filled object.
export const postConditionsSchema = z.object({
  sleepQuality: z.enum(['poor', 'fair', 'good']).optional(),
  caffeine: z.enum(['none', 'low', 'moderate', 'high']).optional(),
  stress: z.enum(['low', 'moderate', 'high']).optional(),
  note: z.string().trim().max(500).optional(),
});

// 24h "HH:MM" time-of-day — HHMM_STRICT_RE is timezone.js's single source of
// truth for this exact zero-padded pattern (shared with dashboardLayouts.js's
// activateWindow validator); don't re-derive a local copy.

// Individual question result (math + memory drills)
// Math: server recomputes expected/correct via scoreDrill (numeric values)
// Memory: client scores with string comparison (text values)
const fillBlankAnswerSchema = z.object({
  // `index` is the source question's answer index, not the position in the
  // submitted array. Keeping it stable makes partial answers attributable even
  // when a client submits them out of order.
  index: z.number().int().min(0),
  value: z.string().nullable(),
  expected: z.string().optional(),
  correct: z.boolean().optional(),
  // Copied onto the question's element by expandMemoryQuestionResults.
  element: masteryKeySchema.nullable().optional(),
});

const questionResultSchema = z.object({
  prompt: z.string(),
  // Cognitive drills key each trial back to its position in the generated
  // drillData (n-back sequence index, digit-span/stroop trial index) so the
  // server can recompute the answer key. Absent for math/memory drills.
  index: z.number().int().min(0).optional(),
  expected: z.union([z.number(), z.string()]).optional(),
  // Fill-blank now submits one indexed entry per generated blank. The scalar
  // forms remain valid for old clients and are intentionally treated as one
  // attributable attempt by the memory service, never as a full prompt pass.
  answered: z.union([z.number(), z.string(), z.array(fillBlankAnswerSchema)]).nullable(),
  correct: z.boolean().optional(),
  responseMs: z.number().min(0),
  // Reaction-time drill only: player pressed before the stimulus appeared.
  // Always scored wrong server-side regardless of any client-supplied correct.
  falseStart: z.boolean().optional(),
  // Executive-control drill evidence. These are server-recomputed from the
  // seeded generated trial, but remain in the stored per-question record so
  // progress/history can explain switch and congruency costs.
  rule: z.enum(['color', 'shape', 'fill']).optional(),
  switched: z.boolean().optional(),
  incongruent: z.boolean().optional(),
  congruent: z.boolean().optional(),
  noGo: z.boolean().optional(),
  // Memory drill questions only: which chunk (memory-sequence) / element
  // (memory-element-flash) this answer attributes to, so submitPostSession can
  // merge per-chunk/per-element mastery (mergeMasteryFromSession in
  // meatspacePostMemory.js) the same way MemoryBuilder's submitPractice does.
  // Absent for math/LLM/cognitive drills.
  chunkId: masteryKeySchema.nullable().optional(),
  element: masteryKeySchema.nullable().optional()
});

// LLM drill response (text-based)
const llmResponseSchema = z.object({
  // questionIndex pairs the response with the correct prompt in drillData.
  // Without it Zod's default strip would drop the field, the scorer would fall
  // back to the array index (always 0 for single-response submits), and every
  // answer would be evaluated against the first prompt.
  questionIndex: z.number().int().min(0).optional(),
  prompt: z.string().max(5000).optional(),
  response: z.string().max(10000).optional(),
  answers: z.array(z.string().max(1000)).max(100).optional(),
  items: z.array(z.string().trim().min(1).max(500)).max(100).optional(),
  responseMs: z.number().min(0).optional().default(0),
  llmScore: z.number().min(0).max(100).optional(),
  llmFeedback: z.string().max(2000).optional()
});

// Drill type configuration
const MATH_DRILL_TYPES = ['doubling-chain', 'serial-subtraction', 'multiplication', 'powers', 'estimation', 'applied-numeracy'];
const MEMORY_DRILL_TYPES = ['memory-fill-blank', 'memory-sequence', 'memory-element-flash'];
// LLM_DRILL_TYPES, COGNITIVE_DRILL_TYPES and POST_SUPPORTED_MEMORY_TYPES live in
// ./postDrillTypes.js (a zod-free leaf, re-exported by the client's
// meatspace/post/constants.js) — imported above, so each list has one owner.
// Canonical set of coarse "module" tags a scored POST task/session can carry
// (mental-math / llm-drills / cognitive drills / memory drills). Shared by the
// session-submit schema (below) and sessionModules config so a typo'd module
// string is rejected at validation instead of silently creating a phantom
// `byModule` stats bucket (issue #2099). Morse is deliberately excluded — it
// only ever posts through the separate, unrestricted `trainingEntrySchema`.
const POST_MODULES = ['mental-math', 'llm-drills', 'cognitive', 'memory'];
// Every scored drill type across the four modules — backs taskResultSchema.type.
const DRILL_TYPES = [...MATH_DRILL_TYPES, ...LLM_DRILL_TYPES, ...MEMORY_DRILL_TYPES, ...COGNITIVE_DRILL_TYPES];
// Morse trainer drill types (client-side scoring — exact-match copy/send comparison).
// Deliberately NOT spliced into DRILL_TYPES: that array also backs
// taskResultSchema.type (the *scored* full-session submit endpoint,
// postSessionSubmitSchema) and postDrillRequestSchema.type (server-side drill
// generation). meatspacePost.js's scoring dispatch only special-cases
// LLM/MEMORY/COGNITIVE types and falls through everything else to scoreDrill's
// math-expression parser (computeExpectedFromPrompt) — a Morse task type would
// pass validation there but silently mis-score as a failed math drill instead
// of being rejected. Morse and rhetoric only ever post through
// trainingEntrySchema below.
const MORSE_DRILL_TYPES = ['morse-copy', 'morse-head-copy', 'morse-send'];
// Rhetoric is a standalone training surface. It never enters a scored POST
// session; its self-score and optional evaluator report use the shared training
// log endpoint for streaks and progress reporting.

const drillTypeConfigSchema = z.object({
  enabled: z.boolean().optional(),
  // Memory drills: the target memory item to drill (falls back to lowest-mastery
  // item when absent). The /post/drill route threads config.memoryItemId into
  // generateMemoryDrill, so it must survive validation rather than being stripped.
  memoryItemId: z.string().optional(),
  steps: z.number().int().min(1).max(50).optional(),
  subtrahend: z.number().int().min(1).max(100).optional(),
  startValue: z.number().int().min(1).optional(),
  startRange: z.array(z.number()).length(2).optional(),
  timeLimitSec: z.number().int().min(10).max(600).optional(),
  // Executive-control generators support up to 60 trials. This shared config
  // schema must accept every generated config on the scored-session round-trip.
  count: z.number().int().min(1).max(60).optional(),
  maxDigits: z.number().int().min(1).max(4).optional(),
  // Progressive multiplication ladder (server/lib/postMultiplicationLadder.js).
  // `progressive` is the config toggle; `level`/`factors` are server-computed
  // effective config stamped into the generated drill (and stored per-task on
  // session submit), so they must survive validation on the round-trip.
  progressive: z.boolean().optional(),
  level: z.number().int().min(0).max(50).optional(),
  technique: z.string().max(100).optional(),
  factors: z.array(z.number().int().min(1).max(4)).min(2).max(6).optional(),
  // Maintenance-review rep (issue #2096): `review` bypasses the progression
  // override so a specific mastered-but-inactive rung is re-verified at its own
  // level; `reviewSkillId` ties the scored task back to the review scheduler so
  // session-submit records the pass/fail. Both survive validation on the drill
  // request AND the session-submit round-trip.
  review: z.boolean().optional(),
  reviewSkillId: z.string().max(200).optional(),
  bases: z.array(z.number().int().min(2).max(20)).min(1).optional(),
  maxExponent: z.number().int().min(2).max(20).optional(),
  tolerancePct: z.number().min(1).max(50).optional(),
  // Applied Numeracy uses an unsigned numeric replay key while the cognitive
  // generators use bounded string seeds. This shared config must preserve both
  // shapes on the request and scored-session round-trips.
  seed: z.union([
    z.string().max(100),
    z.number().int().min(0).max(0xFFFFFFFF),
  ]).optional(),
  difficulty: z.number().int().min(1).max(3).optional(),
  family: z.enum(['percentage', 'ratio', 'unit', 'rate', 'estimate', 'mixed']).optional(),
  // --- Cognitive drill knobs (n-back / digit-span / stroop) ---
  // Bounds match the generator clamps in meatspacePostCognitive.js so the UI /
  // API can't accept a value the generator will silently narrow. Exception:
  // `length`'s effective floor is `n + 5` (dynamic, up to 8) inside the
  // generator — Zod can't express a cross-field minimum here, so this schema
  // keeps a conservative fixed floor of 6 and lets the generator clamp up.
  // (timeLimitSec above is validated but NOT enforced for these drill types —
  // they're self-paced/stimulus-driven; see PostCognitiveDrillRunner.jsx.)
  // stimulusMs (n-back / Go-No-Go) and showMs (digit-span) are the
  // presentation-speed knobs. The lower bound covers Go/No-Go's brief signals;
  // each generator still applies its drill-specific clamp.
  // The progressive ladder (default ON) drives them per rung; manual mode
  // (progressive off) exposes them in the config UI (issue #2095), so they must
  // survive validation. Bounds span the generator clamps in
  // meatspacePostCognitive.js (generateNBack / generateGoNoGo).
  n: z.number().int().min(1).max(3).optional(),
  stimulusMs: z.number().int().min(100).max(5000).optional(),
  showMs: z.number().int().min(400).max(4000).optional(),
  length: z.number().int().min(6).max(60).optional(),
  direction: z.enum(['forward', 'backward']).optional(),
  startLength: z.number().int().min(3).max(9).optional(),
  maxLength: z.number().int().min(3).max(12).optional(),
  // --- Cognitive drill knobs (schulte-table / mental-rotation / reaction-time) ---
  size: z.number().int().min(3).max(7).optional(),
  incongruentPct: z.number().int().min(0).max(100).optional(),
  rotationComplexity: z.number().int().min(1).max(3).optional(),
  optionCount: z.number().int().min(2).max(4).optional(),
  mode: z.enum(['simple', 'choice']).optional(),
  minDelayMs: z.number().int().min(300).max(5000).optional(),
  maxDelayMs: z.number().int().min(300).max(8000).optional(),
  choices: z.number().int().min(2).max(4).optional(),
  ruleCount: z.number().int().min(2).max(3).optional(),
  switchRatePct: z.number().int().min(0).max(100).optional(),
  cueStimulusIntervalMs: z.number().int().min(100).max(2000).optional(),
  responseDeadlineMs: z.number().int().min(500).max(5000).optional(),
  noGoPct: z.number().int().min(5).max(80).optional(),
  lureSimilarity: z.enum(['low', 'high']).optional(),
  congruentPct: z.number().int().min(0).max(100).optional(),
  flankerDistance: z.number().int().min(1).max(4).optional(),
  flankerStrength: z.number().int().min(1).max(3).optional(),
});

// Task result within a session
// score is optional — the server recomputes it via scoreDrill
const taskResultSchema = z.object({
  // Stable client attempt id. Optional for legacy scored-session clients; the
  // store derives a deterministic id from run id + position when absent.
  id: z.string().min(1).max(200).optional(),
  module: z.enum(POST_MODULES),
  type: z.enum(DRILL_TYPES),
  config: drillTypeConfigSchema.optional().default({}),
  questions: z.array(questionResultSchema).optional().default([]),
  responses: z.array(llmResponseSchema).max(50).optional().default([]),
  drillData: z.any().optional(),
  // Memory drills: which memory item this task drilled, so the session-submit
  // path can map the result back and advance that item's spaced-repetition
  // schedule (mirrors the dedicated MemoryBuilder practice flow). Absent for
  // every other drill type.
  memoryItemId: z.string().optional(),
  score: z.number().min(0).max(100).optional(),
  // Separated performance metrics stored alongside the blended `score` (issue
  // #2094). The server always recomputes these from the drill answer key on
  // submit, so an incoming client value is advisory — accepted (optional,
  // nullable where a metric can be genuinely absent) rather than rejected, to
  // keep the request/stored shapes in parity. `accuracy`/`completion` are 0-1
  // fractions; `avgResponseMs`/`medianMs`/`bestMs` are milliseconds. The n-back
  // signal-detection counts and reaction-time latency extremes ride along too.
  accuracy: z.number().min(0).max(1).nullable().optional(),
  completion: z.number().min(0).max(1).nullable().optional(),
  avgResponseMs: z.number().min(0).nullable().optional(),
  answeredCount: z.number().int().min(0).optional(),
  totalCount: z.number().int().min(0).optional(),
  attemptCount: z.number().int().min(0).optional(),
  errorCount: z.number().int().min(0).optional(),
  medianMs: z.number().min(0).nullable().optional(),
  bestMs: z.number().min(0).nullable().optional(),
  span: z.number().int().min(0).optional(),
  hits: z.number().int().min(0).optional(),
  misses: z.number().int().min(0).optional(),
  falseAlarms: z.number().int().min(0).optional(),
  correctRejections: z.number().int().min(0).optional(),
  omissions: z.number().int().min(0).optional(),
  commissionErrors: z.number().int().min(0).optional(),
  switchCostMs: z.number().nullable().optional(),
  switchAccuracy: z.number().min(0).max(1).nullable().optional(),
  repeatAccuracy: z.number().min(0).max(1).nullable().optional(),
  congruencyCostMs: z.number().nullable().optional(),
  congruentAccuracy: z.number().min(0).max(1).nullable().optional(),
  incongruentAccuracy: z.number().min(0).max(1).nullable().optional(),
  falseAlarmRate: z.number().min(0).max(1).nullable().optional(),
  latencyDistributionMs: z.array(z.number().min(0)).max(500).optional(),
  hintUsed: z.boolean().optional(),
  confidence: z.number().min(0).max(1).nullable().optional(),
  inputMode: z.string().min(1).max(50).optional(),
  scorerProvenance: z.string().min(1).max(100).optional(),
  evaluation: postLlmEvaluationSchema.optional(),
  totalMs: z.number().min(0)
}).superRefine((task, ctx) => {
  if (!LLM_DRILL_TYPES.includes(task.type)) return;
  if (!task.evaluation) {
    ctx.addIssue({ code: 'custom', path: ['evaluation'], message: 'scored LLM drills require an evaluation' });
  }
  if (task.score === undefined) {
    ctx.addIssue({ code: 'custom', path: ['score'], message: 'scored LLM drills require a score' });
  }
  if (task.evaluation && task.evaluation.scores.length !== task.responses.length) {
    ctx.addIssue({ code: 'custom', path: ['evaluation', 'scores'], message: 'evaluation score count must match response count' });
  }
  task.responses.forEach((response, index) => {
    if (response.llmScore === undefined) {
      ctx.addIssue({ code: 'custom', path: ['responses', index, 'llmScore'], message: 'scored LLM responses require llmScore' });
    }
  });
});

// Full session submission
export const POST_QUICK_DURATION_MINUTES = [3, 5, 10, 15];
const postQuickDurationSchema = z.union(POST_QUICK_DURATION_MINUTES.map(minutes => z.literal(minutes)));

export const postQuickSessionPlanSchema = z.object({
  targetDurationSec: z.number().int().min(1).max(3600),
  estimatedDurationSec: z.number().min(0).max(3600),
  toleranceSec: z.number().int().min(0).max(600),
  omittedDomains: z.array(z.string().max(100)).max(20),
  omittedReviews: z.array(z.string().max(200)).max(10).optional(),
  selectedTypes: z.array(z.string().max(100)).max(50),
});

// A benchmark is a versioned, fixed-form assessment. It is deliberately
// separate from the adaptive/Quick plan so benchmark history remains
// comparable even when a user's normal POST configuration changes.
export const postBenchmarkSchema = z.object({
  protocolId: z.string().trim().min(1).max(100),
  protocolVersion: z.number().int().min(1).max(100),
  scorerVersion: z.string().trim().min(1).max(100),
  formId: z.string().trim().min(1).max(100),
});

export const postSessionSubmitSchema = z.object({
  // Client-generated session id (uuid) — keys the idempotent upsert in
  // submitPostSession so a retry after a dropped response can't double-record.
  // Optional for back-compat: legacy clients and direct service callers that
  // omit it get a server-assigned uuid.
  id: z.string().uuid().optional(),
  cadence: z.enum(['daily', 'weekly', 'monthly']).optional().default('daily'),
  modules: z.array(z.enum(POST_MODULES)).min(1),
  tasks: z.array(taskResultSchema).min(1),
  tags: postTagsSchema.optional().default({}),
  conditions: postConditionsSchema.optional(),
  startedAt: z.string().datetime().optional(),
  plan: postQuickSessionPlanSchema.optional(),
  benchmark: postBenchmarkSchema.optional(),
});

// LLM drill type configuration
const llmDrillTypeConfigSchema = z.object({
  enabled: z.boolean().optional(),
  count: z.number().int().min(1).max(20).optional(),
  timeLimitSec: z.number().int().min(10).max(600).optional(),
  providerId: z.string().optional(),
  model: z.string().optional()
});

// The evaluator is deliberately a separate opt-in block. Saving a provider or
// effort here must never make an existing POST screen start spending tokens:
// callers still have to set `enabled: true`, and the default config keeps it
// false.
export const postRhetoricEvaluatorConfigSchema = z.object({
  enabled: z.boolean().optional(),
  providerId: z.string().trim().max(300).nullable().optional(),
  model: z.string().trim().max(300).nullable().optional(),
  effort: z.preprocess(
    value => (value === '' ? undefined : value),
    z.enum(EFFORT_LEVELS).nullable().optional(),
  ),
});

// Optional practice goals (issue #2100). Every field is optional so a config
// with no goals — or a legacy config that predates this block entirely — stays
// valid; bounds keep a hand-edited config from persisting a nonsensical target.
// Exported so the settings route / tests can validate a `goals` slice directly.
export const postGoalsSchema = z.object({
  dailyMinutes: z.number().int().min(1).max(1440).optional(),
  weeklySessions: z.number().int().min(1).max(100).optional(),
  streakTarget: z.number().int().min(1).max(3650).optional(),
  morseWpmTarget: z.number().min(1).max(100).optional(),
}).partial();

// Config update (partial)
export const postConfigUpdateSchema = z.object({
  mentalMath: z.object({
    enabled: z.boolean().optional(),
    drillTypes: z.partialRecord(z.enum(MATH_DRILL_TYPES), drillTypeConfigSchema).optional()
  }).optional(),
  llmDrills: z.object({
    enabled: z.boolean().optional(),
    providerId: z.string().nullable().optional(),
    model: z.string().nullable().optional(),
    drillTypes: z.partialRecord(z.enum(LLM_DRILL_TYPES), llmDrillTypeConfigSchema).optional()
  }).optional(),
  rhetoricEvaluator: postRhetoricEvaluatorConfigSchema.optional(),
  // Deterministic cognitive drills — no provider, so no provider/model fields.
  // Partial so an older browser's complete pre-executive-control map remains a
  // valid patch after newer drill types are added to the enum (Zod 4 records
  // with enum keys are otherwise exhaustive).
  cognitive: z.object({
    enabled: z.boolean().optional(),
    drillTypes: z.partialRecord(z.enum(COGNITIVE_DRILL_TYPES), drillTypeConfigSchema).optional()
  }).superRefine((cog, ctx) => {
    // Joint constraints the generators would otherwise silently rewrite. A
    // one-field patch is re-checked against stored values in updatePostConfig.
    for (const [type, cfg] of Object.entries(cog.drillTypes || {})) {
      for (const { field, message } of validateCognitivePair(type, cfg)) {
        ctx.addIssue({ code: 'custom', path: ['drillTypes', type, field], message });
      }
    }
  }).optional(),
  // Memory practice (issue #3252). Mirrors the other module blocks, plus an
  // `items` map so an INDIVIDUAL memorized text — e.g. the seeded Elements Song
  // — can be dropped from the daily rotation without deleting it (which would
  // throw away its mastery/schedule history). Keys are memory item ids, so this
  // is an open `z.string()` record rather than an enum.
  // Sparse maps preserve older-client saves when the registry gains a drill,
  // matching the other module blocks' incremental-update contract.
  memory: z.object({
    enabled: z.boolean().optional(),
    drillTypes: z.partialRecord(z.enum(MEMORY_DRILL_TYPES), drillTypeConfigSchema).optional(),
    // Keys are memory item ids — an open record, capped at the same 200 chars
    // every other id field here uses so a hand-edited config can't grow unbounded.
    items: z.record(z.string().max(200), z.object({ enabled: z.boolean().optional() })).optional()
  }).optional(),
  // Morse (issue #3252). Morse has no drill-type knobs here — its trainer owns
  // its own Koch settings — so the block is just the participation toggle that
  // suppresses the `morse-copy` stalled-progression recommendation.
  morse: z.object({
    enabled: z.boolean().optional()
  }).optional(),
  // Practice-topic participation (issue #3252) — the fine-grained "what am I
  // studying?" layer that sits ON TOP of the coarse `sessionModules` filter.
  // Absent entry = enabled (see server/lib/postTopics.js), so a config that
  // predates this key behaves exactly as before — additive, no migration.
  topics: z.partialRecord(z.enum(TOPIC_IDS), z.object({
    enabled: z.boolean().optional()
  })).optional(),
  sessionModules: z.array(z.enum(POST_MODULES)).optional(),
  quickDurationMin: postQuickDurationSchema.optional(),
  // Optional practice goals (issue #2100) — see postGoalsSchema above.
  goals: postGoalsSchema.optional(),
  scoring: z.object({
    weights: z.record(z.number().min(0).max(1)).optional()
  }).optional(),
  // Opt-in adaptive difficulty: when enabled, math drill params are nudged at
  // generation time from recent scored performance (server/lib/postAdaptive.js).
  // Default OFF so existing installs are unchanged — additive, no migration.
  adaptive: z.object({
    enabled: z.boolean().optional()
  }).optional(),
  // Opt-in daily reminder (default OFF, off by default). `time` is a 24h
  // "HH:MM" string interpreted in the user's configured timezone. The native
  // <input type="time"> can be cleared to '' by the user; treat that as
  // "no change" (absent) rather than a validation failure that would reject
  // the whole config PUT — same UI-sentinel-tolerance pattern AGENTS.md
  // documents for CLI provider endpoints.
  reminder: z.object({
    enabled: z.boolean().optional(),
    time: z.preprocess(
      v => (v === '' ? undefined : v),
      z.string().regex(HHMM_STRICT_RE, 'Must be HH:MM format').optional()
    )
  }).optional()
}).partial();

// Drill generation request
export const postDrillRequestSchema = z.object({
  type: z.enum(DRILL_TYPES),
  config: drillTypeConfigSchema.optional().default({}),
  providerId: z.string().optional(),
  model: z.string().optional()
});

// LLM drill scoring request
export const postLlmScoreRequestSchema = z.object({
  type: z.enum(LLM_DRILL_TYPES),
  drillData: z.unknown(),
  responses: z.array(llmResponseSchema).min(1).max(50),
  timeLimitMs: z.number().min(1000),
  providerId: z.string().min(1).max(300).optional(),
  model: z.string().min(1).max(300).optional()
}).superRefine((request, ctx) => {
  if (!['compound-chain', 'verbal-fluency'].includes(request.type)) return;
  const itemCount = request.responses.reduce((sum, response) => sum + (response.items?.length || 0), 0);
  if (itemCount > POST_LLM_MAX_SEMANTIC_CANDIDATES) {
    ctx.addIssue({
      code: 'custom',
      path: ['responses'],
      message: `semantic drill responses support at most ${POST_LLM_MAX_SEMANTIC_CANDIDATES} items per scoring batch`,
    });
  }
});

// One attempt is sent at a time by the trainer. The browser deliberately does
// not await this request before advancing to the next prompt, so this is a
// bounded single-item contract rather than a batch evaluator endpoint.
export const postRhetoricEvaluationRequestSchema = z.object({
  attemptId: z.string().trim().min(1).max(200),
  mode: z.enum(RHETORIC_MODE_IDS),
  prompt: z.string().trim().min(1).max(1000),
  response: z.string().trim().min(1).max(10000),
  providerId: z.string().trim().min(1).max(300).optional(),
  model: z.string().trim().min(1).max(300).optional(),
  effort: z.preprocess(
    value => (value === '' ? undefined : value),
    z.enum(EFFORT_LEVELS).nullable().optional(),
  ),
});

// Explicit, user-consented request to warm the wordplay drill cache
export const postDrillCacheFillSchema = z.object({
  types: z.array(z.enum(CACHEABLE_TYPES)).min(1).optional(),
  providerId: z.string().optional(),
  model: z.string().optional()
});

// =============================================================================
// MEMORY BUILDER VALIDATION
// =============================================================================

const memoryLineSchema = z.object({
  text: z.string().min(1),
  elements: z.array(z.string()).optional(),
});

const memoryChunkSchema = z.object({
  // Practice submits this id as a mastery key, so it takes the same check.
  id: masteryKeySchema,
  lineRange: z.array(z.number().int().min(0)).length(2),
  label: z.string(),
});

// Spaced-repetition schedule (SM-2 inspired). Server-managed via practice, but
// accepted on both POST (seed an imported item's progress) and PUT (persist an
// out-of-band reschedule). When absent the service stamps a fresh default.
export const memoryScheduleSchema = z.object({
  ease: z.number().min(1.3).max(5),
  intervalDays: z.number().min(0),
  nextReview: z.string(),
  lastReviewed: z.string().nullable().optional(),
});

export const memoryItemCreateSchema = z.object({
  title: z.string().min(1).max(200),
  type: z.enum(['song', 'poem', 'speech', 'sequence', 'text']).optional().default('text'),
  lines: z.array(z.union([z.string(), memoryLineSchema])).min(1),
  chunks: z.array(memoryChunkSchema).optional(),
  schedule: memoryScheduleSchema.optional(),
});

export const memoryItemUpdateSchema = z.object({
  title: z.string().min(1).max(200).optional(),
  type: z.enum(['song', 'poem', 'speech', 'sequence', 'text']).optional(),
  lines: z.array(z.union([z.string(), memoryLineSchema])).optional(),
  chunks: z.array(memoryChunkSchema).optional(),
  schedule: memoryScheduleSchema.optional(),
  mastery: z.object({
    overallPct: z.number().min(0).max(100).optional(),
    chunks: z.record(z.object({
      correct: z.number().int().min(0),
      attempts: z.number().int().min(0),
      lastPracticed: z.string().nullable().optional(),
      recent: z.array(z.union([z.literal(0), z.literal(1)])).max(10).optional(),
      masteredAt: z.string().optional(),
      masterySource: z.enum(['verified', 'attested']).optional(),
    })).optional(),
    elements: z.record(z.object({
      correct: z.number().int().min(0),
      attempts: z.number().int().min(0),
      recent: z.array(z.union([z.literal(0), z.literal(1)])).max(10).optional(),
      masteredAt: z.string().optional(),
      masterySource: z.enum(['verified', 'attested']).optional(),
    })).optional(),
    retention: z.object({
      status: z.enum(['learning', 'attested', 'mastered', 'lapsed']),
      attestedAt: z.string().nullable().optional(),
      masteredAt: z.string().nullable().optional(),
      spotCheckAt: z.string().nullable().optional(),
      spotCheckCompletedAt: z.string().nullable().optional(),
      lapsedAt: z.string().nullable().optional(),
    }).optional(),
  }).optional(),
});

const practiceResultSchema = z.object({
  correct: z.boolean(),
  word: z.string().optional(),
  element: masteryKeySchema.nullable().optional(),
  expected: z.string().optional(),
  answered: z.string().optional(),
  chunkId: masteryKeySchema.optional(),
});

export const memoryPracticeSchema = z.object({
  // `element-study` is the standalone flash-card study mode (ElementsSong.jsx) —
  // logged like `learn` and intentionally does not advance mastery. It is NOT a
  // POST-session drill type (no server generator, see generateMemoryDrill).
  mode: z.enum(['fill-blank', 'sequence', 'element-flash', 'element-study', 'learn', 'speed-run']),
  chunkId: masteryKeySchema.nullable().optional(),
  // Learn mode is an exposure event and legitimately has no scored results.
  // Every retrieval mode still needs at least one result.
  results: z.array(practiceResultSchema),
  totalMs: z.number().min(0).optional(),
}).superRefine((value, ctx) => {
  if (!['learn', 'element-study'].includes(value.mode) && value.results.length === 0) {
    ctx.addIssue({
      code: z.ZodIssueCode.too_small,
      minimum: 1,
      inclusive: true,
      origin: 'array',
      path: ['results'],
      message: 'Retrieval practice requires at least one result',
    });
  }
});

export const memoryMasteryAttestationSchema = z.object({
  acknowledged: z.literal(true),
});

export const memoryDrillRequestSchema = z.object({
  mode: z.enum(['fill-blank', 'sequence', 'element-flash']).optional().default('fill-blank'),
  memoryItemId: z.string().optional(),
  count: z.number().int().min(1).max(30).optional().default(5),
});

// =============================================================================
// MORSE TRAINER PROGRESS VALIDATION
// =============================================================================

// Server-side ceiling for a Koch level — KOCH_ORDER in MorseTrainer.jsx has 41
// entries. Mirrors MAX_KOCH_LEVEL in meatspacePostMorse.js.
const MORSE_MAX_KOCH_LEVEL = 41;

// One recorded prompt→guess character within a Morse round. `guessed` is
// nullable ('' or null = a miss, distinct from a wrong character); `sent` may be
// '' for an insertion (an extra typed character with no transmitted counterpart)
// — the server drops empty-sent items from the confusion matrix but still counts
// them against round accuracy. The `sent` key must still be present (a missing
// key is rejected); the server recomputes `correct` from the pair, so it's
// advisory here.
const morseRoundItemSchema = z.object({
  sent: z.string().max(8),
  guessed: z.string().max(16).nullable().optional(),
  correct: z.boolean().optional(),
  responseMs: z.number().min(0).optional().default(0),
});

// A completed copy/head-copy/send round the client submits on finish.
export const morseRoundSchema = z.object({
  mode: z.enum(['copy', 'head-copy', 'send']),
  kochLevel: z.number().int().min(1).max(MORSE_MAX_KOCH_LEVEL).optional(),
  wpm: z.number().min(1).max(100).optional(),
  farnsworthWpm: z.number().min(1).max(100).optional(),
  samplerVersion: z.string().max(40).optional(),
  materialMode: z.enum(['groups', 'words', 'callsigns', 'qso']).optional(),
  targetedChars: z.array(z.string().max(8)).max(41).optional(),
  // Bounded so a malformed client can't write (and then re-aggregate on every
  // progress read) an unbounded array. A legit round tops out well under this:
  // copy is 10 questions × ≤5-char groups (≈50, doubled by insertions), send is
  // one short prompt — 200 leaves generous headroom.
  items: z.array(morseRoundItemSchema).min(1).max(200),
  durationMs: z.number().min(0).optional().default(0),
});

// Explicit Koch level change (advance/reset) or a one-time localStorage adoption
// (`adopt: true` — server only applies it when it has never had a level).
export const morseLevelUpdateSchema = z.object({
  kochLevel: z.number().int().min(1).max(MORSE_MAX_KOCH_LEVEL),
  adopt: z.boolean().optional().default(false),
  settings: z.object({
    wpm: z.number().min(1).max(100).optional(),
    farnsworthWpm: z.number().min(1).max(100).optional(),
    toneHz: z.number().min(100).max(2000).optional(),
  }).optional(),
});

// =============================================================================
// PROGRESS DASHBOARD QUERY (issue #2091)
// =============================================================================

// GET /post/progress query params. `days` clamps like /post/stats: a NaN /
// missing value falls back to the 90-day default, a value >365 is clamped, and
// <=0 means all-time (0). `bucket` is forward-compat (only day buckets today).
export const postProgressQuerySchema = z.object({
  days: z.preprocess((v) => {
    if (v == null || v === '') return 90;
    const n = parseInt(v, 10);
    if (Number.isNaN(n)) return 90;
    if (n <= 0) return 0;
    return Math.min(n, 365);
  }, z.number().int()),
  bucket: z.enum(['day']).optional().default('day'),
});

// Per-question breakdown for a training-log entry (issue #2114 — follow-up to
// #2097, which only persisted round-level aggregates). Optional and additive:
// entries without it (legacy rows, and non-wordplay training modules that
// never populate it) must stay valid. Field names mirror llmResponseSchema
// above (the shape scored POST sessions store per LLM-drill question) so a
// future progress dashboard can render training-log and scored-session
// breakdowns with the same renderer rather than inventing a training-only shape.
const trainingQuestionSchema = z.object({
  id: z.string().min(1).max(200).optional(),
  prompt: z.string().optional(),
  response: z.string().optional(),
  items: z.array(z.string()).optional(),
  responseMs: z.number().min(0).optional(),
  selfRating: z.number().int().min(1).max(5).optional(),
  score: z.number().min(0).max(100).optional(),
  feedback: z.string().optional(),
  correct: z.boolean().optional(),
  evaluation: rhetoricEvaluationSchema.optional(),
  evaluationError: z.string().max(500).optional(),
});

// Training log entry submission
export const trainingEntrySchema = z.object({
  // Optional stable ids let newer callers retry through the legacy one-entry
  // adapter without duplication. Old callers remain valid and get server ids.
  id: z.string().min(1).max(200).optional(),
  runId: z.string().min(1).max(200).optional(),
  module: z.string(),
  // Training log entries also cover Morse (client-side scored, never a scored
  // POST session) — union in MORSE_DRILL_TYPES here rather than in the shared
  // DRILL_TYPES so postSessionSubmitSchema/postDrillRequestSchema can't accept
  // a Morse or rhetoric type (see the standalone-type comment above).
  drillType: z.enum([...DRILL_TYPES, ...MORSE_DRILL_TYPES, ...RHETORIC_DRILL_TYPES]),
  questionCount: z.number().int().min(0),
  correctCount: z.number().int().min(0),
  totalMs: z.number().min(0),
  questions: z.array(trainingQuestionSchema).optional(),
  difficulty: z.record(z.string(), z.unknown()).nullable().optional(),
  configVersion: z.string().max(100).nullable().optional(),
  correct: z.boolean().nullable().optional(),
  score: z.number().min(0).max(100).nullable().optional(),
  completion: z.number().min(0).max(1).nullable().optional(),
  hintUsed: z.boolean().optional(),
  confidence: z.number().min(0).max(1).nullable().optional(),
  inputMode: z.string().min(1).max(50).optional(),
  scorerProvenance: z.string().min(1).max(100).optional(),
});

const trainingAttemptSchema = z.object({
  id: z.string().min(1).max(200),
  module: z.string().min(1).max(100),
  drillType: z.enum([...DRILL_TYPES, ...MORSE_DRILL_TYPES, ...RHETORIC_DRILL_TYPES]),
  memoryItemId: z.string().min(1).max(200).nullable().optional(),
  difficulty: z.record(z.string(), z.unknown()).nullable().optional(),
  configVersion: z.string().max(100).nullable().optional(),
  questionCount: z.number().int().min(0),
  correctCount: z.number().int().min(0),
  latencyMs: z.number().min(0),
  drillData: z.any().optional(),
  // Deterministic drills retain answer/latency detail for ladder/adaptive
  // evidence; wordplay keeps its established compact training-question shape.
  questions: z.array(z.union([questionResultSchema, trainingQuestionSchema])).max(500).optional(),
  correct: z.boolean().nullable().optional(),
  score: z.number().min(0).max(100).nullable().optional(),
  completion: z.number().min(0).max(1).nullable().optional(),
  hintUsed: z.boolean().optional().default(false),
  confidence: z.number().min(0).max(1).nullable().optional(),
  inputMode: z.string().min(1).max(50).optional().default('unknown'),
  scorerProvenance: z.string().min(1).max(100).optional().default('post-client'),
  accuracy: z.number().min(0).max(1).nullable().optional(),
  avgResponseMs: z.number().min(0).nullable().optional(),
  answeredCount: z.number().int().min(0).optional(),
  totalCount: z.number().int().min(0).optional(),
  attemptCount: z.number().int().min(0).optional(),
  errorCount: z.number().int().min(0).optional(),
  medianMs: z.number().min(0).nullable().optional(),
  bestMs: z.number().min(0).nullable().optional(),
  span: z.number().int().min(0).optional(),
  hits: z.number().int().min(0).optional(),
  misses: z.number().int().min(0).optional(),
  omissions: z.number().int().min(0).optional(),
  commissionErrors: z.number().int().min(0).optional(),
  falseAlarms: z.number().int().min(0).optional(),
  correctRejections: z.number().int().min(0).optional(),
  switchCostMs: z.number().nullable().optional(),
  switchAccuracy: z.number().min(0).max(1).nullable().optional(),
  repeatAccuracy: z.number().min(0).max(1).nullable().optional(),
  congruencyCostMs: z.number().nullable().optional(),
  congruentAccuracy: z.number().min(0).max(1).nullable().optional(),
  incongruentAccuracy: z.number().min(0).max(1).nullable().optional(),
  falseAlarmRate: z.number().min(0).max(1).nullable().optional(),
  latencyDistributionMs: z.array(z.number().min(0)).max(500).optional(),
}).superRefine((attempt, ctx) => {
  if (attempt.correctCount > attempt.questionCount) {
    ctx.addIssue({ code: 'custom', path: ['correctCount'], message: 'correctCount cannot exceed questionCount' });
  }
});

// Complete training-run batch. Validation finishes before the service opens a
// transaction, so malformed attempt N can never leave attempts 0..N-1 saved.
export const trainingRunSubmitSchema = z.object({
  id: z.string().uuid(),
  mode: z.literal('training').optional().default('training'),
  startedAt: z.string().datetime().optional(),
  completedAt: z.string().datetime().optional(),
  planned: z.object({
    modules: z.array(z.string().min(1).max(100)).max(20).optional(),
    drillTypes: z.array(z.enum([...DRILL_TYPES, ...MORSE_DRILL_TYPES])).max(100).optional(),
  }).optional(),
  attempts: z.array(trainingAttemptSchema).min(1).max(100),
}).superRefine((run, ctx) => {
  const ids = new Set();
  run.attempts.forEach((attempt, index) => {
    if (ids.has(attempt.id)) ctx.addIssue({ code: 'custom', path: ['attempts', index, 'id'], message: 'attempt ids must be unique within a run' });
    ids.add(attempt.id);
  });
  if (run.startedAt && run.completedAt && Date.parse(run.completedAt) < Date.parse(run.startedAt)) {
    ctx.addIssue({ code: 'custom', path: ['completedAt'], message: 'completedAt cannot precede startedAt' });
  }
});

export { LLM_DRILL_TYPES, MATH_DRILL_TYPES, MEMORY_DRILL_TYPES, POST_SUPPORTED_MEMORY_TYPES, POST_MODULES, COGNITIVE_DRILL_TYPES, MORSE_DRILL_TYPES };