@joystyk/content 0.0.0-stage → 0.2.0

package/dist/publish.d.ts

@@ -0,0 +1,21 @@
+import type { Json } from '@joystyk/contracts';
+import { type DailyIndexEntry } from '@joystyk/daily';
+export interface PublishedFile {
+    readonly hash: string;
+    readonly size: number;
+    /** Relative to the publish directory: "<game>/<date>.<hash>.json". */
+    readonly file: string;
+}
+export interface Publisher {
+    readonly dir: string;
+    /** Writes one day's puzzle file (if it isn't there already) and returns its hash and size. */
+    writePuzzle(gameId: string, date: string, config: Json): PublishedFile;
+    /** Replaces a game's index. */
+    writeIndex(gameId: string, dates: readonly DailyIndexEntry[]): void;
+}
+/** The puzzle file body for a config: the envelope, as compact JSON. */
+export declare const puzzleFileBody: (gameId: string, date: string, config: Json) => {
+    body: string;
+    hash: string;
+};
+export declare const createPublisher: (dir: string) => Publisher;

package/dist/publish.js

@@ -0,0 +1,56 @@
+import { contentHash } from "./hash.js";
+import { existsSync, mkdirSync, renameSync, writeFileSync } from "node:fs";
+import { DAILY_SCHEMA_VERSION, puzzleId } from "@joystyk/daily";
+import { join } from "node:path";
+//#region src/publish.ts
+/** The puzzle file body for a config: the envelope, as compact JSON. */
+var puzzleFileBody = (gameId, date, config) => {
+	const hash = contentHash(config);
+	const file = {
+		schemaVersion: DAILY_SCHEMA_VERSION,
+		puzzleId: puzzleId(gameId, date),
+		date,
+		contentHash: hash,
+		config
+	};
+	return {
+		body: JSON.stringify(file),
+		hash
+	};
+};
+var counter = 0;
+var writeAtomic = (path, body) => {
+	const temporary = `${path}.${String(process.pid)}.${String(++counter)}.tmp`;
+	writeFileSync(temporary, body);
+	renameSync(temporary, path);
+};
+var createPublisher = (dir) => ({
+	dir,
+	writePuzzle: (gameId, date, config) => {
+		const { body, hash } = puzzleFileBody(gameId, date, config);
+		const folder = join(dir, gameId);
+		mkdirSync(folder, { recursive: true });
+		const name = `${date}.${hash}.json`;
+		const path = join(folder, name);
+		if (!existsSync(path)) writeAtomic(path, body);
+		return {
+			hash,
+			size: Buffer.byteLength(body),
+			file: `${gameId}/${name}`
+		};
+	},
+	writeIndex: (gameId, dates) => {
+		const folder = join(dir, gameId);
+		mkdirSync(folder, { recursive: true });
+		const index = {
+			schemaVersion: DAILY_SCHEMA_VERSION,
+			gameId,
+			dates: [...dates].sort((a, b) => a.date < b.date ? -1 : 1)
+		};
+		writeAtomic(join(folder, "index.json"), `${JSON.stringify(index)}\n`);
+	}
+});
+//#endregion
+export { createPublisher, puzzleFileBody };
+
+//# sourceMappingURL=publish.js.map

