@knights-eye-chess/ai-analysis 0.0.0-stage → 0.1.0-dev.14

package/package.json

@@ -1,6 +1,74 @@
 {
   "name": "@knights-eye-chess/ai-analysis",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0-dev.14",
+  "type": "module",
+  "files": [
+    "dist",
+    "src",
+    "build.mjs",
+    "tsconfig.json",
+    "README.md",
+    "test-types.mts",
+    "test",
+    "SOURCE-ORIGIN.json",
+    "scripts",
+    "LICENSE",
+    "NOTICE",
+    "LICENSING.md",
+    "THIRD_PARTY_NOTICES.md",
+    "licenses",
+    "NPM-PUBLISHING.md",
+    "npm-release.json",
+    "docs"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/types/chess-reasoning/answer-pipeline-exports.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./research": {
+      "types": "./dist/types/chess-reasoning/research-exports.d.ts",
+      "import": "./dist/research.js"
+    },
+    "./shared": {
+      "types": "./dist/types/shared-exports.d.ts",
+      "import": "./dist/shared.js"
+    }
+  },
+  "scripts": {
+    "build": "node build.mjs",
+    "test": "node --test dist/answer-pipeline.test.mjs dist/owner-tests/*.test.mjs",
+    "test:types": "tsc --noEmit --strict --target ES2022 --module NodeNext --moduleResolution NodeNext --lib ES2022,DOM,DOM.Iterable test-types.mts",
+    "check": "npm run build && npm test && npm run test:types",
+    "pack:checked": "npm run check && node scripts/pack.mjs",
+    "pack:artifact": "node scripts/pack.mjs",
+    "publish:verify": "node scripts/verify-release.mjs",
+    "publish:prepare": "npm run pack:checked && npm run publish:verify"
+  },
+  "engines": {
+    "node": ">=24.0.0"
+  },
+  "dependencies": {
+    "@ai-sdk/provider": "4.0.9",
+    "@ai-sdk/provider-utils": "5.0.34",
+    "@knights-eye-chess/move-classifier": "0.1.0-dev.10",
+    "@types/json-schema": "7.0.15",
+    "@types/node": "22.19.19",
+    "ai": "7.0.85",
+    "chess.js": "1.4.0"
+  },
+  "devDependencies": {
+    "esbuild": "0.28.0",
+    "typescript": "5.9.3"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/knights-eye-chess/ai-analysis.git"
+  },
+  "license": "AGPL-3.0-or-later",
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public",
+    "tag": "next"
+  }
+}

package/scripts/check-release-tooling.mjs

@@ -0,0 +1,22 @@
+// Generated from knightseye-net/tools/release-tooling; edit the canonical template and sync.
+import { readFileSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
+
+export function assertReleaseTooling(root = fileURLToPath(new URL('../', import.meta.url))) {
+  const manifest = JSON.parse(readFileSync(path.join(root, 'scripts/release-tooling.json'), 'utf8'));
+  if (manifest.schema !== 1 || manifest.canonical !== 'knightseye-net/tools/release-tooling') throw Error('Invalid release tooling stamp');
+  const required = ['scripts/pack.mjs', 'scripts/publish-reviewed.mjs', '.github/workflows/npm-publish.yml', 'scripts/verify-release.mjs', 'scripts/update-dependency.mjs', 'scripts/check-release-tooling.mjs', '.github/workflows/quality.yml'];
+  if (!manifest.sha256 || required.some(relative => !/^[a-f0-9]{64}$/.test(manifest.sha256[relative] || ''))) throw Error('Incomplete release tooling stamp');
+  for (const [relative, expected] of Object.entries(manifest.sha256)) {
+    if (path.isAbsolute(relative) || relative.split('/').includes('..')) throw Error(`Invalid tooling path: ${relative}`);
+    const actual = createHash('sha256').update(readFileSync(path.join(root, relative))).digest('hex');
+    if (actual !== expected) throw Error(`Release tooling drift: ${relative}. Sync from ${manifest.canonical} before releasing.`);
+  }
+  return manifest;
+}
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  assertReleaseTooling();
+  console.log('Release tooling stamp verified');
+}

package/scripts/pack.mjs

