Semantic de-dup for AI-composed objectives

What changed, and why

"Compose a fresh objective with AI" already guarded against repeats — but only by normalized title. Fold the case and punctuation, compare as a set. That catches a verbatim or lightly-reskinned curated title, and nothing more. The same counterfactual under a new title sailed through: "Save the Library of Alexandria" and "Keep Alexandria's great library from the flames" read as two different goals.

This PR adds the check a title match can't do — a cheap model judge that decides whether a fresh candidate is essentially an existing objective reworded — plus a smarter reroll that tells the model what it just drew so the second attempt diverges.

Blast radius is small and server-only: one file carries the logic (server/utils/objective-generator.ts), one adds a routing lane, one adds an env knob. The route contract, the client, and the composed-objective shape are all unchanged. The whole thing is gated so it can be turned off or run in observe-only mode.

A new routing lane

Every model call in everwhen names a task in one routing table. The judge gets its own lane, objective-dedup, alongside the sibling bounds check: Haiku at temperature 0, a cheap classifier off the critical path. Haiku rejects the effort and thinking params, so — like its sibling — the lane carries neither. It is added to the AiTask union too, which forces the table to define it (the map is keyed by the union), so a missing route is a compile error, not a runtime surprise.

The new lane — same shape as the objective-check bounds classifier.

server/utils/ai-routing.ts · 270 lines

server/utils/ai-routing.ts270 lines · TypeScript

⋯ 212 lines hidden (lines 1–212)1/**
* The per-task model routing table — the provider seam the go-to-market plan
* calls for (dispatch 1's bake-off lives behind this file). Every AI task names
* its lane and its full parameter payload here, because valid parameter sets
* differ by model family:
*
*   - Haiku 4.5 rejects `effort` and has no adaptive thinking — omit both.
*   - Sonnet 4.6 defaults `effort` to HIGH — always set it explicitly (this game
*     wants reflexes, not deliberation). `temperature` is accepted.
*   - Opus 4.8 rejects `temperature`/`top_p`/`top_k` — steer tone via prompts.
*     Thinking is adaptive-only; omitting `thinking` runs without thinking.
*
* Lane defaults were decided by the two-lane bake-off plus the prompt-tuning
* campaign (evals/bakeoff.eval.ts, evals/prompt-tune.eval.ts; snapshots +
* verdict in evals/results/) — quality-first, with cost a close second. Every
* task runs the Anthropic lane: the prose tellings initially lost the blind
* pairwise 19-0 under the shared prompt, and the Claude-voice rewrite
* (buildChroniclePromptClaude) won them back on Sonnet. The OpenAI lane stays
* fully alive behind EVERWHEN_AI_LANE so a forced reverse migration is a
* config change, not a rewrite (the GTM's platform-risk counter).
*/
22 
23export type AiTask =
| "judge"
| "character"
| "timeline"
| "reach-rater"
| "chronicler"
| "epilogue"
| "archivist-study"
| "archive-lookup"
| "objective"
| "objective-check"
| "objective-dedup"
| "suggester"
| "lifespan"
| "disambiguate"
| "sentinel";
39 
40/** 'fixture' is the dev-only deterministic lane (issue #105): a scripted structured
*  output, no model call. Never selected by `routeFor` (the table is anthropic/openai
*  only) — the gateway short-circuits to it when a dev fixture is installed, behind
*  the dev gate. It exists in the union so telemetry can label a fixtured call. */
44export type AiLane = "anthropic" | "openai" | "fixture";
45 
46export interface AnthropicParams {
model: string;
maxTokens: number;
/** Omit on Opus-tier models — the API rejects sampling params there. */
temperature?: number;
/** Omit on Haiku 4.5 — the API rejects the effort parameter there.
 *  'xhigh' exists on Opus 4.7+ and Fable 5 only. */
effort?: "low" | "medium" | "high" | "xhigh";
/** 'adaptive' turns thinking on (billed as output); omitted = no thinking. */
thinking?: "adaptive";
56}
57 
58export interface OpenAiParams {
model: string;
/** gpt-5.5 bills hidden reasoning inside this cap — keep generous headroom. */
maxTokens: number;
reasoningEffort?: "low" | "medium" | "high";
63}
64 
65export interface TaskRoute {
lane: AiLane;
anthropic: AnthropicParams;
openai: OpenAiParams;
69}
70 
71/** The OpenAI lane's flagship — one place, like the old exported MODEL constant. */
72const GPT = "gpt-5.5";
73const OPENAI_DEFAULTS: OpenAiParams = {
model: GPT,
maxTokens: 1200,
reasoningEffort: "low",
77};
78 
79/**
* With thinking off, Anthropic's max_tokens is TRUE output budget — no hidden
* reasoning billed inside it — so caps are sized to real output shapes instead
* of the old padded 1200.
*/
84export const AI_ROUTES: Record<AiTask, TaskRoute> = {
// A rubric classifier in the critical path of every dispatch (it runs before
// the die). Haiku for speed; the calibration eval is its gate.
// #164 (SETTLED 2026-06-28): the bake-off ran (judge-tune.eval.ts, anthropic lane)
// and KEPT Haiku-with-rubric over the once-planned Sonnet bump. With the #167 rubric
// nudge, Haiku makes the top grades reachable (masterful 78% of rung-0 excellent
// messages vs Sonnet's 33% — a LIVE top-craft reward, not a dead one), anchors the
// middle marginally better (mean dev 0.26 vs 0.30), and holds the discrimination
// floor (0 hard violations both). Bumping to Sonnet would have RE-DEADENED the
// masterful reward the +2 CRAFT_MODIFIER / 1.45x CRAFT_GAIN_FACTOR ride on. Verdict
// + numbers: evals/results/2026-06-28-judge-route-164.md.
judge: {
  lane: "anthropic",
  anthropic: { model: "claude-haiku-4-5", maxTokens: 300, temperature: 0 },
  openai: OPENAI_DEFAULTS,
},
// The player converses with this output every turn — prose is product.
character: {
  lane: "anthropic",
  anthropic: {
    model: "claude-sonnet-4-6",
    maxTokens: 700,
    temperature: 0.9,
    effort: "low",
  },
  openai: OPENAI_DEFAULTS,
},
// The rules-critical judgment layer; code clamps swings into the rolled band,
// the model places the swing within it (anachronism is rated separately, by the
// reach-rater, and amplifies the result deterministically). Output is four small
// fields now (#163 moved anachronism out): a ~9-word headline, a 1-2 sentence
// detail, an integer swing, and a valence enum — well under 150 output tokens.
// maxTokens trimmed 600 -> 300 (#164) to fit that real shape; with thinking off
// it's a true output ceiling, and 300 still leaves >2x headroom. temp/effort
// unchanged — the last bake-off held them at 4/4 band ordering and a 7.0 neutral
// corridor, and no fresh signal moved them.
timeline: {
  lane: "anthropic",
  anthropic: {
    model: "claude-sonnet-4-6",
    maxTokens: 300,
    temperature: 0.3,
    effort: "medium",
  },
  openai: OPENAI_DEFAULTS,
},
// The anachronism reach-rater (issue #163): rates how far beyond the figure's
// own era a message reaches — message × era only, BLIND to goal, dice, progress,
// and ledger, so the wager tier can't flex with the outcome it amplifies. A cheap
// temp-0 Haiku classifier off the critical generation path (it runs alongside the
// Judge, before the roll); its tier feeds the deterministic anachronism amplifier.
// Re-confirmed post-split (#164): Haiku/temp-0 is the cheapest tier that rates
// reach reliably (the canonical classifier setting), and the output is two small
// fields — a one-phrase reach gloss plus the tier enum, ~40 output tokens — so the
// 200 cap stays (a true ceiling well clear of the real shape; trimming it saves no
// cost, only risks clipping the tier-anchoring reach phrase). Held as-is.
"reach-rater": {
  lane: "anthropic",
  anthropic: { model: "claude-haiku-4-5", maxTokens: 200, temperature: 0 },
  openai: OPENAI_DEFAULTS,
},
// Re-narrates the whole timeline each turn. The original bake-off lost this
// slot 9-0 under the shared prompt; the Claude-voice rewrite (V2's
// transmission-chain bar, buildChroniclePromptClaude) won it back 8-5 in
// blind pairwise on Sonnet at ~1/4 the prior cost-per-telling — and the
// incumbent lane's quota outage made the flip availability-driven too.
// Higher-N confirmation pending (evals/results/2026-06-11-verdict.md).
chronicler: {
  lane: "anthropic",
  anthropic: {
    model: "claude-sonnet-4-6",
    maxTokens: 2000,
    temperature: 1,
    effort: "high",
  },
  openai: OPENAI_DEFAULTS,
},
// The final telling — the share artifact and the thing people pay for. The
// Claude-voice V1 prompt on SONNET beat the incumbent 16-3 across two
// dual-graded rounds (7-3, then 9-0 at N=12) — decisively confirmed, and
// cheaper than the Opus/Fable candidates it outscored. Sonnet over Opus is
// what the data said, twice; Fable won too but at 4x Sonnet's price for no
// measured gain over it.
epilogue: {
  lane: "anthropic",
  anthropic: {
    model: "claude-sonnet-4-6",
    maxTokens: 2000,
    temperature: 1,
    effort: "high",
  },
  openai: OPENAI_DEFAULTS,
},
// Feeds the player's wager calibration — accuracy matters.
"archivist-study": {
  lane: "anthropic",
  anthropic: {
    model: "claude-sonnet-4-6",
    maxTokens: 800,
    temperature: 0.5,
    effort: "low",
  },
  openai: OPENAI_DEFAULTS,
},
// Factual micro-answers with a known-since stamp.
"archive-lookup": {
  lane: "anthropic",
  anthropic: { model: "claude-haiku-4-5", maxTokens: 500, temperature: 0.3 },
  openai: OPENAI_DEFAULTS,
},
// 0-1 calls per run; the objective steers every layer's valence.
objective: {
  lane: "anthropic",
  anthropic: {
    model: "claude-sonnet-4-6",
    maxTokens: 600,
    temperature: 1,
    effort: "low",
  },
  openai: OPENAI_DEFAULTS,
},
// Gates a freshly composed objective on the safely-historical bounds (#71): a
// cheap, temp-0 classifier (the figure-floor pattern) that catches the
// living-people / current-events framings a year bound alone can't. Haiku,
// off the critical generation path — at most twice per composition.
"objective-check": {
  lane: "anthropic",
  anthropic: { model: "claude-haiku-4-5", maxTokens: 200, temperature: 0 },
  openai: OPENAI_DEFAULTS,
},
// Semantic de-dup of a freshly composed objective (#95 follow-up): a cheap
// temp-0 Haiku judge asked whether the candidate is essentially an existing
// objective (the curated pool + the session's seen titles) reworded — the
// near-duplicate a normalized-title match can't see. Off the critical path;
// at most twice per composition, and only for candidates the free title check
// already let through.
"objective-dedup": {
  lane: "anthropic",
  anthropic: { model: "claude-haiku-4-5", maxTokens: 200, temperature: 0 },
  openai: OPENAI_DEFAULTS,
},
// Tool-using agent verified against free grounding, curated floor beneath it.
⋯ 45 lines hidden (lines 226–270)226  // maxTokens here is per ROUND of the agent loop.
suggester: {
  lane: "anthropic",
  anthropic: { model: "claude-haiku-4-5", maxTokens: 1500, temperature: 0.7 },
  openai: { model: GPT, maxTokens: 2500 },
},
// A dates classifier with hard validation guards behind it (issue #31 bridge).
lifespan: {
  lane: "anthropic",
  anthropic: { model: "claude-haiku-4-5", maxTokens: 300, temperature: 0 },
  openai: OPENAI_DEFAULTS,
},
// Contextual name disambiguation (#186): picks the candidate that fits the run's
// objective/era from the same-name people the deterministic floor surfaced. A cheap
// temp-0 Haiku classifier, off the critical generation path (the interactive picker),
// with the most-notable pick as the floor beneath it. Output is two small fields.
disambiguate: {
  lane: "anthropic",
  anthropic: { model: "claude-haiku-4-5", maxTokens: 200, temperature: 0 },
  openai: OPENAI_DEFAULTS,
},
// The safety Sentinel — classifies a whole exchange against the verbatim
// Usage Policy (server/utils/usage-policy.ts). Haiku at temp 0 for a
// consistent, cheap classifier, exactly the tier Anthropic's content-
// moderation guide recommends. Runs once per user action, never on the
// critical generation path's tokens.
sentinel: {
  lane: "anthropic",
  anthropic: { model: "claude-haiku-4-5", maxTokens: 400, temperature: 0 },
  openai: OPENAI_DEFAULTS,
},
257};
258 
259/**
* Resolves a task to its lane + parameters. EVERWHEN_AI_LANE overrides the
* whole table ('openai' | 'anthropic') — the emergency lever, and how the eval
* matrix runs identical fixtures down each lane.
*/
264export function routeFor(task: AiTask): { lane: AiLane; route: TaskRoute } {
const route = AI_ROUTES[task];
const override = process.env.EVERWHEN_AI_LANE;
const lane =
  override === "openai" || override === "anthropic" ? override : route.lane;
return { lane, route };
270}

Orchestration: the free check first, then two judges in parallel

generateObjective is the loop that composes, validates, and — at most once — rerolls before falling back to curated. Read it top to bottom:

- The free normalized-title set still runs first (line 114). An exact or reskinned collision short-circuits here and spends nothing — no bounds call, no judge call. - Only a candidate that clears that free check reaches the paid checks, and they run together (lines 119-122): objectiveWithinBounds (safety) and objectiveIsDuplicate (freshness), concurrently. Acceptance needs both to pass: inBounds && !dup.duplicate (line 123). - Whatever the reason for a rejection — out of bounds, or a duplicate — it is captured and pushed onto rejected (lines 129-133), which feeds the next attempt.

Compose → free-title check → parallel bounds+dedup → reroll, capped at 2 attempts.

server/utils/objective-generator.ts · 541 lines

server/utils/objective-generator.ts541 lines · TypeScript