package/dist/publish.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"publish.js","names":[],"sources":["../src/publish.ts"],"sourcesContent":["// Publishing: the daily files and each game's index, in exactly the format @joystyk/daily\n// decodes (content-pipeline.md, \"Delivery\"):\n//\n//   <dir>/<game>/index.json              { schemaVersion: 1, gameId, dates: [{ date, hash, size }] }\n//   <dir>/<game>/<date>.<hash>.json      { schemaVersion: 1, puzzleId, date, contentHash, config }\n//\n// The site serves the folder: the index `no-cache`, puzzle files immutable. A puzzle file is\n// never rewritten (its name is its hash); every write goes to a temporary file first and is\n// renamed into place, so the site never serves half a file.\nimport { existsSync, mkdirSync, renameSync, writeFileSync } from 'node:fs';\nimport { join } from 'node:path';\nimport type { Json } from '@joystyk/contracts';\nimport { DAILY_SCHEMA_VERSION, puzzleId, type DailyFile, type DailyIndex, type DailyIndexEntry } from '@joystyk/daily';\nimport { contentHash } from './hash.ts';\n\nexport interface PublishedFile {\n  readonly hash: string;\n  readonly size: number;\n  /** Relative to the publish directory: \"<game>/<date>.<hash>.json\". */\n  readonly file: string;\n}\n\nexport interface Publisher {\n  readonly dir: string;\n  /** Writes one day's puzzle file (if it isn't there already) and returns its hash and size. */\n  writePuzzle(gameId: string, date: string, config: Json): PublishedFile;\n  /** Replaces a game's index. */\n  writeIndex(gameId: string, dates: readonly DailyIndexEntry[]): void;\n}\n\n/** The puzzle file body for a config: the envelope, as compact JSON. */\nexport const puzzleFileBody = (gameId: string, date: string, config: Json): { body: string; hash: string } => {\n  const hash = contentHash(config);\n  const file: DailyFile = {\n    schemaVersion: DAILY_SCHEMA_VERSION,\n    puzzleId: puzzleId(gameId, date),\n    date,\n    contentHash: hash,\n    config,\n  };\n  return { body: JSON.stringify(file), hash };\n};\n\nlet counter = 0;\nconst writeAtomic = (path: string, body: string): void => {\n  const temporary = `${path}.${String(process.pid)}.${String(++counter)}.tmp`;\n  writeFileSync(temporary, body);\n  renameSync(temporary, path);\n};\n\nexport const createPublisher = (dir: string): Publisher => ({\n  dir,\n  writePuzzle: (gameId, date, config) => {\n    const { body, hash } = puzzleFileBody(gameId, date, config);\n    const folder = join(dir, gameId);\n    mkdirSync(folder, { recursive: true });\n    const name = `${date}.${hash}.json`;\n    const path = join(folder, name);\n    if (!existsSync(path)) writeAtomic(path, body);\n    return { hash, size: Buffer.byteLength(body), file: `${gameId}/${name}` };\n  },\n  writeIndex: (gameId, dates) => {\n    const folder = join(dir, gameId);\n    mkdirSync(folder, { recursive: true });\n    const index: DailyIndex = {\n      schemaVersion: DAILY_SCHEMA_VERSION,\n      gameId,\n      dates: [...dates].sort((a, b) => (a.date < b.date ? -1 : 1)),\n    };\n    writeAtomic(join(folder, 'index.json'), `${JSON.stringify(index)}\\n`);\n  },\n});\n"],"mappings":";;;;;;AA+BA,IAAa,kBAAkB,QAAgB,MAAc,WAAiD;CAC5G,MAAM,OAAO,YAAY,MAAM;CAC/B,MAAM,OAAkB;EACtB,eAAe;EACf,UAAU,SAAS,QAAQ,IAAI;EAC/B;EACA,aAAa;EACb;CACF;CACA,OAAO;EAAE,MAAM,KAAK,UAAU,IAAI;EAAG;CAAK;AAC5C;AAEA,IAAI,UAAU;AACd,IAAM,eAAe,MAAc,SAAuB;CACxD,MAAM,YAAY,GAAG,KAAK,GAAG,OAAO,QAAQ,GAAG,EAAE,GAAG,OAAO,EAAE,OAAO,EAAE;CACtE,cAAc,WAAW,IAAI;CAC7B,WAAW,WAAW,IAAI;AAC5B;AAEA,IAAa,mBAAmB,SAA4B;CAC1D;CACA,cAAc,QAAQ,MAAM,WAAW;EACrC,MAAM,EAAE,MAAM,SAAS,eAAe,QAAQ,MAAM,MAAM;EAC1D,MAAM,SAAS,KAAK,KAAK,MAAM;EAC/B,UAAU,QAAQ,EAAE,WAAW,KAAK,CAAC;EACrC,MAAM,OAAO,GAAG,KAAK,GAAG,KAAK;EAC7B,MAAM,OAAO,KAAK,QAAQ,IAAI;EAC9B,IAAI,CAAC,WAAW,IAAI,GAAG,YAAY,MAAM,IAAI;EAC7C,OAAO;GAAE;GAAM,MAAM,OAAO,WAAW,IAAI;GAAG,MAAM,GAAG,OAAO,GAAG;EAAO;CAC1E;CACA,aAAa,QAAQ,UAAU;EAC7B,MAAM,SAAS,KAAK,KAAK,MAAM;EAC/B,UAAU,QAAQ,EAAE,WAAW,KAAK,CAAC;EACrC,MAAM,QAAoB;GACxB,eAAe;GACf;GACA,OAAO,CAAC,GAAG,KAAK,CAAC,CAAC,MAAM,GAAG,MAAO,EAAE,OAAO,EAAE,OAAO,KAAK,CAAE;EAC7D;EACA,YAAY,KAAK,QAAQ,YAAY,GAAG,GAAG,KAAK,UAAU,KAAK,EAAE,GAAG;CACtE;AACF"}

package/dist/ranked.d.ts

@@ -0,0 +1,12 @@
+/** Word → SCOWL size (10, 20, 35, 40, 50, 55 or 60). Lower is more common. */
+export type RankedWords = ReadonlyMap<string, number>;
+/** Parses "<word> <size>" lines; blank lines and "#" comments are skipped. */
+export declare const parseRanked: (text: string) => Map<string, number>;
+/** The ranked list from lists/scowl-ranked.txt. */
+export declare const rankedWords: () => RankedWords;
+/**
+ * A word's familiarity score from 1 to 100, from its SCOWL size (crossword.md, "The crossword
+ * word list"): size 10 scores 100 and each level down costs ten points (size 50 scores 60,
+ * size 60 scores 40). Staff adjustments, when they exist, override it.
+ */
+export declare const scoreOfSize: (size: number) => number;

package/dist/ranked.js

@@ -0,0 +1,40 @@
+import { readFileSync } from "node:fs";
+//#region src/ranked.ts
+/** Parses "<word> <size>" lines; blank lines and "#" comments are skipped. */
+var parseRanked = (text) => {
+	const words = /* @__PURE__ */ new Map();
+	for (const line of text.split("\n")) {
+		const trimmed = line.trim();
+		if (trimmed === "" || trimmed.startsWith("#")) continue;
+		const [word, size] = trimmed.split(/\s+/);
+		const level = Number(size);
+		if (word !== void 0 && /^[a-z]+$/.test(word) && Number.isInteger(level)) words.set(word, level);
+	}
+	return words;
+};
+var cached = null;
+/** The ranked list from lists/scowl-ranked.txt. */
+var rankedWords = () => {
+	cached ??= parseRanked(readFileSync(new URL("../lists/scowl-ranked.txt", import.meta.url), "utf8"));
+	return cached;
+};
+/**
+* A word's familiarity score from 1 to 100, from its SCOWL size (crossword.md, "The crossword
+* word list"): size 10 scores 100 and each level down costs ten points (size 50 scores 60,
+* size 60 scores 40). Staff adjustments, when they exist, override it.
+*/
+var scoreOfSize = (size) => {
+	return {
+		10: 100,
+		20: 90,
+		35: 75,
+		40: 70,
+		50: 60,
+		55: 50,
+		60: 40
+	}[size] ?? Math.max(1, Math.min(100, 110 - size));
+};
+//#endregion
+export { parseRanked, rankedWords, scoreOfSize };
+
+//# sourceMappingURL=ranked.js.map