@@ -0,0 +1,68 @@
+// Generated from knightseye-net/tools/release-tooling; edit the canonical template and sync.
+import { assertReleaseTooling } from './check-release-tooling.mjs';
+assertReleaseTooling();
+import { readFileSync, writeFileSync, mkdtempSync, mkdirSync, copyFileSync, existsSync, rmSync, chmodSync, statSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import path from 'node:path';
+import os from 'node:os';
+import { fileURLToPath } from 'node:url';
+
+const root = fileURLToPath(new URL('../', import.meta.url));
+const destination = path.resolve(process.argv[2] || path.join(root, 'artifacts'));
+const release = JSON.parse(readFileSync(path.join(root, 'npm-release.json'), 'utf8'));
+function run(command, args, cwd = root) {
+  const result = spawnSync(command, args, { cwd, encoding: 'utf8' });
+  if (result.status !== 0) throw Error(result.stderr || result.stdout || `${command} failed`);
+  return result.stdout;
+}
+const listing = JSON.parse(run('npm', ['pack', '--dry-run', '--json', '--ignore-scripts']))[0];
+const stage = mkdtempSync(path.join(os.tmpdir(), 'knights-eye-pack-'));
+const output = mkdtempSync(path.join(os.tmpdir(), 'knights-eye-archive-'));
+try {
+  for (const { path: relative } of listing.files) {
+    if (relative === 'npm-shrinkwrap.json' || relative === 'package-lock.json' || relative.startsWith('vendor/')) continue;
+    const to = path.join(stage, relative);
+    mkdirSync(path.dirname(to), { recursive: true });
+    const source = path.join(root, relative);
+    copyFileSync(source, to);
+    chmodSync(to, statSync(source).mode & 0o111 ? 0o755 : 0o644);
+  }
+  const pkg = JSON.parse(readFileSync(path.join(stage, 'package.json'), 'utf8'));
+  const dependencies = pkg.dependencies || {};
+  const mapping = release.registryDependencies || {};
+  for (const [name, version] of Object.entries(mapping)) {
+    if (!/^\d+\.\d+\.\d+(?:-[\w.-]+)?$/.test(version)) throw Error(`Missing exact registry release version: ${name}`);
+    const value = dependencies[name];
+    if (!value) throw Error(`Unexpected registry release dependency: ${name}`);
+    if (value.startsWith('file:')) {
+      const original = JSON.parse(run('tar', ['-xOf', path.resolve(root, value.slice(5)), 'package/package.json']));
+      if (original.name !== name) throw Error(`Dependency identity mismatch: ${name}`);
+    } else if (value !== version) throw Error(`Registry dependency must match exact release version: ${name}`);
+    dependencies[name] = version;
+  }
+  for (const [name, value] of Object.entries(dependencies)) {
+    if (value.startsWith('file:') || (name.startsWith('@knights-eye-chess/') && !mapping[name])) throw Error(`Missing exact registry release version: ${name}`);
+  }
+  delete pkg.private;
+  delete pkg.overrides;
+  pkg.publishConfig = { registry: 'https://registry.npmjs.org/', access: 'public', tag: 'next' };
+  writeFileSync(path.join(stage, 'package.json'), JSON.stringify(pkg, null, 2) + '\n');
+  chmodSync(path.join(stage, 'package.json'), 0o644);
+  const bins = typeof pkg.bin === 'string' ? [pkg.bin] : Object.values(pkg.bin || {});
+  for (const entry of bins) {
+    const target = path.resolve(stage, entry);
+    if (!target.startsWith(stage + path.sep)) throw Error(`Invalid binary target: ${entry}`);
+    chmodSync(target, 0o755);
+  }
+  const packed = JSON.parse(run('npm', ['pack', '--ignore-scripts', '--json', '--pack-destination', output], stage))[0];
+  const bytes = readFileSync(path.join(output, packed.filename));
+  mkdirSync(destination, { recursive: true });
+  const target = path.join(destination, packed.filename);
+  if (existsSync(target)) {
+    if (!readFileSync(target).equals(bytes)) throw Error(`Archive is immutable: ${target}. Bump the version before changing its contents.`);
+  } else writeFileSync(target, bytes, { flag: 'wx' });
+  console.log(JSON.stringify({ ...packed, archive: target, sourcePrivate: true, registryDependencies: pkg.dependencies || {} }, null, 2));
+} finally {
+  rmSync(stage, { recursive: true, force: true });
+  rmSync(output, { recursive: true, force: true });
+}

package/scripts/publish-reviewed.mjs

@@ -0,0 +1,72 @@
+// Generated from knightseye-net/tools/release-tooling; edit the canonical template and sync.
+import { assertReleaseTooling } from './check-release-tooling.mjs';
+import { readFileSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
+
+export function npmFailure(result) {
+  let error;
+  for (const output of [result.stdout, result.stderr]) {
+    try { const parsed = JSON.parse(output || '{}'); error ||= parsed.error; } catch {}
+  }
+  const allowed = new Set(['EOTP', 'E401', 'E403', 'E404', 'E409', 'E422', 'E429', 'E500', 'E502', 'E503', 'E504', 'EPROVENANCE', 'EUSAGE', 'ENEEDAUTH', 'ENOTP', 'EPRIVATE', 'EPUBLISHCONFLICT', 'EUNSCOPED', 'ECONNRESET', 'ETIMEDOUT', 'ENOTFOUND']);
+  const candidate = typeof error?.code === 'string' ? error.code : (result.stderr || '').match(/^npm (?:error|ERR!) code ([A-Z][A-Z0-9]+)\s*$/m)?.[1];
+  const code = allowed.has(candidate) ? candidate : 'UNKNOWN';
+  const rawStatus = error?.statusCode ?? error?.status ?? (/^E[45]\d\d$/.test(code) ? Number(code.slice(1)) : undefined);
+  const httpStatus = Number.isInteger(rawStatus) && rawStatus >= 400 && rawStatus <= 599 ? rawStatus : 'unknown';
+  const exitStatus = Number.isInteger(result.status) && result.status >= 0 && result.status <= 255 ? result.status : 'unknown';
+  return {code, httpStatus, exitStatus};
+}
+export function publishReviewed({root, version, sha256, env = process.env, run = spawnSync, wait = () => Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 2000)}) {
+  if (env.GITHUB_ACTIONS !== 'true' || env.GITHUB_EVENT_NAME !== 'workflow_dispatch' || env.GITHUB_REF !== 'refs/heads/dev') throw Error('Publishing requires manual GitHub Actions dispatch on dev');
+  if (env.GITHUB_REPOSITORY_VISIBILITY !== 'public') throw Error('Provenance publishing requires a public GitHub repository');
+  if (!env.NODE_AUTH_TOKEN?.trim()) throw Error('Missing NODE_AUTH_TOKEN; publication has no authentication fallback');
+  if (!/^\d+\.\d+\.\d+(?:-[\w.-]+)?$/.test(version || '') || !/^[a-f0-9]{64}$/.test(sha256 || '')) throw Error('Expected reviewed exact version and SHA-256');
+  const source = JSON.parse(readFileSync(path.join(root, 'package.json'), 'utf8'));
+  if (source.version !== version) throw Error('Reviewed version does not match source version');
+  const archive = path.join(root, 'artifacts', `${source.name.replace(/^@/, '').replace('/', '-')}-${version}.tgz`);
+  const bytes = readFileSync(archive);
+  if (createHash('sha256').update(bytes).digest('hex') !== sha256) throw Error('Reviewed archive SHA-256 mismatch');
+  const options = { cwd: root, encoding: 'utf8', env };
+  const metadataResult = run('tar', ['-xOf', archive, 'package/package.json'], options);
+  if (metadataResult.status !== 0) throw Error(metadataResult.stderr || 'Archive inspection failed');
+  const pkg = JSON.parse(metadataResult.stdout);
+  if (pkg.name !== source.name || pkg.version !== version || pkg.private || pkg.publishConfig?.access !== 'public' || pkg.publishConfig?.registry !== 'https://registry.npmjs.org/' || pkg.publishConfig?.tag !== 'next') throw Error('Expected reviewed staged registry candidate');
+  const integrity = 'sha512-' + createHash('sha512').update(bytes).digest('base64');
+  const lookupArgs = ['view', `${pkg.name}@${version}`, '--json', '--registry', 'https://registry.npmjs.org/'];
+  const lookupOptions = { ...options, timeout: 15000 };
+  const lookup = run('npm', lookupArgs, lookupOptions);
+  if (lookup.status === 0) {
+    const existing = JSON.parse(lookup.stdout);
+    if (existing.name !== pkg.name || existing.version !== version || existing.dist?.integrity !== integrity) throw Error('Published version exists with different identity or integrity');
+    return { name: pkg.name, version, sha256, integrity, published: false, alreadyPublished: true, registryConfirmed: true };
+  }
+  let error;
+  try { error = JSON.parse(lookup.stdout || '{}').error; } catch {}
+  if (error?.code !== 'E404') throw Error('Registry lookup failed; refusing publication');
+  const result = run('npm', ['publish', archive, '--ignore-scripts', '--access', 'public', '--tag', 'next', '--registry', 'https://registry.npmjs.org/', '--provenance', '--json'], options);
+  if (result.status !== 0) {
+    const {code, httpStatus, exitStatus} = npmFailure(result);
+    throw Error(`npm publish failed for ${pkg.name}@${version}: code=${code}, httpStatus=${httpStatus}, exitStatus=${exitStatus}`);
+  }
+  let visible = false;
+  for (let attempt = 0; attempt < 3; attempt++) {
+    if (attempt) wait();
+    const confirmation = run('npm', lookupArgs, lookupOptions);
+    if (confirmation.status === 0) {
+      let existing;
+      try { existing = JSON.parse(confirmation.stdout); } catch {}
+      if (existing?.name !== pkg.name || existing?.version !== version || existing?.dist?.integrity !== integrity) throw Error('Postpublication registry identity or integrity mismatch');
+      visible = true;
+      break;
+    }
+  }
+  if (!visible) throw Error(`npm publication returned success but registry confirmation failed for ${pkg.name}@${version}; publication was not retried`);
+  return { name: pkg.name, version, sha256, integrity, published: true, alreadyPublished: false, registryConfirmed: true };
+}
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  assertReleaseTooling();
+  console.log(JSON.stringify(publishReviewed({root: fileURLToPath(new URL('../', import.meta.url)), version: process.argv[2], sha256: process.argv[3]})));
+}