⋯ 99 lines hidden (lines 1–99)1/**
* Live, AI-composed objectives. The curated pool + the GameObjective shape live
* in ./objectives (pure, client-safe); this module owns the model path and is
* therefore SERVER-ONLY — it reaches the AI gateway (and through it the model
* SDKs + the AsyncLocalStorage run-context, which must never enter the browser
* bundle). Client code imports the curated pool + the steer enums from ./objectives
* directly.
*
* A composition is bounded AND steerable (#71):
*  - BOUNDED — the prompt is constrained to safely-historical objectives, and the
*    output is independently validated (the prompt alone isn't trusted): a finite
*    anchor year must sit at or before the shared safely-historical line, a small
*    structured check gates the living-people / current-events framings free prose
*    can smuggle past a year bound, and the text runs through the same moderation
*    seam as messages. Out of bounds → reroll once, then fall back to curated. The
*    curated pool is always the floor; a generation or validation failure never
*    hard-fails the run start, it just yields a curated objective.
*  - STEERED — the player biases the composition along two closed enums (era +
*    theme); see ObjectiveSteer in ./objectives.
*  - FRESH (#95) — a composition may reproduce neither the curated pool nor
*    anything composed earlier this session. Two guards: a free normalized-title
*    match catches verbatim / lightly-reskinned repeats, and a cheap Haiku judge
*    (objectiveIsDuplicate) catches the semantic near-duplicate a title match
*    can't see — the same objective, reworded. A rejected attempt is fed back into
*    the single reroll so it diverges instead of re-drawing the same subject;
*    a persistent collision falls back to an unseen curated pick.
*/
28import {
pickCurated,
listCuratedObjectives,
normalizeObjectiveTitle,
type GameObjective,
type ObjectiveSteer,
34} from "./objectives";
35import { SAFELY_HISTORICAL_BEFORE_YEAR } from "./historical-floor";
36 
37/**
* What generateObjective produced: the objective plus its provenance. `composed`
* is true ONLY when the live AI path yielded this objective; it is false for the
* curated floor — both the default no-AI path and every AI fallback (a generation,
* bounds, or de-dup failure). The endpoint pairs `composed === false` with a
* requested steer to tell the player their steer was quietly dropped (#127), instead
* of letting a silent curated fallback read as "steering is broken".
*/
45export interface GeneratedObjective {
objective: GameObjective;
composed: boolean;
48}
49 
50/**
* A composed candidate this call already rejected (out of bounds or a duplicate),
* fed back into the reroll so the second attempt is told what NOT to draw again.
*/
54interface RejectedComposition {
title: string;
description: string;
reason: string;
58}
59 
60/** A semantic de-dup verdict: is the candidate an existing objective reworded? */
61interface DedupVerdict {
duplicate: boolean;
/** The nearest existing title the judge matched against (telemetry / the reroll). */
closestMatch: string;
/** One short clause on the call — surfaced to the reroll and the [objdedup] log. */
reason: string;
67}
68 
69/**
* Returns an objective for a new run, plus whether the live AI path composed it (vs
* the curated floor). Curated-random by default (instant, no API call); pass
* useAI=true to compose one live under the given steer, with automatic fallback to
* curated. Never throws and never ships an out-of-bounds objective.
*
* `avoid` (#95) is the session's already-composed titles — the only anti-repeat
* memory the stateless server has (the client tracks and supplies them; the curated
* pool the server already knows). A composed result may reproduce NEITHER the
* curated pool NOR anything seen this session: a free normalized-title match catches
* exact / reskinned repeats, and a Haiku judge (objectiveIsDuplicate) catches the
* semantic near-duplicate a title match misses. A collision is rerolled once — the
* rejected attempt fed back so the reroll diverges — then the curated FALLBACK itself
* avoids the seen titles, so even the floor stays fresh.
*/
84export async function generateObjective(
useAI = false,
steer: ObjectiveSteer = {},
avoid: string[] = [],
88): Promise<GeneratedObjective> {
// The curated pool — the far half of the free de-dup Set and the candidate list
// the semantic judge compares against. (The compose exemplars and the fallback
// floor re-read the pool through their own helpers.)
const curated = listCuratedObjectives();
// Session-seen titles, normalized — used both for the curated fallback (so it
// never re-serves a seen objective) and, unioned with the curated pool below,
// for the free post-generation collision guard.
const seen = new Set(avoid.map(normalizeObjectiveTitle).filter(Boolean));
const dedupe = new Set(seen);
for (const o of curated) dedupe.add(normalizeObjectiveTitle(o.title));
99 
if (useAI) {
  // Never ship out of bounds OR a duplicate, never hard-fail the run: compose
  // live, and on an out-of-bounds / colliding result reroll exactly once, then
  // fall back to the (unseen) curated floor. Each rejected attempt is fed back
  // into the reroll so the second draw diverges rather than repeating itself. A
  // transport/parse failure won't heal on a reroll, so it drops straight to
  // curated instead of a second call.
  const rejected: RejectedComposition[] = [];
  for (let attempt = 1; attempt <= 2; attempt++) {
    try {
      const candidate = await composeObjective(steer, avoid, rejected);
      let reason: string;
      // The free normalized-title match short-circuits ahead of the paid checks:
      // an exact / reskinned collision never spends a bounds or de-dup call.
      if (dedupe.has(normalizeObjectiveTitle(candidate.title))) {
        reason = "duplicates an existing objective";
      } else {
        // Bounds (safety, fail-closed) and the semantic de-dup judge (freshness,
        // fail-open) are independent — run them together; either one rejects.
        const [inBounds, dup] = await Promise.all([
          objectiveWithinBounds(candidate),
          objectiveIsDuplicate(candidate, curated, avoid),
        ]);
        if (inBounds && !dup.duplicate)
          return { objective: candidate, composed: true };
        reason = !inBounds
          ? "outside the safely-historical bounds"
          : dup.reason || "too close to an existing objective";
      }
      rejected.push({
        title: candidate.title,
        description: candidate.description,
        reason,
      });
      console.warn(
        `AI objective rejected (${reason}) on attempt ${attempt} of 2; ${attempt < 2 ? "rerolling" : "falling back to curated"}`,
      );
    } catch (error) {
      console.error(
        "AI objective generation failed; falling back to curated pool:",
        error,
      );
      break;
    }
  }
}
⋯ 396 lines hidden (lines 146–541)146  // The curated floor — reached by the default no-AI path or any AI fallback.
return { objective: pickCurated(seen), composed: false };
148}
149 
150/**
* Composes one fresh objective with the model under the steer, steering away from
* the session's seen titles and any attempt already rejected this call. Returns the
* same shape as the curated pool so the rest of the game treats them identically.
* Throws on an empty/malformed answer (the caller owns the fallback).
*/
156async function composeObjective(
steer: ObjectiveSteer,
seenTitles: string[] = [],
rejected: RejectedComposition[] = [],
160): Promise<GameObjective> {
// Imported lazily so the curated (default) path never pulls the model SDKs
// into the bundle.
const { completeStructured } = await import("./ai-gateway");
164 
const content = await completeStructured({
  task: "objective",
  system: composeSystemPrompt(),
  turns: [
    { role: "user", content: composeUserPrompt(steer, seenTitles, rejected) },
  ],
  schemaName: "game_objective",
  schema: {
    type: "object",
    properties: {
      title: { type: "string", description: "Punchy objective title" },
      description: {
        type: "string",
        description:
          'A grounded brief: a few newline-separated "• " bullet lines stating the real-timeline date(s) and place this departs from in our history, what winning looks like, and where it is centered (or, if global/cross-era, said so with the span named)',
      },
      era: { type: "string", description: "Anchoring era / setting" },
      icon: {
        type: "string",
        description: "A single emoji that fits the objective",
      },
      anchorYear: {
        type: ["integer", "null"],
        description: `Signed year the objective is aimed at (negative for BC), at or before ${SAFELY_HISTORICAL_BEFORE_YEAR}, or null if it spans all history`,
      },
    },
    required: ["title", "description", "era", "icon", "anchorYear"],
    additionalProperties: false,
  },
});
195 
if (!content) throw new Error("No objective generated");
197 
const parsed = JSON.parse(content) as GameObjective;
if (!parsed.title || !parsed.description)
  throw new Error("Invalid objective format generated");
return {
  title: parsed.title,
  description: parsed.description,
  era: parsed.era || "Across the ages",
  icon: parsed.icon || "🕰️",
  // A finite signed year anchors the chain dial; null / junk → no anchor (no-op).
  anchorYear:
    typeof parsed.anchorYear === "number" &&
    Number.isFinite(parsed.anchorYear)
      ? Math.round(parsed.anchorYear)
      : undefined,
};
213}
214 
215/**
* Validates a composed objective against the safely-historical bounds (#71) —
* the prompt is asked to obey them, but never trusted to. Three gates: a pure year
* bound, the same moderation seam messages pass through, and a structured subject
* check for the living-people / current-events framings a year bound can't see.
* Never throws. The year and subject gates fail CLOSED — an inconclusive result
* (junk, an empty answer, an outage) reads as out of bounds, so an unvetted
* composition falls back to curated rather than shipping. Moderation fails OPEN,
* the same fail-open-but-loud seam messages pass through (a safety classifier
* being down must never take the game down); it rejects only on an active flag.
*/
226async function objectiveWithinBounds(o: GameObjective): Promise<boolean> {
// 1. Year bound — pure, deterministic, free. A finite anchor must sit at or
//    before the safely-historical line; a null anchor (spans-all-history) is
//    allowed, its content still gated by the subject check below.
if (
  typeof o.anchorYear === "number" &&
  o.anchorYear > SAFELY_HISTORICAL_BEFORE_YEAR
)
  return false;
235 
const text = `${o.title}\n${o.description}`;
// 2 + 3 are independent model/detector calls — run them together; first "out"
//    wins. Lazy import keeps moderation (and its SDKs) off the curated path.
const { hardBlockCheck } = await import("./moderation");
const [mod, subjectInBounds] = await Promise.all([
  hardBlockCheck(text, "objective", "output"),
  checkObjectiveSubject(o),
]);
if (mod.blocked) return false;
return subjectInBounds;
246}
247 
248/**
* The structured subject check (the figure-floor pattern, server/utils/
* lifespan-estimator.ts): a cheap classifier that gates the free-prose title +
* description a year bound can't reach — does this center on living people,
* contemporary figures, ongoing conflicts, or post-cutoff events? Fails CLOSED:
* an empty answer, junk, or an outage returns false, so an unvetted objective is
* never shipped (it falls back to the safe curated floor instead). Never throws.
*/
256async function checkObjectiveSubject(o: GameObjective): Promise<boolean> {
const { completeStructured } = await import("./ai-gateway");
try {
  const content = await completeStructured({
    task: "objective-check",
    system: boundsCheckSystemPrompt(),
    turns: [
      {
        role: "user",
        content: `Title: ${o.title}\nDescription: ${o.description}\nEra: ${o.era}\nAnchor year: ${o.anchorYear ?? "none (spans all history)"}`,
      },
    ],
    schemaName: "objective_bounds",
    schema: {
      type: "object",
      properties: {
        withinBounds: {
          type: "boolean",
          description:
            "True only when the subject is safely historical (settled past, no living people or current events)",
        },
        reason: {
          type: "string",
          description: "One short clause on the call",
        },
      },
      required: ["withinBounds", "reason"],
      additionalProperties: false,
    },
  });
  if (!content) return false; // the model blipped — fail closed to the curated floor
  return mapBoundsWire(JSON.parse(content)) === true;
} catch (error) {
  console.error("Objective bounds check error:", error);
  return false; // an outage must never let an unvetted objective through
}
292}
293 
294/**
* The bounds-check wire → a clean verdict. `null` for an unusable shape (missing /
* non-boolean flag), which the caller treats exactly like "out of bounds". Exported
* pure so the guard is directly testable, like mapLifespanWire.
*/
299export function mapBoundsWire(wire: unknown): boolean | null {
const w = wire as { withinBounds?: unknown } | null;
if (!w || typeof w.withinBounds !== "boolean") return null;
return w.withinBounds;
303}
304 
305/**
* Semantic de-dup (#95 follow-up). The free normalized-title match in
* generateObjective catches verbatim / reskinned repeats; this catches the ones it
* can't — the SAME objective reworded under a fresh title ("Save the Library of
* Alexandria" vs "Keep Alexandria's great library from the flames"). A cheap Haiku
* judge compares the candidate against everything already on offer (the curated pool
* in full, plus the session's seen titles) and answers: is this essentially one of
* them again?
*
* Freshness, not safety, so this fails OPEN: an outage, empty answer, or junk verdict
* reads as "not a duplicate" and ships (the opposite stance from the bounds gate — a
* de-dup classifier being down must never cost the player a composition). Modes via
* EVERWHEN_OBJECTIVE_DEDUP mirror moderation: 'off' skips the call, 'shadow' runs and
* logs what it WOULD reject without acting, 'enforce' (default) rejects for real.
* Never throws.
*/
321async function objectiveIsDuplicate(
candidate: GameObjective,
curated: GameObjective[],
seenTitles: string[],
325): Promise<DedupVerdict> {
const fresh: DedupVerdict = {
  duplicate: false,
  closestMatch: "",
  reason: "",
};
const mode = objectiveDedupMode();
if (mode === "off") return fresh;
333 
let verdict: DedupVerdict;
try {
  const { completeStructured } = await import("./ai-gateway");
  const content = await completeStructured({
    task: "objective-dedup",
    system: dedupSystemPrompt(),
    turns: [
      {
        role: "user",
        content: dedupUserPrompt(candidate, curated, seenTitles),
      },
    ],
    schemaName: "objective_dedup",
    schema: {
      type: "object",
      properties: {
        // Fact-retrieval before the decision it informs (schema order is
        // load-bearing): name the nearest existing objective first, then judge.
        closestMatch: {
          type: "string",
          description:
            'Title of the nearest existing objective, or "none" if nothing is close',
        },
        duplicate: {
          type: "boolean",
          description:
            "True only when the candidate is essentially that existing objective reworded — the same counterfactual, not merely the same era or theme",
        },
        reason: {
          type: "string",
          description: "One short clause on the call",
        },
      },
      required: ["closestMatch", "duplicate", "reason"],
      additionalProperties: false,
    },
  });
  // Fail open on an unusable verdict — a de-dup blip must not drop a composition.
  verdict = (content && mapDedupWire(JSON.parse(content))) || fresh;
} catch (error) {
  console.error("Objective de-dup check error:", error);
  return fresh; // freshness fails open — never take a composition down
}
377 
if (verdict.duplicate) {
  emitObjDedup({
    mode,
    wouldReject: true,
    enforced: mode === "enforce",
    closestMatch: verdict.closestMatch,
    candidate: candidate.title,
  });
  if (mode === "shadow") return fresh; // observe without biting — ship it
}
return verdict;
389}
390 
391/** EVERWHEN_OBJECTIVE_DEDUP: off | shadow | enforce (default enforce), the same
*  three-mode shape as EVERWHEN_MODERATION. */
393function objectiveDedupMode(): "off" | "shadow" | "enforce" {
const m = process.env.EVERWHEN_OBJECTIVE_DEDUP;
return m === "off" || m === "shadow" ? m : "enforce";
396}
397 
398/** One greppable [objdedup] line per flagged duplicate — the calibration
*  instrument for shadow mode. Quiet under tests, like [mod]. */
400function emitObjDedup(line: Record<string, unknown>): void {
if (!process.env.VITEST) console.info(`[objdedup] ${JSON.stringify(line)}`);
402}
403 
404/**
* The de-dup wire → a clean verdict, or `null` for an unusable shape (a missing /
* non-boolean flag), which the caller treats as "not a duplicate" (fail open).
* Exported pure so the guard is directly testable, like mapBoundsWire.
*/
409export function mapDedupWire(wire: unknown): DedupVerdict | null {
const w = wire as {
  duplicate?: unknown;
  closestMatch?: unknown;
  reason?: unknown;
} | null;
if (!w || typeof w.duplicate !== "boolean") return null;
return {
  duplicate: w.duplicate,
  closestMatch: typeof w.closestMatch === "string" ? w.closestMatch : "",
  reason: typeof w.reason === "string" ? w.reason : "",
};
421}
422 
423/** System prompt for the semantic de-dup judge. */
424function dedupSystemPrompt(): string {
return `You are a de-dup check for a historical strategy game. You are given a freshly composed objective and the list of objectives already on offer. Decide whether the new one is essentially one of the existing objectives reworded.
426 
427Mark it a DUPLICATE (duplicate=true) when it aims at the SAME counterfactual as an existing objective — the same pivotal event, person, or outcome — even if the title, wording, era label, or framing differ ("Save the Library of Alexandria" and "Keep Alexandria's great library from the flames" are the same objective).
428 
429Mark it NOT a duplicate (duplicate=false) when it targets a genuinely different event, person, place, or outcome — even if it shares a broad theme (war, science, empire) or era with an existing one. Sharing a subject is not enough; aiming at the same specific turning point is.
430 
431Name the closest existing title in closestMatch (or "none"), then decide, then give one short reason.`;
432}
433 
434/** De-dup user turn: the candidate, then everything already on offer (the curated
*  pool in full, plus the session's seen titles). */
436function dedupUserPrompt(
candidate: GameObjective,
curated: GameObjective[],
seenTitles: string[],
440): string {
const existing = [
  ...curated.map((o) => `• ${o.title} — ${o.description}`),
  ...seenTitles.map((t) => `• ${t}`),
].join("\n");
return `CANDIDATE objective:
446Title: ${candidate.title}
447Description: ${candidate.description}
448 
449Objectives ALREADY on offer:
450${existing}
451 
452Is the candidate essentially one of the objectives already on offer, reworded?`;
453}
454 
455/** System prompt for composition: the tone bar, the grounding bar, and the
*  non-negotiable safety bounds. */
457function composeSystemPrompt(): string {
return `You are a historian and game designer inventing grand, evocative counterfactual objectives for a game where players text historical figures to bend history.
459 
460Hold every objective to three bars:
461 
462TONE — sweeping and vivid, a whole world to remake in the spirit of the examples, never a small errand.
463 
464GROUNDING (issue #82) — every brief names the real-timeline date(s) and the place it departs from in our history, so a player who is not American and does not already know the date still gets a concrete anchor. Never assume the reader's frame.
465 
466BOUNDS (safety, non-negotiable) — the objective must be safely historical:
467- Set in the settled past. Any pivotal anchor year must be at or before ${SAFELY_HISTORICAL_BEFORE_YEAR}.
468- Never centered on, and never requiring contact with, living people, contemporary public figures, ongoing conflicts, or current events. Reach for history, not the present or the recent past.`;
469}
470 
471/** Composition user turn: curated few-shot exemplars (framed as territory already
*  taken, never a menu to copy), the session avoid-list, any attempt already
*  rejected this call, the steer, and the ask. */
474function composeUserPrompt(
steer: ObjectiveSteer,
seenTitles: string[],
rejected: RejectedComposition[] = [],
478): string {
return `Objectives we love — match their TONE, SCALE, and brief SHAPE, but treat their SUBJECTS as territory already taken. Invent something genuinely new; vary away from every one in subject, era, and region. Do NOT reproduce or lightly reskin them (especially over-familiar picks like "Save the Library of Alexandria"):
480${curatedExemplars()}
481${avoidClause(seenTitles)}${rejectedClause(rejected)}
482Invent ONE fresh objective, unlike anything above — a different subject, era, and region from the examples${seenTitles.length ? " and from anything already composed this session" : ""}.${steerClause(steer)}
483 
484Give it: a punchy title; an anchoring era; a single emoji; the anchor year it is aimed at (the pivotal year where winning is decided) as a SIGNED integer — negative for BC, at or before ${SAFELY_HISTORICAL_BEFORE_YEAR} — or null if it genuinely spans all of history with no single hinge; and a GROUNDED BRIEF as the description.
485 
486The brief is a few short bullet lines, each beginning with "• " and separated by newlines (the same shape as the examples above), that together state: (1) when and where this actually happened or ended in OUR timeline, with real dates; (2) what winning looks like; (3) where on Earth it is centered — name the region or country, or, if it genuinely spans the globe or all eras, say so and name the span rather than forcing one country. Put the real date IN the brief; the real-timeline date(s) are NOT the anchor year — state the actual history, never merely restate the anchor. Keep each bullet tight.`;
487}
488 
489/** System prompt for the structured subject check. */
490function boundsCheckSystemPrompt(): string {
return `You are a safety check for a historical strategy game. You are given a freshly generated objective (title, description, era, anchor year). Decide whether it stays safely in the settled past.
492 
493Mark it OUT OF BOUNDS (withinBounds=false) if it centers on, or would require contacting, any of:
494- a living person or a present-day public figure,
495- an ongoing conflict or a current event,
496- anything anchored after the year ${SAFELY_HISTORICAL_BEFORE_YEAR}.
497 
498Mark it IN BOUNDS (withinBounds=true) only when its subject is historical — people and events settled in the past, before living memory. Dramatic history is fine (wars, plagues, empires, revolutions); the test is WHEN and WHO, not how grand.
499 
500When you are unsure, answer withinBounds=false. Give a short reason either way.`;
501}
502 
503/** The curated pool rendered as few-shot exemplars (title — description), read
*  live from the pool so the bar can never drift from a hardcoded copy. */
505function curatedExemplars(): string {
return listCuratedObjectives()
  .map((o) => `• ${o.title} — ${o.description}`)
  .join("\n");
509}
510 
511/** The session's already-composed titles, listed so the model steers away from
*  repeating them (#95). Empty when nothing's been rolled yet — the first compose
*  carries no clause, so an unseeded prompt stays identical to before. */
514function avoidClause(seenTitles: string[]): string {
if (!seenTitles.length) return "";
return `\nYou have ALREADY composed these this session — do not repeat or echo them; pick an entirely different subject:\n${seenTitles.map((t) => `• ${t}`).join("\n")}\n`;
517}
518 
519/** The attempt already rejected in THIS compose (the loop caps at 2, so at most one),
*  listed so a reroll is told what not to draw again and diverges instead of
*  reproducing what just failed. Empty on the first attempt, so an un-rerolled prompt
*  stays byte-identical to before. */
523function rejectedClause(rejected: RejectedComposition[]): string {
if (!rejected.length) return "";
return `\nAlready rejected this compose — do not repeat or lightly reskin; go somewhere entirely different:\n${rejected.map((r) => `• ${r.title} — ${r.reason}`).join("\n")}\n`;
526}
527 
528/** Turns the closed-enum steer into a short clause biasing the model. Absent axes
*  simply don't appear, leaving them to the model ("no preference"). */
530function steerClause(steer: ObjectiveSteer): string {
const parts: string[] = [];
if (steer.era) {
  parts.push(
    steer.era === "Across the ages"
      ? "Let it span the ages rather than a single era."
      : `Anchor it in this stretch of history: ${steer.era}.`,
  );
}
if (steer.theme) parts.push(`Center it on the theme of ${steer.theme}.`);
return parts.length ? ` ${parts.join(" ")}` : "";
541}

The judge, and why it fails open

objectiveIsDuplicate is the heart of the change. Three things make it safe:

1. Mode gate (line 332). off returns before importing the gateway or spending a token. Only shadow/enforce make the call. 2. Fail open (line 372). content && mapDedupWire(JSON.parse(content)) || fresh — a null/empty answer short-circuits to fresh, a malformed body throws into the catch which also returns fresh, and an unusable shape maps to null which || fresh absorbs. Every failure path resolves to "not a duplicate." 3. Shadow observes without biting (line 386). When the verdict is a duplicate it logs a [objdedup] line, then — in shadow — returns fresh anyway, so the composition still ships. Only enforce returns the real verdict.

Signature + mode gate, then the fail-open tail (the JSON schema between is folded).

server/utils/objective-generator.ts · 541 lines

server/utils/objective-generator.ts541 lines · TypeScript

