@volter/editor-game 0.5.65

package/src/host/coverage/coverage-accounting.ts

@@ -0,0 +1,261 @@
+/**
+ * THE COVERAGE UNIT — one derivation for every printer.
+ *
+ * Two numbers have been published for the same template walk: "editor 11 of 42"
+ * and "editor 7 of 21". 42 is root-instances (21 editor seams × 2 graded
+ * roots). 21 is distinct capabilities. Neither printer said which, so a
+ * legitimate applicability change (#2238) was indistinguishable from a
+ * silently more-forgiving instrument.
+ *
+ * This module is the one owner of both numbers. A capability is a unique
+ * seam; a root-instance is one row (one seam on one root). A capability is a
+ * gap if ANY applicable root is short of it — gap-wins, so a per-root miss
+ * cannot vanish into a sibling's ok. An all-N-A seam is not a capability of
+ * this session (that is the applicability rule, not a silent drop).
+ *
+ * Pure: no editor session, no filesystem. Callers that already hold rows
+ * (console, CLI banner, doctor, portfolio) format them here.
+ */
+
+export interface CoverageAccountingRow {
+  readonly seam: string;
+  readonly status: string;
+  /** Root this row belongs to, when the same seam appears once per mount. */
+  readonly subject?: string | null;
+  /** Fallback for subject when the union stamped `[label] ` onto `detail`. */
+  readonly detail?: string;
+}
+
+export interface CoverageFamilyAccounting {
+  readonly family: string;
+  /** Distinct applicable seams (the capabilities unit). */
+  readonly capabilities: number;
+  /** Distinct seams with a gap on any applicable root (gap-wins). */
+  readonly capabilityGaps: number;
+  /** Rows in this family — the root-instances unit, including N-A. */
+  readonly rootInstances: number;
+}
+
+export interface CoverageAccounting {
+  readonly capabilities: number;
+  readonly capabilityGaps: number;
+  readonly rootsGraded: number;
+  readonly rootInstances: number;
+  readonly families: readonly CoverageFamilyAccounting[];
+}
+
+export class CoverageReconcileError extends Error {
+  constructor(message: string) {
+    super(`coverage-accounting: ${message}`);
+    this.name = 'CoverageReconcileError';
+  }
+}
+
+/** The family a seam belongs to: the segment before its first `.`, or the whole
+ *  seam for the single-word ones (`loop`, `persistence`, `systems`). */
+export function coverageSeamFamily(seam: string): string {
+  const dot = seam.indexOf('.');
+  return dot === -1 ? seam : seam.slice(0, dot);
+}
+
+/** Subject stamped by `unionCoverageReport` as `[label] ` on the detail. */
+export function subjectFromDetail(detail: string | undefined): string | null {
+  if (!detail) return null;
+  const match = /^\[([^\]]+)\] /.exec(detail);
+  return match?.[1] ?? null;
+}
+
+function rowSubject(row: CoverageAccountingRow): string | null {
+  if (row.subject !== undefined && row.subject !== null && row.subject !== '') {
+    return row.subject;
+  }
+  return subjectFromDetail(row.detail);
+}
+
+interface SeamFold {
+  gap: boolean;
+  applicable: boolean;
+}
+
+function foldSeam(existing: SeamFold | undefined, status: string): SeamFold {
+  const fold = existing ?? { gap: false, applicable: false };
+  if (status === 'na') return fold;
+  return { gap: fold.gap || status === 'gap', applicable: true };
+}
+
+function familyAccounting(
+  family: string,
+  rows: readonly CoverageAccountingRow[],
+): CoverageFamilyAccounting {
+  const folds = new Map<string, SeamFold>();
+  for (const row of rows) {
+    folds.set(row.seam, foldSeam(folds.get(row.seam), row.status));
+  }
+  let capabilities = 0;
+  let capabilityGaps = 0;
+  for (const fold of folds.values()) {
+    if (!fold.applicable) continue;
+    capabilities += 1;
+    if (fold.gap) capabilityGaps += 1;
+  }
+  return { family, capabilities, capabilityGaps, rootInstances: rows.length };
+}
+
+/**
+ * Both units, from the same rows. Gap-wins on the capabilities unit so a
+ * miss on one root cannot be hidden by another root's ok.
+ */
+export function deriveCoverageAccounting(
+  rows: readonly CoverageAccountingRow[],
+): CoverageAccounting {
+  const subjects = new Set<string>();
+  const familyRows = new Map<string, CoverageAccountingRow[]>();
+  for (const row of rows) {
+    const subject = rowSubject(row);
+    if (subject !== null) subjects.add(subject);
+    const family = coverageSeamFamily(row.seam);
+    const list = familyRows.get(family);
+    if (list) list.push(row);
+    else familyRows.set(family, [row]);
+  }
+  const families = [...familyRows].map(([family, familyList]) =>
+    familyAccounting(family, familyList),
+  );
+  const folds = new Map<string, SeamFold>();
+  for (const row of rows) {
+    folds.set(row.seam, foldSeam(folds.get(row.seam), row.status));
+  }
+  let capabilities = 0;
+  let capabilityGaps = 0;
+  for (const fold of folds.values()) {
+    if (!fold.applicable) continue;
+    capabilities += 1;
+    if (fold.gap) capabilityGaps += 1;
+  }
+  return {
+    capabilities,
+    capabilityGaps,
+    rootsGraded: subjects.size,
+    rootInstances: rows.length,
+    families,
+  };
+}
+
+/** `8 of 30 capabilities are MISSING` */
+export function formatCoverageMissingLead(accounting: CoverageAccounting): string {
+  return `${accounting.capabilityGaps} of ${accounting.capabilities} capabilities are MISSING`;
+}
+
+/** `2 roots graded; 51 root-instances` — omitted roots clause when none were labelled. */
+export function formatCoverageDerivation(accounting: CoverageAccounting): string {
+  const roots = accounting.rootsGraded > 0 ? `${accounting.rootsGraded} roots graded; ` : '';
+  return `${roots}${accounting.rootInstances} root-instances`;
+}
+
+/**
+ * `editor 7 of 21 capabilities (2 roots graded; 42 root-instances)` when the
+ * family is counted per-root; `system 0 of 7 capabilities` when instances
+ * already equal capabilities.
+ */
+export function formatCoverageFamilyBreakdown(
+  family: CoverageFamilyAccounting,
+  opts: { readonly rootsGraded?: number } = {},
+): string {
+  const roots = opts.rootsGraded ?? 0;
+  const showInstances = family.rootInstances !== family.capabilities || roots > 1;
+  const head = `${family.family} ${family.capabilityGaps} of ${family.capabilities} capabilities`;
+  if (!showInstances) return head;
+  const rootsBit = roots > 1 ? `${roots} roots graded; ` : '';
+  return `${head} (${rootsBit}${family.rootInstances} root-instances)`;
+}
+
+function familyOpts(
+  family: CoverageFamilyAccounting,
+  accounting: CoverageAccounting,
+): { readonly rootsGraded?: number } {
+  return family.family === 'editor' ? { rootsGraded: accounting.rootsGraded } : {};
+}
+
+/** THE sentence. Head names the subject; the rest is this module's unit. */
+export function formatCoverageGapHeadline(head: string, accounting: CoverageAccounting): string {
+  const breakdown = accounting.families
+    .map((family) => formatCoverageFamilyBreakdown(family, familyOpts(family, accounting)))
+    .join(', ');
+  return `${head} — ${formatCoverageMissingLead(accounting)} (${formatCoverageDerivation(accounting)}: ${breakdown}).`;
+}
+
+export interface ParsedCoverageHeadline {
+  readonly capabilityGaps: number;
+  readonly capabilities: number;
+  readonly rootsGraded: number;
+  readonly rootInstances: number;
+}
+
+/** Pull the unit numbers back out of a headline so a report can fail closed. */
+export function parseCoverageHeadline(headline: string): ParsedCoverageHeadline {
+  const lead = /(\d+) of (\d+) capabilities are MISSING/.exec(headline);
+  if (!lead) {
+    throw new CoverageReconcileError(
+      'headline does not state the capabilities unit (missing "N of M capabilities are MISSING")',
+    );
+  }
+  const roots = /(\d+) roots graded/.exec(headline);
+  const instances = /(\d+) root-instances/.exec(headline);
+  if (!instances) {
+    throw new CoverageReconcileError('headline does not state root-instances');
+  }
+  return {
+    capabilityGaps: Number(lead[1]),
+    capabilities: Number(lead[2]),
+    rootsGraded: roots ? Number(roots[1]) : 0,
+    rootInstances: Number(instances[1]),
+  };
+}
+
+/**
+ * A report whose members cannot reconcile with its headline is a broken
+ * report. Detail rows are the source; the headline must be derivable from
+ * them, and the headline's numbers must be those derived values.
+ */
+export function assertCoverageReconciles(
+  rows: readonly CoverageAccountingRow[],
+  headline: string,
+): void {
+  const derived = deriveCoverageAccounting(rows);
+  const parsed = parseCoverageHeadline(headline);
+  if (parsed.capabilityGaps !== derived.capabilityGaps) {
+    throw new CoverageReconcileError(
+      `headline capability-gaps ${parsed.capabilityGaps} !== row-derived ${derived.capabilityGaps}`,
+    );
+  }
+  if (parsed.capabilities !== derived.capabilities) {
+    throw new CoverageReconcileError(
+      `headline capabilities ${parsed.capabilities} !== row-derived ${derived.capabilities}`,
+    );
+  }
+  if (parsed.rootInstances !== derived.rootInstances) {
+    throw new CoverageReconcileError(
+      `headline root-instances ${parsed.rootInstances} !== row-derived ${derived.rootInstances}`,
+    );
+  }
+  if (parsed.rootsGraded !== derived.rootsGraded) {
+    throw new CoverageReconcileError(
+      `headline roots-graded ${parsed.rootsGraded} !== row-derived ${derived.rootsGraded}`,
+    );
+  }
+  const familyInstanceSum = derived.families.reduce((sum, family) => sum + family.rootInstances, 0);
+  if (familyInstanceSum !== derived.rootInstances) {
+    throw new CoverageReconcileError(
+      `family root-instances ${familyInstanceSum} !== ${derived.rootInstances}`,
+    );
+  }
+  const familyCapabilitySum = derived.families.reduce(
+    (sum, family) => sum + family.capabilities,
+    0,
+  );
+  if (familyCapabilitySum !== derived.capabilities) {
+    throw new CoverageReconcileError(
+      `family capabilities ${familyCapabilitySum} !== ${derived.capabilities}`,
+    );
+  }
+}

