@volter/twin-standard 1.0.148 → 1.0.150

package/src/tools/score-pack.ts

@@ -0,0 +1,244 @@
+#!/usr/bin/env bun
+// score-pack — a Protocol 3 pack's report (docs/contributing/architecture.md, "Protocol 3", Scoring). One customer
+// life per pack is walked through the pack's own fetch on the in-memory World, and the report says:
+//   - the life: whether a judge's plausible verdict names its current content (a verdict its author wrote is not one);
+//   - correctness: every check on every step (status, expectations, captures, SHAPE, the beats) and the life
+//     answering byte for byte the same on a second fresh World;
+//   - coverage: the hand-written code the life and the vendor's published examples run and the declared state logic
+//     they reach (life-coverage.ts), with what they never reach;
+//   - the vendor's published examples: replayed and judged (vendor-examples.ts);
+//   - breadth: the spec's operations (a line protocol's commands) by what serves them (a handler, the generated
+//     core, a legacy fallback, nothing).
+// This is source-journey evidence, not installed readiness or pack completion. pack-done owns completion and consumes
+// this report alongside the exact artifact's installed customer assessment in the one final run.
+//
+// Usage: twin-standard walk <vendor> [--write] [--report <path>]   (from the pack repository's root; twin-world's
+//        bun scripts/score-pack.ts <vendor> runs the same)
+//   --write keeps journeys/score.json and journeys/coverage.json; --report writes the report and what it lacks for done
+//   to <path> as JSON and changes nothing in the checkout
+
+import { parseExactJson } from '@volter/world-core/exact-json';
+import { notIndependent } from '../verdict.ts';
+import { spawnSync } from 'node:child_process';
+import { existsSync, mkdtempSync, readFileSync, realpathSync, writeFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { tmpdir } from 'node:os';
+import { dirname, join, sep } from 'node:path';
+import { inMemoryWorld, walk, withPinnedWorldDraws, type Failure, usePacks } from '../walk/behavior-journey.ts';
+import { expandFills, waitMs, type Journey } from '../walk/journey-kit.ts';
+import { vendorFetch, vendorStream } from '../walk/vendor-fetch.ts';
+import { existenceProbe } from '../walk/journey-kit.ts';
+import { kernelCheckout, packsRoot, toolPath } from './packs-root.ts';
+const PACKS = packsRoot();
+usePacks(PACKS);
+
+const vendor = process.argv[2];
+if (!vendor || vendor.startsWith('-')) { console.error('usage: twin-standard walk <vendor> [--write] [--report <path>]   (from the pack repository\'s root)'); process.exit(1); }
+// The surface measured: the kernel the pack repository resolves, named in the report. twin-world's own scripts require
+// it to be their checkout's (linked in development, decision 0029): a pack repository whose node_modules resolves
+// @volter/* into another checkout scores the pack against someone else's kernel, no measurement of this one.
+const kernel = ((): string => {
+  try { return realpathSync(join(PACKS, 'node_modules', '@volter', 'world-core')); } catch { /* resolved through a parent's node_modules */ }
+  try {
+    let at = dirname(realpathSync(createRequire(join(PACKS, 'package.json')).resolve('@volter/world-core')));
+    while (!existsSync(join(at, 'package.json')) && dirname(at) !== at) at = dirname(at);
+    return at;
+  } catch { return '(unresolved)'; }
+})();
+const checkout = kernelCheckout();
+if (checkout && !kernel.startsWith(realpathSync(checkout) + sep)) { // the platform's separator: '/' never prefixes a Windows path
+  console.error(`score-pack: @volter/world-core resolves to ${kernel}, outside this checkout (${realpathSync(checkout)}); link the pack repository's node_modules/@volter/* to this checkout's packages before scoring`);
+  process.exit(2);
+}
+const PKG = join(PACKS, vendor);
+const lifePath = join(PKG, 'journeys', 'customer-life.json');
+if (!existsSync(lifePath)) { console.error(`${vendor}: no journeys/customer-life.json`); process.exit(1); }
+
+// ── the life and its verdict ─────────────────────────────────────────────────────────────────
+const text = readFileSync(lifePath, 'utf8');
+// its fills written out once, so the steps the walk hands back are the life's own (a sitting is found by position)
+const life = expandFills(parseExactJson(text) as Journey);
+const verdictPath = join(PKG, 'journeys', 'customer-life.verdict.json');
+const verdict = existsSync(verdictPath) ? (parseExactJson(readFileSync(verdictPath, 'utf8')) as { sha256?: string; plausible?: boolean; judge?: { session?: string; name?: string; agent?: string }; authors?: string[] } ) : undefined;
+// A verdict is a judge's in another session: one its author wrote (marked self-judged) rules nothing, however it reads.
+// The dispatcher stamps the judge’s author name (`judge.agent`) and every author of the life
+// (`authors`) consistently when it commits the verdict; a verdict without them,
+// or whose judge is among the authors, is not independent.
+// one judging per pack: the verdict stands, and the life's changes since (its rulings applied, a review's fixes, steps for
+// coverage) keep it (architecture, "Writing a life", Judge)
+const dependent = verdict ? notIndependent(verdict, life.author) : undefined;
+const judged = life.steps.length === 0 || !verdict ? 'unjudged' : dependent ? dependent : verdict.plausible ? 'plausible' : 'rejected';
+
+// ── correctness ──────────────────────────────────────────────────────────────────────────────
+const world = inMemoryWorld(`score-${vendor}`);
+const failures: Failure[] = [];
+await walk(life, world.root(), failures, { beats: true });
+const answers = async (): Promise<string[]> => {
+  const seen: string[] = [];
+  // the World's own draws (its seed, its keys) are the same in both: two Worlds differ only by what is beyond them (R9)
+  await withPinnedWorldDraws(() => walk(life, world.root(), [], { beats: false, hooks: { after: (step, p, a) => seen.push(`${(step as { name?: string }).name ?? ''}\u0000${p} ${a.status} ${JSON.stringify(a.body)}`) } }));
+  return seen;
+};
+const [first, second] = [await answers(), await answers()];
+
+// ── what a judge rejects on sight ────────────────────────────────────────────────────────────
+// The patterns independent judges rejected every self-judged life for (the Journeys section): a failing repeat of a
+// request that succeeded earlier in the same sitting, three or more refusals in a row, and a resource written A → B → A
+// or made and removed in one sitting. A sitting is the steps between two `wait` steps. These are flags for the author
+// and the judge, not failed checks: the judge rules, and a flag the story gives a shown cause may stand.
+type Flag = { step: string; pattern: 'REPEAT' | 'RUN' | 'TOGGLE' | 'TIME' | 'CRED'; detail: string };
+const flags: Flag[] = [];
+// CRED: a life where steps act with different credentials carries no life-wide default one; a default leaks one actor's
+// credential into every step that forgot its own (a judge found octocat's token on a server's call).
+{
+  const auth = (h?: Record<string, string>) => Object.entries(h ?? {}).find(([k]) => k.toLowerCase() === 'authorization')?.[1];
+  const own = new Set(life.steps.flatMap((st) => { const a = auth((st as { headers?: Record<string, string> }).headers); return a ? [a] : []; }));
+  const fallback = auth((life as { headers?: Record<string, string> }).headers);
+  if (fallback && own.size > 0) {
+    const leaning = life.steps.filter((st) => 'method' in st && !auth((st as { headers?: Record<string, string> }).headers));
+    if (leaning.length) flags.push({ step: (leaning[0] as { name: string }).name, pattern: 'CRED', detail: `${leaning.length} steps act with the life-wide default credential in a life of ${own.size + 1} credentials; give each its actor's own` });
+  }
+}
+{
+  const walked: Array<{ index: number; name: string; key: string; path: string; method: string; body: string; refused: boolean; status: number }> = [];
+  const refusedAnswer = (a: { status: number; body: unknown }): boolean => {
+    const b = a.body as Record<string, unknown> | null;
+    return a.status >= 400 || (!!b && typeof b === 'object' && (b.ok === false || (Array.isArray(b.errors) && b.errors.length > 0 && b.data === undefined) || typeof b.error === 'string'));
+  };
+  // CRED too: a credential a person was shown once (a key on a dashboard, a token in a mail) is read off what showed it
+  // (a capture), never typed in: a literal equal to what an earlier answer showed means the life knows how the twin mints it
+  const shown = new Set<string>();
+  let literalFlags = 0;
+  await walk(life, inMemoryWorld(`flags-${vendor}`).root(), [], { beats: false, hooks: { after: (step, path, answer) => {
+    const s = step as { name: string; connection?: string; resp?: unknown; method?: string; git?: string; on?: string; send?: unknown; body?: unknown; ref?: string; delete?: boolean; headers?: Record<string, string>; socket?: string; open?: string; close?: boolean; mysql?: string; values?: unknown; link?: string; signIn?: { user: string } };
+    for (const [k, v] of Object.entries(s.headers ?? {})) {
+      if (!/^(authorization|x-api-key|api-key|cookie)$/i.test(k) || v.includes('{')) continue;
+      const secret = v.replace(/^(bearer|token|basic)\s+/i, '').replace(/^[a-z_]+=/i, '');
+      if (secret.length >= 16 && shown.has(secret) && literalFlags++ < 3) flags.push({ step: s.name, pattern: 'CRED', detail: `sends as a literal the credential an earlier answer showed (${secret.slice(0, 12)}…): capture it where it was shown` });
+    }
+    const text = typeof answer.body === 'string' ? answer.body : JSON.stringify(answer.body ?? '');
+    // a token ends before trailing punctuation (a key closing a sentence); a JWT's inner dots stay
+    for (const t of text.match(/[A-Za-z0-9_-]+(?:\.[A-Za-z0-9_-]+)*/g) ?? []) if (t.length >= 16) shown.add(t);
+    const method = s.method ?? (s.mysql !== undefined || s.signIn ? `MySQL ${s.link ?? 'mysql'}` : s.connection ? `RESP ${s.connection}` : s.socket ? `socket ${s.open ? 'open' : s.close ? 'close' : 'send'}` : s.git ? `git ${s.git}${s.delete ? ' delete' : ''}` : `line ${s.on}`);
+    const body = JSON.stringify(s.mysql !== undefined || s.signIn ? { mysql: s.mysql ?? null, values: s.values ?? null, signIn: s.signIn?.user ?? null } : s.resp ?? s.body ?? s.send ?? (s.ref ? { ref: s.ref } : null));
+    // an operation named in a header (AWS's X-Amz-Target) is part of what the request is; who sends it is not
+    const named = Object.entries(s.headers ?? {}).filter(([k]) => !/^(authorization|stripe-account|x-slack-|cookie)/i.test(k)).sort().map(([k, v]) => `${k}=${v}`).join('&');
+    // and so is the region an AWS request is signed for (its credential scope), which says where it goes
+    const region = /Credential=[^/]+\/\d{8}\/([a-z0-9-]+)\//.exec((s.headers ?? {}).authorization ?? (life.headers ?? {}).authorization ?? '')?.[1];
+    const where = named || region ? `${path} [${[named, region ? `region=${region}` : ''].filter(Boolean).join('&')}]` : path;
+    walked.push({ index: life.steps.indexOf(step as never), name: s.name, key: `${method} ${where} ${body}`, path: where, method, body, refused: s.socket ? (answer.status !== 101 && answer.status !== 1000) : refusedAnswer(answer), status: answer.status });
+  } } });
+  const sitting = (i: number): number => life.steps.slice(0, i).filter((x) => 'wait' in x).length;
+  // a client asking whether something exists before it makes it is not a refusal (existenceProbe, journey-kit)
+  const probe = (n: number): boolean => existenceProbe(walked.map((w) => ({ ...w, sitting: sitting(w.index) })), n);
+  let run: typeof walked = [];
+  const endRun = () => { if (run.length >= 3) flags.push({ step: run[0]!.name, pattern: 'RUN', detail: `${run.length} refusals in a row, from "${run[0]!.name.slice(0, 50)}" to "${run.at(-1)!.name.slice(0, 50)}"` }); run = []; };
+  walked.forEach((w, n) => {
+    if (w.refused && !probe(n)) run.push(w); else if (!w.refused) endRun();
+    const earlier = walked.slice(0, n).filter((e) => sitting(e.index) === sitting(w.index));
+    if (w.refused && earlier.some((e) => !e.refused && e.key === w.key)) flags.push({ step: w.name, pattern: 'REPEAT', detail: `repeats a request that succeeded earlier in the sitting (${w.method} ${w.path.slice(0, 60)})` });
+    if (!w.refused && /^(POST|PUT|PATCH)$/.test(w.method)) {
+      const writes = earlier.filter((e) => !e.refused && e.method === w.method && e.path === w.path);
+      if (writes.length >= 2 && writes.at(-2)!.body === w.body && writes.at(-1)!.body !== w.body) flags.push({ step: w.name, pattern: 'TOGGLE', detail: `writes ${w.path.slice(0, 60)} back to what it was two writes before, in one sitting` });
+    }
+    if (!w.refused && w.method === 'DELETE' && earlier.some((e) => !e.refused && (e.method === 'PUT' || e.method === 'POST') && e.path === w.path)) flags.push({ step: w.name, pattern: 'TOGGLE', detail: `removes ${w.path.slice(0, 60)}, made earlier in the same sitting` });
+  });
+  endRun();
+  // a time of day a step names that its hour on the World clock contradicts (the clock starts at startsAt or the default and
+  // moves only by `wait` steps; a wait's name tells what happens once it has passed)
+  const hours: Array<[RegExp, number, number]> = [[/\bmorning\b/i, 5, 12], [/\blunch\b/i, 11, 15], [/\bafternoon\b/i, 12, 18], [/\bevening\b/i, 17, 23]];
+  const WEEKDAYS = ['sunday', 'monday', 'tuesday', 'wednesday', 'thursday', 'friday', 'saturday'];
+  const MONTHS = ['january', 'february', 'march', 'april', 'may', 'june', 'july', 'august', 'september', 'october', 'november', 'december'];
+  const DATED = /\b(Monday|Tuesday|Wednesday|Thursday|Friday|Saturday|Sunday),? (\d{1,2}) (January|February|March|April|May|June|July|August|September|October|November|December)(?:,? (\d{4}))?/g;
+  let clock = Date.parse(life.startsAt ?? '2026-01-01T00:00:00Z');
+  for (const step of life.steps) {
+    if ('wait' in step) clock += waitMs(step.wait);
+    const hour = new Date(clock).getUTCHours();
+    for (const [word, from, to] of hours) {
+      if (word.test(step.name) && (hour < from || hour >= to)) flags.push({ step: step.name, pattern: 'TIME', detail: `says ${word.source.replace(/\\b/g, '')} at ${String(hour).padStart(2, '0')}:00 on the World clock` });
+    }
+    // a weekday named with its date is a fact of the calendar, and a wait's name says the date the clock reaches
+    for (const m of step.name.matchAll(DATED)) {
+      const [, weekday, day, month, year] = m;
+      const at = new Date(Date.UTC(year ? Number(year) : new Date(clock).getUTCFullYear(), MONTHS.indexOf(month!.toLowerCase()), Number(day)));
+      if (WEEKDAYS[at.getUTCDay()] !== weekday!.toLowerCase()) flags.push({ step: step.name, pattern: 'TIME', detail: `says ${weekday} ${day} ${month}, which is a ${WEEKDAYS[at.getUTCDay()]}` });
+      else if ('wait' in step && at.toISOString().slice(0, 10) !== new Date(clock).toISOString().slice(0, 10)) flags.push({ step: step.name, pattern: 'TIME', detail: `its wait reaches ${new Date(clock).toISOString().slice(0, 10)}, not ${weekday} ${day} ${month}` });
+    }
+  }
+}
+const differs = first.findIndex((line, i) => line !== second[i]);
+if (differs >= 0 || first.length !== second.length) failures.push({ step: '(whole life)', beat: 'REPLAYABLE', detail: `a second fresh World answered differently at "${(first[differs] ?? second[differs] ?? first.at(-1) ?? '').split('\u0000')[0]}" (the ${differs + 1}th answered step; waits are not counted)` });
+
+// ── breadth ──────────────────────────────────────────────────────────────────────────────────
+const factory = await vendorFetch(PACKS, vendor);
+const fetch = factory?.(world.root()) as ((r: Request) => Promise<Response>) & { owners?: () => Record<string, string> } | undefined;
+// a line protocol's commands are served on its stream
+const stream = (await vendorStream(PACKS, vendor))?.(world.root()) as { owners?: () => Record<string, string> } | undefined;
+const owners = fetch?.owners?.() ?? stream?.owners?.() ?? {};
+world.restore();
+const breadth: Record<string, number> = {};
+for (const o of Object.values(owners)) breadth[o] = (breadth[o] ?? 0) + 1;
+const operations = Object.keys(owners).length;
+
+// ── coverage ─────────────────────────────────────────────────────────────────────────────────
+// the measurement is kept (journeys/coverage.json) only with --write; a plain run leaves the checkout as it found it
+const keep = process.argv.includes('--write');
+const coveragePath = keep ? join(PKG, 'journeys', 'coverage.json') : join(mkdtempSync(join(tmpdir(), 'score-coverage-')), 'coverage.json');
+// each tool in a process of its own, run from the pack repository, naming it as this one does
+const tool = (name: string, args: string[]) => spawnSync(process.execPath, [toolPath('run-tool'), PACKS, checkout ?? '', toolPath(name), ...args], { cwd: PACKS, stdio: ['ignore', 'pipe', 'pipe'] });
+const measured = tool('life-coverage', [vendor, ...(keep ? ['--write'] : ['--out', coveragePath])]);
+// a measurement that failed reports so, never the last one it kept
+const coverage = measured.status === 0 && existsSync(coveragePath) ? (parseExactJson(readFileSync(coveragePath, 'utf8')) as { missing: number; code: { lines: number; run: number; recorded: number; missing: number }; state: { declared: number; reached: number; recorded: number; missing: string[]; undeclared: string[] } }) : undefined;
+
+// ── the vendor's published examples (vendor-examples.ts) ────────────────────────────────────────
+const replay = tool('vendor-examples', [vendor]);
+const replayOut = String(replay.stdout).trim().split('\n');
+const replayLine = replayOut.at(-1) ?? '';
+// replayed and judged are two lacks: the replay is the twin's, the verdict a judge's (pack-done's (d) and (f))
+const examples = {
+  done: replay.status === 0,
+  replayed: replayOut.some((l) => l.trim() === 'replayed: yes'),
+  verdict: replayOut.find((l) => l.trim().startsWith('verdict: '))?.trim().slice('verdict: '.length) ?? 'not measured',
+  failures: replayOut.filter((line) => /^\s*(?:FAIL|GAP)\s/.test(line)).map((line) => line.trim()),
+  line: replayLine.replace(/^\S+\s+/, ''),
+};
+
+const pct = (hit: number, found: number): string => (found ? `${((hit / found) * 100).toFixed(1)}%` : 'n/a');
+const score = {
+  scope: 'source-customer-life-and-published-examples',
+  vendor,
+  life: { steps: life.steps.length, verdict: judged, judge: verdict?.judge?.agent ?? verdict?.judge?.name ?? null, authors: verdict?.authors ?? [] },
+  failures: failures.map((f) => ({ step: f.step, beat: f.beat, detail: f.detail })),
+  flags,
+  coverage: coverage ?? null,
+  examples,
+  breadth: { operations, ...breadth },
+};
+console.log(`  measured through: ${kernel}`);
+console.log(`${vendor}: life of ${life.steps.length} steps, ${judged}; ${failures.length} checks failing`);
+if (!coverage) console.log(`  coverage: NOT MEASURED — life-coverage failed: ${String(measured.stderr).trim().split('\n').slice(-3).join(' ')}`);
+if (coverage) console.log(`  coverage: ${coverage.missing === 0 ? 'meets the standard' : `${coverage.missing} missing`} — hand-written lines ${pct(coverage.code.run, coverage.code.lines)} run, ${coverage.code.recorded} recorded unreachable, ${coverage.code.missing} missing; state logic ${coverage.state.reached}/${coverage.state.declared} reached, ${coverage.state.recorded} recorded, ${coverage.state.missing.length} missing, ${coverage.state.undeclared.length} undeclared moves`);
+console.log(`  ${examples.line || 'examples: not measured'}`);
+console.log(`  breadth: ${operations} spec operations — ${Object.entries(breadth).map(([k, n]) => `${n} ${k}`).join(', ')}`);
+for (const f of failures.slice(0, 20)) console.log(`  FAIL ${f.beat} ${f.step.slice(0, 60)}: ${f.detail.slice(0, 140)}`);
+console.log(`  judge flags: ${flags.length ? `${flags.length} (${(['REPEAT', 'RUN', 'TOGGLE', 'TIME', 'CRED'] as const).map((p) => `${flags.filter((f) => f.pattern === p).length} ${p}`).join(', ')}) — what judges reject on sight; resolve each or give it a cause the story shows` : 'none'}`);
+for (const f of flags.slice(0, 30)) console.log(`  FLAG ${f.pattern} ${f.step.slice(0, 60)}: ${f.detail}`);
+// Source requirements used by pack-done's report step; keep the field name for existing report consumers.
+const missingForDone = [
+  judged !== 'plausible' ? `a plausible verdict from another session (now: ${judged})` : '',
+  failures.length ? `${failures.length} checks failing` : '',
+  flags.length ? `${flags.length} judge flags` : '',
+  !coverage ? 'coverage not measured' : coverage.missing ? `${coverage.missing} coverage items missing` : '',
+  breadth.legacy ? `${breadth.legacy} operations on a legacy fallback` : '',
+  examples.replayed ? '' : "the vendor's published examples not all replayed",
+  examples.verdict === 'plausible' ? '' : `a plausible verdict on the vendor's published examples (now: ${examples.verdict})`,
+].filter(Boolean);
+console.log(`  source journey: ${missingForDone.length ? `incomplete — ${missingForDone.join('; ')}` : 'meets the source requirements'}`);
+console.log('  pack completion: not assessed — pack-done consumes the exact installed assessment in the final run');
+const reportAt = process.argv.indexOf('--report');
+if (reportAt >= 0 && process.argv[reportAt + 1]) {
+  writeFileSync(process.argv[reportAt + 1]!, `${JSON.stringify({ ...score, missingForDone }, null, 2)}\n`);
+}
+if (process.argv.includes('--write')) {
+  writeFileSync(join(PKG, 'journeys', 'score.json'), `${JSON.stringify(score, null, 2)}\n`);
+}