⋯ 320 lines hidden (lines 1–320)1/**
* Live, AI-composed objectives. The curated pool + the GameObjective shape live
* in ./objectives (pure, client-safe); this module owns the model path and is
* therefore SERVER-ONLY — it reaches the AI gateway (and through it the model
* SDKs + the AsyncLocalStorage run-context, which must never enter the browser
* bundle). Client code imports the curated pool + the steer enums from ./objectives
* directly.
*
* A composition is bounded AND steerable (#71):
*  - BOUNDED — the prompt is constrained to safely-historical objectives, and the
*    output is independently validated (the prompt alone isn't trusted): a finite
*    anchor year must sit at or before the shared safely-historical line, a small
*    structured check gates the living-people / current-events framings free prose
*    can smuggle past a year bound, and the text runs through the same moderation
*    seam as messages. Out of bounds → reroll once, then fall back to curated. The
*    curated pool is always the floor; a generation or validation failure never
*    hard-fails the run start, it just yields a curated objective.
*  - STEERED — the player biases the composition along two closed enums (era +
*    theme); see ObjectiveSteer in ./objectives.
*  - FRESH (#95) — a composition may reproduce neither the curated pool nor
*    anything composed earlier this session. Two guards: a free normalized-title
*    match catches verbatim / lightly-reskinned repeats, and a cheap Haiku judge
*    (objectiveIsDuplicate) catches the semantic near-duplicate a title match
*    can't see — the same objective, reworded. A rejected attempt is fed back into
*    the single reroll so it diverges instead of re-drawing the same subject;
*    a persistent collision falls back to an unseen curated pick.
*/
28import {
pickCurated,
listCuratedObjectives,
normalizeObjectiveTitle,
type GameObjective,
type ObjectiveSteer,
34} from "./objectives";
35import { SAFELY_HISTORICAL_BEFORE_YEAR } from "./historical-floor";
36 
37/**
* What generateObjective produced: the objective plus its provenance. `composed`
* is true ONLY when the live AI path yielded this objective; it is false for the
* curated floor — both the default no-AI path and every AI fallback (a generation,
* bounds, or de-dup failure). The endpoint pairs `composed === false` with a
* requested steer to tell the player their steer was quietly dropped (#127), instead
* of letting a silent curated fallback read as "steering is broken".
*/
45export interface GeneratedObjective {
objective: GameObjective;
composed: boolean;
48}
49 
50/**
* A composed candidate this call already rejected (out of bounds or a duplicate),
* fed back into the reroll so the second attempt is told what NOT to draw again.
*/
54interface RejectedComposition {
title: string;
description: string;
reason: string;
58}
59 
60/** A semantic de-dup verdict: is the candidate an existing objective reworded? */
61interface DedupVerdict {
duplicate: boolean;
/** The nearest existing title the judge matched against (telemetry / the reroll). */
closestMatch: string;
/** One short clause on the call — surfaced to the reroll and the [objdedup] log. */
reason: string;
67}
68 
69/**
* Returns an objective for a new run, plus whether the live AI path composed it (vs
* the curated floor). Curated-random by default (instant, no API call); pass
* useAI=true to compose one live under the given steer, with automatic fallback to
* curated. Never throws and never ships an out-of-bounds objective.
*
* `avoid` (#95) is the session's already-composed titles — the only anti-repeat
* memory the stateless server has (the client tracks and supplies them; the curated
* pool the server already knows). A composed result may reproduce NEITHER the
* curated pool NOR anything seen this session: a free normalized-title match catches
* exact / reskinned repeats, and a Haiku judge (objectiveIsDuplicate) catches the
* semantic near-duplicate a title match misses. A collision is rerolled once — the
* rejected attempt fed back so the reroll diverges — then the curated FALLBACK itself
* avoids the seen titles, so even the floor stays fresh.
*/
84export async function generateObjective(
useAI = false,
steer: ObjectiveSteer = {},
avoid: string[] = [],
88): Promise<GeneratedObjective> {
// The curated pool — the far half of the free de-dup Set and the candidate list
// the semantic judge compares against. (The compose exemplars and the fallback
// floor re-read the pool through their own helpers.)
const curated = listCuratedObjectives();
// Session-seen titles, normalized — used both for the curated fallback (so it
// never re-serves a seen objective) and, unioned with the curated pool below,
// for the free post-generation collision guard.
const seen = new Set(avoid.map(normalizeObjectiveTitle).filter(Boolean));
const dedupe = new Set(seen);
for (const o of curated) dedupe.add(normalizeObjectiveTitle(o.title));
99 
if (useAI) {
  // Never ship out of bounds OR a duplicate, never hard-fail the run: compose
  // live, and on an out-of-bounds / colliding result reroll exactly once, then
  // fall back to the (unseen) curated floor. Each rejected attempt is fed back
  // into the reroll so the second draw diverges rather than repeating itself. A
  // transport/parse failure won't heal on a reroll, so it drops straight to
  // curated instead of a second call.
  const rejected: RejectedComposition[] = [];
  for (let attempt = 1; attempt <= 2; attempt++) {
    try {
      const candidate = await composeObjective(steer, avoid, rejected);
      let reason: string;
      // The free normalized-title match short-circuits ahead of the paid checks:
      // an exact / reskinned collision never spends a bounds or de-dup call.
      if (dedupe.has(normalizeObjectiveTitle(candidate.title))) {
        reason = "duplicates an existing objective";
      } else {
        // Bounds (safety, fail-closed) and the semantic de-dup judge (freshness,
        // fail-open) are independent — run them together; either one rejects.
        const [inBounds, dup] = await Promise.all([
          objectiveWithinBounds(candidate),
          objectiveIsDuplicate(candidate, curated, avoid),
        ]);
        if (inBounds && !dup.duplicate)
          return { objective: candidate, composed: true };
        reason = !inBounds
          ? "outside the safely-historical bounds"
          : dup.reason || "too close to an existing objective";
      }
      rejected.push({
        title: candidate.title,
        description: candidate.description,
        reason,
      });
      console.warn(
        `AI objective rejected (${reason}) on attempt ${attempt} of 2; ${attempt < 2 ? "rerolling" : "falling back to curated"}`,
      );
    } catch (error) {
      console.error(
        "AI objective generation failed; falling back to curated pool:",
        error,
      );
      break;
    }
  }
}
// The curated floor — reached by the default no-AI path or any AI fallback.
return { objective: pickCurated(seen), composed: false };
148}
149 
150/**
* Composes one fresh objective with the model under the steer, steering away from
* the session's seen titles and any attempt already rejected this call. Returns the
* same shape as the curated pool so the rest of the game treats them identically.
* Throws on an empty/malformed answer (the caller owns the fallback).
*/
156async function composeObjective(
steer: ObjectiveSteer,
seenTitles: string[] = [],
rejected: RejectedComposition[] = [],
160): Promise<GameObjective> {
// Imported lazily so the curated (default) path never pulls the model SDKs
// into the bundle.
const { completeStructured } = await import("./ai-gateway");
164 
const content = await completeStructured({
  task: "objective",
  system: composeSystemPrompt(),
  turns: [
    { role: "user", content: composeUserPrompt(steer, seenTitles, rejected) },
  ],
  schemaName: "game_objective",
  schema: {
    type: "object",
    properties: {
      title: { type: "string", description: "Punchy objective title" },
      description: {
        type: "string",
        description:
          'A grounded brief: a few newline-separated "• " bullet lines stating the real-timeline date(s) and place this departs from in our history, what winning looks like, and where it is centered (or, if global/cross-era, said so with the span named)',
      },
      era: { type: "string", description: "Anchoring era / setting" },
      icon: {
        type: "string",
        description: "A single emoji that fits the objective",
      },
      anchorYear: {
        type: ["integer", "null"],
        description: `Signed year the objective is aimed at (negative for BC), at or before ${SAFELY_HISTORICAL_BEFORE_YEAR}, or null if it spans all history`,
      },
    },
    required: ["title", "description", "era", "icon", "anchorYear"],
    additionalProperties: false,
  },
});
195 
if (!content) throw new Error("No objective generated");
197 
const parsed = JSON.parse(content) as GameObjective;
if (!parsed.title || !parsed.description)
  throw new Error("Invalid objective format generated");
return {
  title: parsed.title,
  description: parsed.description,
  era: parsed.era || "Across the ages",
  icon: parsed.icon || "🕰️",
  // A finite signed year anchors the chain dial; null / junk → no anchor (no-op).
  anchorYear:
    typeof parsed.anchorYear === "number" &&
    Number.isFinite(parsed.anchorYear)
      ? Math.round(parsed.anchorYear)
      : undefined,
};
213}
214 
215/**
* Validates a composed objective against the safely-historical bounds (#71) —
* the prompt is asked to obey them, but never trusted to. Three gates: a pure year
* bound, the same moderation seam messages pass through, and a structured subject
* check for the living-people / current-events framings a year bound can't see.
* Never throws. The year and subject gates fail CLOSED — an inconclusive result
* (junk, an empty answer, an outage) reads as out of bounds, so an unvetted
* composition falls back to curated rather than shipping. Moderation fails OPEN,
* the same fail-open-but-loud seam messages pass through (a safety classifier
* being down must never take the game down); it rejects only on an active flag.
*/
226async function objectiveWithinBounds(o: GameObjective): Promise<boolean> {
// 1. Year bound — pure, deterministic, free. A finite anchor must sit at or
//    before the safely-historical line; a null anchor (spans-all-history) is
//    allowed, its content still gated by the subject check below.
if (
  typeof o.anchorYear === "number" &&
  o.anchorYear > SAFELY_HISTORICAL_BEFORE_YEAR
)
  return false;
235 
const text = `${o.title}\n${o.description}`;
// 2 + 3 are independent model/detector calls — run them together; first "out"
//    wins. Lazy import keeps moderation (and its SDKs) off the curated path.
const { hardBlockCheck } = await import("./moderation");
const [mod, subjectInBounds] = await Promise.all([
  hardBlockCheck(text, "objective", "output"),
  checkObjectiveSubject(o),
]);
if (mod.blocked) return false;
return subjectInBounds;
246}
247 
248/**
* The structured subject check (the figure-floor pattern, server/utils/
* lifespan-estimator.ts): a cheap classifier that gates the free-prose title +
* description a year bound can't reach — does this center on living people,
* contemporary figures, ongoing conflicts, or post-cutoff events? Fails CLOSED:
* an empty answer, junk, or an outage returns false, so an unvetted objective is
* never shipped (it falls back to the safe curated floor instead). Never throws.
*/
256async function checkObjectiveSubject(o: GameObjective): Promise<boolean> {
const { completeStructured } = await import("./ai-gateway");
try {
  const content = await completeStructured({
    task: "objective-check",
    system: boundsCheckSystemPrompt(),
    turns: [
      {
        role: "user",
        content: `Title: ${o.title}\nDescription: ${o.description}\nEra: ${o.era}\nAnchor year: ${o.anchorYear ?? "none (spans all history)"}`,
      },
    ],
    schemaName: "objective_bounds",
    schema: {
      type: "object",
      properties: {
        withinBounds: {
          type: "boolean",
          description:
            "True only when the subject is safely historical (settled past, no living people or current events)",
        },
        reason: {
          type: "string",
          description: "One short clause on the call",
        },
      },
      required: ["withinBounds", "reason"],
      additionalProperties: false,
    },
  });
  if (!content) return false; // the model blipped — fail closed to the curated floor
  return mapBoundsWire(JSON.parse(content)) === true;
} catch (error) {
  console.error("Objective bounds check error:", error);
  return false; // an outage must never let an unvetted objective through
}
292}
293 
294/**
* The bounds-check wire → a clean verdict. `null` for an unusable shape (missing /
* non-boolean flag), which the caller treats exactly like "out of bounds". Exported
* pure so the guard is directly testable, like mapLifespanWire.
*/
299export function mapBoundsWire(wire: unknown): boolean | null {
const w = wire as { withinBounds?: unknown } | null;
if (!w || typeof w.withinBounds !== "boolean") return null;
return w.withinBounds;
303}
304 
305/**
* Semantic de-dup (#95 follow-up). The free normalized-title match in
* generateObjective catches verbatim / reskinned repeats; this catches the ones it
* can't — the SAME objective reworded under a fresh title ("Save the Library of
* Alexandria" vs "Keep Alexandria's great library from the flames"). A cheap Haiku
* judge compares the candidate against everything already on offer (the curated pool
* in full, plus the session's seen titles) and answers: is this essentially one of
* them again?
*
* Freshness, not safety, so this fails OPEN: an outage, empty answer, or junk verdict
* reads as "not a duplicate" and ships (the opposite stance from the bounds gate — a
* de-dup classifier being down must never cost the player a composition). Modes via
* EVERWHEN_OBJECTIVE_DEDUP mirror moderation: 'off' skips the call, 'shadow' runs and
* logs what it WOULD reject without acting, 'enforce' (default) rejects for real.
* Never throws.
*/
321async function objectiveIsDuplicate(
candidate: GameObjective,
curated: GameObjective[],
seenTitles: string[],
325): Promise<DedupVerdict> {
const fresh: DedupVerdict = {
  duplicate: false,
  closestMatch: "",
  reason: "",
};
const mode = objectiveDedupMode();
if (mode === "off") return fresh;
⋯ 37 lines hidden (lines 333–369)333 
let verdict: DedupVerdict;
try {
  const { completeStructured } = await import("./ai-gateway");
  const content = await completeStructured({
    task: "objective-dedup",
    system: dedupSystemPrompt(),
    turns: [
      {
        role: "user",
        content: dedupUserPrompt(candidate, curated, seenTitles),
      },
    ],
    schemaName: "objective_dedup",
    schema: {
      type: "object",
      properties: {
        // Fact-retrieval before the decision it informs (schema order is
        // load-bearing): name the nearest existing objective first, then judge.
        closestMatch: {
          type: "string",
          description:
            'Title of the nearest existing objective, or "none" if nothing is close',
        },
        duplicate: {
          type: "boolean",
          description:
            "True only when the candidate is essentially that existing objective reworded — the same counterfactual, not merely the same era or theme",
        },
        reason: {
          type: "string",
          description: "One short clause on the call",
        },
      },
      required: ["closestMatch", "duplicate", "reason"],
      additionalProperties: false,
    },
  });
  // Fail open on an unusable verdict — a de-dup blip must not drop a composition.
  verdict = (content && mapDedupWire(JSON.parse(content))) || fresh;
} catch (error) {
  console.error("Objective de-dup check error:", error);
  return fresh; // freshness fails open — never take a composition down
}
377 
if (verdict.duplicate) {
  emitObjDedup({
    mode,
    wouldReject: true,
    enforced: mode === "enforce",
    closestMatch: verdict.closestMatch,
    candidate: candidate.title,
  });
  if (mode === "shadow") return fresh; // observe without biting — ship it
}
return verdict;
389}
⋯ 152 lines hidden (lines 390–541)390 
391/** EVERWHEN_OBJECTIVE_DEDUP: off | shadow | enforce (default enforce), the same
*  three-mode shape as EVERWHEN_MODERATION. */
393function objectiveDedupMode(): "off" | "shadow" | "enforce" {
const m = process.env.EVERWHEN_OBJECTIVE_DEDUP;
return m === "off" || m === "shadow" ? m : "enforce";
396}
397 
398/** One greppable [objdedup] line per flagged duplicate — the calibration
*  instrument for shadow mode. Quiet under tests, like [mod]. */
400function emitObjDedup(line: Record<string, unknown>): void {
if (!process.env.VITEST) console.info(`[objdedup] ${JSON.stringify(line)}`);
402}
403 
404/**
* The de-dup wire → a clean verdict, or `null` for an unusable shape (a missing /
* non-boolean flag), which the caller treats as "not a duplicate" (fail open).
* Exported pure so the guard is directly testable, like mapBoundsWire.
*/
409export function mapDedupWire(wire: unknown): DedupVerdict | null {
const w = wire as {
  duplicate?: unknown;
  closestMatch?: unknown;
  reason?: unknown;
} | null;
if (!w || typeof w.duplicate !== "boolean") return null;
return {
  duplicate: w.duplicate,
  closestMatch: typeof w.closestMatch === "string" ? w.closestMatch : "",
  reason: typeof w.reason === "string" ? w.reason : "",
};
421}
422 
423/** System prompt for the semantic de-dup judge. */
424function dedupSystemPrompt(): string {
return `You are a de-dup check for a historical strategy game. You are given a freshly composed objective and the list of objectives already on offer. Decide whether the new one is essentially one of the existing objectives reworded.
426 
427Mark it a DUPLICATE (duplicate=true) when it aims at the SAME counterfactual as an existing objective — the same pivotal event, person, or outcome — even if the title, wording, era label, or framing differ ("Save the Library of Alexandria" and "Keep Alexandria's great library from the flames" are the same objective).
428 
429Mark it NOT a duplicate (duplicate=false) when it targets a genuinely different event, person, place, or outcome — even if it shares a broad theme (war, science, empire) or era with an existing one. Sharing a subject is not enough; aiming at the same specific turning point is.
430 
431Name the closest existing title in closestMatch (or "none"), then decide, then give one short reason.`;
432}
433 
434/** De-dup user turn: the candidate, then everything already on offer (the curated
*  pool in full, plus the session's seen titles). */
436function dedupUserPrompt(
candidate: GameObjective,
curated: GameObjective[],
seenTitles: string[],
440): string {
const existing = [
  ...curated.map((o) => `• ${o.title} — ${o.description}`),
  ...seenTitles.map((t) => `• ${t}`),
].join("\n");
return `CANDIDATE objective:
446Title: ${candidate.title}
447Description: ${candidate.description}
448 
449Objectives ALREADY on offer:
450${existing}
451 
452Is the candidate essentially one of the objectives already on offer, reworded?`;
453}
454 
455/** System prompt for composition: the tone bar, the grounding bar, and the
*  non-negotiable safety bounds. */
457function composeSystemPrompt(): string {
return `You are a historian and game designer inventing grand, evocative counterfactual objectives for a game where players text historical figures to bend history.
459 
460Hold every objective to three bars:
461 
462TONE — sweeping and vivid, a whole world to remake in the spirit of the examples, never a small errand.
463 
464GROUNDING (issue #82) — every brief names the real-timeline date(s) and the place it departs from in our history, so a player who is not American and does not already know the date still gets a concrete anchor. Never assume the reader's frame.
465 
466BOUNDS (safety, non-negotiable) — the objective must be safely historical:
467- Set in the settled past. Any pivotal anchor year must be at or before ${SAFELY_HISTORICAL_BEFORE_YEAR}.
468- Never centered on, and never requiring contact with, living people, contemporary public figures, ongoing conflicts, or current events. Reach for history, not the present or the recent past.`;
469}
470 
471/** Composition user turn: curated few-shot exemplars (framed as territory already
*  taken, never a menu to copy), the session avoid-list, any attempt already
*  rejected this call, the steer, and the ask. */
474function composeUserPrompt(
steer: ObjectiveSteer,
seenTitles: string[],
rejected: RejectedComposition[] = [],
478): string {
return `Objectives we love — match their TONE, SCALE, and brief SHAPE, but treat their SUBJECTS as territory already taken. Invent something genuinely new; vary away from every one in subject, era, and region. Do NOT reproduce or lightly reskin them (especially over-familiar picks like "Save the Library of Alexandria"):
480${curatedExemplars()}
481${avoidClause(seenTitles)}${rejectedClause(rejected)}
482Invent ONE fresh objective, unlike anything above — a different subject, era, and region from the examples${seenTitles.length ? " and from anything already composed this session" : ""}.${steerClause(steer)}
483 
484Give it: a punchy title; an anchoring era; a single emoji; the anchor year it is aimed at (the pivotal year where winning is decided) as a SIGNED integer — negative for BC, at or before ${SAFELY_HISTORICAL_BEFORE_YEAR} — or null if it genuinely spans all of history with no single hinge; and a GROUNDED BRIEF as the description.
485 
486The brief is a few short bullet lines, each beginning with "• " and separated by newlines (the same shape as the examples above), that together state: (1) when and where this actually happened or ended in OUR timeline, with real dates; (2) what winning looks like; (3) where on Earth it is centered — name the region or country, or, if it genuinely spans the globe or all eras, say so and name the span rather than forcing one country. Put the real date IN the brief; the real-timeline date(s) are NOT the anchor year — state the actual history, never merely restate the anchor. Keep each bullet tight.`;
487}
488 
489/** System prompt for the structured subject check. */
490function boundsCheckSystemPrompt(): string {
return `You are a safety check for a historical strategy game. You are given a freshly generated objective (title, description, era, anchor year). Decide whether it stays safely in the settled past.
492 
493Mark it OUT OF BOUNDS (withinBounds=false) if it centers on, or would require contacting, any of:
494- a living person or a present-day public figure,
495- an ongoing conflict or a current event,
496- anything anchored after the year ${SAFELY_HISTORICAL_BEFORE_YEAR}.
497 
498Mark it IN BOUNDS (withinBounds=true) only when its subject is historical — people and events settled in the past, before living memory. Dramatic history is fine (wars, plagues, empires, revolutions); the test is WHEN and WHO, not how grand.
499 
500When you are unsure, answer withinBounds=false. Give a short reason either way.`;
501}
502 
503/** The curated pool rendered as few-shot exemplars (title — description), read
*  live from the pool so the bar can never drift from a hardcoded copy. */
505function curatedExemplars(): string {
return listCuratedObjectives()
  .map((o) => `• ${o.title} — ${o.description}`)
  .join("\n");
509}
510 
511/** The session's already-composed titles, listed so the model steers away from
*  repeating them (#95). Empty when nothing's been rolled yet — the first compose
*  carries no clause, so an unseeded prompt stays identical to before. */
514function avoidClause(seenTitles: string[]): string {
if (!seenTitles.length) return "";
return `\nYou have ALREADY composed these this session — do not repeat or echo them; pick an entirely different subject:\n${seenTitles.map((t) => `• ${t}`).join("\n")}\n`;
517}
518 
519/** The attempt already rejected in THIS compose (the loop caps at 2, so at most one),
*  listed so a reroll is told what not to draw again and diverges instead of
*  reproducing what just failed. Empty on the first attempt, so an un-rerolled prompt
*  stays byte-identical to before. */
523function rejectedClause(rejected: RejectedComposition[]): string {
if (!rejected.length) return "";
return `\nAlready rejected this compose — do not repeat or lightly reskin; go somewhere entirely different:\n${rejected.map((r) => `• ${r.title} — ${r.reason}`).join("\n")}\n`;
526}
527 
528/** Turns the closed-enum steer into a short clause biasing the model. Absent axes
*  simply don't appear, leaving them to the model ("no preference"). */
530function steerClause(steer: ObjectiveSteer): string {
const parts: string[] = [];
if (steer.era) {
  parts.push(
    steer.era === "Across the ages"
      ? "Let it span the ages rather than a single era."
      : `Anchor it in this stretch of history: ${steer.era}.`,
  );
}
if (steer.theme) parts.push(`Center it on the theme of ${steer.theme}.`);
return parts.length ? ` ${parts.join(" ")}` : "";
541}

The mode reader mirrors the moderation seam exactly — off | shadow | enforce, defaulting to enforce — and the wire guard is a pure, exported function so the fail-open mapping is unit-testable on its own.

EVERWHEN_OBJECTIVE_DEDUP — the same three-mode shape as EVERWHEN_MODERATION.

server/utils/objective-generator.ts · 541 lines

server/utils/objective-generator.ts541 lines · TypeScript