package/scripts/release-tooling.json

@@ -0,0 +1,13 @@
+{
+  "schema": 1,
+  "canonical": "knightseye-net/tools/release-tooling",
+  "sha256": {
+    "scripts/pack.mjs": "334aa4041e59b14fd2b072969f50beea64449136f7f9146d63d7277fc2e4808a",
+    "scripts/publish-reviewed.mjs": "e9e8a6f5eeff37d5050b96e75fda2fa33084b1f9bc5d5a6688b0aef737dd51c5",
+    ".github/workflows/npm-publish.yml": "b25cec136db205d69a407284dae2bb66f3d56be13ed2a1367f0db167a232050d",
+    "scripts/verify-release.mjs": "d0f9baead779e553385bb7c26f1238ad4e60a189a818d4db4f721a1e5f88dedc",
+    "scripts/update-dependency.mjs": "9919f172be33973f124eabf56c1dc70e41e941e601783ef01aba1c47dd70db9d",
+    "scripts/check-release-tooling.mjs": "29563619bdc3e86ef10dec1e983274e36138193f04d33f2455501b59a4016e0d",
+    ".github/workflows/quality.yml": "a014920a9f89dc494a020bee5f69aec779cf58825f491690f9ed1ec089ed6fa0"
+  }
+}

package/scripts/update-dependency.mjs