package/dist/ranked.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ranked.js","names":[],"sources":["../src/ranked.ts"],"sourcesContent":["// The ranked word list (lists/build-ranked.ts): lowercase SCOWL words of 3 to 12 letters with\n// the smallest SCOWL size level that lists each one. Grid games build their answers from it:\n// Crossword scores fill by size, and Word Flux limits each puzzle size to a size level.\n// Loaded once, lazily, from the package's lists/ folder.\nimport { readFileSync } from 'node:fs';\n\n/** Word → SCOWL size (10, 20, 35, 40, 50, 55 or 60). Lower is more common. */\nexport type RankedWords = ReadonlyMap<string, number>;\n\n/** Parses \"<word> <size>\" lines; blank lines and \"#\" comments are skipped. */\nexport const parseRanked = (text: string): Map<string, number> => {\n  const words = new Map<string, number>();\n  for (const line of text.split('\\n')) {\n    const trimmed = line.trim();\n    if (trimmed === '' || trimmed.startsWith('#')) continue;\n    const [word, size] = trimmed.split(/\\s+/);\n    const level = Number(size);\n    if (word !== undefined && /^[a-z]+$/.test(word) && Number.isInteger(level)) words.set(word, level);\n  }\n  return words;\n};\n\nlet cached: RankedWords | null = null;\n\n/** The ranked list from lists/scowl-ranked.txt. */\nexport const rankedWords = (): RankedWords => {\n  cached ??= parseRanked(readFileSync(new URL('../lists/scowl-ranked.txt', import.meta.url), 'utf8'));\n  return cached;\n};\n\n/**\n * A word's familiarity score from 1 to 100, from its SCOWL size (crossword.md, \"The crossword\n * word list\"): size 10 scores 100 and each level down costs ten points (size 50 scores 60,\n * size 60 scores 40). Staff adjustments, when they exist, override it.\n */\nexport const scoreOfSize = (size: number): number => {\n  const scores: Readonly<Record<number, number>> = { 10: 100, 20: 90, 35: 75, 40: 70, 50: 60, 55: 50, 60: 40 };\n  return scores[size] ?? Math.max(1, Math.min(100, 110 - size));\n};\n"],"mappings":";;;AAUA,IAAa,eAAe,SAAsC;CAChE,MAAM,wBAAQ,IAAI,IAAoB;CACtC,KAAK,MAAM,QAAQ,KAAK,MAAM,IAAI,GAAG;EACnC,MAAM,UAAU,KAAK,KAAK;EAC1B,IAAI,YAAY,MAAM,QAAQ,WAAW,GAAG,GAAG;EAC/C,MAAM,CAAC,MAAM,QAAQ,QAAQ,MAAM,KAAK;EACxC,MAAM,QAAQ,OAAO,IAAI;EACzB,IAAI,SAAS,KAAA,KAAa,WAAW,KAAK,IAAI,KAAK,OAAO,UAAU,KAAK,GAAG,MAAM,IAAI,MAAM,KAAK;CACnG;CACA,OAAO;AACT;AAEA,IAAI,SAA6B;;AAGjC,IAAa,oBAAiC;CAC5C,WAAW,YAAY,aAAa,IAAI,IAAI,6BAA6B,YAAY,GAAG,GAAG,MAAM,CAAC;CAClG,OAAO;AACT;;;;;;AAOA,IAAa,eAAe,SAAyB;CAEnD,OAAO;EAD4C,IAAI;EAAK,IAAI;EAAI,IAAI;EAAI,IAAI;EAAI,IAAI;EAAI,IAAI;EAAI,IAAI;CACjG,EAAO,SAAS,KAAK,IAAI,GAAG,KAAK,IAAI,KAAK,MAAM,IAAI,CAAC;AAC9D"}

package/dist/screen.d.ts