package/src/host/coverage/game-contract-seam-evidence.ts

@@ -0,0 +1,82 @@
+/** Current-epoch evidence for the game→host contract. */
+
+import {
+  gradeSeamEvidence,
+  inspectSeamShape,
+  type SeamEvidenceReceipt,
+  type SeamEvidenceVerdict,
+} from '@volter/editor-project/adapter';
+import type {
+  VgaiGameContract,
+  VgaiGameLifecycle,
+  VgaiGameSystems,
+} from '@volter/editor-project/adapter/ingest/game-contract';
+import {
+  GAME_CONTRACT_SHAPE,
+  GAME_LIFECYCLE_SHAPE,
+  GAME_SYSTEMS_SHAPE,
+} from '@volter/editor-project/adapter/ingest/game-contract-seams';
+import { liveSeamEvidence } from '@volter/editor-core/coverage/live-seam-evidence';
+
+const EPOCHS = new WeakMap<object, string>();
+let nextEpoch = 1;
+
+export function gameContractEpoch(contract: VgaiGameContract): string {
+  const found = EPOCHS.get(contract);
+  if (found) return found;
+  const epoch = `contract-${nextEpoch++}`;
+  EPOCHS.set(contract, epoch);
+  return epoch;
+}
+
+export interface GameContractEvidence {
+  readonly root: SeamEvidenceVerdict;
+  readonly start: SeamEvidenceVerdict;
+  readonly pause: SeamEvidenceVerdict;
+  readonly resume: SeamEvidenceVerdict;
+  readonly systems: SeamEvidenceVerdict;
+}
+
+export function inspectGameContractSeams(options: {
+  readonly contract: VgaiGameContract;
+  readonly subject?: string | undefined;
+  readonly epoch?: string | undefined;
+  readonly receipts?: readonly SeamEvidenceReceipt[] | undefined;
+}): GameContractEvidence {
+  const subject = options.subject ?? 'game';
+  const epoch = options.epoch ?? gameContractEpoch(options.contract);
+  const receipts: SeamEvidenceReceipt[] = [
+    ...inspectSeamShape<VgaiGameContract>({
+      prefix: 'contract',
+      value: options.contract,
+      shape: GAME_CONTRACT_SHAPE,
+      subject,
+      epoch,
+    }),
+    ...inspectSeamShape<VgaiGameLifecycle>({
+      prefix: 'contract.lifecycle',
+      value: options.contract.lifecycle,
+      shape: GAME_LIFECYCLE_SHAPE,
+      subject,
+      epoch,
+    }),
+    ...inspectSeamShape<VgaiGameSystems>({
+      prefix: 'contract.systems',
+      value: options.contract.systems,
+      shape: GAME_SYSTEMS_SHAPE,
+      subject,
+      epoch,
+    }),
+    ...liveSeamEvidence.receipts({ subject, epoch }),
+    ...(options.receipts ?? []),
+  ];
+  const verdict = (seam: string, required: 'operation' | 'effect'): SeamEvidenceVerdict =>
+    gradeSeamEvidence({ seam, subject, epoch, required, receipts });
+  return {
+    root: verdict('contract.root', 'effect'),
+    start: verdict('contract.lifecycle.start', 'effect'),
+    pause: verdict('contract.lifecycle.pause', 'effect'),
+    resume: verdict('contract.lifecycle.resume', 'effect'),
+    systems: verdict('contract.systems', 'operation'),
+  };
+}