⋯ 390 lines hidden (lines 1–390)1/**
* Live, AI-composed objectives. The curated pool + the GameObjective shape live
* in ./objectives (pure, client-safe); this module owns the model path and is
* therefore SERVER-ONLY — it reaches the AI gateway (and through it the model
* SDKs + the AsyncLocalStorage run-context, which must never enter the browser
* bundle). Client code imports the curated pool + the steer enums from ./objectives
* directly.
*
* A composition is bounded AND steerable (#71):
*  - BOUNDED — the prompt is constrained to safely-historical objectives, and the
*    output is independently validated (the prompt alone isn't trusted): a finite
*    anchor year must sit at or before the shared safely-historical line, a small
*    structured check gates the living-people / current-events framings free prose
*    can smuggle past a year bound, and the text runs through the same moderation
*    seam as messages. Out of bounds → reroll once, then fall back to curated. The
*    curated pool is always the floor; a generation or validation failure never
*    hard-fails the run start, it just yields a curated objective.
*  - STEERED — the player biases the composition along two closed enums (era +
*    theme); see ObjectiveSteer in ./objectives.
*  - FRESH (#95) — a composition may reproduce neither the curated pool nor
*    anything composed earlier this session. Two guards: a free normalized-title
*    match catches verbatim / lightly-reskinned repeats, and a cheap Haiku judge
*    (objectiveIsDuplicate) catches the semantic near-duplicate a title match
*    can't see — the same objective, reworded. A rejected attempt is fed back into
*    the single reroll so it diverges instead of re-drawing the same subject;
*    a persistent collision falls back to an unseen curated pick.
*/
28import {
pickCurated,
listCuratedObjectives,
normalizeObjectiveTitle,
type GameObjective,
type ObjectiveSteer,
34} from "./objectives";
35import { SAFELY_HISTORICAL_BEFORE_YEAR } from "./historical-floor";
36 
37/**
* What generateObjective produced: the objective plus its provenance. `composed`
* is true ONLY when the live AI path yielded this objective; it is false for the
* curated floor — both the default no-AI path and every AI fallback (a generation,
* bounds, or de-dup failure). The endpoint pairs `composed === false` with a
* requested steer to tell the player their steer was quietly dropped (#127), instead
* of letting a silent curated fallback read as "steering is broken".
*/
45export interface GeneratedObjective {
objective: GameObjective;
composed: boolean;
48}
49 
50/**
* A composed candidate this call already rejected (out of bounds or a duplicate),
* fed back into the reroll so the second attempt is told what NOT to draw again.
*/
54interface RejectedComposition {
title: string;
description: string;
reason: string;
58}
59 
60/** A semantic de-dup verdict: is the candidate an existing objective reworded? */
61interface DedupVerdict {
duplicate: boolean;
/** The nearest existing title the judge matched against (telemetry / the reroll). */
closestMatch: string;
/** One short clause on the call — surfaced to the reroll and the [objdedup] log. */
reason: string;
67}
68 
69/**
* Returns an objective for a new run, plus whether the live AI path composed it (vs
* the curated floor). Curated-random by default (instant, no API call); pass
* useAI=true to compose one live under the given steer, with automatic fallback to
* curated. Never throws and never ships an out-of-bounds objective.
*
* `avoid` (#95) is the session's already-composed titles — the only anti-repeat
* memory the stateless server has (the client tracks and supplies them; the curated
* pool the server already knows). A composed result may reproduce NEITHER the
* curated pool NOR anything seen this session: a free normalized-title match catches
* exact / reskinned repeats, and a Haiku judge (objectiveIsDuplicate) catches the
* semantic near-duplicate a title match misses. A collision is rerolled once — the
* rejected attempt fed back so the reroll diverges — then the curated FALLBACK itself
* avoids the seen titles, so even the floor stays fresh.
*/
84export async function generateObjective(
useAI = false,
steer: ObjectiveSteer = {},
avoid: string[] = [],
88): Promise<GeneratedObjective> {
// The curated pool — the far half of the free de-dup Set and the candidate list
// the semantic judge compares against. (The compose exemplars and the fallback
// floor re-read the pool through their own helpers.)
const curated = listCuratedObjectives();
// Session-seen titles, normalized — used both for the curated fallback (so it
// never re-serves a seen objective) and, unioned with the curated pool below,
// for the free post-generation collision guard.
const seen = new Set(avoid.map(normalizeObjectiveTitle).filter(Boolean));
const dedupe = new Set(seen);
for (const o of curated) dedupe.add(normalizeObjectiveTitle(o.title));
99 
if (useAI) {
  // Never ship out of bounds OR a duplicate, never hard-fail the run: compose
  // live, and on an out-of-bounds / colliding result reroll exactly once, then
  // fall back to the (unseen) curated floor. Each rejected attempt is fed back
  // into the reroll so the second draw diverges rather than repeating itself. A
  // transport/parse failure won't heal on a reroll, so it drops straight to
  // curated instead of a second call.
  const rejected: RejectedComposition[] = [];
  for (let attempt = 1; attempt <= 2; attempt++) {
    try {
      const candidate = await composeObjective(steer, avoid, rejected);
      let reason: string;
      // The free normalized-title match short-circuits ahead of the paid checks:
      // an exact / reskinned collision never spends a bounds or de-dup call.
      if (dedupe.has(normalizeObjectiveTitle(candidate.title))) {
        reason = "duplicates an existing objective";
      } else {
        // Bounds (safety, fail-closed) and the semantic de-dup judge (freshness,
        // fail-open) are independent — run them together; either one rejects.
        const [inBounds, dup] = await Promise.all([
          objectiveWithinBounds(candidate),
          objectiveIsDuplicate(candidate, curated, avoid),
        ]);
        if (inBounds && !dup.duplicate)
          return { objective: candidate, composed: true };
        reason = !inBounds
          ? "outside the safely-historical bounds"
          : dup.reason || "too close to an existing objective";
      }
      rejected.push({
        title: candidate.title,
        description: candidate.description,
        reason,
      });
      console.warn(
        `AI objective rejected (${reason}) on attempt ${attempt} of 2; ${attempt < 2 ? "rerolling" : "falling back to curated"}`,
      );
    } catch (error) {
      console.error(
        "AI objective generation failed; falling back to curated pool:",
        error,
      );
      break;
    }
  }
}
// The curated floor — reached by the default no-AI path or any AI fallback.
return { objective: pickCurated(seen), composed: false };
148}
149 
150/**
* Composes one fresh objective with the model under the steer, steering away from
* the session's seen titles and any attempt already rejected this call. Returns the
* same shape as the curated pool so the rest of the game treats them identically.
* Throws on an empty/malformed answer (the caller owns the fallback).
*/
156async function composeObjective(
steer: ObjectiveSteer,
seenTitles: string[] = [],
rejected: RejectedComposition[] = [],
160): Promise<GameObjective> {
// Imported lazily so the curated (default) path never pulls the model SDKs
// into the bundle.
const { completeStructured } = await import("./ai-gateway");
164 
const content = await completeStructured({
  task: "objective",
  system: composeSystemPrompt(),
  turns: [
    { role: "user", content: composeUserPrompt(steer, seenTitles, rejected) },
  ],
  schemaName: "game_objective",
  schema: {
    type: "object",
    properties: {
      title: { type: "string", description: "Punchy objective title" },
      description: {
        type: "string",
        description:
          'A grounded brief: a few newline-separated "• " bullet lines stating the real-timeline date(s) and place this departs from in our history, what winning looks like, and where it is centered (or, if global/cross-era, said so with the span named)',
      },
      era: { type: "string", description: "Anchoring era / setting" },
      icon: {
        type: "string",
        description: "A single emoji that fits the objective",
      },
      anchorYear: {
        type: ["integer", "null"],
        description: `Signed year the objective is aimed at (negative for BC), at or before ${SAFELY_HISTORICAL_BEFORE_YEAR}, or null if it spans all history`,
      },
    },
    required: ["title", "description", "era", "icon", "anchorYear"],
    additionalProperties: false,
  },
});
195 
if (!content) throw new Error("No objective generated");
197 
const parsed = JSON.parse(content) as GameObjective;
if (!parsed.title || !parsed.description)
  throw new Error("Invalid objective format generated");
return {
  title: parsed.title,
  description: parsed.description,
  era: parsed.era || "Across the ages",
  icon: parsed.icon || "🕰️",
  // A finite signed year anchors the chain dial; null / junk → no anchor (no-op).
  anchorYear:
    typeof parsed.anchorYear === "number" &&
    Number.isFinite(parsed.anchorYear)
      ? Math.round(parsed.anchorYear)
      : undefined,
};
213}
214 
215/**
* Validates a composed objective against the safely-historical bounds (#71) —
* the prompt is asked to obey them, but never trusted to. Three gates: a pure year
* bound, the same moderation seam messages pass through, and a structured subject
* check for the living-people / current-events framings a year bound can't see.
* Never throws. The year and subject gates fail CLOSED — an inconclusive result
* (junk, an empty answer, an outage) reads as out of bounds, so an unvetted
* composition falls back to curated rather than shipping. Moderation fails OPEN,
* the same fail-open-but-loud seam messages pass through (a safety classifier
* being down must never take the game down); it rejects only on an active flag.
*/
226async function objectiveWithinBounds(o: GameObjective): Promise<boolean> {
// 1. Year bound — pure, deterministic, free. A finite anchor must sit at or
//    before the safely-historical line; a null anchor (spans-all-history) is
//    allowed, its content still gated by the subject check below.
if (
  typeof o.anchorYear === "number" &&
  o.anchorYear > SAFELY_HISTORICAL_BEFORE_YEAR
)
  return false;
235 
const text = `${o.title}\n${o.description}`;
// 2 + 3 are independent model/detector calls — run them together; first "out"
//    wins. Lazy import keeps moderation (and its SDKs) off the curated path.
const { hardBlockCheck } = await import("./moderation");
const [mod, subjectInBounds] = await Promise.all([
  hardBlockCheck(text, "objective", "output"),
  checkObjectiveSubject(o),
]);
if (mod.blocked) return false;
return subjectInBounds;
246}
247 
248/**
* The structured subject check (the figure-floor pattern, server/utils/
* lifespan-estimator.ts): a cheap classifier that gates the free-prose title +
* description a year bound can't reach — does this center on living people,
* contemporary figures, ongoing conflicts, or post-cutoff events? Fails CLOSED:
* an empty answer, junk, or an outage returns false, so an unvetted objective is
* never shipped (it falls back to the safe curated floor instead). Never throws.
*/
256async function checkObjectiveSubject(o: GameObjective): Promise<boolean> {
const { completeStructured } = await import("./ai-gateway");
try {
  const content = await completeStructured({
    task: "objective-check",
    system: boundsCheckSystemPrompt(),
    turns: [
      {
        role: "user",
        content: `Title: ${o.title}\nDescription: ${o.description}\nEra: ${o.era}\nAnchor year: ${o.anchorYear ?? "none (spans all history)"}`,
      },
    ],
    schemaName: "objective_bounds",
    schema: {
      type: "object",
      properties: {
        withinBounds: {
          type: "boolean",
          description:
            "True only when the subject is safely historical (settled past, no living people or current events)",
        },
        reason: {
          type: "string",
          description: "One short clause on the call",
        },
      },
      required: ["withinBounds", "reason"],
      additionalProperties: false,
    },
  });
  if (!content) return false; // the model blipped — fail closed to the curated floor
  return mapBoundsWire(JSON.parse(content)) === true;
} catch (error) {
  console.error("Objective bounds check error:", error);
  return false; // an outage must never let an unvetted objective through
}
292}
293 
294/**
* The bounds-check wire → a clean verdict. `null` for an unusable shape (missing /
* non-boolean flag), which the caller treats exactly like "out of bounds". Exported
* pure so the guard is directly testable, like mapLifespanWire.
*/
299export function mapBoundsWire(wire: unknown): boolean | null {
const w = wire as { withinBounds?: unknown } | null;
if (!w || typeof w.withinBounds !== "boolean") return null;
return w.withinBounds;
303}
304 
305/**
* Semantic de-dup (#95 follow-up). The free normalized-title match in
* generateObjective catches verbatim / reskinned repeats; this catches the ones it
* can't — the SAME objective reworded under a fresh title ("Save the Library of
* Alexandria" vs "Keep Alexandria's great library from the flames"). A cheap Haiku
* judge compares the candidate against everything already on offer (the curated pool
* in full, plus the session's seen titles) and answers: is this essentially one of
* them again?
*
* Freshness, not safety, so this fails OPEN: an outage, empty answer, or junk verdict
* reads as "not a duplicate" and ships (the opposite stance from the bounds gate — a
* de-dup classifier being down must never cost the player a composition). Modes via
* EVERWHEN_OBJECTIVE_DEDUP mirror moderation: 'off' skips the call, 'shadow' runs and
* logs what it WOULD reject without acting, 'enforce' (default) rejects for real.
* Never throws.
*/
321async function objectiveIsDuplicate(
candidate: GameObjective,
curated: GameObjective[],
seenTitles: string[],
325): Promise<DedupVerdict> {
const fresh: DedupVerdict = {
  duplicate: false,
  closestMatch: "",
  reason: "",
};
const mode = objectiveDedupMode();
if (mode === "off") return fresh;
333 
let verdict: DedupVerdict;
try {
  const { completeStructured } = await import("./ai-gateway");
  const content = await completeStructured({
    task: "objective-dedup",
    system: dedupSystemPrompt(),
    turns: [
      {
        role: "user",
        content: dedupUserPrompt(candidate, curated, seenTitles),
      },
    ],
    schemaName: "objective_dedup",
    schema: {
      type: "object",
      properties: {
        // Fact-retrieval before the decision it informs (schema order is
        // load-bearing): name the nearest existing objective first, then judge.
        closestMatch: {
          type: "string",
          description:
            'Title of the nearest existing objective, or "none" if nothing is close',
        },
        duplicate: {
          type: "boolean",
          description:
            "True only when the candidate is essentially that existing objective reworded — the same counterfactual, not merely the same era or theme",
        },
        reason: {
          type: "string",
          description: "One short clause on the call",
        },
      },
      required: ["closestMatch", "duplicate", "reason"],
      additionalProperties: false,
    },
  });
  // Fail open on an unusable verdict — a de-dup blip must not drop a composition.
  verdict = (content && mapDedupWire(JSON.parse(content))) || fresh;
} catch (error) {
  console.error("Objective de-dup check error:", error);
  return fresh; // freshness fails open — never take a composition down
}
377 
if (verdict.duplicate) {
  emitObjDedup({
    mode,
    wouldReject: true,
    enforced: mode === "enforce",
    closestMatch: verdict.closestMatch,
    candidate: candidate.title,
  });
  if (mode === "shadow") return fresh; // observe without biting — ship it
}
return verdict;
389}
390 
391/** EVERWHEN_OBJECTIVE_DEDUP: off | shadow | enforce (default enforce), the same
*  three-mode shape as EVERWHEN_MODERATION. */
393function objectiveDedupMode(): "off" | "shadow" | "enforce" {
const m = process.env.EVERWHEN_OBJECTIVE_DEDUP;
return m === "off" || m === "shadow" ? m : "enforce";
396}
⋯ 145 lines hidden (lines 397–541)397 
398/** One greppable [objdedup] line per flagged duplicate — the calibration
*  instrument for shadow mode. Quiet under tests, like [mod]. */
400function emitObjDedup(line: Record<string, unknown>): void {
if (!process.env.VITEST) console.info(`[objdedup] ${JSON.stringify(line)}`);
402}
403 
404/**
* The de-dup wire → a clean verdict, or `null` for an unusable shape (a missing /
* non-boolean flag), which the caller treats as "not a duplicate" (fail open).
* Exported pure so the guard is directly testable, like mapBoundsWire.
*/
409export function mapDedupWire(wire: unknown): DedupVerdict | null {
const w = wire as {
  duplicate?: unknown;
  closestMatch?: unknown;
  reason?: unknown;
} | null;
if (!w || typeof w.duplicate !== "boolean") return null;
return {
  duplicate: w.duplicate,
  closestMatch: typeof w.closestMatch === "string" ? w.closestMatch : "",
  reason: typeof w.reason === "string" ? w.reason : "",
};
421}
422 
423/** System prompt for the semantic de-dup judge. */
424function dedupSystemPrompt(): string {
return `You are a de-dup check for a historical strategy game. You are given a freshly composed objective and the list of objectives already on offer. Decide whether the new one is essentially one of the existing objectives reworded.
426 
427Mark it a DUPLICATE (duplicate=true) when it aims at the SAME counterfactual as an existing objective — the same pivotal event, person, or outcome — even if the title, wording, era label, or framing differ ("Save the Library of Alexandria" and "Keep Alexandria's great library from the flames" are the same objective).
428 
429Mark it NOT a duplicate (duplicate=false) when it targets a genuinely different event, person, place, or outcome — even if it shares a broad theme (war, science, empire) or era with an existing one. Sharing a subject is not enough; aiming at the same specific turning point is.
430 
431Name the closest existing title in closestMatch (or "none"), then decide, then give one short reason.`;
432}
433 
434/** De-dup user turn: the candidate, then everything already on offer (the curated
*  pool in full, plus the session's seen titles). */
436function dedupUserPrompt(
candidate: GameObjective,
curated: GameObjective[],
seenTitles: string[],
440): string {
const existing = [
  ...curated.map((o) => `• ${o.title} — ${o.description}`),
  ...seenTitles.map((t) => `• ${t}`),
].join("\n");
return `CANDIDATE objective:
446Title: ${candidate.title}
447Description: ${candidate.description}
448 
449Objectives ALREADY on offer:
450${existing}
451 
452Is the candidate essentially one of the objectives already on offer, reworded?`;
453}
454 
455/** System prompt for composition: the tone bar, the grounding bar, and the
*  non-negotiable safety bounds. */
457function composeSystemPrompt(): string {
return `You are a historian and game designer inventing grand, evocative counterfactual objectives for a game where players text historical figures to bend history.
459 
460Hold every objective to three bars:
461 
462TONE — sweeping and vivid, a whole world to remake in the spirit of the examples, never a small errand.
463 
464GROUNDING (issue #82) — every brief names the real-timeline date(s) and the place it departs from in our history, so a player who is not American and does not already know the date still gets a concrete anchor. Never assume the reader's frame.
465 
466BOUNDS (safety, non-negotiable) — the objective must be safely historical:
467- Set in the settled past. Any pivotal anchor year must be at or before ${SAFELY_HISTORICAL_BEFORE_YEAR}.
468- Never centered on, and never requiring contact with, living people, contemporary public figures, ongoing conflicts, or current events. Reach for history, not the present or the recent past.`;
469}
470 
471/** Composition user turn: curated few-shot exemplars (framed as territory already
*  taken, never a menu to copy), the session avoid-list, any attempt already
*  rejected this call, the steer, and the ask. */
474function composeUserPrompt(
steer: ObjectiveSteer,
seenTitles: string[],
rejected: RejectedComposition[] = [],
478): string {
return `Objectives we love — match their TONE, SCALE, and brief SHAPE, but treat their SUBJECTS as territory already taken. Invent something genuinely new; vary away from every one in subject, era, and region. Do NOT reproduce or lightly reskin them (especially over-familiar picks like "Save the Library of Alexandria"):
480${curatedExemplars()}
481${avoidClause(seenTitles)}${rejectedClause(rejected)}
482Invent ONE fresh objective, unlike anything above — a different subject, era, and region from the examples${seenTitles.length ? " and from anything already composed this session" : ""}.${steerClause(steer)}
483 
484Give it: a punchy title; an anchoring era; a single emoji; the anchor year it is aimed at (the pivotal year where winning is decided) as a SIGNED integer — negative for BC, at or before ${SAFELY_HISTORICAL_BEFORE_YEAR} — or null if it genuinely spans all of history with no single hinge; and a GROUNDED BRIEF as the description.
485 
486The brief is a few short bullet lines, each beginning with "• " and separated by newlines (the same shape as the examples above), that together state: (1) when and where this actually happened or ended in OUR timeline, with real dates; (2) what winning looks like; (3) where on Earth it is centered — name the region or country, or, if it genuinely spans the globe or all eras, say so and name the span rather than forcing one country. Put the real date IN the brief; the real-timeline date(s) are NOT the anchor year — state the actual history, never merely restate the anchor. Keep each bullet tight.`;
487}
488 
489/** System prompt for the structured subject check. */
490function boundsCheckSystemPrompt(): string {
return `You are a safety check for a historical strategy game. You are given a freshly generated objective (title, description, era, anchor year). Decide whether it stays safely in the settled past.
492 
493Mark it OUT OF BOUNDS (withinBounds=false) if it centers on, or would require contacting, any of:
494- a living person or a present-day public figure,
495- an ongoing conflict or a current event,
496- anything anchored after the year ${SAFELY_HISTORICAL_BEFORE_YEAR}.
497 
498Mark it IN BOUNDS (withinBounds=true) only when its subject is historical — people and events settled in the past, before living memory. Dramatic history is fine (wars, plagues, empires, revolutions); the test is WHEN and WHO, not how grand.
499 
500When you are unsure, answer withinBounds=false. Give a short reason either way.`;
501}
502 
503/** The curated pool rendered as few-shot exemplars (title — description), read
*  live from the pool so the bar can never drift from a hardcoded copy. */
505function curatedExemplars(): string {
return listCuratedObjectives()
  .map((o) => `• ${o.title} — ${o.description}`)
  .join("\n");
509}
510 
511/** The session's already-composed titles, listed so the model steers away from
*  repeating them (#95). Empty when nothing's been rolled yet — the first compose
*  carries no clause, so an unseeded prompt stays identical to before. */
514function avoidClause(seenTitles: string[]): string {
if (!seenTitles.length) return "";
return `\nYou have ALREADY composed these this session — do not repeat or echo them; pick an entirely different subject:\n${seenTitles.map((t) => `• ${t}`).join("\n")}\n`;
517}
518 
519/** The attempt already rejected in THIS compose (the loop caps at 2, so at most one),
*  listed so a reroll is told what not to draw again and diverges instead of
*  reproducing what just failed. Empty on the first attempt, so an un-rerolled prompt
*  stays byte-identical to before. */
523function rejectedClause(rejected: RejectedComposition[]): string {
if (!rejected.length) return "";
return `\nAlready rejected this compose — do not repeat or lightly reskin; go somewhere entirely different:\n${rejected.map((r) => `• ${r.title} — ${r.reason}`).join("\n")}\n`;
526}
527 
528/** Turns the closed-enum steer into a short clause biasing the model. Absent axes
*  simply don't appear, leaving them to the model ("no preference"). */
530function steerClause(steer: ObjectiveSteer): string {
const parts: string[] = [];
if (steer.era) {
  parts.push(
    steer.era === "Across the ages"
      ? "Let it span the ages rather than a single era."
      : `Anchor it in this stretch of history: ${steer.era}.`,
  );
}
if (steer.theme) parts.push(`Center it on the theme of ${steer.theme}.`);
return parts.length ? ` ${parts.join(" ")}` : "";
541}

mapDedupWire: null on any unusable shape → the caller treats it as not-a-duplicate.

server/utils/objective-generator.ts · 541 lines

server/utils/objective-generator.ts541 lines · TypeScript