@@ -0,0 +1,25 @@
+import { type Result } from '@joystyk/contracts';
+import * as z from 'zod';
+import type { FieldText } from './filter.js';
+import type { CompletionFailure, ModelClient, CallInfo } from './model.js';
+export declare const SCREEN_PROMPT_VERSION = "screen-v1";
+export declare const screenVerdict: z.ZodObject<{
+    safe: z.ZodBoolean;
+    reasons: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;
+export type ScreenVerdict = z.infer<typeof screenVerdict>;
+export declare const SCREEN_SYSTEM: string;
+export declare const screenMessages: (fields: readonly FieldText[]) => readonly [{
+    readonly role: "system";
+    readonly content: string;
+}, {
+    readonly role: "user";
+    readonly content: `Check these fields:
+${string}`;
+}];
+export type ScreenResult = Result<{
+    verdict: ScreenVerdict;
+    call: CallInfo;
+}, CompletionFailure>;
+/** Runs the model screen over the fields. */
+export declare const modelScreen: (model: ModelClient, fields: readonly FieldText[], signal?: AbortSignal) => Promise<ScreenResult>;

package/dist/screen.js

@@ -0,0 +1,46 @@
+import { err, ok } from "@joystyk/contracts";
+import * as z from "zod";
+//#region src/screen.ts
+var SCREEN_PROMPT_VERSION = "screen-v1";
+var screenVerdict = z.object({
+	safe: z.boolean(),
+	reasons: z.array(z.string().max(200)).max(10)
+});
+var SCREEN_SYSTEM = [
+	"You check text for a puzzle website that children play. Be strict.",
+	"Mark the text unsafe if any field contains or implies any of these:",
+	"- profanity, insults, slurs, or anything sexual or romantic;",
+	"- violence, weapons, war, death, injury, illness, or disasters;",
+	"- crime, drugs, alcohol, tobacco, or gambling;",
+	"- religion, politics, or current news;",
+	"- a real living person, a brand, a product, or a company;",
+	"- anything scary, cruel, mean, or sad enough to upset a young child.",
+	"Judge safety only. Puzzles include wrong answer choices on purpose, so never mark text unsafe for being false, nonsensical or ungrammatical; other checks handle accuracy.",
+	"Everyday things are fine: mild feelings (bored, grumpy, tired), harmless tricks and games, the ordinary words \"news\" or \"newspaper\" without naming real events, school, family and pets. Words for ordinary unkind behavior, such as scolding, teasing or grumbling, are fine when the text itself is gentle.",
+	"Reply with JSON: {\"safe\": boolean, \"reasons\": [short reasons, empty when safe]}."
+].join("\n");
+var screenMessages = (fields) => [{
+	role: "system",
+	content: SCREEN_SYSTEM
+}, {
+	role: "user",
+	content: `Check these fields:\n${fields.map((field) => `${field.path}: ${field.text}`).join("\n")}`
+}];
+/** Runs the model screen over the fields. */
+var modelScreen = async (model, fields, signal) => {
+	const result = await model.complete({
+		name: "safety_screen",
+		schema: screenVerdict,
+		messages: screenMessages(fields),
+		temperature: 0,
+		...signal === void 0 ? {} : { signal }
+	});
+	return result.ok ? ok({
+		verdict: result.value.value,
+		call: result.value.call
+	}) : err(result.error);
+};
+//#endregion
+export { SCREEN_PROMPT_VERSION, SCREEN_SYSTEM, modelScreen, screenMessages, screenVerdict };
+
+//# sourceMappingURL=screen.js.map

package/dist/screen.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"screen.js","names":[],"sources":["../src/screen.ts"],"sourcesContent":["// Layer 3 of the all-ages filter: a second model call screens every text field against the\n// same rules as the word lists (content-pipeline.md, \"The all-ages filter\"). It can only add\n// a rejection: a \"safe\" verdict never overrides the blocklist or the sensitive list, and a\n// failed screening call fails the attempt, because nothing publishes unscreened.\nimport { err, ok, type Result } from '@joystyk/contracts';\nimport * as z from 'zod';\nimport type { FieldText } from './filter.ts';\nimport type { CompletionFailure, ModelClient, CallInfo } from './model.ts';\n\nexport const SCREEN_PROMPT_VERSION = 'screen-v1';\n\nexport const screenVerdict = z.object({\n  safe: z.boolean(),\n  reasons: z.array(z.string().max(200)).max(10),\n});\nexport type ScreenVerdict = z.infer<typeof screenVerdict>;\n\nexport const SCREEN_SYSTEM = [\n  'You check text for a puzzle website that children play. Be strict.',\n  'Mark the text unsafe if any field contains or implies any of these:',\n  '- profanity, insults, slurs, or anything sexual or romantic;',\n  '- violence, weapons, war, death, injury, illness, or disasters;',\n  '- crime, drugs, alcohol, tobacco, or gambling;',\n  '- religion, politics, or current news;',\n  '- a real living person, a brand, a product, or a company;',\n  '- anything scary, cruel, mean, or sad enough to upset a young child.',\n  'Judge safety only. Puzzles include wrong answer choices on purpose, so never mark text unsafe for being false, nonsensical or ungrammatical; other checks handle accuracy.',\n  'Everyday things are fine: mild feelings (bored, grumpy, tired), harmless tricks and games, the ordinary words \"news\" or \"newspaper\" without naming real events, school, family and pets. Words for ordinary unkind behavior, such as scolding, teasing or grumbling, are fine when the text itself is gentle.',\n  'Reply with JSON: {\"safe\": boolean, \"reasons\": [short reasons, empty when safe]}.',\n].join('\\n');\n\nexport const screenMessages = (fields: readonly FieldText[]) =>\n  [\n    { role: 'system', content: SCREEN_SYSTEM },\n    {\n      role: 'user',\n      content: `Check these fields:\\n${fields.map((field) => `${field.path}: ${field.text}`).join('\\n')}`,\n    },\n  ] as const;\n\nexport type ScreenResult = Result<{ verdict: ScreenVerdict; call: CallInfo }, CompletionFailure>;\n\n/** Runs the model screen over the fields. */\nexport const modelScreen = async (\n  model: ModelClient,\n  fields: readonly FieldText[],\n  signal?: AbortSignal,\n): Promise<ScreenResult> => {\n  const result = await model.complete({\n    name: 'safety_screen',\n    schema: screenVerdict,\n    messages: screenMessages(fields),\n    temperature: 0,\n    ...(signal === undefined ? {} : { signal }),\n  });\n  return result.ok ? ok({ verdict: result.value.value, call: result.value.call }) : err(result.error);\n};\n"],"mappings":";;;AASA,IAAa,wBAAwB;AAErC,IAAa,gBAAgB,EAAE,OAAO;CACpC,MAAM,EAAE,QAAQ;CAChB,SAAS,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE;AAC9C,CAAC;AAGD,IAAa,gBAAgB;CAC3B;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;AACF,CAAC,CAAC,KAAK,IAAI;AAEX,IAAa,kBAAkB,WAC7B,CACE;CAAE,MAAM;CAAU,SAAS;AAAc,GACzC;CACE,MAAM;CACN,SAAS,wBAAwB,OAAO,KAAK,UAAU,GAAG,MAAM,KAAK,IAAI,MAAM,MAAM,CAAC,CAAC,KAAK,IAAI;AAClG,CACF;;AAKF,IAAa,cAAc,OACzB,OACA,QACA,WAC0B;CAC1B,MAAM,SAAS,MAAM,MAAM,SAAS;EAClC,MAAM;EACN,QAAQ;EACR,UAAU,eAAe,MAAM;EAC/B,aAAa;EACb,GAAI,WAAW,KAAA,IAAY,CAAC,IAAI,EAAE,OAAO;CAC3C,CAAC;CACD,OAAO,OAAO,KAAK,GAAG;EAAE,SAAS,OAAO,MAAM;EAAO,MAAM,OAAO,MAAM;CAAK,CAAC,IAAI,IAAI,OAAO,KAAK;AACpG"}