@@ -0,0 +1,44 @@
+// Generated from knightseye-net/tools/release-tooling; edit the canonical template and sync.
+import { assertReleaseTooling } from './check-release-tooling.mjs';
+assertReleaseTooling();
+import {readFileSync,writeFileSync,mkdirSync,existsSync,copyFileSync} from 'node:fs';
+import {createHash} from 'node:crypto';
+import {spawnSync} from 'node:child_process';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+process.chdir(fileURLToPath(new URL('../', import.meta.url)));
+const [name,input,registryVersion]=process.argv.slice(2);
+const exact=/^\d+\.\d+\.\d+(?:-[\w.-]+)?$/;
+if(!name?.startsWith('@knights-eye-chess/')||!input)throw Error('Usage: node scripts/update-dependency.mjs @knights-eye-chess/name /absolute/package.tgz | --registry EXACT_VERSION | EXACT_VERSION');
+const pkg=JSON.parse(readFileSync('package.json','utf8'));
+if(!pkg.dependencies?.[name])throw Error('Not an existing package dependency');
+const version=input==='--registry'?registryVersion:exact.test(input)?input:null;
+if(input==='--registry'||version){
+  if(!exact.test(version||''))throw Error('Expected exact registry version');
+  const probe=spawnSync('npm',['view',`${name}@${version}`,'--json','--registry','https://registry.npmjs.org/'],{encoding:'utf8'});
+  if(probe.status!==0)throw Error(probe.stderr||'Registry lookup failed');
+  const metadata=JSON.parse(probe.stdout);
+  if(metadata.name!==name||metadata.version!==version)throw Error('Registry identity/version mismatch');
+  pkg.dependencies[name]=version;
+  const release=JSON.parse(readFileSync('npm-release.json','utf8'));
+  release.registryDependencies ||= {};
+  release.registryDependencies[name]=version;
+  writeFileSync('npm-release.json',JSON.stringify(release,null,2)+'\n');
+  writeFileSync('package.json',JSON.stringify(pkg,null,2)+'\n');
+  const lock=spawnSync('npm',['install','--package-lock-only','--ignore-scripts','--registry','https://registry.npmjs.org/'],{stdio:'inherit'});
+  if(lock.status!==0)process.exit(lock.status||1);
+  console.log(JSON.stringify({name,version,registry:'https://registry.npmjs.org/'}));
+}else{
+  const archive=path.resolve(input);
+  const probe=spawnSync('tar',['-xOf',archive,'package/package.json'],{encoding:'utf8'});
+  if(probe.status!==0)throw Error(probe.stderr);
+  const metadata=JSON.parse(probe.stdout);
+  if(!exact.test(metadata.version||'')||metadata.name!==name||(metadata.private!==true && !(metadata.publishConfig?.registry==='https://registry.npmjs.org/' && metadata.publishConfig?.access==='public' && metadata.publishConfig?.tag==='next')))throw Error('Expected matching private preview or registry candidate');
+  const file=path.basename(archive),destination='vendor/npm/'+file;
+  const bytes=readFileSync(archive),sha256=createHash('sha256').update(bytes).digest('hex');
+  mkdirSync('vendor/npm',{recursive:true});
+  if(existsSync(destination)&&createHash('sha256').update(readFileSync(destination)).digest('hex')!==sha256)throw Error('Refusing to overwrite a different immutable archive');
+  copyFileSync(archive,destination);pkg.dependencies[name]='file:'+destination;writeFileSync('package.json',JSON.stringify(pkg,null,2)+'\n');
+  const lock=spawnSync('npm',['install','--package-lock-only','--ignore-scripts'],{stdio:'inherit'});if(lock.status!==0)process.exit(lock.status||1);
+  console.log(JSON.stringify({name,version:metadata.version,archive:destination,sha256}));
+}