⋯ 403 lines hidden (lines 1–403)1/**
* Live, AI-composed objectives. The curated pool + the GameObjective shape live
* in ./objectives (pure, client-safe); this module owns the model path and is
* therefore SERVER-ONLY — it reaches the AI gateway (and through it the model
* SDKs + the AsyncLocalStorage run-context, which must never enter the browser
* bundle). Client code imports the curated pool + the steer enums from ./objectives
* directly.
*
* A composition is bounded AND steerable (#71):
*  - BOUNDED — the prompt is constrained to safely-historical objectives, and the
*    output is independently validated (the prompt alone isn't trusted): a finite
*    anchor year must sit at or before the shared safely-historical line, a small
*    structured check gates the living-people / current-events framings free prose
*    can smuggle past a year bound, and the text runs through the same moderation
*    seam as messages. Out of bounds → reroll once, then fall back to curated. The
*    curated pool is always the floor; a generation or validation failure never
*    hard-fails the run start, it just yields a curated objective.
*  - STEERED — the player biases the composition along two closed enums (era +
*    theme); see ObjectiveSteer in ./objectives.
*  - FRESH (#95) — a composition may reproduce neither the curated pool nor
*    anything composed earlier this session. Two guards: a free normalized-title
*    match catches verbatim / lightly-reskinned repeats, and a cheap Haiku judge
*    (objectiveIsDuplicate) catches the semantic near-duplicate a title match
*    can't see — the same objective, reworded. A rejected attempt is fed back into
*    the single reroll so it diverges instead of re-drawing the same subject;
*    a persistent collision falls back to an unseen curated pick.
*/
28import {
pickCurated,
listCuratedObjectives,
normalizeObjectiveTitle,
type GameObjective,
type ObjectiveSteer,
34} from "./objectives";
35import { SAFELY_HISTORICAL_BEFORE_YEAR } from "./historical-floor";
36 
37/**
* What generateObjective produced: the objective plus its provenance. `composed`
* is true ONLY when the live AI path yielded this objective; it is false for the
* curated floor — both the default no-AI path and every AI fallback (a generation,
* bounds, or de-dup failure). The endpoint pairs `composed === false` with a
* requested steer to tell the player their steer was quietly dropped (#127), instead
* of letting a silent curated fallback read as "steering is broken".
*/
45export interface GeneratedObjective {
objective: GameObjective;
composed: boolean;
48}
49 
50/**
* A composed candidate this call already rejected (out of bounds or a duplicate),
* fed back into the reroll so the second attempt is told what NOT to draw again.
*/
54interface RejectedComposition {
title: string;
description: string;
reason: string;
58}
59 
60/** A semantic de-dup verdict: is the candidate an existing objective reworded? */
61interface DedupVerdict {
duplicate: boolean;
/** The nearest existing title the judge matched against (telemetry / the reroll). */
closestMatch: string;
/** One short clause on the call — surfaced to the reroll and the [objdedup] log. */
reason: string;
67}
68 
69/**
* Returns an objective for a new run, plus whether the live AI path composed it (vs
* the curated floor). Curated-random by default (instant, no API call); pass
* useAI=true to compose one live under the given steer, with automatic fallback to
* curated. Never throws and never ships an out-of-bounds objective.
*
* `avoid` (#95) is the session's already-composed titles — the only anti-repeat
* memory the stateless server has (the client tracks and supplies them; the curated
* pool the server already knows). A composed result may reproduce NEITHER the
* curated pool NOR anything seen this session: a free normalized-title match catches
* exact / reskinned repeats, and a Haiku judge (objectiveIsDuplicate) catches the
* semantic near-duplicate a title match misses. A collision is rerolled once — the
* rejected attempt fed back so the reroll diverges — then the curated FALLBACK itself
* avoids the seen titles, so even the floor stays fresh.
*/
84export async function generateObjective(
useAI = false,
steer: ObjectiveSteer = {},
avoid: string[] = [],
88): Promise<GeneratedObjective> {
// The curated pool — the far half of the free de-dup Set and the candidate list
// the semantic judge compares against. (The compose exemplars and the fallback
// floor re-read the pool through their own helpers.)
const curated = listCuratedObjectives();
// Session-seen titles, normalized — used both for the curated fallback (so it
// never re-serves a seen objective) and, unioned with the curated pool below,
// for the free post-generation collision guard.
const seen = new Set(avoid.map(normalizeObjectiveTitle).filter(Boolean));
const dedupe = new Set(seen);
for (const o of curated) dedupe.add(normalizeObjectiveTitle(o.title));
99 
if (useAI) {
  // Never ship out of bounds OR a duplicate, never hard-fail the run: compose
  // live, and on an out-of-bounds / colliding result reroll exactly once, then
  // fall back to the (unseen) curated floor. Each rejected attempt is fed back
  // into the reroll so the second draw diverges rather than repeating itself. A
  // transport/parse failure won't heal on a reroll, so it drops straight to
  // curated instead of a second call.
  const rejected: RejectedComposition[] = [];
  for (let attempt = 1; attempt <= 2; attempt++) {
    try {
      const candidate = await composeObjective(steer, avoid, rejected);
      let reason: string;
      // The free normalized-title match short-circuits ahead of the paid checks:
      // an exact / reskinned collision never spends a bounds or de-dup call.
      if (dedupe.has(normalizeObjectiveTitle(candidate.title))) {
        reason = "duplicates an existing objective";
      } else {
        // Bounds (safety, fail-closed) and the semantic de-dup judge (freshness,
        // fail-open) are independent — run them together; either one rejects.
        const [inBounds, dup] = await Promise.all([
          objectiveWithinBounds(candidate),
          objectiveIsDuplicate(candidate, curated, avoid),
        ]);
        if (inBounds && !dup.duplicate)
          return { objective: candidate, composed: true };
        reason = !inBounds
          ? "outside the safely-historical bounds"
          : dup.reason || "too close to an existing objective";
      }
      rejected.push({
        title: candidate.title,
        description: candidate.description,
        reason,
      });
      console.warn(
        `AI objective rejected (${reason}) on attempt ${attempt} of 2; ${attempt < 2 ? "rerolling" : "falling back to curated"}`,
      );
    } catch (error) {
      console.error(
        "AI objective generation failed; falling back to curated pool:",
        error,
      );
      break;
    }
  }
}
// The curated floor — reached by the default no-AI path or any AI fallback.
return { objective: pickCurated(seen), composed: false };
148}
149 
150/**
* Composes one fresh objective with the model under the steer, steering away from
* the session's seen titles and any attempt already rejected this call. Returns the
* same shape as the curated pool so the rest of the game treats them identically.
* Throws on an empty/malformed answer (the caller owns the fallback).
*/
156async function composeObjective(
steer: ObjectiveSteer,
seenTitles: string[] = [],
rejected: RejectedComposition[] = [],
160): Promise<GameObjective> {
// Imported lazily so the curated (default) path never pulls the model SDKs
// into the bundle.
const { completeStructured } = await import("./ai-gateway");
164 
const content = await completeStructured({
  task: "objective",
  system: composeSystemPrompt(),
  turns: [
    { role: "user", content: composeUserPrompt(steer, seenTitles, rejected) },
  ],
  schemaName: "game_objective",
  schema: {
    type: "object",
    properties: {
      title: { type: "string", description: "Punchy objective title" },
      description: {
        type: "string",
        description:
          'A grounded brief: a few newline-separated "• " bullet lines stating the real-timeline date(s) and place this departs from in our history, what winning looks like, and where it is centered (or, if global/cross-era, said so with the span named)',
      },
      era: { type: "string", description: "Anchoring era / setting" },
      icon: {
        type: "string",
        description: "A single emoji that fits the objective",
      },
      anchorYear: {
        type: ["integer", "null"],
        description: `Signed year the objective is aimed at (negative for BC), at or before ${SAFELY_HISTORICAL_BEFORE_YEAR}, or null if it spans all history`,
      },
    },
    required: ["title", "description", "era", "icon", "anchorYear"],
    additionalProperties: false,
  },
});
195 
if (!content) throw new Error("No objective generated");
197 
const parsed = JSON.parse(content) as GameObjective;
if (!parsed.title || !parsed.description)
  throw new Error("Invalid objective format generated");
return {
  title: parsed.title,
  description: parsed.description,
  era: parsed.era || "Across the ages",
  icon: parsed.icon || "🕰️",
  // A finite signed year anchors the chain dial; null / junk → no anchor (no-op).
  anchorYear:
    typeof parsed.anchorYear === "number" &&
    Number.isFinite(parsed.anchorYear)
      ? Math.round(parsed.anchorYear)
      : undefined,
};
213}
214 
215/**
* Validates a composed objective against the safely-historical bounds (#71) —
* the prompt is asked to obey them, but never trusted to. Three gates: a pure year
* bound, the same moderation seam messages pass through, and a structured subject
* check for the living-people / current-events framings a year bound can't see.
* Never throws. The year and subject gates fail CLOSED — an inconclusive result
* (junk, an empty answer, an outage) reads as out of bounds, so an unvetted
* composition falls back to curated rather than shipping. Moderation fails OPEN,
* the same fail-open-but-loud seam messages pass through (a safety classifier
* being down must never take the game down); it rejects only on an active flag.
*/
226async function objectiveWithinBounds(o: GameObjective): Promise<boolean> {
// 1. Year bound — pure, deterministic, free. A finite anchor must sit at or
//    before the safely-historical line; a null anchor (spans-all-history) is
//    allowed, its content still gated by the subject check below.
if (
  typeof o.anchorYear === "number" &&
  o.anchorYear > SAFELY_HISTORICAL_BEFORE_YEAR
)
  return false;
235 
const text = `${o.title}\n${o.description}`;
// 2 + 3 are independent model/detector calls — run them together; first "out"
//    wins. Lazy import keeps moderation (and its SDKs) off the curated path.
const { hardBlockCheck } = await import("./moderation");
const [mod, subjectInBounds] = await Promise.all([
  hardBlockCheck(text, "objective", "output"),
  checkObjectiveSubject(o),
]);
if (mod.blocked) return false;
return subjectInBounds;
246}
247 
248/**
* The structured subject check (the figure-floor pattern, server/utils/
* lifespan-estimator.ts): a cheap classifier that gates the free-prose title +
* description a year bound can't reach — does this center on living people,
* contemporary figures, ongoing conflicts, or post-cutoff events? Fails CLOSED:
* an empty answer, junk, or an outage returns false, so an unvetted objective is
* never shipped (it falls back to the safe curated floor instead). Never throws.
*/
256async function checkObjectiveSubject(o: GameObjective): Promise<boolean> {
const { completeStructured } = await import("./ai-gateway");
try {
  const content = await completeStructured({
    task: "objective-check",
    system: boundsCheckSystemPrompt(),
    turns: [
      {
        role: "user",
        content: `Title: ${o.title}\nDescription: ${o.description}\nEra: ${o.era}\nAnchor year: ${o.anchorYear ?? "none (spans all history)"}`,
      },
    ],
    schemaName: "objective_bounds",
    schema: {
      type: "object",
      properties: {
        withinBounds: {
          type: "boolean",
          description:
            "True only when the subject is safely historical (settled past, no living people or current events)",
        },
        reason: {
          type: "string",
          description: "One short clause on the call",
        },
      },
      required: ["withinBounds", "reason"],
      additionalProperties: false,
    },
  });
  if (!content) return false; // the model blipped — fail closed to the curated floor
  return mapBoundsWire(JSON.parse(content)) === true;
} catch (error) {
  console.error("Objective bounds check error:", error);
  return false; // an outage must never let an unvetted objective through
}
292}
293 
294/**
* The bounds-check wire → a clean verdict. `null` for an unusable shape (missing /
* non-boolean flag), which the caller treats exactly like "out of bounds". Exported
* pure so the guard is directly testable, like mapLifespanWire.
*/
299export function mapBoundsWire(wire: unknown): boolean | null {
const w = wire as { withinBounds?: unknown } | null;
if (!w || typeof w.withinBounds !== "boolean") return null;
return w.withinBounds;
303}
304 
305/**
* Semantic de-dup (#95 follow-up). The free normalized-title match in
* generateObjective catches verbatim / reskinned repeats; this catches the ones it
* can't — the SAME objective reworded under a fresh title ("Save the Library of
* Alexandria" vs "Keep Alexandria's great library from the flames"). A cheap Haiku
* judge compares the candidate against everything already on offer (the curated pool
* in full, plus the session's seen titles) and answers: is this essentially one of
* them again?
*
* Freshness, not safety, so this fails OPEN: an outage, empty answer, or junk verdict
* reads as "not a duplicate" and ships (the opposite stance from the bounds gate — a
* de-dup classifier being down must never cost the player a composition). Modes via
* EVERWHEN_OBJECTIVE_DEDUP mirror moderation: 'off' skips the call, 'shadow' runs and
* logs what it WOULD reject without acting, 'enforce' (default) rejects for real.
* Never throws.
*/
321async function objectiveIsDuplicate(
candidate: GameObjective,
curated: GameObjective[],
seenTitles: string[],
325): Promise<DedupVerdict> {
const fresh: DedupVerdict = {
  duplicate: false,
  closestMatch: "",
  reason: "",
};
const mode = objectiveDedupMode();
if (mode === "off") return fresh;
333 
let verdict: DedupVerdict;
try {
  const { completeStructured } = await import("./ai-gateway");
  const content = await completeStructured({
    task: "objective-dedup",
    system: dedupSystemPrompt(),
    turns: [
      {
        role: "user",
        content: dedupUserPrompt(candidate, curated, seenTitles),
      },
    ],
    schemaName: "objective_dedup",
    schema: {
      type: "object",
      properties: {
        // Fact-retrieval before the decision it informs (schema order is
        // load-bearing): name the nearest existing objective first, then judge.
        closestMatch: {
          type: "string",
          description:
            'Title of the nearest existing objective, or "none" if nothing is close',
        },
        duplicate: {
          type: "boolean",
          description:
            "True only when the candidate is essentially that existing objective reworded — the same counterfactual, not merely the same era or theme",
        },
        reason: {
          type: "string",
          description: "One short clause on the call",
        },
      },
      required: ["closestMatch", "duplicate", "reason"],
      additionalProperties: false,
    },
  });
  // Fail open on an unusable verdict — a de-dup blip must not drop a composition.
  verdict = (content && mapDedupWire(JSON.parse(content))) || fresh;
} catch (error) {
  console.error("Objective de-dup check error:", error);
  return fresh; // freshness fails open — never take a composition down
}
377 
if (verdict.duplicate) {
  emitObjDedup({
    mode,
    wouldReject: true,
    enforced: mode === "enforce",
    closestMatch: verdict.closestMatch,
    candidate: candidate.title,
  });
  if (mode === "shadow") return fresh; // observe without biting — ship it
}
return verdict;
389}
390 
391/** EVERWHEN_OBJECTIVE_DEDUP: off | shadow | enforce (default enforce), the same
*  three-mode shape as EVERWHEN_MODERATION. */
393function objectiveDedupMode(): "off" | "shadow" | "enforce" {
const m = process.env.EVERWHEN_OBJECTIVE_DEDUP;
return m === "off" || m === "shadow" ? m : "enforce";
396}
397 
398/** One greppable [objdedup] line per flagged duplicate — the calibration
*  instrument for shadow mode. Quiet under tests, like [mod]. */
400function emitObjDedup(line: Record<string, unknown>): void {
if (!process.env.VITEST) console.info(`[objdedup] ${JSON.stringify(line)}`);
402}
403 
404/**
* The de-dup wire → a clean verdict, or `null` for an unusable shape (a missing /
* non-boolean flag), which the caller treats as "not a duplicate" (fail open).
* Exported pure so the guard is directly testable, like mapBoundsWire.
*/
409export function mapDedupWire(wire: unknown): DedupVerdict | null {
const w = wire as {
  duplicate?: unknown;
  closestMatch?: unknown;
  reason?: unknown;
} | null;
if (!w || typeof w.duplicate !== "boolean") return null;
return {
  duplicate: w.duplicate,
  closestMatch: typeof w.closestMatch === "string" ? w.closestMatch : "",
  reason: typeof w.reason === "string" ? w.reason : "",
};
421}
⋯ 120 lines hidden (lines 422–541)422 
423/** System prompt for the semantic de-dup judge. */
424function dedupSystemPrompt(): string {
return `You are a de-dup check for a historical strategy game. You are given a freshly composed objective and the list of objectives already on offer. Decide whether the new one is essentially one of the existing objectives reworded.
426 
427Mark it a DUPLICATE (duplicate=true) when it aims at the SAME counterfactual as an existing objective — the same pivotal event, person, or outcome — even if the title, wording, era label, or framing differ ("Save the Library of Alexandria" and "Keep Alexandria's great library from the flames" are the same objective).
428 
429Mark it NOT a duplicate (duplicate=false) when it targets a genuinely different event, person, place, or outcome — even if it shares a broad theme (war, science, empire) or era with an existing one. Sharing a subject is not enough; aiming at the same specific turning point is.
430 
431Name the closest existing title in closestMatch (or "none"), then decide, then give one short reason.`;
432}
433 
434/** De-dup user turn: the candidate, then everything already on offer (the curated
*  pool in full, plus the session's seen titles). */
436function dedupUserPrompt(
candidate: GameObjective,
curated: GameObjective[],
seenTitles: string[],
440): string {
const existing = [
  ...curated.map((o) => `• ${o.title} — ${o.description}`),
  ...seenTitles.map((t) => `• ${t}`),
].join("\n");
return `CANDIDATE objective:
446Title: ${candidate.title}
447Description: ${candidate.description}
448 
449Objectives ALREADY on offer:
450${existing}
451 
452Is the candidate essentially one of the objectives already on offer, reworded?`;
453}
454 
455/** System prompt for composition: the tone bar, the grounding bar, and the
*  non-negotiable safety bounds. */
457function composeSystemPrompt(): string {
return `You are a historian and game designer inventing grand, evocative counterfactual objectives for a game where players text historical figures to bend history.
459 
460Hold every objective to three bars:
461 
462TONE — sweeping and vivid, a whole world to remake in the spirit of the examples, never a small errand.
463 
464GROUNDING (issue #82) — every brief names the real-timeline date(s) and the place it departs from in our history, so a player who is not American and does not already know the date still gets a concrete anchor. Never assume the reader's frame.
465 
466BOUNDS (safety, non-negotiable) — the objective must be safely historical:
467- Set in the settled past. Any pivotal anchor year must be at or before ${SAFELY_HISTORICAL_BEFORE_YEAR}.
468- Never centered on, and never requiring contact with, living people, contemporary public figures, ongoing conflicts, or current events. Reach for history, not the present or the recent past.`;
469}
470 
471/** Composition user turn: curated few-shot exemplars (framed as territory already
*  taken, never a menu to copy), the session avoid-list, any attempt already
*  rejected this call, the steer, and the ask. */
474function composeUserPrompt(
steer: ObjectiveSteer,
seenTitles: string[],
rejected: RejectedComposition[] = [],
478): string {
return `Objectives we love — match their TONE, SCALE, and brief SHAPE, but treat their SUBJECTS as territory already taken. Invent something genuinely new; vary away from every one in subject, era, and region. Do NOT reproduce or lightly reskin them (especially over-familiar picks like "Save the Library of Alexandria"):
480${curatedExemplars()}
481${avoidClause(seenTitles)}${rejectedClause(rejected)}
482Invent ONE fresh objective, unlike anything above — a different subject, era, and region from the examples${seenTitles.length ? " and from anything already composed this session" : ""}.${steerClause(steer)}
483 
484Give it: a punchy title; an anchoring era; a single emoji; the anchor year it is aimed at (the pivotal year where winning is decided) as a SIGNED integer — negative for BC, at or before ${SAFELY_HISTORICAL_BEFORE_YEAR} — or null if it genuinely spans all of history with no single hinge; and a GROUNDED BRIEF as the description.
485 
486The brief is a few short bullet lines, each beginning with "• " and separated by newlines (the same shape as the examples above), that together state: (1) when and where this actually happened or ended in OUR timeline, with real dates; (2) what winning looks like; (3) where on Earth it is centered — name the region or country, or, if it genuinely spans the globe or all eras, say so and name the span rather than forcing one country. Put the real date IN the brief; the real-timeline date(s) are NOT the anchor year — state the actual history, never merely restate the anchor. Keep each bullet tight.`;
487}
488 
489/** System prompt for the structured subject check. */
490function boundsCheckSystemPrompt(): string {
return `You are a safety check for a historical strategy game. You are given a freshly generated objective (title, description, era, anchor year). Decide whether it stays safely in the settled past.
492 
493Mark it OUT OF BOUNDS (withinBounds=false) if it centers on, or would require contacting, any of:
494- a living person or a present-day public figure,
495- an ongoing conflict or a current event,
496- anything anchored after the year ${SAFELY_HISTORICAL_BEFORE_YEAR}.
497 
498Mark it IN BOUNDS (withinBounds=true) only when its subject is historical — people and events settled in the past, before living memory. Dramatic history is fine (wars, plagues, empires, revolutions); the test is WHEN and WHO, not how grand.
499 
500When you are unsure, answer withinBounds=false. Give a short reason either way.`;
501}
502 
503/** The curated pool rendered as few-shot exemplars (title — description), read
*  live from the pool so the bar can never drift from a hardcoded copy. */
505function curatedExemplars(): string {
return listCuratedObjectives()
  .map((o) => `• ${o.title} — ${o.description}`)
  .join("\n");
509}
510 
511/** The session's already-composed titles, listed so the model steers away from
*  repeating them (#95). Empty when nothing's been rolled yet — the first compose
*  carries no clause, so an unseeded prompt stays identical to before. */
514function avoidClause(seenTitles: string[]): string {
if (!seenTitles.length) return "";
return `\nYou have ALREADY composed these this session — do not repeat or echo them; pick an entirely different subject:\n${seenTitles.map((t) => `• ${t}`).join("\n")}\n`;
517}
518 
519/** The attempt already rejected in THIS compose (the loop caps at 2, so at most one),
*  listed so a reroll is told what not to draw again and diverges instead of
*  reproducing what just failed. Empty on the first attempt, so an un-rerolled prompt
*  stays byte-identical to before. */
523function rejectedClause(rejected: RejectedComposition[]): string {
if (!rejected.length) return "";
return `\nAlready rejected this compose — do not repeat or lightly reskin; go somewhere entirely different:\n${rejected.map((r) => `• ${r.title} — ${r.reason}`).join("\n")}\n`;
526}
527 
528/** Turns the closed-enum steer into a short clause biasing the model. Absent axes
*  simply don't appear, leaving them to the model ("no preference"). */
530function steerClause(steer: ObjectiveSteer): string {
const parts: string[] = [];
if (steer.era) {
  parts.push(
    steer.era === "Across the ages"
      ? "Let it span the ages rather than a single era."
      : `Anchor it in this stretch of history: ${steer.era}.`,
  );
}
if (steer.theme) parts.push(`Center it on the theme of ${steer.theme}.`);
return parts.length ? ` ${parts.join(" ")}` : "";
541}

Reroll feedback, and the byte-identical default prompt

The second half of the change is small but easy to get wrong. A rejected attempt is now fed back into the compose prompt so the reroll diverges. That means the prompt gained a new conditional clause — and the reviewer's fair question is whether the common path (a first compose, nothing seen, nothing rejected) still produces the exact same bytes it did before.

It does. The new rejectedClause is spliced immediately after avoidClause on the same line (line 481: ${avoidClause(seenTitles)}${rejectedClause(rejected)}). Both return "" when empty, so an un-rerolled, un-seeded compose renders the identical string in the identical slot the single avoidClause occupied before.

The interpolation slot — both clauses empty on the first attempt.

server/utils/objective-generator.ts · 541 lines

server/utils/objective-generator.ts541 lines · TypeScript