package/dist/store.d.ts

@@ -0,0 +1,136 @@
+import { type Json } from '@joystyk/contracts';
+export type ItemStatus = 'scheduled' | 'generating' | 'failed' | 'validated' | 'published' | 'withdrawn';
+export type ItemSource = 'generated' | 'bank' | 'staff';
+/** Reason codes for a takedown (content-pipeline.md, "Moderation in /admin"). */
+export declare const WITHDRAW_REASONS: readonly ["inaccurate", "unfair", "unsafe", "dull", "other"];
+export type WithdrawReason = (typeof WITHDRAW_REASONS)[number];
+export interface ItemRow {
+    readonly id: number;
+    readonly gameId: string;
+    readonly puzzleId: string;
+    readonly date: string;
+    readonly status: ItemStatus;
+    readonly source: ItemSource | null;
+    readonly inputs: Json | null;
+    readonly seed: string | null;
+    readonly model: string | null;
+    readonly promptVersion: string | null;
+    /** The answer key used for duplicate checks, e.g. the day's word. */
+    readonly answer: string | null;
+    readonly config: Json | null;
+    readonly contentHash: string | null;
+    readonly size: number | null;
+    readonly attempts: number;
+    /** Every attempt's report: calls, validator issues, filter and screen outcomes. */
+    readonly report: Json | null;
+    readonly createdAt: string;
+    readonly updatedAt: string;
+    readonly publishedAt: string | null;
+    readonly withdrawnAt: string | null;
+    readonly withdrawnReason: string | null;
+    readonly withdrawnBy: string | null;
+}
+export type ItemPatch = Partial<Pick<ItemRow, 'status' | 'source' | 'inputs' | 'seed' | 'model' | 'promptVersion' | 'answer' | 'config' | 'contentHash' | 'size' | 'attempts' | 'report' | 'publishedAt'>>;
+export interface BankChange {
+    readonly gameId: string;
+    readonly key: string;
+    readonly config: Json | null;
+    readonly retired: boolean;
+    readonly actor: string;
+    readonly changedAt: string;
+}
+export interface RunRow {
+    readonly id: number;
+    readonly startedAt: string;
+    readonly finishedAt: string | null;
+    readonly trigger: string;
+    readonly status: 'running' | 'ok' | 'partial' | 'failed' | 'aborted';
+    readonly summary: Json | null;
+}
+export interface ContentStore {
+    readonly path: string;
+    bankChanges(gameId: string): readonly BankChange[];
+    changeBank(input: {
+        readonly gameId: string;
+        readonly key: string;
+        readonly config: Json | null;
+        readonly retired: boolean;
+        readonly actor: string;
+        readonly now: number;
+    }): void;
+    /** Atomically archives the prior version and creates a validated staff replacement. */
+    replaceItem(input: {
+        readonly expectedId: number;
+        readonly actor: string;
+        readonly note: string;
+        readonly now: number;
+        readonly source: 'staff' | 'bank';
+        readonly inputs?: Json | null;
+        readonly status: 'validated' | 'published';
+        readonly config: Json;
+        readonly answer: string | null;
+        readonly hash: string;
+        readonly size: number;
+    }): ItemRow | null;
+    /** The item that currently holds a puzzle id (any status but withdrawn), or null. */
+    current(puzzleId: string): ItemRow | null;
+    item(id: number): ItemRow | null;
+    /** Every item for a puzzle id, oldest first, withdrawn ones included. */
+    history(puzzleId: string): ItemRow[];
+    createItem(input: {
+        gameId: string;
+        puzzleId: string;
+        date: string;
+        inputs: Json;
+        seed: string;
+        answer: string | null;
+        now: number;
+    }): ItemRow;
+    updateItem(id: number, patch: ItemPatch, now: number, event?: {
+        kind: string;
+        actor?: string;
+        detail?: Json;
+    }): ItemRow;
+    /**
+     * Answers used by a game's items dated in [from, to], withdrawn ones included (they count as
+     * used), and the answers their schedules reserved, even where a bank item took the slot: a
+     * word that failed on one day isn't tried again the next.
+     */
+    usedAnswers(gameId: string, from: string, to: string): {
+        date: string;
+        answer: string;
+        status: ItemStatus;
+    }[];
+    /** Published (not withdrawn) items of a game dated in [from, to], by date. */
+    published(gameId: string, from: string, to: string): ItemRow[];
+    /** Validated items waiting to publish, dated up to `through`. */
+    validatedThrough(gameId: string, through: string): ItemRow[];
+    /** Items of a game in [from, to] with any status, current ones only, by date. */
+    items(gameId: string, from: string, to: string): ItemRow[];
+    /** All versions in the date range, including withdrawn content, for repeat checks. */
+    versions(gameId: string, from: string, to: string): ItemRow[];
+    /** Takes an item down (content-pipeline.md, "Corrections"). Returns the withdrawn row, or null if none held the id. */
+    withdraw(puzzleId: string, reason: WithdrawReason, actor: string, now: number, note?: string): ItemRow | null;
+    addEvent(itemId: number | null, kind: string, actor: string, now: number, detail?: Json): void;
+    events(itemId: number): {
+        at: string;
+        kind: string;
+        actor: string;
+        detail: Json | null;
+    }[];
+    startRun(trigger: string, now: number): number;
+    finishRun(id: number, status: RunRow['status'], summary: Json, now: number): void;
+    recentRuns(limit: number): RunRow[];
+    /**
+     * Takes the named lock for `owner` until `now + ttlMs`, or refreshes it if `owner` holds it.
+     * False when someone else holds an unexpired lock. A crashed holder's lock expires.
+     */
+    tryLock(name: string, owner: string, now: number, ttlMs: number): boolean;
+    releaseLock(name: string, owner: string): void;
+    lockHolder(name: string, now: number): {
+        owner: string;
+        acquiredAt: string;
+    } | null;
+    close(): void;
+}
+export declare const openStore: (path: string) => ContentStore;

