@joystyk/content 0.0.0-stage → 0.2.0

package/dist/pipeline.d.ts

@@ -0,0 +1,252 @@
+import { type Json, type Result, type StandardSchemaV1 } from '@joystyk/contracts';
+import type { FieldText, FilterHit, WordFilter } from './filter.js';
+import { type Logger } from './log.js';
+import { type CallInfo, type CompletionFailure, type ModelClient } from './model.js';
+import type { Publisher } from './publish.js';
+import type { ContentStore, ItemRow, WithdrawReason } from './store.js';
+export interface ScheduleContext {
+    readonly date: string;
+    readonly puzzleId: string;
+    /** Answers used or reserved within the requested history window, withdrawn ones included. */
+    readonly used: readonly {
+        readonly date: string;
+        readonly answer: string;
+    }[];
+}
+export interface Scheduled<Inputs extends Json> {
+    readonly inputs: Inputs;
+    readonly seed: string;
+    /** The answer key the inputs commit to, if the schedule picks it (Word of the Day's word). */
+    readonly answer: string | null;
+}
+export interface GenerateContext<Inputs extends Json> {
+    readonly date: string;
+    readonly puzzleId: string;
+    readonly inputs: Inputs;
+    readonly seed: string;
+    /** 1-based, within this run. */
+    readonly attempt: number;
+    /** What was wrong with the previous attempt, in words the prompt can repeat. Empty on the first. */
+    readonly feedback: readonly string[];
+    readonly model: ModelClient;
+    /** Normalized text keys used on nearby dates, withdrawn content included. */
+    readonly recentKeys?: readonly {
+        readonly date: string;
+        readonly key: string;
+    }[];
+    /** Published reusable catalogs for this game; each generator decodes its own schema. */
+    readonly catalogs?: readonly Json[];
+    readonly signal?: AbortSignal;
+    /**
+     * Keeps a game's own check results (for example Crossword's fact-check verdicts) in the
+     * attempt's report, under `checks[name]`, whether the attempt passes or fails. A later
+     * call with the same name replaces the earlier one. Absent when a test calls `generate`
+     * directly.
+     */
+    readonly record?: (name: string, detail: Json) => void;
+}
+export type GenerateFailure = 
+/** A model call failed: the endpoint, or a reply that didn't parse or match its schema. */
+{
+    readonly kind: 'model';
+    readonly error: CompletionFailure;
+}
+/** The game's own model checks refused the draft (for example a blind answer check). */
+ | {
+    readonly kind: 'rejected';
+    readonly issues: readonly string[];
+};
+export interface DailyGenerator<Config extends Json = Json, Inputs extends Json = Json> {
+    readonly gameId: string;
+    /** Recorded with every item, e.g. "wotd-v1". */
+    readonly promptVersion: string;
+    /** Scheduling history on either side of the date; defaults to 365 days. */
+    readonly historyDays?: number;
+    /** Numeric/card/grid configurations with no generated player-visible text. They can
+     * publish without a model endpoint; `texts` must be empty. */
+    readonly modelFree?: boolean;
+    /** Optional additional no-repeat rule, independent of the answer schedule. */
+    readonly repeatWindowDays?: number;
+    readonly reusesCatalogs?: boolean;
+    repeatKeys?(config: Config): readonly string[];
+    /** The game's `schemas.config`: every config is decoded through it before anything else. */
+    readonly configSchema: StandardSchemaV1<unknown, Config>;
+    /** Deterministic inputs for a slot: the same date and history always give the same inputs. */
+    schedule(context: ScheduleContext): Scheduled<Inputs>;
+    generate(context: GenerateContext<Inputs>): Promise<Result<Config, GenerateFailure>>;
+    /** The game validators: pure; an empty list means the config passes. */
+    validate(config: Config, context: {
+        readonly date: string;
+        readonly puzzleId: string;
+        readonly inputs: Inputs | null;
+    }): readonly string[];
+    /** Every player-visible text, for the all-ages filter and the model screen. */
+    texts(config: Config): readonly FieldText[];
+    /** The answer key for duplicate checks. */
+    answerOf(config: Config): string | null;
+    /** The reviewed fallback bank: `size` complete items, each turned into a config for a date. */
+    readonly bank: {
+        readonly size: number;
+        config(index: number, puzzleId: string): Config;
+    };
+}
+export interface CallReport {
+    readonly name: string;
+    readonly ok: boolean;
+    readonly error: string | null;
+    readonly latencyMs: number;
+    readonly requests: number;
+    readonly mode: string;
+    readonly promptTokens: number | null;
+    readonly completionTokens: number | null;
+    readonly totalTokens: number | null;
+}
+export type AttemptOutcome = 'validated' | 'endpoint' | 'reply' | 'schema' | 'rejected' | 'invalid' | 'duplicate' | 'filtered' | 'screened' | 'aborted';
+export interface AttemptReport {
+    readonly attempt: number;
+    readonly outcome: AttemptOutcome;
+    readonly issues: readonly string[];
+    readonly calls: readonly CallReport[];
+    /** Null when the attempt never reached the filter. */
+    readonly filter: {
+        readonly ok: boolean;
+        readonly hits: readonly FilterHit[];
+    } | null;
+    /** Null when the attempt never reached the screen (or screening is off). */
+    readonly screen: {
+        readonly safe: boolean;
+        readonly reasons: readonly string[];
+    } | null;
+    /** What the game's own checks recorded (`GenerateContext.record`); absent when nothing was. */
+    readonly checks?: Readonly<Record<string, Json>>;
+}
+export type SlotAction = 'existing' | 'generated' | 'bank' | 'failed' | 'deferred' | 'aborted';
+export interface SlotReport {
+    readonly gameId: string;
+    readonly date: string;
+    readonly puzzleId: string;
+    readonly action: SlotAction;
+    readonly status: string;
+    readonly source: string | null;
+    readonly answer: string | null;
+    /** The slot's scheduled inputs (a bank item may replace what they asked for). */
+    readonly inputs: Json | null;
+    readonly attempts: readonly AttemptReport[];
+    readonly contentHash: string | null;
+    readonly config: Json | null;
+}
+export interface PublishReport {
+    readonly gameId: string;
+    readonly date: string;
+    readonly file: string;
+    readonly hash: string;
+    readonly size: number;
+}
+export interface RunReport {
+    readonly runId: number;
+    readonly status: 'ok' | 'partial' | 'failed' | 'aborted';
+    readonly today: string;
+    readonly slots: readonly SlotReport[];
+    readonly published: readonly PublishReport[];
+    readonly breakerOpen: boolean;
+}
+export interface PipelineOptions {
+    readonly store: ContentStore;
+    readonly generators: readonly DailyGenerator[];
+    /** Null runs without a model: existing items publish and late slots take bank items. */
+    readonly model: ModelClient | null;
+    readonly filter: WordFilter;
+    /** Null for a dry run: nothing is written to the published-files folder. */
+    readonly publisher: Publisher | null;
+    readonly now?: () => number;
+    /** The dates to fill. Default: today and the next `daysAhead` days. */
+    readonly dates?: readonly string[];
+    /** Default 1: today and tomorrow (D-46). */
+    readonly daysAhead?: number;
+    /** Only these games. */
+    readonly games?: readonly string[];
+    readonly maxAttempts?: number;
+    /** Consecutive endpoint errors that end generation for the run. Default 5. */
+    readonly breakerThreshold?: number;
+    /** A slot not validated this long before its release takes a bank item. Default 48 hours. */
+    readonly deadlineHours?: number;
+    /** Give a late slot a bank item (default true). `content bank`, which grows the banks, turns it off. */
+    readonly bankFallback?: boolean;
+    /** The newest date published and listed, as days after today. Default 1 (D-46). */
+    readonly listAheadDays?: number;
+    /** How many past days the index keeps listing. Default 14. */
+    readonly indexBackDays?: number;
+    /** Run the model screen (layer 3). Default true. */
+    readonly screen?: boolean;
+    /** Pause before attempt n + 1 is `backoffMs * 2^(n-1)`. Default 2000. */
+    readonly backoffMs?: number;
+    readonly sleep?: (ms: number, signal?: AbortSignal) => Promise<void>;
+    readonly signal?: AbortSignal;
+    readonly log?: Logger;
+    /** Recorded on the run: "schedule", "manual", "live-validation"… */
+    readonly trigger?: string;
+}
+/** @internal Shared with packs.ts. */
+export declare const defaultSleep: (ms: number, signal?: AbortSignal) => Promise<void>;
+/** @internal Shared with packs.ts. */
+export declare const callReport: (call: CallInfo, error: CompletionFailure | null) => CallReport;
+/** Wraps a model client so every call, successful or not, lands in `calls`. */
+/** @internal Shared with packs.ts. */
+export declare const recording: (model: ModelClient, calls: CallReport[]) => ModelClient;
+/** @internal Shared with packs.ts. */
+export declare const outcomeOf: (error: CompletionFailure) => AttemptOutcome;
+/** @internal Shared with packs.ts. */
+export declare const issuesOf: (error: CompletionFailure) => string[];
+/** @internal Shared with packs.ts. */
+export declare const decodeConfig: <Config>(schema: StandardSchemaV1<unknown, Config>, value: unknown) => Promise<Result<Config, string[]>>;
+/** Nearby text keys decoded through the game schema; corrections on the same date may retain clues. */
+export declare const recentContentKeys: (store: ContentStore, generator: DailyGenerator, date: string) => Promise<{
+    date: string;
+    key: string;
+}[]>;
+/**
+ * Checks a config the way every item is checked: the schema, the game validators, the
+ * duplicate rule and the word lists. The model screen is separate (it needs the endpoint).
+ */
+export declare const checkDailyConfig: (generator: DailyGenerator, value: unknown, context: {
+    date: string;
+    puzzleId: string;
+    inputs: Json | null;
+    used: readonly {
+        date: string;
+        answer: string;
+    }[];
+    filter: WordFilter;
+    recentKeys?: readonly {
+        date: string;
+        key: string;
+    }[];
+}) => Promise<{
+    outcome: AttemptOutcome;
+    issues: string[];
+    config: Json | null;
+    filter: AttemptReport["filter"];
+}>;
+export declare const runPipeline: (options: PipelineOptions) => Promise<RunReport>;
+/** Rewrites a game's index from the store: published items from `indexBackDays` ago through today + `listAheadDays`. */
+export declare const rebuildIndex: (store: ContentStore, publisher: Publisher, gameId: string, today: string, { listAheadDays, indexBackDays }?: {
+    listAheadDays?: number;
+    indexBackDays?: number;
+}) => void;
+/**
+ * Takes an item down (content-pipeline.md, "Corrections"): the item is withdrawn with a
+ * reason code and actor, the game's index drops it at once, and the next run fills the slot
+ * again, from the model or the bank. The withdrawn answer counts as used, so the replacement
+ * gets a different one. Returns the withdrawn item, or null if no item held the puzzle.
+ */
+export declare const withdrawItem: (options: {
+    readonly store: ContentStore;
+    readonly publisher: Publisher | null;
+    readonly gameId: string;
+    readonly date: string;
+    readonly reason: WithdrawReason;
+    readonly actor: string;
+    readonly note?: string;
+    readonly now?: number;
+    readonly listAheadDays?: number;
+}) => ItemRow | null;