⋯ 470 lines hidden (lines 1–470)1/**
* Live, AI-composed objectives. The curated pool + the GameObjective shape live
* in ./objectives (pure, client-safe); this module owns the model path and is
* therefore SERVER-ONLY — it reaches the AI gateway (and through it the model
* SDKs + the AsyncLocalStorage run-context, which must never enter the browser
* bundle). Client code imports the curated pool + the steer enums from ./objectives
* directly.
*
* A composition is bounded AND steerable (#71):
*  - BOUNDED — the prompt is constrained to safely-historical objectives, and the
*    output is independently validated (the prompt alone isn't trusted): a finite
*    anchor year must sit at or before the shared safely-historical line, a small
*    structured check gates the living-people / current-events framings free prose
*    can smuggle past a year bound, and the text runs through the same moderation
*    seam as messages. Out of bounds → reroll once, then fall back to curated. The
*    curated pool is always the floor; a generation or validation failure never
*    hard-fails the run start, it just yields a curated objective.
*  - STEERED — the player biases the composition along two closed enums (era +
*    theme); see ObjectiveSteer in ./objectives.
*  - FRESH (#95) — a composition may reproduce neither the curated pool nor
*    anything composed earlier this session. Two guards: a free normalized-title
*    match catches verbatim / lightly-reskinned repeats, and a cheap Haiku judge
*    (objectiveIsDuplicate) catches the semantic near-duplicate a title match
*    can't see — the same objective, reworded. A rejected attempt is fed back into
*    the single reroll so it diverges instead of re-drawing the same subject;
*    a persistent collision falls back to an unseen curated pick.
*/
28import {
pickCurated,
listCuratedObjectives,
normalizeObjectiveTitle,
type GameObjective,
type ObjectiveSteer,
34} from "./objectives";
35import { SAFELY_HISTORICAL_BEFORE_YEAR } from "./historical-floor";
36 
37/**
* What generateObjective produced: the objective plus its provenance. `composed`
* is true ONLY when the live AI path yielded this objective; it is false for the
* curated floor — both the default no-AI path and every AI fallback (a generation,
* bounds, or de-dup failure). The endpoint pairs `composed === false` with a
* requested steer to tell the player their steer was quietly dropped (#127), instead
* of letting a silent curated fallback read as "steering is broken".
*/
45export interface GeneratedObjective {
objective: GameObjective;
composed: boolean;
48}
49 
50/**
* A composed candidate this call already rejected (out of bounds or a duplicate),
* fed back into the reroll so the second attempt is told what NOT to draw again.
*/
54interface RejectedComposition {
title: string;
description: string;
reason: string;
58}
59 
60/** A semantic de-dup verdict: is the candidate an existing objective reworded? */
61interface DedupVerdict {
duplicate: boolean;
/** The nearest existing title the judge matched against (telemetry / the reroll). */
closestMatch: string;
/** One short clause on the call — surfaced to the reroll and the [objdedup] log. */
reason: string;
67}
68 
69/**
* Returns an objective for a new run, plus whether the live AI path composed it (vs
* the curated floor). Curated-random by default (instant, no API call); pass
* useAI=true to compose one live under the given steer, with automatic fallback to
* curated. Never throws and never ships an out-of-bounds objective.
*
* `avoid` (#95) is the session's already-composed titles — the only anti-repeat
* memory the stateless server has (the client tracks and supplies them; the curated
* pool the server already knows). A composed result may reproduce NEITHER the
* curated pool NOR anything seen this session: a free normalized-title match catches
* exact / reskinned repeats, and a Haiku judge (objectiveIsDuplicate) catches the
* semantic near-duplicate a title match misses. A collision is rerolled once — the
* rejected attempt fed back so the reroll diverges — then the curated FALLBACK itself
* avoids the seen titles, so even the floor stays fresh.
*/
84export async function generateObjective(
useAI = false,
steer: ObjectiveSteer = {},
avoid: string[] = [],
88): Promise<GeneratedObjective> {
// The curated pool — the far half of the free de-dup Set and the candidate list
// the semantic judge compares against. (The compose exemplars and the fallback
// floor re-read the pool through their own helpers.)
const curated = listCuratedObjectives();
// Session-seen titles, normalized — used both for the curated fallback (so it
// never re-serves a seen objective) and, unioned with the curated pool below,
// for the free post-generation collision guard.
const seen = new Set(avoid.map(normalizeObjectiveTitle).filter(Boolean));
const dedupe = new Set(seen);
for (const o of curated) dedupe.add(normalizeObjectiveTitle(o.title));
99 
if (useAI) {
  // Never ship out of bounds OR a duplicate, never hard-fail the run: compose
  // live, and on an out-of-bounds / colliding result reroll exactly once, then
  // fall back to the (unseen) curated floor. Each rejected attempt is fed back
  // into the reroll so the second draw diverges rather than repeating itself. A
  // transport/parse failure won't heal on a reroll, so it drops straight to
  // curated instead of a second call.
  const rejected: RejectedComposition[] = [];
  for (let attempt = 1; attempt <= 2; attempt++) {
    try {
      const candidate = await composeObjective(steer, avoid, rejected);
      let reason: string;
      // The free normalized-title match short-circuits ahead of the paid checks:
      // an exact / reskinned collision never spends a bounds or de-dup call.
      if (dedupe.has(normalizeObjectiveTitle(candidate.title))) {
        reason = "duplicates an existing objective";
      } else {
        // Bounds (safety, fail-closed) and the semantic de-dup judge (freshness,
        // fail-open) are independent — run them together; either one rejects.
        const [inBounds, dup] = await Promise.all([
          objectiveWithinBounds(candidate),
          objectiveIsDuplicate(candidate, curated, avoid),
        ]);
        if (inBounds && !dup.duplicate)
          return { objective: candidate, composed: true };
        reason = !inBounds
          ? "outside the safely-historical bounds"
          : dup.reason || "too close to an existing objective";
      }
      rejected.push({
        title: candidate.title,
        description: candidate.description,
        reason,
      });
      console.warn(
        `AI objective rejected (${reason}) on attempt ${attempt} of 2; ${attempt < 2 ? "rerolling" : "falling back to curated"}`,
      );
    } catch (error) {
      console.error(
        "AI objective generation failed; falling back to curated pool:",
        error,
      );
      break;
    }
  }
}
// The curated floor — reached by the default no-AI path or any AI fallback.
return { objective: pickCurated(seen), composed: false };
148}
149 
150/**
* Composes one fresh objective with the model under the steer, steering away from
* the session's seen titles and any attempt already rejected this call. Returns the
* same shape as the curated pool so the rest of the game treats them identically.
* Throws on an empty/malformed answer (the caller owns the fallback).
*/
156async function composeObjective(
steer: ObjectiveSteer,
seenTitles: string[] = [],
rejected: RejectedComposition[] = [],
160): Promise<GameObjective> {
// Imported lazily so the curated (default) path never pulls the model SDKs
// into the bundle.
const { completeStructured } = await import("./ai-gateway");
164 
const content = await completeStructured({
  task: "objective",
  system: composeSystemPrompt(),
  turns: [
    { role: "user", content: composeUserPrompt(steer, seenTitles, rejected) },
  ],
  schemaName: "game_objective",
  schema: {
    type: "object",
    properties: {
      title: { type: "string", description: "Punchy objective title" },
      description: {
        type: "string",
        description:
          'A grounded brief: a few newline-separated "• " bullet lines stating the real-timeline date(s) and place this departs from in our history, what winning looks like, and where it is centered (or, if global/cross-era, said so with the span named)',
      },
      era: { type: "string", description: "Anchoring era / setting" },
      icon: {
        type: "string",
        description: "A single emoji that fits the objective",
      },
      anchorYear: {
        type: ["integer", "null"],
        description: `Signed year the objective is aimed at (negative for BC), at or before ${SAFELY_HISTORICAL_BEFORE_YEAR}, or null if it spans all history`,
      },
    },
    required: ["title", "description", "era", "icon", "anchorYear"],
    additionalProperties: false,
  },
});
195 
if (!content) throw new Error("No objective generated");
197 
const parsed = JSON.parse(content) as GameObjective;
if (!parsed.title || !parsed.description)
  throw new Error("Invalid objective format generated");
return {
  title: parsed.title,
  description: parsed.description,
  era: parsed.era || "Across the ages",
  icon: parsed.icon || "🕰️",
  // A finite signed year anchors the chain dial; null / junk → no anchor (no-op).
  anchorYear:
    typeof parsed.anchorYear === "number" &&
    Number.isFinite(parsed.anchorYear)
      ? Math.round(parsed.anchorYear)
      : undefined,
};
213}
214 
215/**
* Validates a composed objective against the safely-historical bounds (#71) —
* the prompt is asked to obey them, but never trusted to. Three gates: a pure year
* bound, the same moderation seam messages pass through, and a structured subject
* check for the living-people / current-events framings a year bound can't see.
* Never throws. The year and subject gates fail CLOSED — an inconclusive result
* (junk, an empty answer, an outage) reads as out of bounds, so an unvetted
* composition falls back to curated rather than shipping. Moderation fails OPEN,
* the same fail-open-but-loud seam messages pass through (a safety classifier
* being down must never take the game down); it rejects only on an active flag.
*/
226async function objectiveWithinBounds(o: GameObjective): Promise<boolean> {
// 1. Year bound — pure, deterministic, free. A finite anchor must sit at or
//    before the safely-historical line; a null anchor (spans-all-history) is
//    allowed, its content still gated by the subject check below.
if (
  typeof o.anchorYear === "number" &&
  o.anchorYear > SAFELY_HISTORICAL_BEFORE_YEAR
)
  return false;
235 
const text = `${o.title}\n${o.description}`;
// 2 + 3 are independent model/detector calls — run them together; first "out"
//    wins. Lazy import keeps moderation (and its SDKs) off the curated path.
const { hardBlockCheck } = await import("./moderation");
const [mod, subjectInBounds] = await Promise.all([
  hardBlockCheck(text, "objective", "output"),
  checkObjectiveSubject(o),
]);
if (mod.blocked) return false;
return subjectInBounds;
246}
247 
248/**
* The structured subject check (the figure-floor pattern, server/utils/
* lifespan-estimator.ts): a cheap classifier that gates the free-prose title +
* description a year bound can't reach — does this center on living people,
* contemporary figures, ongoing conflicts, or post-cutoff events? Fails CLOSED:
* an empty answer, junk, or an outage returns false, so an unvetted objective is
* never shipped (it falls back to the safe curated floor instead). Never throws.
*/
256async function checkObjectiveSubject(o: GameObjective): Promise<boolean> {
const { completeStructured } = await import("./ai-gateway");
try {
  const content = await completeStructured({
    task: "objective-check",
    system: boundsCheckSystemPrompt(),
    turns: [
      {
        role: "user",
        content: `Title: ${o.title}\nDescription: ${o.description}\nEra: ${o.era}\nAnchor year: ${o.anchorYear ?? "none (spans all history)"}`,
      },
    ],
    schemaName: "objective_bounds",
    schema: {
      type: "object",
      properties: {
        withinBounds: {
          type: "boolean",
          description:
            "True only when the subject is safely historical (settled past, no living people or current events)",
        },
        reason: {
          type: "string",
          description: "One short clause on the call",
        },
      },
      required: ["withinBounds", "reason"],
      additionalProperties: false,
    },
  });
  if (!content) return false; // the model blipped — fail closed to the curated floor
  return mapBoundsWire(JSON.parse(content)) === true;
} catch (error) {
  console.error("Objective bounds check error:", error);
  return false; // an outage must never let an unvetted objective through
}
292}
293 
294/**
* The bounds-check wire → a clean verdict. `null` for an unusable shape (missing /
* non-boolean flag), which the caller treats exactly like "out of bounds". Exported
* pure so the guard is directly testable, like mapLifespanWire.
*/
299export function mapBoundsWire(wire: unknown): boolean | null {
const w = wire as { withinBounds?: unknown } | null;
if (!w || typeof w.withinBounds !== "boolean") return null;
return w.withinBounds;
303}
304 
305/**
* Semantic de-dup (#95 follow-up). The free normalized-title match in
* generateObjective catches verbatim / reskinned repeats; this catches the ones it
* can't — the SAME objective reworded under a fresh title ("Save the Library of
* Alexandria" vs "Keep Alexandria's great library from the flames"). A cheap Haiku
* judge compares the candidate against everything already on offer (the curated pool
* in full, plus the session's seen titles) and answers: is this essentially one of
* them again?
*
* Freshness, not safety, so this fails OPEN: an outage, empty answer, or junk verdict
* reads as "not a duplicate" and ships (the opposite stance from the bounds gate — a
* de-dup classifier being down must never cost the player a composition). Modes via
* EVERWHEN_OBJECTIVE_DEDUP mirror moderation: 'off' skips the call, 'shadow' runs and
* logs what it WOULD reject without acting, 'enforce' (default) rejects for real.
* Never throws.
*/
321async function objectiveIsDuplicate(
candidate: GameObjective,
curated: GameObjective[],
seenTitles: string[],
325): Promise<DedupVerdict> {
const fresh: DedupVerdict = {
  duplicate: false,
  closestMatch: "",
  reason: "",
};
const mode = objectiveDedupMode();
if (mode === "off") return fresh;
333 
let verdict: DedupVerdict;
try {
  const { completeStructured } = await import("./ai-gateway");
  const content = await completeStructured({
    task: "objective-dedup",
    system: dedupSystemPrompt(),
    turns: [
      {
        role: "user",
        content: dedupUserPrompt(candidate, curated, seenTitles),
      },
    ],
    schemaName: "objective_dedup",
    schema: {
      type: "object",
      properties: {
        // Fact-retrieval before the decision it informs (schema order is
        // load-bearing): name the nearest existing objective first, then judge.
        closestMatch: {
          type: "string",
          description:
            'Title of the nearest existing objective, or "none" if nothing is close',
        },
        duplicate: {
          type: "boolean",
          description:
            "True only when the candidate is essentially that existing objective reworded — the same counterfactual, not merely the same era or theme",
        },
        reason: {
          type: "string",
          description: "One short clause on the call",
        },
      },
      required: ["closestMatch", "duplicate", "reason"],
      additionalProperties: false,
    },
  });
  // Fail open on an unusable verdict — a de-dup blip must not drop a composition.
  verdict = (content && mapDedupWire(JSON.parse(content))) || fresh;
} catch (error) {
  console.error("Objective de-dup check error:", error);
  return fresh; // freshness fails open — never take a composition down
}
377 
if (verdict.duplicate) {
  emitObjDedup({
    mode,
    wouldReject: true,
    enforced: mode === "enforce",
    closestMatch: verdict.closestMatch,
    candidate: candidate.title,
  });
  if (mode === "shadow") return fresh; // observe without biting — ship it
}
return verdict;
389}
390 
391/** EVERWHEN_OBJECTIVE_DEDUP: off | shadow | enforce (default enforce), the same
*  three-mode shape as EVERWHEN_MODERATION. */
393function objectiveDedupMode(): "off" | "shadow" | "enforce" {
const m = process.env.EVERWHEN_OBJECTIVE_DEDUP;
return m === "off" || m === "shadow" ? m : "enforce";
396}
397 
398/** One greppable [objdedup] line per flagged duplicate — the calibration
*  instrument for shadow mode. Quiet under tests, like [mod]. */
400function emitObjDedup(line: Record<string, unknown>): void {
if (!process.env.VITEST) console.info(`[objdedup] ${JSON.stringify(line)}`);
402}
403 
404/**
* The de-dup wire → a clean verdict, or `null` for an unusable shape (a missing /
* non-boolean flag), which the caller treats as "not a duplicate" (fail open).
* Exported pure so the guard is directly testable, like mapBoundsWire.
*/
409export function mapDedupWire(wire: unknown): DedupVerdict | null {
const w = wire as {
  duplicate?: unknown;
  closestMatch?: unknown;
  reason?: unknown;
} | null;
if (!w || typeof w.duplicate !== "boolean") return null;
return {
  duplicate: w.duplicate,
  closestMatch: typeof w.closestMatch === "string" ? w.closestMatch : "",
  reason: typeof w.reason === "string" ? w.reason : "",
};
421}
422 
423/** System prompt for the semantic de-dup judge. */
424function dedupSystemPrompt(): string {
return `You are a de-dup check for a historical strategy game. You are given a freshly composed objective and the list of objectives already on offer. Decide whether the new one is essentially one of the existing objectives reworded.
426 
427Mark it a DUPLICATE (duplicate=true) when it aims at the SAME counterfactual as an existing objective — the same pivotal event, person, or outcome — even if the title, wording, era label, or framing differ ("Save the Library of Alexandria" and "Keep Alexandria's great library from the flames" are the same objective).
428 
429Mark it NOT a duplicate (duplicate=false) when it targets a genuinely different event, person, place, or outcome — even if it shares a broad theme (war, science, empire) or era with an existing one. Sharing a subject is not enough; aiming at the same specific turning point is.
430 
431Name the closest existing title in closestMatch (or "none"), then decide, then give one short reason.`;
432}
433 
434/** De-dup user turn: the candidate, then everything already on offer (the curated
*  pool in full, plus the session's seen titles). */
436function dedupUserPrompt(
candidate: GameObjective,
curated: GameObjective[],
seenTitles: string[],
440): string {
const existing = [
  ...curated.map((o) => `• ${o.title} — ${o.description}`),
  ...seenTitles.map((t) => `• ${t}`),
].join("\n");
return `CANDIDATE objective:
446Title: ${candidate.title}
447Description: ${candidate.description}
448 
449Objectives ALREADY on offer:
450${existing}
451 
452Is the candidate essentially one of the objectives already on offer, reworded?`;
453}
454 
455/** System prompt for composition: the tone bar, the grounding bar, and the
*  non-negotiable safety bounds. */
457function composeSystemPrompt(): string {
return `You are a historian and game designer inventing grand, evocative counterfactual objectives for a game where players text historical figures to bend history.
459 
460Hold every objective to three bars:
461 
462TONE — sweeping and vivid, a whole world to remake in the spirit of the examples, never a small errand.
463 
464GROUNDING (issue #82) — every brief names the real-timeline date(s) and the place it departs from in our history, so a player who is not American and does not already know the date still gets a concrete anchor. Never assume the reader's frame.
465 
466BOUNDS (safety, non-negotiable) — the objective must be safely historical:
467- Set in the settled past. Any pivotal anchor year must be at or before ${SAFELY_HISTORICAL_BEFORE_YEAR}.
468- Never centered on, and never requiring contact with, living people, contemporary public figures, ongoing conflicts, or current events. Reach for history, not the present or the recent past.`;
469}
470 
471/** Composition user turn: curated few-shot exemplars (framed as territory already
*  taken, never a menu to copy), the session avoid-list, any attempt already
*  rejected this call, the steer, and the ask. */
474function composeUserPrompt(
steer: ObjectiveSteer,
seenTitles: string[],
rejected: RejectedComposition[] = [],
478): string {
return `Objectives we love — match their TONE, SCALE, and brief SHAPE, but treat their SUBJECTS as territory already taken. Invent something genuinely new; vary away from every one in subject, era, and region. Do NOT reproduce or lightly reskin them (especially over-familiar picks like "Save the Library of Alexandria"):
480${curatedExemplars()}
481${avoidClause(seenTitles)}${rejectedClause(rejected)}
482Invent ONE fresh objective, unlike anything above — a different subject, era, and region from the examples${seenTitles.length ? " and from anything already composed this session" : ""}.${steerClause(steer)}
483 
484Give it: a punchy title; an anchoring era; a single emoji; the anchor year it is aimed at (the pivotal year where winning is decided) as a SIGNED integer — negative for BC, at or before ${SAFELY_HISTORICAL_BEFORE_YEAR} — or null if it genuinely spans all of history with no single hinge; and a GROUNDED BRIEF as the description.
485 
486The brief is a few short bullet lines, each beginning with "• " and separated by newlines (the same shape as the examples above), that together state: (1) when and where this actually happened or ended in OUR timeline, with real dates; (2) what winning looks like; (3) where on Earth it is centered — name the region or country, or, if it genuinely spans the globe or all eras, say so and name the span rather than forcing one country. Put the real date IN the brief; the real-timeline date(s) are NOT the anchor year — state the actual history, never merely restate the anchor. Keep each bullet tight.`;
487}
⋯ 54 lines hidden (lines 488–541)488 
489/** System prompt for the structured subject check. */
490function boundsCheckSystemPrompt(): string {
return `You are a safety check for a historical strategy game. You are given a freshly generated objective (title, description, era, anchor year). Decide whether it stays safely in the settled past.
492 
493Mark it OUT OF BOUNDS (withinBounds=false) if it centers on, or would require contacting, any of:
494- a living person or a present-day public figure,
495- an ongoing conflict or a current event,
496- anything anchored after the year ${SAFELY_HISTORICAL_BEFORE_YEAR}.
497 
498Mark it IN BOUNDS (withinBounds=true) only when its subject is historical — people and events settled in the past, before living memory. Dramatic history is fine (wars, plagues, empires, revolutions); the test is WHEN and WHO, not how grand.
499 
500When you are unsure, answer withinBounds=false. Give a short reason either way.`;
501}
502 
503/** The curated pool rendered as few-shot exemplars (title — description), read
*  live from the pool so the bar can never drift from a hardcoded copy. */
505function curatedExemplars(): string {
return listCuratedObjectives()
  .map((o) => `• ${o.title} — ${o.description}`)
  .join("\n");
509}
510 
511/** The session's already-composed titles, listed so the model steers away from
*  repeating them (#95). Empty when nothing's been rolled yet — the first compose
*  carries no clause, so an unseeded prompt stays identical to before. */
514function avoidClause(seenTitles: string[]): string {
if (!seenTitles.length) return "";
return `\nYou have ALREADY composed these this session — do not repeat or echo them; pick an entirely different subject:\n${seenTitles.map((t) => `• ${t}`).join("\n")}\n`;
517}
518 
519/** The attempt already rejected in THIS compose (the loop caps at 2, so at most one),
*  listed so a reroll is told what not to draw again and diverges instead of
*  reproducing what just failed. Empty on the first attempt, so an un-rerolled prompt
*  stays byte-identical to before. */
523function rejectedClause(rejected: RejectedComposition[]): string {
if (!rejected.length) return "";
return `\nAlready rejected this compose — do not repeat or lightly reskin; go somewhere entirely different:\n${rejected.map((r) => `• ${r.title} — ${r.reason}`).join("\n")}\n`;
526}
527 
528/** Turns the closed-enum steer into a short clause biasing the model. Absent axes
*  simply don't appear, leaving them to the model ("no preference"). */
530function steerClause(steer: ObjectiveSteer): string {
const parts: string[] = [];
if (steer.era) {
  parts.push(
    steer.era === "Across the ages"
      ? "Let it span the ages rather than a single era."
      : `Anchor it in this stretch of history: ${steer.era}.`,
  );
}
if (steer.theme) parts.push(`Center it on the theme of ${steer.theme}.`);
return parts.length ? ` ${parts.join(" ")}` : "";
541}

rejectedClause: empty ⇒ no bytes; otherwise names what was rejected, and why.

server/utils/objective-generator.ts · 541 lines

server/utils/objective-generator.ts541 lines · TypeScript