package/src/host/coverage/project-verb-coverage.ts

@@ -0,0 +1,148 @@
+/**
+ * THE `project.*` RULES — the pure half of `@volter/editor-game/coverage/live-project-verbs.ts`.
+ *
+ * ## The defect this closes
+ *
+ * Derived coverage had exactly two families, and both are pinned to an
+ * INTERFACE: `editor.*` to `AuthoringAdapter`'s provider vocabulary
+ * (`AUTHORING_PROVIDER_PRESENCE`) and `system.*` to `SystemAdapters`' slots.
+ * That is what makes them exhaustive — of what an ADAPTER can be asked. Native
+ * verbs like the export/build path are not an adapter's to answer at all,
+ * because their subject is the PROJECT rather than a mounted root: whether
+ * this project can produce the standalone build that is the ONLY way it runs
+ * outside the editor.
+ *
+ * So a project could be green in both families and silently lack it, which
+ * violates the standing rule that an unreached capability is an OPEN warning
+ * and never silence.
+ *
+ * ## Every row is a real fact with a real reader
+ *
+ * Nothing here is a schema field invented for the report. Each rule reads
+ * something the product itself already acts on:
+ *
+ *  - `export` reads what the export path ACTUALLY requires of a project, taken
+ *    from the door's own source: `create-vgai-project/src/deploy.ts` runs
+ *    `npm run build` in the project (`runProjectBuild`) and stages the `dist/`
+ *    that emits (`stageBuildOutput`). Ingest roots pass that door because the
+ *    ingest project's own build is already its standalone game; arbitrary
+ *    module roots and unsupported built-ins remain a named refusal. These are
+ *    static, manifest/package-readable preconditions; neither is a guess.
+ *
+ * Pure over its inputs, so the whole table is unit-testable with no browser and
+ * no live session — same shape and same reason as
+ * `coverage/system-adapter-coverage.ts`.
+ */
+
+import { commandLine } from '@volter/editor-core/product-command';
+import {
+  PROJECT_VERB_SLOTS,
+  type ProjectVerbMeasurement,
+  type ProjectVerbSlot,
+} from './capability-coverage';
+
+/** One manifest root, in the terms the export door's wall reads. */
+export interface ProjectRootFact {
+  readonly id: string;
+  /** `ResolvedAdapter['type']` — `builtin` | `module` | `ingest`. */
+  readonly type: string;
+  /** `ResolvedAdapter['identity']` — `three`/`dom`/`ingest-three`/… */
+  readonly identity: string;
+}
+
+/** Everything the rules read. Every field arrives as data, and every `null`
+ *  means NOBODY LOOKED — never "there is none". */
+export interface ProjectVerbFacts {
+  /**
+   * The script names the project's `package.json` declares, `[]` when it has a
+   * `package.json` with no scripts, and `null` when the question could not be
+   * asked (a fetch that has not landed, no server).
+   */
+  readonly scripts: readonly string[] | null;
+  /** Does the project have a `package.json` at all? `false` with `scripts: []`
+   *  is a measured absence and reads differently from an empty scripts block. */
+  readonly hasPackageJson: boolean;
+  /** The manifest's roots as the export wall reads them; `null` ⇒ unasked. */
+  readonly roots: readonly ProjectRootFact[] | null;
+  /** Why the file-read facts above are `null`, in the fetcher's own words.
+   *  Shown verbatim, so an unanswered row can never read as a clean one. */
+  readonly unavailable: string | null;
+}
+
+/** The sentence an unanswered row prints. One place, so all three agree. */
+function unanswered(
+  slot: ProjectVerbMeasurement['slot'],
+  why: string | null,
+): ProjectVerbMeasurement {
+  return {
+    slot,
+    state: 'unanswered',
+    evidence:
+      `nobody has read this project's own files yet, so ${slot} is unmeasured — ` +
+      (why ?? 'the editor has not asked its dev server for them'),
+  };
+}
+
+/** Is every root this project declares an ingest root? An ingest-only
+ *  project's own build is already its standalone game, which changes what the
+ *  export wall says about it. */
+function ingestOnly(roots: readonly ProjectRootFact[]): boolean {
+  return roots.length > 0 && roots.every((root) => root.type === 'ingest');
+}
+
+function exportVerb(facts: ProjectVerbFacts): ProjectVerbMeasurement {
+  const { scripts, roots } = facts;
+  if (scripts === null || roots === null) return unanswered('export', facts.unavailable);
+  if (!scripts.includes('build')) {
+    return {
+      slot: 'export',
+      state: 'absent',
+      evidence: facts.hasPackageJson
+        ? "this project's package.json declares no `build` script, and the export path runs " +
+          '`npm run build` in the project and stages the `dist/` it emits'
+        : 'this project has no package.json, so there is no `build` script for the export path to run',
+      missing:
+        'this project cannot produce a standalone build, so it runs NOWHERE but the editor — the ' +
+        'dev-served standalone page refuses an unexported game outright',
+      fix: "add the scaffold's `build` script (`build: tsc && vite build`), which is what every deploy path runs",
+    };
+  }
+  const refused = roots.filter(
+    (root) => root.type !== 'ingest' && (root.type !== 'builtin' || root.identity !== 'three'),
+  );
+  const wallLeg =
+    refused.length > 0
+      ? `; note that the legacy ${commandLine('deploy')} verb additionally refuses ${refused
+          .map((root) => `root "${root.id}" (${root.identity})`)
+          .join(
+            ', ',
+          )} — use the project-owned deploy scripts (${commandLine('add deploy-cloudflare')}/\`deploy-vercel\`, then \`npm run deploy\`)`
+      : '';
+  const deployLeg = scripts.includes('deploy')
+    ? ', and a `deploy` script to ship it'
+    : ` (no \`deploy\` script yet — ${commandLine('add deploy-cloudflare')}/\`deploy-vercel\` adds one)`;
+  const ingestLeg = ingestOnly(roots)
+    ? '; this ingest project ships the standalone bundle produced by its own build unchanged'
+    : '';
+  return {
+    slot: 'export',
+    state: 'present',
+    evidence: `this project declares a \`build\` script, which is what the export path runs to emit the \`dist/\` it stages${deployLeg}${ingestLeg}${wallLeg}`,
+  };
+}
+
+/**
+ * The terminal state of every native verb for the OPEN PROJECT.
+ *
+ * Order is `PROJECT_VERB_SLOTS`, so two reports of the same project stay
+ * diffable line for line — the same property the other two families have.
+ */
+export function measureProjectVerbs(facts: ProjectVerbFacts): readonly ProjectVerbMeasurement[] {
+  // A `Record` keyed by the slot union, so a verb added to the vocabulary fails
+  // to compile until it has a rule — the same compile pin the vocabulary itself
+  // carries in `coverage/capability-coverage.ts`.
+  const rules: Record<ProjectVerbSlot, (f: ProjectVerbFacts) => ProjectVerbMeasurement> = {
+    export: exportVerb,
+  };
+  return PROJECT_VERB_SLOTS.map((slot) => rules[slot](facts));
+}