package/dist/store.js

@@ -0,0 +1,300 @@
+import { isJson } from "@joystyk/contracts";
+import { DatabaseSync } from "node:sqlite";
+import * as z from "zod/mini";
+//#region src/store.ts
+/** Reason codes for a takedown (content-pipeline.md, "Moderation in /admin"). */
+var WITHDRAW_REASONS = [
+	"inaccurate",
+	"unfair",
+	"unsafe",
+	"dull",
+	"other"
+];
+/** The schema, one migration per `user_version`. Append; never edit a shipped entry. */
+var MIGRATIONS = [`CREATE TABLE items (
+     id INTEGER PRIMARY KEY,
+     game_id TEXT NOT NULL,
+     puzzle_id TEXT NOT NULL,
+     date TEXT NOT NULL,
+     status TEXT NOT NULL,
+     source TEXT,
+     inputs TEXT,
+     seed TEXT,
+     model TEXT,
+     prompt_version TEXT,
+     answer TEXT,
+     reserved TEXT,
+     config TEXT,
+     content_hash TEXT,
+     size INTEGER,
+     attempts INTEGER NOT NULL DEFAULT 0,
+     report TEXT,
+     created_at TEXT NOT NULL,
+     updated_at TEXT NOT NULL,
+     published_at TEXT,
+     withdrawn_at TEXT,
+     withdrawn_reason TEXT,
+     withdrawn_by TEXT
+   );
+   CREATE UNIQUE INDEX items_current ON items (puzzle_id) WHERE status <> 'withdrawn';
+   CREATE INDEX items_game_date ON items (game_id, date);
+   CREATE TABLE runs (
+     id INTEGER PRIMARY KEY,
+     started_at TEXT NOT NULL,
+     finished_at TEXT,
+     trigger TEXT NOT NULL,
+     status TEXT NOT NULL,
+     summary TEXT
+   );
+   CREATE TABLE events (
+     id INTEGER PRIMARY KEY,
+     item_id INTEGER REFERENCES items (id),
+     at TEXT NOT NULL,
+     kind TEXT NOT NULL,
+     actor TEXT NOT NULL,
+     detail TEXT
+   );
+   CREATE INDEX events_item ON events (item_id);
+   CREATE TABLE locks (
+     name TEXT PRIMARY KEY,
+     owner TEXT NOT NULL,
+     acquired_at TEXT NOT NULL,
+     expires_at INTEGER NOT NULL
+   );`, `CREATE TABLE bank_changes (
+    game_id TEXT NOT NULL,
+    bank_key TEXT NOT NULL,
+    config TEXT,
+    retired INTEGER NOT NULL CHECK (retired IN (0, 1)),
+    actor TEXT NOT NULL,
+    changed_at TEXT NOT NULL,
+    PRIMARY KEY (game_id, bank_key)
+  );`];
+var iso = (ms) => new Date(ms).toISOString();
+var json = (value) => value === null || value === void 0 ? null : JSON.stringify(value);
+var storedJson = z.custom(isJson);
+var parse = (text) => typeof text === "string" ? storedJson.parse(JSON.parse(text)) : null;
+var str = (value) => typeof value === "string" ? value : null;
+var toItem = (row) => ({
+	id: Number(row["id"]),
+	gameId: String(row["game_id"]),
+	puzzleId: String(row["puzzle_id"]),
+	date: String(row["date"]),
+	status: String(row["status"]),
+	source: str(row["source"]),
+	inputs: parse(row["inputs"]),
+	seed: str(row["seed"]),
+	model: str(row["model"]),
+	promptVersion: str(row["prompt_version"]),
+	answer: str(row["answer"]),
+	config: parse(row["config"]),
+	contentHash: str(row["content_hash"]),
+	size: row["size"] === null || row["size"] === void 0 ? null : Number(row["size"]),
+	attempts: Number(row["attempts"]),
+	report: parse(row["report"]),
+	createdAt: String(row["created_at"]),
+	updatedAt: String(row["updated_at"]),
+	publishedAt: str(row["published_at"]),
+	withdrawnAt: str(row["withdrawn_at"]),
+	withdrawnReason: str(row["withdrawn_reason"]),
+	withdrawnBy: str(row["withdrawn_by"])
+});
+var COLUMNS = {
+	status: "status",
+	source: "source",
+	inputs: "inputs",
+	seed: "seed",
+	model: "model",
+	promptVersion: "prompt_version",
+	answer: "answer",
+	config: "config",
+	contentHash: "content_hash",
+	size: "size",
+	attempts: "attempts",
+	report: "report",
+	publishedAt: "published_at"
+};
+var JSON_FIELDS = /* @__PURE__ */ new Set([
+	"inputs",
+	"config",
+	"report"
+]);
+var openStore = (path) => {
+	const db = new DatabaseSync(path);
+	db.exec("PRAGMA busy_timeout = 5000");
+	if (path !== ":memory:") db.exec("PRAGMA journal_mode = WAL");
+	db.exec("PRAGMA foreign_keys = ON");
+	const version = Number(db.prepare("PRAGMA user_version").get().user_version);
+	if (version > MIGRATIONS.length) {
+		db.close();
+		throw new Error(`content.db has schema version ${String(version)}, newer than this build (${String(MIGRATIONS.length)}). Roll forward, or restore an older backup.`);
+	}
+	for (let v = version; v < MIGRATIONS.length; v++) {
+		db.exec("BEGIN IMMEDIATE");
+		try {
+			db.exec(MIGRATIONS[v] ?? "");
+			db.exec(`PRAGMA user_version = ${String(v + 1)}`);
+			db.exec("COMMIT");
+		} catch (error) {
+			db.exec("ROLLBACK");
+			throw error;
+		}
+	}
+	const all = (sql, ...params) => db.prepare(sql).all(...params);
+	const one = (sql, ...params) => db.prepare(sql).get(...params);
+	const run = (sql, ...params) => db.prepare(sql).run(...params);
+	const transaction = (fn) => {
+		db.exec("BEGIN IMMEDIATE");
+		try {
+			const value = fn();
+			db.exec("COMMIT");
+			return value;
+		} catch (error) {
+			db.exec("ROLLBACK");
+			throw error;
+		}
+	};
+	const addEvent = (itemId, kind, actor, now, detail) => {
+		run("INSERT INTO events (item_id, at, kind, actor, detail) VALUES (?, ?, ?, ?, ?)", itemId, iso(now), kind, actor, json(detail));
+	};
+	const item = (id) => {
+		const row = one("SELECT * FROM items WHERE id = ?", id);
+		return row === void 0 ? null : toItem(row);
+	};
+	return {
+		path,
+		current: (puzzleId) => {
+			const row = one("SELECT * FROM items WHERE puzzle_id = ? AND status <> 'withdrawn'", puzzleId);
+			return row === void 0 ? null : toItem(row);
+		},
+		item,
+		history: (puzzleId) => all("SELECT * FROM items WHERE puzzle_id = ? ORDER BY id", puzzleId).map(toItem),
+		bankChanges: (gameId) => all("SELECT * FROM bank_changes WHERE game_id = ? ORDER BY bank_key", gameId).map((row) => ({
+			gameId: String(row["game_id"]),
+			key: String(row["bank_key"]),
+			config: parse(row["config"]),
+			retired: row["retired"] === 1,
+			actor: String(row["actor"]),
+			changedAt: String(row["changed_at"])
+		})),
+		changeBank: ({ gameId, key, config, retired, actor, now }) => transaction(() => {
+			run("INSERT INTO bank_changes (game_id, bank_key, config, retired, actor, changed_at) VALUES (?, ?, ?, ?, ?, ?) ON CONFLICT (game_id, bank_key) DO UPDATE SET config = excluded.config, retired = excluded.retired, actor = excluded.actor, changed_at = excluded.changed_at", gameId, key, json(config), retired ? 1 : 0, actor, iso(now));
+			addEvent(null, "bank.changed", actor, now, {
+				gameId,
+				key,
+				retired
+			});
+		}),
+		replaceItem: (input) => transaction(() => {
+			const previous = item(input.expectedId);
+			if (previous === null || previous.status === "withdrawn") return null;
+			const at = iso(input.now);
+			run("UPDATE items SET status = 'withdrawn', withdrawn_at = ?, withdrawn_reason = 'other', withdrawn_by = ?, updated_at = ? WHERE id = ?", at, input.actor, at, previous.id);
+			addEvent(previous.id, "withdrawn", input.actor, input.now, {
+				reason: "other",
+				from: previous.status,
+				note: input.note || "Staff correction."
+			});
+			const report = [{ checks: { staff: {
+				schema: true,
+				gameValidators: true,
+				allAgesFilter: true,
+				modelChecks: "not rerun; human correction",
+				previousItem: previous.id
+			} } }];
+			const result = run(`INSERT INTO items (game_id, puzzle_id, date, status, source, inputs, seed, answer, reserved, config, content_hash, size, prompt_version, report, created_at, updated_at, published_at)
+        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`, previous.gameId, previous.puzzleId, previous.date, input.status, input.source, json(input.inputs === void 0 ? previous.inputs : input.inputs), previous.seed, input.answer, input.answer, json(input.config), input.hash, input.size, "staff-validated-v1", json(report), at, at, input.status === "published" ? at : null);
+			const id = Number(result.lastInsertRowid);
+			addEvent(id, input.source === "bank" ? "bank.selected" : "staff.edited", input.actor, input.now, {
+				previousItem: previous.id,
+				note: input.note,
+				hash: input.hash
+			});
+			return item(id);
+		}),
+		createItem: ({ gameId, puzzleId, date, inputs, seed, answer, now }) => transaction(() => {
+			const result = run(`INSERT INTO items (game_id, puzzle_id, date, status, inputs, seed, answer, reserved, created_at, updated_at)
+           VALUES (?, ?, ?, 'scheduled', ?, ?, ?, ?, ?, ?)`, gameId, puzzleId, date, json(inputs), seed, answer, answer, iso(now), iso(now));
+			const id = Number(result.lastInsertRowid);
+			addEvent(id, "scheduled", "content", now, { inputs });
+			return item(id);
+		}),
+		updateItem: (id, patch, now, event) => transaction(() => {
+			const sets = ["updated_at = ?"];
+			const values = [iso(now)];
+			for (const [key, value] of Object.entries(patch)) {
+				if (value === void 0) continue;
+				sets.push(`${COLUMNS[key]} = ?`);
+				values.push(JSON_FIELDS.has(key) ? json(value) : value);
+			}
+			if (run(`UPDATE items SET ${sets.join(", ")} WHERE id = ? AND status <> 'withdrawn'`, ...values, id).changes !== 0 && event !== void 0) addEvent(id, event.kind, event.actor ?? "content", now, event.detail);
+			return item(id);
+		}),
+		usedAnswers: (gameId, from, to) => all(`SELECT date, answer, status FROM items WHERE game_id = ? AND date >= ? AND date <= ? AND answer IS NOT NULL
+         UNION SELECT date, reserved, status FROM items WHERE game_id = ? AND date >= ? AND date <= ? AND reserved IS NOT NULL
+         ORDER BY date`, gameId, from, to, gameId, from, to).map((row) => ({
+			date: String(row["date"]),
+			answer: String(row["answer"]),
+			status: String(row["status"])
+		})),
+		published: (gameId, from, to) => all("SELECT * FROM items WHERE game_id = ? AND status = 'published' AND date >= ? AND date <= ? ORDER BY date", gameId, from, to).map(toItem),
+		validatedThrough: (gameId, through) => all("SELECT * FROM items WHERE game_id = ? AND status = 'validated' AND date <= ? ORDER BY date", gameId, through).map(toItem),
+		items: (gameId, from, to) => all("SELECT * FROM items WHERE game_id = ? AND status <> 'withdrawn' AND date >= ? AND date <= ? ORDER BY date", gameId, from, to).map(toItem),
+		versions: (gameId, from, to) => all("SELECT * FROM items WHERE game_id = ? AND date >= ? AND date <= ? ORDER BY date, id", gameId, from, to).map(toItem),
+		withdraw: (puzzleId, reason, actor, now, note) => transaction(() => {
+			const row = one("SELECT * FROM items WHERE puzzle_id = ? AND status <> 'withdrawn'", puzzleId);
+			if (row === void 0) return null;
+			const before = toItem(row);
+			run("UPDATE items SET status = 'withdrawn', withdrawn_at = ?, withdrawn_reason = ?, withdrawn_by = ?, updated_at = ? WHERE id = ?", iso(now), reason, actor, iso(now), before.id);
+			addEvent(before.id, "withdrawn", actor, now, {
+				reason,
+				from: before.status,
+				...note === void 0 ? {} : { note }
+			});
+			return item(before.id);
+		}),
+		addEvent,
+		events: (itemId) => all("SELECT at, kind, actor, detail FROM events WHERE item_id = ? ORDER BY id", itemId).map((row) => ({
+			at: String(row["at"]),
+			kind: String(row["kind"]),
+			actor: String(row["actor"]),
+			detail: parse(row["detail"])
+		})),
+		startRun: (trigger, now) => Number(run("INSERT INTO runs (started_at, trigger, status) VALUES (?, ?, 'running')", iso(now), trigger).lastInsertRowid),
+		finishRun: (id, status, summary, now) => {
+			run("UPDATE runs SET finished_at = ?, status = ?, summary = ? WHERE id = ?", iso(now), status, json(summary), id);
+		},
+		recentRuns: (limit) => all("SELECT * FROM runs ORDER BY id DESC LIMIT ?", limit).map((row) => ({
+			id: Number(row["id"]),
+			startedAt: String(row["started_at"]),
+			finishedAt: str(row["finished_at"]),
+			trigger: String(row["trigger"]),
+			status: String(row["status"]),
+			summary: parse(row["summary"])
+		})),
+		tryLock: (name, owner, now, ttlMs) => transaction(() => {
+			const row = one("SELECT owner, expires_at FROM locks WHERE name = ?", name);
+			if (row !== void 0 && row["owner"] !== owner && Number(row["expires_at"]) > now) return false;
+			run(`INSERT INTO locks (name, owner, acquired_at, expires_at) VALUES (?, ?, ?, ?)
+           ON CONFLICT (name) DO UPDATE SET owner = excluded.owner, expires_at = excluded.expires_at,
+             acquired_at = CASE WHEN locks.owner = excluded.owner THEN locks.acquired_at ELSE excluded.acquired_at END`, name, owner, iso(now), now + ttlMs);
+			return true;
+		}),
+		releaseLock: (name, owner) => {
+			run("DELETE FROM locks WHERE name = ? AND owner = ?", name, owner);
+		},
+		lockHolder: (name, now) => {
+			const row = one("SELECT owner, acquired_at, expires_at FROM locks WHERE name = ?", name);
+			return row === void 0 || Number(row["expires_at"]) <= now ? null : {
+				owner: String(row["owner"]),
+				acquiredAt: String(row["acquired_at"])
+			};
+		},
+		close: () => {
+			if (db.isOpen) db.close();
+		}
+	};
+};
+//#endregion
+export { WITHDRAW_REASONS, openStore };
+
+//# sourceMappingURL=store.js.map