⋯ 518 lines hidden (lines 1–518)1/**
* Live, AI-composed objectives. The curated pool + the GameObjective shape live
* in ./objectives (pure, client-safe); this module owns the model path and is
* therefore SERVER-ONLY — it reaches the AI gateway (and through it the model
* SDKs + the AsyncLocalStorage run-context, which must never enter the browser
* bundle). Client code imports the curated pool + the steer enums from ./objectives
* directly.
*
* A composition is bounded AND steerable (#71):
*  - BOUNDED — the prompt is constrained to safely-historical objectives, and the
*    output is independently validated (the prompt alone isn't trusted): a finite
*    anchor year must sit at or before the shared safely-historical line, a small
*    structured check gates the living-people / current-events framings free prose
*    can smuggle past a year bound, and the text runs through the same moderation
*    seam as messages. Out of bounds → reroll once, then fall back to curated. The
*    curated pool is always the floor; a generation or validation failure never
*    hard-fails the run start, it just yields a curated objective.
*  - STEERED — the player biases the composition along two closed enums (era +
*    theme); see ObjectiveSteer in ./objectives.
*  - FRESH (#95) — a composition may reproduce neither the curated pool nor
*    anything composed earlier this session. Two guards: a free normalized-title
*    match catches verbatim / lightly-reskinned repeats, and a cheap Haiku judge
*    (objectiveIsDuplicate) catches the semantic near-duplicate a title match
*    can't see — the same objective, reworded. A rejected attempt is fed back into
*    the single reroll so it diverges instead of re-drawing the same subject;
*    a persistent collision falls back to an unseen curated pick.
*/
28import {
pickCurated,
listCuratedObjectives,
normalizeObjectiveTitle,
type GameObjective,
type ObjectiveSteer,
34} from "./objectives";
35import { SAFELY_HISTORICAL_BEFORE_YEAR } from "./historical-floor";
36 
37/**
* What generateObjective produced: the objective plus its provenance. `composed`
* is true ONLY when the live AI path yielded this objective; it is false for the
* curated floor — both the default no-AI path and every AI fallback (a generation,
* bounds, or de-dup failure). The endpoint pairs `composed === false` with a
* requested steer to tell the player their steer was quietly dropped (#127), instead
* of letting a silent curated fallback read as "steering is broken".
*/
45export interface GeneratedObjective {
objective: GameObjective;
composed: boolean;
48}
49 
50/**
* A composed candidate this call already rejected (out of bounds or a duplicate),
* fed back into the reroll so the second attempt is told what NOT to draw again.
*/
54interface RejectedComposition {
title: string;
description: string;
reason: string;
58}
59 
60/** A semantic de-dup verdict: is the candidate an existing objective reworded? */
61interface DedupVerdict {
duplicate: boolean;
/** The nearest existing title the judge matched against (telemetry / the reroll). */
closestMatch: string;
/** One short clause on the call — surfaced to the reroll and the [objdedup] log. */
reason: string;
67}
68 
69/**
* Returns an objective for a new run, plus whether the live AI path composed it (vs
* the curated floor). Curated-random by default (instant, no API call); pass
* useAI=true to compose one live under the given steer, with automatic fallback to
* curated. Never throws and never ships an out-of-bounds objective.
*
* `avoid` (#95) is the session's already-composed titles — the only anti-repeat
* memory the stateless server has (the client tracks and supplies them; the curated
* pool the server already knows). A composed result may reproduce NEITHER the
* curated pool NOR anything seen this session: a free normalized-title match catches
* exact / reskinned repeats, and a Haiku judge (objectiveIsDuplicate) catches the
* semantic near-duplicate a title match misses. A collision is rerolled once — the
* rejected attempt fed back so the reroll diverges — then the curated FALLBACK itself
* avoids the seen titles, so even the floor stays fresh.
*/
84export async function generateObjective(
useAI = false,
steer: ObjectiveSteer = {},
avoid: string[] = [],
88): Promise<GeneratedObjective> {
// The curated pool — the far half of the free de-dup Set and the candidate list
// the semantic judge compares against. (The compose exemplars and the fallback
// floor re-read the pool through their own helpers.)
const curated = listCuratedObjectives();
// Session-seen titles, normalized — used both for the curated fallback (so it
// never re-serves a seen objective) and, unioned with the curated pool below,
// for the free post-generation collision guard.
const seen = new Set(avoid.map(normalizeObjectiveTitle).filter(Boolean));
const dedupe = new Set(seen);
for (const o of curated) dedupe.add(normalizeObjectiveTitle(o.title));
99 
if (useAI) {
  // Never ship out of bounds OR a duplicate, never hard-fail the run: compose
  // live, and on an out-of-bounds / colliding result reroll exactly once, then
  // fall back to the (unseen) curated floor. Each rejected attempt is fed back
  // into the reroll so the second draw diverges rather than repeating itself. A
  // transport/parse failure won't heal on a reroll, so it drops straight to
  // curated instead of a second call.
  const rejected: RejectedComposition[] = [];
  for (let attempt = 1; attempt <= 2; attempt++) {
    try {
      const candidate = await composeObjective(steer, avoid, rejected);
      let reason: string;
      // The free normalized-title match short-circuits ahead of the paid checks:
      // an exact / reskinned collision never spends a bounds or de-dup call.
      if (dedupe.has(normalizeObjectiveTitle(candidate.title))) {
        reason = "duplicates an existing objective";
      } else {
        // Bounds (safety, fail-closed) and the semantic de-dup judge (freshness,
        // fail-open) are independent — run them together; either one rejects.
        const [inBounds, dup] = await Promise.all([
          objectiveWithinBounds(candidate),
          objectiveIsDuplicate(candidate, curated, avoid),
        ]);
        if (inBounds && !dup.duplicate)
          return { objective: candidate, composed: true };
        reason = !inBounds
          ? "outside the safely-historical bounds"
          : dup.reason || "too close to an existing objective";
      }
      rejected.push({
        title: candidate.title,
        description: candidate.description,
        reason,
      });
      console.warn(
        `AI objective rejected (${reason}) on attempt ${attempt} of 2; ${attempt < 2 ? "rerolling" : "falling back to curated"}`,
      );
    } catch (error) {
      console.error(
        "AI objective generation failed; falling back to curated pool:",
        error,
      );
      break;
    }
  }
}
// The curated floor — reached by the default no-AI path or any AI fallback.
return { objective: pickCurated(seen), composed: false };
148}
149 
150/**
* Composes one fresh objective with the model under the steer, steering away from
* the session's seen titles and any attempt already rejected this call. Returns the
* same shape as the curated pool so the rest of the game treats them identically.
* Throws on an empty/malformed answer (the caller owns the fallback).
*/
156async function composeObjective(
steer: ObjectiveSteer,
seenTitles: string[] = [],
rejected: RejectedComposition[] = [],
160): Promise<GameObjective> {
// Imported lazily so the curated (default) path never pulls the model SDKs
// into the bundle.
const { completeStructured } = await import("./ai-gateway");
164 
const content = await completeStructured({
  task: "objective",
  system: composeSystemPrompt(),
  turns: [
    { role: "user", content: composeUserPrompt(steer, seenTitles, rejected) },
  ],
  schemaName: "game_objective",
  schema: {
    type: "object",
    properties: {
      title: { type: "string", description: "Punchy objective title" },
      description: {
        type: "string",
        description:
          'A grounded brief: a few newline-separated "• " bullet lines stating the real-timeline date(s) and place this departs from in our history, what winning looks like, and where it is centered (or, if global/cross-era, said so with the span named)',
      },
      era: { type: "string", description: "Anchoring era / setting" },
      icon: {
        type: "string",
        description: "A single emoji that fits the objective",
      },
      anchorYear: {
        type: ["integer", "null"],
        description: `Signed year the objective is aimed at (negative for BC), at or before ${SAFELY_HISTORICAL_BEFORE_YEAR}, or null if it spans all history`,
      },
    },
    required: ["title", "description", "era", "icon", "anchorYear"],
    additionalProperties: false,
  },
});
195 
if (!content) throw new Error("No objective generated");
197 
const parsed = JSON.parse(content) as GameObjective;
if (!parsed.title || !parsed.description)
  throw new Error("Invalid objective format generated");
return {
  title: parsed.title,
  description: parsed.description,
  era: parsed.era || "Across the ages",
  icon: parsed.icon || "🕰️",
  // A finite signed year anchors the chain dial; null / junk → no anchor (no-op).
  anchorYear:
    typeof parsed.anchorYear === "number" &&
    Number.isFinite(parsed.anchorYear)
      ? Math.round(parsed.anchorYear)
      : undefined,
};
213}
214 
215/**
* Validates a composed objective against the safely-historical bounds (#71) —
* the prompt is asked to obey them, but never trusted to. Three gates: a pure year
* bound, the same moderation seam messages pass through, and a structured subject
* check for the living-people / current-events framings a year bound can't see.
* Never throws. The year and subject gates fail CLOSED — an inconclusive result
* (junk, an empty answer, an outage) reads as out of bounds, so an unvetted
* composition falls back to curated rather than shipping. Moderation fails OPEN,
* the same fail-open-but-loud seam messages pass through (a safety classifier
* being down must never take the game down); it rejects only on an active flag.
*/
226async function objectiveWithinBounds(o: GameObjective): Promise<boolean> {
// 1. Year bound — pure, deterministic, free. A finite anchor must sit at or
//    before the safely-historical line; a null anchor (spans-all-history) is
//    allowed, its content still gated by the subject check below.
if (
  typeof o.anchorYear === "number" &&
  o.anchorYear > SAFELY_HISTORICAL_BEFORE_YEAR
)
  return false;
235 
const text = `${o.title}\n${o.description}`;
// 2 + 3 are independent model/detector calls — run them together; first "out"
//    wins. Lazy import keeps moderation (and its SDKs) off the curated path.
const { hardBlockCheck } = await import("./moderation");
const [mod, subjectInBounds] = await Promise.all([
  hardBlockCheck(text, "objective", "output"),
  checkObjectiveSubject(o),
]);
if (mod.blocked) return false;
return subjectInBounds;
246}
247 
248/**
* The structured subject check (the figure-floor pattern, server/utils/
* lifespan-estimator.ts): a cheap classifier that gates the free-prose title +
* description a year bound can't reach — does this center on living people,
* contemporary figures, ongoing conflicts, or post-cutoff events? Fails CLOSED:
* an empty answer, junk, or an outage returns false, so an unvetted objective is
* never shipped (it falls back to the safe curated floor instead). Never throws.
*/
256async function checkObjectiveSubject(o: GameObjective): Promise<boolean> {
const { completeStructured } = await import("./ai-gateway");
try {
  const content = await completeStructured({
    task: "objective-check",
    system: boundsCheckSystemPrompt(),
    turns: [
      {
        role: "user",
        content: `Title: ${o.title}\nDescription: ${o.description}\nEra: ${o.era}\nAnchor year: ${o.anchorYear ?? "none (spans all history)"}`,
      },
    ],
    schemaName: "objective_bounds",
    schema: {
      type: "object",
      properties: {
        withinBounds: {
          type: "boolean",
          description:
            "True only when the subject is safely historical (settled past, no living people or current events)",
        },
        reason: {
          type: "string",
          description: "One short clause on the call",
        },
      },
      required: ["withinBounds", "reason"],
      additionalProperties: false,
    },
  });
  if (!content) return false; // the model blipped — fail closed to the curated floor
  return mapBoundsWire(JSON.parse(content)) === true;
} catch (error) {
  console.error("Objective bounds check error:", error);
  return false; // an outage must never let an unvetted objective through
}
292}
293 
294/**
* The bounds-check wire → a clean verdict. `null` for an unusable shape (missing /
* non-boolean flag), which the caller treats exactly like "out of bounds". Exported
* pure so the guard is directly testable, like mapLifespanWire.
*/
299export function mapBoundsWire(wire: unknown): boolean | null {
const w = wire as { withinBounds?: unknown } | null;
if (!w || typeof w.withinBounds !== "boolean") return null;
return w.withinBounds;
303}
304 
305/**
* Semantic de-dup (#95 follow-up). The free normalized-title match in
* generateObjective catches verbatim / reskinned repeats; this catches the ones it
* can't — the SAME objective reworded under a fresh title ("Save the Library of
* Alexandria" vs "Keep Alexandria's great library from the flames"). A cheap Haiku
* judge compares the candidate against everything already on offer (the curated pool
* in full, plus the session's seen titles) and answers: is this essentially one of
* them again?
*
* Freshness, not safety, so this fails OPEN: an outage, empty answer, or junk verdict
* reads as "not a duplicate" and ships (the opposite stance from the bounds gate — a
* de-dup classifier being down must never cost the player a composition). Modes via
* EVERWHEN_OBJECTIVE_DEDUP mirror moderation: 'off' skips the call, 'shadow' runs and
* logs what it WOULD reject without acting, 'enforce' (default) rejects for real.
* Never throws.
*/
321async function objectiveIsDuplicate(
candidate: GameObjective,
curated: GameObjective[],
seenTitles: string[],
325): Promise<DedupVerdict> {
const fresh: DedupVerdict = {
  duplicate: false,
  closestMatch: "",
  reason: "",
};
const mode = objectiveDedupMode();
if (mode === "off") return fresh;
333 
let verdict: DedupVerdict;
try {
  const { completeStructured } = await import("./ai-gateway");
  const content = await completeStructured({
    task: "objective-dedup",
    system: dedupSystemPrompt(),
    turns: [
      {
        role: "user",
        content: dedupUserPrompt(candidate, curated, seenTitles),
      },
    ],
    schemaName: "objective_dedup",
    schema: {
      type: "object",
      properties: {
        // Fact-retrieval before the decision it informs (schema order is
        // load-bearing): name the nearest existing objective first, then judge.
        closestMatch: {
          type: "string",
          description:
            'Title of the nearest existing objective, or "none" if nothing is close',
        },
        duplicate: {
          type: "boolean",
          description:
            "True only when the candidate is essentially that existing objective reworded — the same counterfactual, not merely the same era or theme",
        },
        reason: {
          type: "string",
          description: "One short clause on the call",
        },
      },
      required: ["closestMatch", "duplicate", "reason"],
      additionalProperties: false,
    },
  });
  // Fail open on an unusable verdict — a de-dup blip must not drop a composition.
  verdict = (content && mapDedupWire(JSON.parse(content))) || fresh;
} catch (error) {
  console.error("Objective de-dup check error:", error);
  return fresh; // freshness fails open — never take a composition down
}
377 
if (verdict.duplicate) {
  emitObjDedup({
    mode,
    wouldReject: true,
    enforced: mode === "enforce",
    closestMatch: verdict.closestMatch,
    candidate: candidate.title,
  });
  if (mode === "shadow") return fresh; // observe without biting — ship it
}
return verdict;
389}
390 
391/** EVERWHEN_OBJECTIVE_DEDUP: off | shadow | enforce (default enforce), the same
*  three-mode shape as EVERWHEN_MODERATION. */
393function objectiveDedupMode(): "off" | "shadow" | "enforce" {
const m = process.env.EVERWHEN_OBJECTIVE_DEDUP;
return m === "off" || m === "shadow" ? m : "enforce";
396}
397 
398/** One greppable [objdedup] line per flagged duplicate — the calibration
*  instrument for shadow mode. Quiet under tests, like [mod]. */
400function emitObjDedup(line: Record<string, unknown>): void {
if (!process.env.VITEST) console.info(`[objdedup] ${JSON.stringify(line)}`);
402}
403 
404/**
* The de-dup wire → a clean verdict, or `null` for an unusable shape (a missing /
* non-boolean flag), which the caller treats as "not a duplicate" (fail open).
* Exported pure so the guard is directly testable, like mapBoundsWire.
*/
409export function mapDedupWire(wire: unknown): DedupVerdict | null {
const w = wire as {
  duplicate?: unknown;
  closestMatch?: unknown;
  reason?: unknown;
} | null;
if (!w || typeof w.duplicate !== "boolean") return null;
return {
  duplicate: w.duplicate,
  closestMatch: typeof w.closestMatch === "string" ? w.closestMatch : "",
  reason: typeof w.reason === "string" ? w.reason : "",
};
421}
422 
423/** System prompt for the semantic de-dup judge. */
424function dedupSystemPrompt(): string {
return `You are a de-dup check for a historical strategy game. You are given a freshly composed objective and the list of objectives already on offer. Decide whether the new one is essentially one of the existing objectives reworded.
426 
427Mark it a DUPLICATE (duplicate=true) when it aims at the SAME counterfactual as an existing objective — the same pivotal event, person, or outcome — even if the title, wording, era label, or framing differ ("Save the Library of Alexandria" and "Keep Alexandria's great library from the flames" are the same objective).
428 
429Mark it NOT a duplicate (duplicate=false) when it targets a genuinely different event, person, place, or outcome — even if it shares a broad theme (war, science, empire) or era with an existing one. Sharing a subject is not enough; aiming at the same specific turning point is.
430 
431Name the closest existing title in closestMatch (or "none"), then decide, then give one short reason.`;
432}
433 
434/** De-dup user turn: the candidate, then everything already on offer (the curated
*  pool in full, plus the session's seen titles). */
436function dedupUserPrompt(
candidate: GameObjective,
curated: GameObjective[],
seenTitles: string[],
440): string {
const existing = [
  ...curated.map((o) => `• ${o.title} — ${o.description}`),
  ...seenTitles.map((t) => `• ${t}`),
].join("\n");
return `CANDIDATE objective:
446Title: ${candidate.title}
447Description: ${candidate.description}
448 
449Objectives ALREADY on offer:
450${existing}
451 
452Is the candidate essentially one of the objectives already on offer, reworded?`;
453}
454 
455/** System prompt for composition: the tone bar, the grounding bar, and the
*  non-negotiable safety bounds. */
457function composeSystemPrompt(): string {
return `You are a historian and game designer inventing grand, evocative counterfactual objectives for a game where players text historical figures to bend history.
459 
460Hold every objective to three bars:
461 
462TONE — sweeping and vivid, a whole world to remake in the spirit of the examples, never a small errand.
463 
464GROUNDING (issue #82) — every brief names the real-timeline date(s) and the place it departs from in our history, so a player who is not American and does not already know the date still gets a concrete anchor. Never assume the reader's frame.
465 
466BOUNDS (safety, non-negotiable) — the objective must be safely historical:
467- Set in the settled past. Any pivotal anchor year must be at or before ${SAFELY_HISTORICAL_BEFORE_YEAR}.
468- Never centered on, and never requiring contact with, living people, contemporary public figures, ongoing conflicts, or current events. Reach for history, not the present or the recent past.`;
469}
470 
471/** Composition user turn: curated few-shot exemplars (framed as territory already
*  taken, never a menu to copy), the session avoid-list, any attempt already
*  rejected this call, the steer, and the ask. */
474function composeUserPrompt(
steer: ObjectiveSteer,
seenTitles: string[],
rejected: RejectedComposition[] = [],
478): string {
return `Objectives we love — match their TONE, SCALE, and brief SHAPE, but treat their SUBJECTS as territory already taken. Invent something genuinely new; vary away from every one in subject, era, and region. Do NOT reproduce or lightly reskin them (especially over-familiar picks like "Save the Library of Alexandria"):
480${curatedExemplars()}
481${avoidClause(seenTitles)}${rejectedClause(rejected)}
482Invent ONE fresh objective, unlike anything above — a different subject, era, and region from the examples${seenTitles.length ? " and from anything already composed this session" : ""}.${steerClause(steer)}
483 
484Give it: a punchy title; an anchoring era; a single emoji; the anchor year it is aimed at (the pivotal year where winning is decided) as a SIGNED integer — negative for BC, at or before ${SAFELY_HISTORICAL_BEFORE_YEAR} — or null if it genuinely spans all of history with no single hinge; and a GROUNDED BRIEF as the description.
485 
486The brief is a few short bullet lines, each beginning with "• " and separated by newlines (the same shape as the examples above), that together state: (1) when and where this actually happened or ended in OUR timeline, with real dates; (2) what winning looks like; (3) where on Earth it is centered — name the region or country, or, if it genuinely spans the globe or all eras, say so and name the span rather than forcing one country. Put the real date IN the brief; the real-timeline date(s) are NOT the anchor year — state the actual history, never merely restate the anchor. Keep each bullet tight.`;
487}
488 
489/** System prompt for the structured subject check. */
490function boundsCheckSystemPrompt(): string {
return `You are a safety check for a historical strategy game. You are given a freshly generated objective (title, description, era, anchor year). Decide whether it stays safely in the settled past.
492 
493Mark it OUT OF BOUNDS (withinBounds=false) if it centers on, or would require contacting, any of:
494- a living person or a present-day public figure,
495- an ongoing conflict or a current event,
496- anything anchored after the year ${SAFELY_HISTORICAL_BEFORE_YEAR}.
497 
498Mark it IN BOUNDS (withinBounds=true) only when its subject is historical — people and events settled in the past, before living memory. Dramatic history is fine (wars, plagues, empires, revolutions); the test is WHEN and WHO, not how grand.
499 
500When you are unsure, answer withinBounds=false. Give a short reason either way.`;
501}
502 
503/** The curated pool rendered as few-shot exemplars (title — description), read
*  live from the pool so the bar can never drift from a hardcoded copy. */
505function curatedExemplars(): string {
return listCuratedObjectives()
  .map((o) => `• ${o.title} — ${o.description}`)
  .join("\n");
509}
510 
511/** The session's already-composed titles, listed so the model steers away from
*  repeating them (#95). Empty when nothing's been rolled yet — the first compose
*  carries no clause, so an unseeded prompt stays identical to before. */
514function avoidClause(seenTitles: string[]): string {
if (!seenTitles.length) return "";
return `\nYou have ALREADY composed these this session — do not repeat or echo them; pick an entirely different subject:\n${seenTitles.map((t) => `• ${t}`).join("\n")}\n`;
517}
518 
519/** The attempt already rejected in THIS compose (the loop caps at 2, so at most one),
*  listed so a reroll is told what not to draw again and diverges instead of
*  reproducing what just failed. Empty on the first attempt, so an un-rerolled prompt
*  stays byte-identical to before. */
523function rejectedClause(rejected: RejectedComposition[]): string {
if (!rejected.length) return "";
return `\nAlready rejected this compose — do not repeat or lightly reskin; go somewhere entirely different:\n${rejected.map((r) => `• ${r.title} — ${r.reason}`).join("\n")}\n`;
526}
⋯ 15 lines hidden (lines 527–541)527 
528/** Turns the closed-enum steer into a short clause biasing the model. Absent axes
*  simply don't appear, leaving them to the model ("no preference"). */
530function steerClause(steer: ObjectiveSteer): string {
const parts: string[] = [];
if (steer.era) {
  parts.push(
    steer.era === "Across the ages"
      ? "Let it span the ages rather than a single era."
      : `Anchor it in this stretch of history: ${steer.era}.`,
  );
}
if (steer.theme) parts.push(`Center it on the theme of ${steer.theme}.`);
return parts.length ? ` ${parts.join(" ")}` : "";
541}

The tests that pin the risky claims

The suite drives the real generateObjective and mocks only the model boundary, dispatching canned responses by JSON-schema name — so a test says "these composes, these bounds verdicts, these de-dup verdicts" without depending on call order. The de-dup judge defaults to off in the harness (mirroring how moderation is off by default), and the dedicated tests flip it on.

Two of the new tests are the ones a skeptic wants, both under enforce:

- Fail open end-to-end — the judge returns blank content, and the composition still ships (composed === true). This exercises the fail-open path through the real function, not just the mapDedupWire unit. - Short-circuit holds under enforce — a verbatim curated title is caught by the free set and spends neither a bounds nor a de-dup call; only the clean reroll consults each. This is the regression guard for the "free check first" claim.

Fail-open-through-the-real-function, and the enforce-mode short-circuit.

tests/unit/server/utils/objective-generator.spec.ts · 675 lines

tests/unit/server/utils/objective-generator.spec.ts675 lines · TypeScript