package/scripts/verify-release.mjs

@@ -0,0 +1,52 @@
+// Generated from knightseye-net/tools/release-tooling; edit the canonical template and sync.
+import { assertReleaseTooling } from './check-release-tooling.mjs';
+assertReleaseTooling();
+import { readFileSync, mkdtempSync, rmSync, existsSync, readdirSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
+import os from 'node:os';
+
+const root = fileURLToPath(new URL('../', import.meta.url));
+const source = JSON.parse(readFileSync(path.join(root, 'package.json'), 'utf8'));
+const name = source.name.replace(/^@/, '').replace('/', '-');
+const archive = path.resolve(process.argv[2] || path.join(root, 'artifacts', `${name}-${source.version}.tgz`));
+const stage = mkdtempSync(path.join(os.tmpdir(), 'knights-eye-verify-'));
+function run(command, args) {
+  const result = spawnSync(command, args, { cwd: root, encoding: 'utf8' });
+  if (result.status !== 0) throw Error(result.stderr || result.stdout || `${command} failed`);
+  return result.stdout;
+}
+function requirePath(relative) {
+  if (!relative.startsWith('./') || relative.includes('..')) throw Error(`Invalid package target: ${relative}`);
+  const target = path.join(stage, 'package', relative);
+  if (relative.includes('*')) {
+    const directory = path.dirname(target);
+    if (!existsSync(directory) || !readdirSync(directory).length) throw Error(`Missing exported assets: ${relative}`);
+  } else if (!existsSync(target)) throw Error(`Missing package target: ${relative}`);
+}
+try {
+  run('tar', ['-xzf', archive, '-C', stage]);
+  const pkg = JSON.parse(readFileSync(path.join(stage, 'package/package.json'), 'utf8'));
+  if (pkg.name !== source.name || pkg.version !== source.version || pkg.private) throw Error('Unexpected identity or private package');
+  if (pkg.publishConfig?.access !== 'public' || pkg.publishConfig.registry !== 'https://registry.npmjs.org/' || pkg.publishConfig.tag !== 'next') throw Error('Expected public npm prerelease settings');
+  if (existsSync(path.join(stage, 'package/npm-shrinkwrap.json')) || existsSync(path.join(stage, 'package/vendor'))) throw Error('Source-only dependency pins leaked into the consumer package');
+  for (const section of ['dependencies', 'optionalDependencies', 'peerDependencies', 'devDependencies']) {
+    for (const [dependency, version] of Object.entries(pkg[section] || {})) {
+      if (/^(file:|link:|workspace:|https?:|git)/.test(version)) throw Error(`Non-registry dependency: ${dependency}`);
+    }
+  }
+  for (const [subpath, entry] of Object.entries(pkg.exports || {})) {
+    if (typeof entry === 'string') requirePath(entry);
+    else {
+      if (!entry.types || !entry.import) throw Error(`Missing runtime/types export: ${subpath}`);
+      requirePath(entry.types); requirePath(entry.import);
+    }
+  }
+  for (const entry of Object.values(pkg.bin || {})) requirePath('./' + entry.replace(/^\.\//, ''));
+  for (const file of ['LICENSE', 'NOTICE', 'LICENSING.md', 'THIRD_PARTY_NOTICES.md', 'SOURCE-ORIGIN.json', 'NPM-PUBLISHING.md']) requirePath('./' + file);
+  const dryRun = JSON.parse(run('npm', ['publish', archive, '--dry-run', '--ignore-scripts', '--access', 'public', '--tag', 'next', '--registry', 'https://registry.npmjs.org/', '--json']));
+  console.log(JSON.stringify({ package: pkg.name, version: pkg.version, archive, registryDependencies: pkg.dependencies || {}, files: dryRun.files?.length, dryRun: true, registryWrite: false }, null, 2));
+} finally {
+  rmSync(stage, { recursive: true, force: true });
+}

package/src/ai-request-failure.ts

@@ -0,0 +1,34 @@
+/** Public finite error vocabulary. Never copy arbitrary provider text or transport bodies. */
+export type AiFailureDetails = { code: string; status?: number; retryAfterSeconds?: number; providerDispatched?: boolean; requestId?: string; providerRequestId?: string; stage: string; reportable: boolean };
+const known = new Set(['insufficient_credits','invalid_key','rate_limited','model_unavailable','provider_unavailable','free_unavailable','free_funds_exhausted','ai_request_active','ai_hourly_limit','ai_admission_busy','sign_in_required','forbidden','connection_changed','cancelled','request_too_large','request_timeout','network_error','response_invalid','unknown_error','tool_evidence_contract_failed','output_truncated','empty_answer','no_final_answer','context_byte_budget']);
+const expected = new Set(['insufficient_credits','invalid_key','rate_limited','model_unavailable','free_unavailable','free_funds_exhausted','ai_hourly_limit','sign_in_required','forbidden','connection_changed','cancelled']);
+export function aiFailureDetails(code: string, fields: Partial<AiFailureDetails> = {}): AiFailureDetails {
+  code = known.has(code) ? code : 'unknown_error';
+  return { ...fields, code, stage: fields.stage || 'simple-model', reportable: !expected.has(code) };
+}
+export function aiFailureMessage(f: AiFailureDetails, reported = false): string {
+  const minutes = Math.max(1, Math.ceil((f.retryAfterSeconds ?? 0) / 60));
+  const wait = f.retryAfterSeconds ? ` Please try again in about ${minutes} ${minutes === 1 ? 'minute' : 'minutes'}.` : ' Please wait a moment and try again.';
+  switch(f.code) {
+    case 'ai_request_active': return 'Your previous AI request is still processing or being released after it stopped.' + wait;
+    case 'ai_hourly_limit': return 'The hourly AI allowance has been reached.' + wait;
+    case 'rate_limited': return 'Your AI provider is temporarily limiting requests.' + wait;
+    case 'insufficient_credits': return 'Your AI account has insufficient credits or reached its spending limit. Add credits or adjust the limit, then try again.';
+    case 'invalid_key': case 'connection_changed': return 'Your AI connection needs attention. Open your profile and reconnect your AI account.';
+    case 'sign_in_required': return 'Your session has expired. Please sign in again to ask a question.';
+    case 'forbidden': return 'You cannot ask questions about this game with the current account. Sign in to the owning account or create your own copy.';
+    case 'model_unavailable': return 'The selected model is unavailable. Check your AI connection in your profile or try again later.';
+    case 'free_unavailable': case 'free_funds_exhausted': return 'Free AI is temporarily unavailable. Connect your own AI account in your profile, or try again later.';
+    case 'cancelled': return 'The request was cancelled.';
+    case 'network_error': return 'We could not reach the AI service. Check your internet connection and try again.';
+    case 'request_timeout': return 'The AI request took too long. Please try again later. The provider may have charged for this attempt.';
+    case 'request_too_large': case 'context_byte_budget': return 'This question and its context are too large to send. Try a shorter question or start a new chat.';
+    default: return reported ? "Something went wrong. We've received an automatic report and will look into it. Please try again." : 'Something went wrong. Please try again. You can also report this problem to us.';
+  }
+}
+export function failureFromError(error: unknown, code = 'unknown_error'): AiFailureDetails {
+  const e = error as { details?: AiFailureDetails; name?: string } | null;
+  if(e?.details) return e.details;
+  if(e?.name === 'AbortError') return aiFailureDetails('cancelled');
+  return aiFailureDetails(code);
+}

package/src/ai-request-limits.ts

@@ -0,0 +1,4 @@
+/** Byte safety ceilings, not token estimates. Wire encoding, server policy and
+ * opaque provider continuation require headroom beyond model evidence JSON. */
+export const AI_MODEL_CONTEXT_MAX_BYTES = 1_000_000;
+export const AI_RELAY_MAX_REQUEST_BYTES = 2_000_000;

package/src/ai-routing-diagnostics.ts

@@ -0,0 +1,33 @@
+/** Public, bounded routing facts only. Never provider text, headers or credentials. */
+export const AI_ROUTING_HEADER = 'x-knights-eye-ai-routing';
+export type AiRoutingDiagnostics = {
+  requestedTier: 'flex' | 'default' | 'priority' | null;
+  actualTier: 'flex' | 'default' | 'priority' | null;
+  reason: 'flex_available' | 'cooldown_active' | 'storage_unavailable' | 'unsupported' | 'user_disabled' | 'user_standard' | 'user_fast';
+  elapsedMs: number;
+  slowThresholdMs: number;
+  timingEligible?: boolean;
+  cooldownUntil: number | null;
+  cooldownTriggered: boolean;
+  persistenceError?: boolean;
+};
+export function readAiRoutingDiagnostics(headers?: Headers | Record<string, string>): AiRoutingDiagnostics | undefined {
+  try {
+    const raw = headers instanceof Headers ? headers.get(AI_ROUTING_HEADER) : headers?.[AI_ROUTING_HEADER];
+    if (!raw || raw.length > 2048) return undefined;
+    const value = JSON.parse(raw);
+    if (!value || ![null,'flex','default','priority'].includes(value.requestedTier)
+      || ![null,'flex','default','priority'].includes(value.actualTier)
+      || !['flex_available','cooldown_active','storage_unavailable','unsupported','user_disabled','user_standard','user_fast'].includes(value.reason)
+      || !Number.isFinite(value.elapsedMs) || value.elapsedMs < 0
+      || !Number.isFinite(value.slowThresholdMs) || value.slowThresholdMs <= 0
+      || (value.cooldownUntil !== null && (!Number.isSafeInteger(value.cooldownUntil) || value.cooldownUntil < 0))
+      || typeof value.cooldownTriggered !== 'boolean'
+      || (value.timingEligible !== undefined && typeof value.timingEligible !== 'boolean')) return undefined;
+    return {requestedTier:value.requestedTier,actualTier:value.actualTier,reason:value.reason,
+      elapsedMs:value.elapsedMs,slowThresholdMs:value.slowThresholdMs,cooldownUntil:value.cooldownUntil,
+      cooldownTriggered:value.cooldownTriggered,
+      ...(typeof value.timingEligible === 'boolean' ? {timingEligible:value.timingEligible} : {}),
+      ...(value.persistenceError === true ? {persistenceError:true} : {})};
+  } catch { return undefined; }
+}