⋯ 544 lines hidden (lines 1–544)1import {
describe,
it,
expect,
vi,
beforeAll,
afterAll,
beforeEach,
9} from "vitest";
10import {
generateObjective,
mapBoundsWire,
mapDedupWire,
14} from "../../../../server/utils/objective-generator";
15import { listCuratedObjectives } from "../../../../server/utils/objectives";
16import { SAFELY_HISTORICAL_BEFORE_YEAR } from "../../../../server/utils/historical-floor";
17import { MAX_OBJECTIVE_DESC_CHARS } from "../../../../server/utils/validate";
18 
19// The AI path routes through the gateway; mock the OpenAI SDK (chat completions +
20// moderations) and pin the legacy lane, the same shape the lifespan spec uses. The
21// curated (default) path below never constructs a client, so it is unaffected.
22const createMock = vi.hoisted(() => vi.fn());
23const modMock = vi.hoisted(() => vi.fn());
24vi.mock("openai", () => ({
default: vi.fn(function () {
  return {
    chat: { completions: { create: createMock } },
    moderations: { create: modMock },
  };
}),
31}));
32 
33describe("Objective Generator — curated path (no API call)", () => {
it("returns a well-formed objective", async () => {
  const { objective, composed } = await generateObjective();
36 
  // The default (no-AI) path is the curated floor — never a composition.
  expect(composed).toBe(false);
  expect(typeof objective.title).toBe("string");
  expect(objective.title.length).toBeGreaterThan(0);
  expect(typeof objective.description).toBe("string");
  expect(objective.description.length).toBeGreaterThan(10);
  expect(typeof objective.era).toBe("string");
  expect(typeof objective.icon).toBe("string");
  expect(objective.icon.length).toBeGreaterThan(0);
});
47 
it("draws from the curated pool by default (no API call)", async () => {
  const titles = listCuratedObjectives().map((o) => o.title);
  const { objective } = await generateObjective();
  expect(titles).toContain(objective.title);
});
53 
it("exposes a pool of several distinct objectives", () => {
  const pool = listCuratedObjectives();
  expect(pool.length).toBeGreaterThanOrEqual(5);
  const titles = new Set(pool.map((o) => o.title));
  expect(titles.size).toBe(pool.length);
});
60 
it("offers variety across runs rather than a single hardcoded objective", async () => {
  const seen = new Set<string>();
  for (let i = 0; i < 40; i++) {
    seen.add((await generateObjective()).objective.title);
  }
  expect(seen.size).toBeGreaterThan(1);
});
68});
69 
70/**
* The bounds (#71): a composition is independently validated, never trusted to the
* prompt. Out of bounds → reroll once → curated floor; the moderation seam runs over
* generated text. Curated stays the floor, so a failure never hard-fails run start.
*/
75describe("Objective Generator — AI bounds + steer (#71)", () => {
const VALID = {
  title: "Chart the Southern Stars",
  description:
    "Map the unknown skies a full century early and redraw every voyage of the age.",
  era: "Age of sail",
  icon: "🌌",
  anchorYear: 1600,
};
const FUTURE = {
  ...VALID,
  title: "Settle the Red Planet",
  description: "Plant a thriving city on Mars within the decade.",
  anchorYear: 2200,
};
90 
// A queue per call kind, dispatched by the request's schema name, so a test
// declares "these composes, these checks" without depending on call ordering.
let composeQueue: unknown[];
let checkQueue: unknown[];
let dedupeQueue: unknown[];
const asContent = (payload: unknown) => ({
  choices: [{ message: { content: JSON.stringify(payload) } }],
});
const inBounds = { withinBounds: true, reason: "settled past" };
100 
beforeAll(() => {
  process.env.OPENAI_API_KEY = "test-key";
  process.env.EVERWHEN_AI_LANE = "openai";
});
afterAll(() => {
  delete process.env.EVERWHEN_AI_LANE;
  delete process.env.EVERWHEN_MODERATION;
  delete process.env.EVERWHEN_OBJECTIVE_DEDUP;
});
110 
beforeEach(() => {
  createMock.mockReset();
  modMock.mockReset();
  composeQueue = [];
  checkQueue = [];
  dedupeQueue = [];
  // Most tests isolate the year + subject logic from moderation and the semantic
  // de-dup judge; the dedicated tests flip these to 'enforce'/'shadow' themselves.
  process.env.EVERWHEN_MODERATION = "off";
  process.env.EVERWHEN_OBJECTIVE_DEDUP = "off";
  createMock.mockImplementation(
    async (req: {
      response_format?: { json_schema?: { name?: string } };
    }) => {
      const name = req?.response_format?.json_schema?.name;
      const q =
        name === "objective_bounds"
          ? checkQueue
          : name === "objective_dedup"
            ? dedupeQueue
            : composeQueue;
      return asContent(q.shift());
    },
  );
  // Default: nothing flagged (only consulted when moderation is enforced).
  modMock.mockResolvedValue({ results: [{ category_scores: {} }] });
});
138 
it("returns a composition that clears every bound", async () => {
  composeQueue = [VALID];
  checkQueue = [inBounds];
142 
  const { objective: result, composed } = await generateObjective(true);
144 
  expect(composed).toBe(true); // the AI path produced it — not a fallback
  expect(result.title).toBe(VALID.title);
  expect(result.anchorYear).toBe(1600);
  // One compose + one subject check — no reroll.
  expect(createMock).toHaveBeenCalledTimes(2);
});
151 
it("rejects an out-of-bounds anchor year, rerolls once, and returns the valid reroll", async () => {
  composeQueue = [FUTURE, VALID];
  checkQueue = [inBounds];
155 
  const { objective: result } = await generateObjective(true);
157 
  expect(result.title).toBe(VALID.title);
  // The year bound is pure: FUTURE is rejected before any subject-check call,
  // so only the in-bounds reroll consults the checker.
  const checkCalls = createMock.mock.calls.filter(
    (c) => c[0]?.response_format?.json_schema?.name === "objective_bounds",
  );
  expect(checkCalls).toHaveLength(1);
});
166 
it('accepts an anchor exactly at the cutoff (the gate is "> cutoff")', async () => {
  // Derived from the constant — the cutoff is a moving target (year - 100).
  composeQueue = [{ ...VALID, anchorYear: SAFELY_HISTORICAL_BEFORE_YEAR }];
  checkQueue = [inBounds];
171 
  const { objective: result } = await generateObjective(true);
173 
  expect(result.anchorYear).toBe(SAFELY_HISTORICAL_BEFORE_YEAR);
});
176 
it("rejects an anchor one year past the cutoff, before any subject check", async () => {
  composeQueue = [
    { ...VALID, anchorYear: SAFELY_HISTORICAL_BEFORE_YEAR + 1 },
    VALID,
  ];
  checkQueue = [inBounds];
183 
  const { objective: result } = await generateObjective(true);
185 
  expect(result.title).toBe(VALID.title);
  // cutoff+1 is rejected by the pure year gate, so only the reroll is checked.
  const checkCalls = createMock.mock.calls.filter(
    (c) => c[0]?.response_format?.json_schema?.name === "objective_bounds",
  );
  expect(checkCalls).toHaveLength(1);
});
193 
it("accepts a BC (negative) anchor through the signed year bound", async () => {
  composeQueue = [{ ...VALID, anchorYear: -48 }];
  checkQueue = [inBounds];
197 
  const { objective: result } = await generateObjective(true);
199 
  expect(result.anchorYear).toBe(-48);
});
202 
it("still subject-checks a null-anchor (spans-all-history) composition", async () => {
  // A null anchor skips the year gate by design, so the subject check is the
  // only thing between a "spans all history" framing and the player.
  composeQueue = [{ ...VALID, anchorYear: null }, VALID];
  checkQueue = [
    { withinBounds: false, reason: "centers on a living person" },
    inBounds,
  ];
211 
  const { objective: result } = await generateObjective(true);
213 
  expect(result.title).toBe(VALID.title);
  // Both compositions reached the subject check — the null-anchor one included.
  const checkCalls = createMock.mock.calls.filter(
    (c) => c[0]?.response_format?.json_schema?.name === "objective_bounds",
  );
  expect(checkCalls).toHaveLength(2);
});
221 
it("fails closed and rerolls when the subject check returns no content", async () => {
  createMock.mockReset();
  let checks = 0;
  createMock.mockImplementation(
    async (req: {
      response_format?: { json_schema?: { name?: string } };
    }) => {
      if (req?.response_format?.json_schema?.name === "objective_bounds") {
        checks++;
        // First subject check blips (empty content) → fail closed; next is clean.
        return checks === 1
          ? { choices: [{ message: { content: "" } }] }
          : asContent(inBounds);
      }
      return asContent(VALID); // both composes are year-valid
    },
  );
239 
  const { objective: result } = await generateObjective(true);
241 
  expect(result.title).toBe(VALID.title);
  const checkCalls = createMock.mock.calls.filter(
    (c) => c[0]?.response_format?.json_schema?.name === "objective_bounds",
  );
  expect(checkCalls).toHaveLength(2);
});
248 
it("rejects a composition the subject check flags, then rerolls", async () => {
  composeQueue = [VALID, { ...VALID, title: "A Safer Frame" }];
  checkQueue = [
    { withinBounds: false, reason: "centers on a living person" },
    inBounds,
  ];
255 
  const { objective: result } = await generateObjective(true);
257 
  expect(result.title).toBe("A Safer Frame");
});
260 
it("falls back to the curated floor when both attempts are out of bounds", async () => {
  composeQueue = [FUTURE, { ...FUTURE, title: "Still Out of Bounds" }];
  checkQueue = [];
264 
  const { objective: result, composed } = await generateObjective(true);
266 
  expect(composed).toBe(false); // both attempts out of bounds → the curated floor
  const curatedTitles = listCuratedObjectives().map((o) => o.title);
  expect(curatedTitles).toContain(result.title);
  // Exactly two compose attempts (the original + one reroll), then curated.
  expect(createMock).toHaveBeenCalledTimes(2);
});
273 
it("falls back to curated, without a reroll, on a transport failure", async () => {
  const quiet = vi.spyOn(console, "error").mockImplementation(() => {});
  createMock.mockReset();
  createMock.mockRejectedValue(new Error("model down"));
278 
  const { objective: result, composed } = await generateObjective(true);
280 
  expect(composed).toBe(false); // a transport failure drops straight to curated
  const curatedTitles = listCuratedObjectives().map((o) => o.title);
  expect(curatedTitles).toContain(result.title);
  // A transport error won't heal on a reroll — one attempt, then curated.
  expect(createMock).toHaveBeenCalledTimes(1);
  quiet.mockRestore();
});
288 
it("runs generated text through the moderation seam", async () => {
  process.env.EVERWHEN_MODERATION = "enforce";
  // First composition trips the detector; the reroll is clean.
  modMock.mockReset();
  modMock
    .mockResolvedValueOnce({
      results: [{ category_scores: { sexual: 0.95 } }],
    })
    .mockResolvedValue({ results: [{ category_scores: {} }] });
  composeQueue = [VALID, { ...VALID, title: "Clean Frame" }];
  checkQueue = [inBounds, inBounds];
300 
  const { objective: result } = await generateObjective(true);
302 
  expect(result.title).toBe("Clean Frame");
  // Moderation actually ran over the generated text (title + description).
  expect(modMock).toHaveBeenCalled();
  expect(modMock.mock.calls[0][0].input).toContain(VALID.title);
  expect(modMock.mock.calls[0][0].input).toContain(VALID.description);
});
309 
it("threads the session avoid-list into the compose prompt (#95)", async () => {
  composeQueue = [VALID];
  checkQueue = [inBounds];
313 
  await generateObjective(true, {}, [
    "Reach the Moon by 1900",
    "Forge the First Aqueducts",
  ]);
318 
  const composeCall = createMock.mock.calls.find(
    (c) => c[0]?.response_format?.json_schema?.name === "game_objective",
  )!;
  const user = (
    composeCall[0].messages as Array<{ role: string; content: string }>
  ).find((m) => m.role === "user")!.content;
  // The already-seen titles are listed for the model to steer away from.
  expect(user).toContain("Reach the Moon by 1900");
  expect(user).toContain("Forge the First Aqueducts");
  expect(user.toLowerCase()).toContain("already composed");
});
330 
it("rejects a composition that duplicates the curated pool, then rerolls (#95)", async () => {
  // The model reproduces a curated title verbatim (the exact bug #95 reports);
  // the reroll is fresh. The de-dup is free, so the rejected one never reaches
  // the (paid) subject check — only the clean reroll is checked.
  composeQueue = [
    { ...VALID, title: "Save the Library of Alexandria" },
    VALID,
  ];
  checkQueue = [inBounds];
340 
  const { objective: result } = await generateObjective(true);
342 
  expect(result.title).toBe(VALID.title);
  const checkCalls = createMock.mock.calls.filter(
    (c) => c[0]?.response_format?.json_schema?.name === "objective_bounds",
  );
  expect(checkCalls).toHaveLength(1);
});
349 
it("catches a duplicate that only differs in case/punctuation (#95)", async () => {
  // Normalized comparison: a re-skin of a curated title must still collide.
  composeQueue = [
    { ...VALID, title: "save the LIBRARY of alexandria!!!" },
    VALID,
  ];
  checkQueue = [inBounds];
357 
  const { objective: result } = await generateObjective(true);
359 
  expect(result.title).toBe(VALID.title);
});
362 
it("rejects a composition that repeats a title seen this session, then rerolls (#95)", async () => {
  // The session avoid-list (not curated) catches the repeat; the reroll is fresh.
  composeQueue = [{ ...VALID, title: "My Earlier Roll" }, VALID];
  checkQueue = [inBounds];
367 
  const { objective: result } = await generateObjective(true, {}, [
    "My Earlier Roll",
  ]);
371 
  expect(result.title).toBe(VALID.title);
});
374 
it("falls back to an UNSEEN curated objective when both attempts collide (#95)", async () => {
  // Both compositions duplicate the curated pool; the curated FALLBACK must then
  // avoid the one title we mark as already-seen, so even the floor stays fresh.
  const seen = "Save the Library of Alexandria";
  composeQueue = [
    { ...VALID, title: seen },
    { ...VALID, title: "Break the Black Death" },
  ];
  checkQueue = [];
384 
  const { objective: result, composed } = await generateObjective(true, {}, [
    seen,
  ]);
388 
  expect(composed).toBe(false); // both attempts collided → the curated floor
  const curatedTitles = listCuratedObjectives().map((o) => o.title);
  expect(curatedTitles).toContain(result.title);
  expect(result.title).not.toBe(seen);
  // Two compose attempts, both duplicates → no subject check spent, then curated.
  expect(createMock).toHaveBeenCalledTimes(2);
  const checkCalls = createMock.mock.calls.filter(
    (c) => c[0]?.response_format?.json_schema?.name === "objective_bounds",
  );
  expect(checkCalls).toHaveLength(0);
});
400 
it("constrains and steers the compose prompt", async () => {
  composeQueue = [VALID];
  checkQueue = [inBounds];
404 
  await generateObjective(true, {
    era: "Antiquity",
    theme: "Science & Medicine",
  });
409 
  const composeCall = createMock.mock.calls.find(
    (c) => c[0]?.response_format?.json_schema?.name === "game_objective",
  );
  expect(composeCall).toBeDefined();
  const messages = composeCall![0].messages as Array<{
    role: string;
    content: string;
  }>;
  const system = messages.find((m) => m.role === "system")!.content;
  const user = messages.find((m) => m.role === "user")!.content;
420 
  // The bounds are in the prompt (the model is asked to obey them)…
  expect(system).toContain(String(SAFELY_HISTORICAL_BEFORE_YEAR));
  expect(system.toLowerCase()).toContain("living people");
  // …the steer is injected…
  expect(user).toContain("Antiquity");
  expect(user).toContain("Science & Medicine");
  // …and the curated pool is shown as few-shot exemplars.
  expect(user).toContain("Save the Library of Alexandria");
});
430 
it("de-dup off (the spec default) never spends a judge call", async () => {
  // Guards against the judge silently running on every compose: with the mode
  // off, a clean composition ships with zero objective_dedup calls.
  composeQueue = [VALID];
  checkQueue = [inBounds];
436 
  const { objective: result, composed } = await generateObjective(true);
438 
  expect(composed).toBe(true);
  expect(result.title).toBe(VALID.title);
  const dedupCalls = createMock.mock.calls.filter(
    (c) => c[0]?.response_format?.json_schema?.name === "objective_dedup",
  );
  expect(dedupCalls).toHaveLength(0);
});
446 
it("enforce: rejects a semantic near-duplicate a title match misses, then rerolls", async () => {
  process.env.EVERWHEN_OBJECTIVE_DEDUP = "enforce";
  // A fresh TITLE (no normalized collision) the judge flags as the same objective
  // reworded — the exact case a pure title match cannot catch.
  composeQueue = [
    { ...VALID, title: "Keep Alexandria's Great Library from the Flames" },
    { ...VALID, title: "A Genuinely Fresh Frontier" },
  ];
  checkQueue = [inBounds, inBounds];
  dedupeQueue = [
    {
      closestMatch: "Save the Library of Alexandria",
      duplicate: true,
      reason: "same library, reworded",
    },
    { closestMatch: "none", duplicate: false, reason: "" },
  ];
464 
  const { objective: result } = await generateObjective(true);
466 
  expect(result.title).toBe("A Genuinely Fresh Frontier");
  // The judge ran on both attempts — the near-dup, then the clean reroll.
  const dedupCalls = createMock.mock.calls.filter(
    (c) => c[0]?.response_format?.json_schema?.name === "objective_dedup",
  );
  expect(dedupCalls).toHaveLength(2);
});
474 
it("enforce: the judge sees the curated pool AND the session's seen titles", async () => {
  process.env.EVERWHEN_OBJECTIVE_DEDUP = "enforce";
  composeQueue = [VALID];
  checkQueue = [inBounds];
  dedupeQueue = [{ closestMatch: "none", duplicate: false, reason: "" }];
480 
  await generateObjective(true, {}, ["Forge the First Aqueducts"]);
482 
  const dedupCall = createMock.mock.calls.find(
    (c) => c[0]?.response_format?.json_schema?.name === "objective_dedup",
  )!;
  const user = (
    dedupCall[0].messages as Array<{ role: string; content: string }>
  ).find((m) => m.role === "user")!.content;
  // The candidate, a curated title, and the session-seen title are all present.
  expect(user).toContain(VALID.title);
  expect(user).toContain("Save the Library of Alexandria");
  expect(user).toContain("Forge the First Aqueducts");
});
494 
it("shadow: logs the would-be duplicate but still ships it", async () => {
  process.env.EVERWHEN_OBJECTIVE_DEDUP = "shadow";
  composeQueue = [
    { ...VALID, title: "Keep Alexandria's Great Library from the Flames" },
  ];
  checkQueue = [inBounds];
  dedupeQueue = [
    {
      closestMatch: "Save the Library of Alexandria",
      duplicate: true,
      reason: "same library, reworded",
    },
  ];
508 
  const { objective: result, composed } = await generateObjective(true);
510 
  // Shadow observes without acting — the flagged composition ships, no reroll.
  expect(composed).toBe(true);
  expect(result.title).toBe(
    "Keep Alexandria's Great Library from the Flames",
  );
  const dedupCalls = createMock.mock.calls.filter(
    (c) => c[0]?.response_format?.json_schema?.name === "objective_dedup",
  );
  expect(dedupCalls).toHaveLength(1);
});
521 
it("feeds the rejected attempt back into the reroll prompt", async () => {
  // The year bound rejects FUTURE; the reroll must be TOLD it was rejected, so
  // the second draw diverges instead of re-rolling the same subject.
  composeQueue = [FUTURE, VALID];
  checkQueue = [inBounds];
527 
  await generateObjective(true);
529 
  const composeCalls = createMock.mock.calls.filter(
    (c) => c[0]?.response_format?.json_schema?.name === "game_objective",
  );
  const firstUser = (
    composeCalls[0][0].messages as Array<{ role: string; content: string }>
  ).find((m) => m.role === "user")!.content;
  const rerollUser = (
    composeCalls[1][0].messages as Array<{ role: string; content: string }>
  ).find((m) => m.role === "user")!.content;
  // Attempt 1 carries no rejection clause; the reroll names what was rejected.
  expect(firstUser.toLowerCase()).not.toContain("rejected");
  expect(rerollUser).toContain(FUTURE.title);
  expect(rerollUser.toLowerCase()).toContain("rejected");
});
544 
it("enforce: fails open — a blank de-dup verdict still ships the composition", async () => {
  process.env.EVERWHEN_OBJECTIVE_DEDUP = "enforce";
  // The judge returns nothing (an outage / empty content). Freshness fails OPEN:
  // the composition ships rather than being dropped — unlike the bounds gate.
  composeQueue = [VALID];
  checkQueue = [inBounds];
  dedupeQueue = []; // empty → the mock yields blank content for the dedup call
552 
  const { objective: result, composed } = await generateObjective(true);
554 
  expect(composed).toBe(true);
  expect(result.title).toBe(VALID.title);
  // The judge WAS consulted under enforce — it just failed open.
  const dedupCalls = createMock.mock.calls.filter(
    (c) => c[0]?.response_format?.json_schema?.name === "objective_dedup",
  );
  expect(dedupCalls).toHaveLength(1);
});
563 
it("enforce: an exact title collision short-circuits — no de-dup call spent", async () => {
  process.env.EVERWHEN_OBJECTIVE_DEDUP = "enforce";
  // A verbatim curated title is caught by the free normalized-title Set BEFORE any
  // paid call — so even under enforce the colliding attempt spends neither a bounds
  // nor a de-dup call; only the clean reroll consults each judge.
  composeQueue = [
    { ...VALID, title: "Save the Library of Alexandria" },
    VALID,
  ];
  checkQueue = [inBounds];
  dedupeQueue = [{ closestMatch: "none", duplicate: false, reason: "" }];
575 
  const { objective: result } = await generateObjective(true);
577 
  expect(result.title).toBe(VALID.title);
⋯ 97 lines hidden (lines 579–675)579    const dedupCalls = createMock.mock.calls.filter(
    (c) => c[0]?.response_format?.json_schema?.name === "objective_dedup",
  );
  const checkCalls = createMock.mock.calls.filter(
    (c) => c[0]?.response_format?.json_schema?.name === "objective_bounds",
  );
  expect(dedupCalls).toHaveLength(1);
  expect(checkCalls).toHaveLength(1);
});
588});
589 
590describe("mapBoundsWire", () => {
it("reads a clean verdict", () => {
  expect(mapBoundsWire({ withinBounds: true, reason: "" })).toBe(true);
  expect(
    mapBoundsWire({ withinBounds: false, reason: "living person" }),
  ).toBe(false);
});
597 
it("returns null for an unusable shape (treated as out of bounds)", () => {
  expect(mapBoundsWire(null)).toBeNull();
  expect(mapBoundsWire("blocked")).toBeNull();
  expect(mapBoundsWire({})).toBeNull();
  expect(mapBoundsWire({ withinBounds: "yes" })).toBeNull();
});
604});
605 
606describe("mapDedupWire", () => {
it("reads a clean verdict", () => {
  expect(
    mapDedupWire({ duplicate: true, closestMatch: "X", reason: "same" }),
  ).toEqual({ duplicate: true, closestMatch: "X", reason: "same" });
  expect(
    mapDedupWire({ duplicate: false, closestMatch: "none", reason: "" }),
  ).toEqual({ duplicate: false, closestMatch: "none", reason: "" });
});
615 
it("keeps the boolean decision, defaulting missing string fields", () => {
  expect(mapDedupWire({ duplicate: true })).toEqual({
    duplicate: true,
    closestMatch: "",
    reason: "",
  });
});
623 
it("returns null for an unusable shape (treated as not a duplicate)", () => {
  expect(mapDedupWire(null)).toBeNull();
  expect(mapDedupWire("dup")).toBeNull();
  expect(mapDedupWire({})).toBeNull();
  expect(mapDedupWire({ duplicate: "yes" })).toBeNull();
});
630});
631 
632describe("Curated briefs are grounded (issue #82)", () => {
const pool = listCuratedObjectives();
634 
it("every brief states a real-timeline date and reads as bullet lines", () => {
  for (const obj of pool) {
    // A concrete date so a player who does not already hold one (non-US /
    // non-Western) gets an anchor: every brief names at least one 3-4 digit
    // year (1914, 476, 285, 221, …) or none of the issue's point is met.
    expect(obj.description, `${obj.title}: brief needs a real date`).toMatch(
      /\d{3,4}/,
    );
    // Bulleted, multi-line — not the old single vague sentence.
    expect(
      obj.description,
      `${obj.title}: brief should be bullet lines`,
    ).toContain("\n");
    expect(
      obj.description,
      `${obj.title}: bullets start with "• "`,
    ).toContain("• ");
  }
});
654 
it("every brief fits the (raised) description cap", () => {
  for (const obj of pool) {
    expect(
      obj.description.length,
      `${obj.title}: brief exceeds the cap`,
    ).toBeLessThanOrEqual(MAX_OBJECTIVE_DESC_CHARS);
  }
});
663 
it("states the real abolition dates distinct from the in-game anchor (anchorYear is not the real date)", () => {
  // Slavery is the canonical case the issue calls out: anchor 1750 is the
  // counterfactual target, NOT when abolition actually happened. The brief must
  // carry the real dates, proving the two are kept distinct, not conflated.
  const slavery = pool.find(
    (o) => o.title === "Abolish Slavery a Century Early",
  )!;
  expect(slavery.anchorYear).toBe(1750);
  // The real abolition dates appear in the brief, and they are not the anchor.
  expect(slavery.description).toMatch(/1807|1833|1865|1888/);
});
675});