@openwop/openwop-conformance 1.106.1 → 1.124.0

package/src/lib/requirement-ledger.ts

@@ -16,6 +16,8 @@
  * That is the whole mechanism. Everything else here is bookkeeping.
  */
 
+import { appendFileSync, readFileSync, existsSync } from 'node:fs';
+
 /** RFC 0148 §A. Exactly one of these per requirement, per run. */
 export type Disposition =
   /** The assertion executed against the target and passed. */
@@ -54,9 +56,21 @@ export interface LedgerEntry {
   readonly disposition: Disposition;
   /** Why — required for every disposition except `executed-pass`. */
   readonly detail?: string;
+  /** How many `expect` assertions actually ran for this requirement (RFC 0148
+   *  §C `assertionCount`). `executed-pass` with `0` is the vacuous pass the
+   *  program exists to make visible; the runner treats it as unclassified for
+   *  a claimed profile's floor. */
+  readonly assertionCount?: number;
 }
 
 const ledger = new Map<string, LedgerEntry>();
+/**
+ * Append-only journal of every recording in call order (duplicates included).
+ * `setup.ts` marks the journal length before a file's tests and reads what was
+ * recorded since, so a file's own gate decisions can be found even when the
+ * same requirement id was recorded earlier in the worker.
+ */
+const journal: LedgerEntry[] = [];
 
 /**
  * Record a requirement's outcome. Recording the same id twice with different
@@ -68,6 +82,7 @@ export function recordRequirement(
   requirementId: string,
   disposition: Disposition,
   detail?: string,
+  extras?: { assertionCount?: number },
 ): void {
   const prior = ledger.get(requirementId);
   if (prior !== undefined && prior.disposition !== disposition) {
@@ -82,7 +97,59 @@ export function recordRequirement(
         'Anything other than executed-pass MUST say why, or the ledger records an outcome nobody can act on.',
     );
   }
-  ledger.set(requirementId, detail === undefined ? { requirementId, disposition } : { requirementId, disposition, detail });
+  const entry: LedgerEntry = {
+    requirementId,
+    disposition,
+    ...(detail === undefined ? {} : { detail }),
+    ...(extras?.assertionCount === undefined ? {} : { assertionCount: extras.assertionCount }),
+  };
+  ledger.set(requirementId, entry);
+  journal.push(entry);
+  // File sink (RFC 0148 acceptance item 2, S6). The in-memory map lives in a
+  // vitest worker; the `--certify` runner is a separate process reading a
+  // per-file JSON report. When the runner sets OPENWOP_LEDGER_PATH the worker
+  // appends every recording as one JSONL line so the runner can build
+  // requirement-level dispositions from what scenarios actually recorded —
+  // rather than inferring them from per-file pass/fail/skip, which cannot
+  // tell `skipped` from `inapplicable` from `blocked`. Best-effort: a sink
+  // failure must never turn a real assertion into a crash.
+  const sink = process.env['OPENWOP_LEDGER_PATH'];
+  if (sink !== undefined && sink !== '' && sink !== suspendedSink) {
+    try {
+      appendFileSync(sink, JSON.stringify(entry) + '\n');
+    } catch {
+      /* ignore — the in-memory ledger is still authoritative for this worker */
+    }
+  }
+}
+
+/**
+ * Read a ledger JSONL file written through the sink above. Duplicate lines for
+ * the same id (a scenario re-recording the same disposition, or several files
+ * gating the same profile) collapse to one entry; a CONFLICT (two different
+ * dispositions for one id across workers) resolves to the least certifiable
+ * — `executed-fail` > `blocked` > `executed-pass` > `skipped` > `inapplicable`
+ * — because "one worker said it failed" outranks "another said it passed", and
+ * an unresolvable disagreement must never round toward certification.
+ * Returns an empty array when the file is absent.
+ */
+export function readLedgerFile(path: string): readonly LedgerEntry[] {
+  if (!existsSync(path)) return [];
+  const rank: Record<Disposition, number> = { 'executed-fail': 0, blocked: 1, 'executed-pass': 2, skipped: 3, inapplicable: 4 };
+  const merged = new Map<string, LedgerEntry>();
+  for (const line of readFileSync(path, 'utf8').split('\n')) {
+    if (line.trim() === '') continue;
+    let e: LedgerEntry;
+    try {
+      e = JSON.parse(line) as LedgerEntry;
+    } catch {
+      continue;
+    }
+    if (typeof e.requirementId !== 'string' || !DISPOSITIONS.includes(e.disposition)) continue;
+    const prior = merged.get(e.requirementId);
+    if (prior === undefined || rank[e.disposition] < rank[prior.disposition]) merged.set(e.requirementId, e);
+  }
+  return [...merged.values()].sort((a, b) => a.requirementId.localeCompare(b.requirementId));
 }
 
 /**
@@ -110,8 +177,38 @@ export function snapshot(): readonly LedgerEntry[] {
 }
 
 /** Test-support only. Production runs record once and read once. */
+let suspendedSink: string | undefined;
+/**
+ * Scenarios that exercise `recordRequirement` itself (the ledger's own unit
+ * tests) record REAL requirement ids as fixtures — e.g. the whole core-standard
+ * floor as `executed-pass`. With the file sink on, those fixture rows would
+ * reach the runner's ledger and, under the reader's conflict rank, out-vote a
+ * genuine `inapplicable` recorded by the scenario that owns the requirement.
+ * Such a test file calls this in `beforeAll` and the returned restore in
+ * `afterAll`: recordings made in between are kept in memory but NOT appended to
+ * the sink that was active at the time of the call. A different path set by the
+ * test itself (its own scratch sink) is unaffected.
+ */
+export function suspendSinkForFixtures(): () => void {
+  suspendedSink = process.env['OPENWOP_LEDGER_PATH'];
+  return () => {
+    suspendedSink = undefined;
+  };
+}
+
+/** Number of recordings so far in this worker (a mark for `journalSince`). */
+export function journalLength(): number {
+  return journal.length;
+}
+
+/** Every recording made since `mark` (from `journalLength()`), in call order. */
+export function journalSince(mark: number): readonly LedgerEntry[] {
+  return journal.slice(mark);
+}
+
 export function resetLedger(): void {
   ledger.clear();
+  journal.length = 0;
 }
 
 export interface ProfileVerdict {

package/src/lib/requirement-registry.ts

@@ -42,12 +42,50 @@ export function requirementIdForPrefix(prefix: string): string {
  * to close. `null` forces the caller to decide between `discoveryOnly` (an empty
  * floor by design) and unspecified (no floor written yet).
  */
-export function requirementsFor(profile: string): readonly string[] | null {
+/** Read a dot-path (RFC 0073 root families) out of a discovery document. */
+function readPath(doc: Readonly<Record<string, unknown>>, path: string): unknown {
+  let cur: unknown = doc;
+  for (const seg of path.split('.')) {
+    if (cur === null || typeof cur !== 'object') return undefined;
+    cur = (cur as Record<string, unknown>)[seg];
+  }
+  return cur;
+}
+
+/**
+ * The scenario FILES a profile's floor requires against a given discovery
+ * document — the unconditional `required` list plus every `conditional` branch
+ * whose `path` array includes its `includes` value. `null` when the floor is
+ * conditional and no document was supplied (unevaluable ≠ empty), or when the
+ * profile has no floor at all.
+ */
+export function floorFilesFor(profile: string, document?: Readonly<Record<string, unknown>>): readonly string[] | null {
+  const floor = PROFILE_FLOOR_SCENARIOS[profile];
+  if (floor === undefined) return null;
+  const files = [...floor.required];
+  if (floor.conditional !== undefined && floor.conditional.length > 0) {
+    if (document === undefined) return null;
+    for (const c of floor.conditional) {
+      const arr = readPath(document, c.path);
+      if (Array.isArray(arr) && arr.includes(c.includes)) files.push(...c.required);
+    }
+  }
+  return [...new Set(files)];
+}
+
+/**
+ * Requirement ids for a profile's floor. `document` is needed for a
+ * discovery-conditional floor (RFC 0148 §C G7 — `openwop-replay-fork`): without
+ * it such a floor is UNEVALUABLE and this returns `null`, never `[]`.
+ */
+export function requirementsFor(profile: string, document?: Readonly<Record<string, unknown>>): readonly string[] | null {
   const floor = PROFILE_FLOOR_SCENARIOS[profile];
   if (floor === undefined) return null;
   if (floor.discoveryOnly === true) return [];
+  const files = floorFilesFor(profile, document);
+  if (files === null) return null;
   return [
-    ...floor.required.map(requirementIdForScenario),
+    ...files.map(requirementIdForScenario),
     ...(floor.requiredAnyPrefix ?? []).map(requirementIdForPrefix),
   ];
 }
@@ -55,8 +93,13 @@ export function requirementsFor(profile: string): readonly string[] | null {
 /** Every registered requirement ID across every profile with a runtime floor. */
 export function allRequirements(): readonly string[] {
   const ids = new Set<string>();
-  for (const profile of Object.keys(PROFILE_FLOOR_SCENARIOS)) {
-    for (const id of requirementsFor(profile) ?? []) ids.add(id);
+  for (const [profile, floor] of Object.entries(PROFILE_FLOOR_SCENARIOS)) {
+    if (floor.discoveryOnly === true) continue;
+    // every branch of a conditional floor is a registered requirement
+    for (const f of floor.required) ids.add(requirementIdForScenario(f));
+    for (const c of floor.conditional ?? []) for (const f of c.required) ids.add(requirementIdForScenario(f));
+    for (const p of floor.requiredAnyPrefix ?? []) ids.add(requirementIdForPrefix(p));
+    void profile;
   }
   return [...ids].sort();
 }

package/src/lib/scenario-disposition.ts

@@ -0,0 +1,291 @@
+/**
+ * RFC 0148 §A / acceptance item 2 (S6) — file-level requirement recording and
+ * the runner's derivation.
+ *
+ * Two halves that meet through the ledger file sink:
+ *
+ * 1. **In the vitest worker** (`setup.ts` hooks): every scenario FILE records
+ *    exactly one disposition for its own requirement id when it finishes —
+ *    `executed-fail` if any test failed, `executed-pass` if any test passed and
+ *    none failed, and for a file whose tests ALL skipped: `inapplicable` /
+ *    `skipped` if a `behaviorGate` inside the file recorded one of those for the
+ *    profile it gates on (the honest reason the tests did not run), else
+ *    `blocked` — an all-skipped file with no recorded reason is an unclassified
+ *    return, and §A resolves it to `blocked`, never to a pass.
+ *
+ * 2. **In the `--certify` runner** (`deriveRequirementDispositions`): every
+ *    scenario file's requirement is taken FROM THE LEDGER when present, falling
+ *    back to the vitest per-file report only for pass/fail (which the ledger
+ *    would agree with) and to `blocked` (unclassified) otherwise; the floor's
+ *    prefix requirements (`openwop.floor.any.<prefix>`) are derived from the
+ *    files that match; and a claimed profile whose floor contains ANY requirement
+ *    with no ledger entry is flagged `unclassified` so the runner can REJECT the
+ *    certification rather than round the silence up.
+ *
+ * Pure functions, no I/O, so `runner-ledger.test.ts` can pin them without a
+ * host or a vitest subprocess.
+ */
+
+import { PROFILE_FLOOR_SCENARIOS } from './profiles.js';
+import { requirementIdForScenario, requirementIdForPrefix, requirementsFor } from './requirement-registry.js';
+import { UNCLASSIFIED_RETURN_DETAIL } from './soft-skip.js';
+import { CERTIFIABLE, type Disposition, type LedgerEntry } from './requirement-ledger.js';
+
+/** All scenario basenames that appear in some profile's runtime floor. */
+export function floorScenarioFiles(): ReadonlySet<string> {
+  const out = new Set<string>();
+  for (const floor of Object.values(PROFILE_FLOOR_SCENARIOS)) {
+    for (const f of floor.required) out.add(f);
+    for (const c of floor.conditional ?? []) for (const f of c.required) out.add(f);
+  }
+  return out;
+}
+
+/** The requirement id a scenario FILE records under: the §A floor id when the
+ *  file is part of a floor, else the runner's per-scenario id. */
+export function requirementIdForFile(basename: string): string {
+  return floorScenarioFiles().has(basename)
+    ? requirementIdForScenario(basename)
+    : `openwop.scenario.${basename.replace(/\.test\.ts$/, '')}`;
+}
+
+export type FileTestState = 'pass' | 'fail' | 'skip';
+
+/** Worker half: fold a file's per-test states (+ any gate-recorded reason) into
+ *  the ONE disposition the file records. */
+export function fileDisposition(
+  states: readonly FileTestState[],
+  gateReason: 'inapplicable' | 'skipped' | undefined,
+  assertionCount?: number,
+): { disposition: Disposition; detail?: string } {
+  if (states.some((s) => s === 'fail')) return { disposition: 'executed-fail', detail: 'one or more assertions in the file failed' };
+  if (states.some((s) => s === 'pass')) {
+    // A test that early-returned through `behaviorGate` is reported by vitest
+    // as a pass with zero assertions. When EVERY passing test in the file did
+    // that (assertionCount 0) and the gate recorded why, the file's honest
+    // disposition is the gate's — `inapplicable` / `skipped` with its reason —
+    // not a vacuous executed-pass. Without a gate reason a zero-assertion pass
+    // stays `executed-pass` with `assertionCount: 0`, which certification
+    // rejects as unclassified (RFC 0148 §A).
+    if (assertionCount === 0 && gateReason === 'inapplicable') {
+      return { disposition: 'inapplicable', detail: 'every test returned early through behaviorGate with zero assertions: profile not advertised in the captured discovery set' };
+    }
+    if (assertionCount === 0 && gateReason === 'skipped') {
+      return { disposition: 'skipped', detail: 'every test returned early through behaviorGate with zero assertions: operator opted the profile out (OPENWOP_OPTED_OUT_PROFILES)' };
+    }
+    return { disposition: 'executed-pass' };
+  }
+  if (gateReason === 'inapplicable') return { disposition: 'inapplicable', detail: 'every test skipped: profile not advertised in the captured discovery set (behaviorGate)' };
+  if (gateReason === 'skipped') return { disposition: 'skipped', detail: 'every test skipped: operator opted the profile out (OPENWOP_OPTED_OUT_PROFILES)' };
+  return {
+    disposition: 'blocked',
+    detail:
+      states.length === 0
+        ? 'no test executed and no disposition recorded — unclassified return (RFC 0148 §A resolves it to blocked)'
+        : 'every test skipped with no recorded reason — unclassified return (RFC 0148 §A resolves it to blocked)',
+  };
+}
+
+/**
+ * The runner's file-level record (RFC 0148 §A), as `setup.ts` computes it in
+ * `afterAll`. Pure so `conformance-execution-witness.test.ts` can pin the rule
+ * the hooks apply:
+ *   - a failed test ⇒ executed-fail; a witnessed pass ⇒ executed-pass;
+ *   - a zero-assertion "pass" ⇒ the file's noted reason (`softSkip` /
+ *     `seamAbsent`: inapplicable | skipped | blocked) or a behaviorGate reason;
+ *   - a zero-assertion "pass" with NO reason ⇒ `blocked` + the marker detail —
+ *     an early return can never become a pass.
+ */
+export function resolveFileRecord(
+  states: readonly FileTestState[],
+  gateReason: 'inapplicable' | 'skipped' | undefined,
+  assertionCount: number,
+  noted: { kind: 'inapplicable' | 'skipped' | 'blocked'; reason: string } | null,
+): { disposition: Disposition; detail?: string } {
+  let { disposition, detail } = fileDisposition(states, gateReason, assertionCount);
+  if (disposition === 'executed-pass' && assertionCount === 0) {
+    if (noted !== null) {
+      disposition = noted.kind;
+      detail = noted.reason;
+    } else {
+      disposition = 'blocked';
+      detail = UNCLASSIFIED_RETURN_DETAIL;
+    }
+  }
+  return detail === undefined ? { disposition } : { disposition, detail };
+}
+
+export interface DerivedRequirement {
+  readonly requirementId: string;
+  readonly scenarioId: string;
+  readonly disposition: Disposition;
+  readonly detail?: string;
+  /** RFC 0148 §C — present when the ledger recorded it. */
+  readonly assertionCount?: number;
+}
+
+export interface DerivedProfileVerdict {
+  readonly profile: string;
+  /** Floor requirement ids with NO ledger entry (unclassified returns). */
+  readonly unclassified: readonly string[];
+  /** Floor requirement ids whose disposition is not certifiable. */
+  readonly blocking: readonly string[];
+  readonly certifiable: boolean;
+  /**
+   * `PROFILE_FLOOR_SCENARIOS[profile].runtimeDerived`: the profile is HELD only
+   * when every floor requirement is a witnessed `executed-pass`. When false for
+   * such a profile the emitter drops it from `claimedProfiles` — the host does
+   * not hold it — rather than reporting a rejection or a blocked claim.
+   */
+  readonly runtimeDerived: boolean;
+  /** For runtime-derived profiles: every floor row is a witnessed executed-pass. */
+  readonly held: boolean;
+}
+
+export interface Derivation {
+  readonly requirements: readonly DerivedRequirement[];
+  readonly totals: { executedPass: number; executedFail: number; skipped: number; inapplicable: number; blocked: number };
+  readonly verdicts: readonly DerivedProfileVerdict[];
+  /** True when ANY claimed profile has an unclassified floor requirement. The
+   *  runner MUST reject certification in that case (RFC 0148 acceptance item 2). */
+  readonly rejectUnclassified: boolean;
+  /** Whether a ledger was available at all (false ⇒ every row is report-derived). */
+  readonly ledgerPresent: boolean;
+}
+
+/**
+ * Runner half. `reportStates` is what vitest's JSON report said per file
+ * (`passed`/`failed`/`skipped`); `ledger` is what the workers recorded.
+ */
+export function deriveRequirementDispositions(
+  reportStates: ReadonlyMap<string, 'passed' | 'failed' | 'skipped'>,
+  ledger: readonly LedgerEntry[],
+  claimedProfiles: readonly string[],
+  /** The captured discovery document — needed to evaluate a discovery-conditional floor (G7). */
+  document?: Readonly<Record<string, unknown>>,
+): Derivation {
+  const byId = new Map(ledger.map((e) => [e.requirementId, e] as const));
+  const ledgerPresent = ledger.length > 0;
+  const rows: DerivedRequirement[] = [];
+  const perFile = new Map<string, DerivedRequirement>();
+
+  for (const [file, state] of [...reportStates.entries()].sort((a, b) => a[0].localeCompare(b[0]))) {
+    const id = requirementIdForFile(file);
+    const rec = byId.get(id);
+    let row: DerivedRequirement;
+    if (rec !== undefined) {
+      row = {
+        requirementId: id,
+        scenarioId: file,
+        disposition: rec.disposition,
+        ...(rec.detail === undefined ? {} : { detail: rec.detail }),
+        ...(rec.assertionCount === undefined ? {} : { assertionCount: rec.assertionCount }),
+      };
+    } else if (state === 'passed') {
+      row = ledgerPresent
+        ? { requirementId: id, scenarioId: file, disposition: 'executed-pass', detail: 'report-derived: vitest passed the file but no disposition was recorded (assertion count unknown) — unclassified for a claimed floor' }
+        : { requirementId: id, scenarioId: file, disposition: 'executed-pass' };
+    } else if (state === 'failed') {
+      row = { requirementId: id, scenarioId: file, disposition: 'executed-fail', detail: 'the scenario executed and failed (report-derived; no ledger entry)' };
+    } else {
+      row = {
+        requirementId: id,
+        scenarioId: file,
+        disposition: 'blocked',
+        detail: ledgerPresent
+          ? 'unclassified return: the file recorded no disposition — RFC 0148 §A resolves it to blocked, never to a pass'
+          : 'runner cannot classify a skipped file without a ledger; RFC 0148 §A resolves an unclassifiable requirement to blocked',
+      };
+    }
+    rows.push(row);
+    perFile.set(file, row);
+  }
+
+  // Prefix requirements: derived from the matching files.
+  const prefixIds = new Set<string>();
+  for (const floor of Object.values(PROFILE_FLOOR_SCENARIOS)) for (const p of floor.requiredAnyPrefix ?? []) prefixIds.add(p);
+  for (const prefix of [...prefixIds].sort()) {
+    const matching = [...perFile.entries()].filter(([f]) => f.startsWith(prefix)).map(([, r]) => r);
+    const id = requirementIdForPrefix(prefix);
+    let row: DerivedRequirement;
+    if (matching.some((r) => r.disposition === 'executed-pass')) {
+      // Witnessed by the matching passes: the summary row carries their
+      // combined assertion count so a consumer reading only this row still
+      // sees a witnessed pass (RFC 0148 §C `assertionCount`).
+      const witnessed = matching.filter((r) => r.disposition === 'executed-pass').reduce((n, r) => n + (r.assertionCount ?? 0), 0);
+      row = { requirementId: id, scenarioId: `${prefix}*`, disposition: 'executed-pass', assertionCount: witnessed };
+    } else if (matching.some((r) => r.disposition === 'executed-fail')) {
+      row = { requirementId: id, scenarioId: `${prefix}*`, disposition: 'executed-fail', detail: `no ${prefix}* scenario passed and at least one failed` };
+    } else if (matching.length === 0) {
+      row = { requirementId: id, scenarioId: `${prefix}*`, disposition: 'blocked', detail: `no ${prefix}* scenario ran — unclassified return` };
+    } else {
+      // all matching files are skipped/inapplicable/blocked: the prefix requirement is met by ANY pass, so none ⇒ blocked
+      row = { requirementId: id, scenarioId: `${prefix}*`, disposition: 'blocked', detail: `no ${prefix}* scenario executed a passing assertion (${matching.map((r) => r.disposition).join(', ')})` };
+    }
+    rows.push(row);
+  }
+
+  const totals = { executedPass: 0, executedFail: 0, skipped: 0, inapplicable: 0, blocked: 0 };
+  for (const r of rows) {
+    if (r.disposition === 'executed-pass') totals.executedPass++;
+    else if (r.disposition === 'executed-fail') totals.executedFail++;
+    else if (r.disposition === 'skipped') totals.skipped++;
+    else if (r.disposition === 'inapplicable') totals.inapplicable++;
+    else totals.blocked++;
+  }
+
+  const rowById = new Map(rows.map((r) => [r.requirementId, r] as const));
+  const verdicts: DerivedProfileVerdict[] = [];
+  for (const profile of claimedProfiles) {
+    const ids = requirementsFor(profile, document);
+    if (ids === null) {
+      const floor = PROFILE_FLOOR_SCENARIOS[profile];
+      const why = floor === undefined ? `(no floor defined for ${profile})` : `(discovery-conditional floor for ${profile} is unevaluable without the discovery document)`;
+      verdicts.push({ profile, unclassified: [], blocking: [why], certifiable: false, runtimeDerived: false, held: false });
+      continue;
+    }
+    const unclassified: string[] = [];
+    const blocking: string[] = [];
+    let witnessedPasses = 0;
+    for (const id of ids) {
+      const r = rowById.get(id);
+      const fromLedger = byId.has(id) || (r !== undefined && r.scenarioId.endsWith('*'));
+      if (r !== undefined && r.disposition === 'executed-pass' && (r.assertionCount ?? 0) > 0) witnessedPasses += 1;
+      // Unclassified: no row, or a report-derived blocked (nothing recorded), or a
+      // VACUOUS pass — executed-pass with assertionCount 0 is a witness of nothing
+      // (RFC 0148 §A: "a required behavior MUST NOT be certified without a target
+      // execution witness"), so for a claimed floor it counts as unclassified.
+      const vacuous =
+        r !== undefined &&
+        ((r.disposition === 'executed-pass' && r.assertionCount === 0) ||
+          // the runner's own §A resolution of a zero-assertion file that noted no
+          // reason: honest as a row, still an unclassified return for a floor
+          (r.disposition === 'blocked' && r.detail === UNCLASSIFIED_RETURN_DETAIL));
+      // With a ledger present, ANY floor row that did not come from the ledger is
+      // unclassified: silence is evidence of nothing (RFC 0148 §A). Without a
+      // ledger only report-blocked rows are unclassified (the pre-S6 reading).
+      const silent = !fromLedger && (ledgerPresent || r?.disposition === 'blocked');
+      if (r === undefined || silent || vacuous) unclassified.push(id);
+      // Unclassified always blocks: a requirement nobody recorded cannot certify.
+      if (r === undefined || silent || vacuous || !CERTIFIABLE.includes(r.disposition)) blocking.push(id);
+    }
+    // discoveryOnly floors have ids.length === 0 and certify by design here (the
+    // requirement-ledger's verifyProfileRequirements is stricter; the runner
+    // consults PROFILE_FLOOR_SCENARIOS.discoveryOnly separately).
+    const discoveryOnly = PROFILE_FLOOR_SCENARIOS[profile]?.discoveryOnly === true;
+    const runtimeDerived = PROFILE_FLOOR_SCENARIOS[profile]?.runtimeDerived === true;
+    // A runtime-derived profile is HELD only when every floor row is a witnessed
+    // pass ("derivable from which scenarios pass" — profiles.md). Anything else
+    // means the host does not hold it: not a rejection, not a blocked claim.
+    const held = ids.length > 0 && witnessedPasses === ids.length;
+    verdicts.push({
+      profile,
+      unclassified: runtimeDerived && !held ? [] : unclassified,
+      blocking: runtimeDerived && !held ? ids.filter((id) => rowById.get(id)?.disposition !== 'executed-pass' || (rowById.get(id)?.assertionCount ?? 0) === 0) : blocking,
+      certifiable: runtimeDerived ? held : discoveryOnly || (ids.length > 0 && blocking.length === 0),
+      runtimeDerived,
+      held,
+    });
+  }
+  return { requirements: rows, totals, verdicts, rejectUnclassified: verdicts.some((v) => v.unclassified.length > 0), ledgerPresent };
+}

package/src/lib/soft-skip.ts

@@ -0,0 +1,89 @@
+/**
+ * RFC 0148 §A — say WHY a scenario returned early.
+ *
+ * A test that returns before its first `expect` reports to vitest as a pass
+ * with zero assertions. Under the ledger that is an UNCLASSIFIED return: the
+ * runner cannot tell "capability not advertised" from "seam not mounted" from
+ * "operator opted out". `behaviorGate` records the first two cases for
+ * profile-gated files; every other early return in the corpus was silent.
+ *
+ * `softSkip(kind, reason)` notes the reason for the CURRENT test file (from
+ * vitest's `expect.getState().testPath`) and returns `undefined`, so an
+ * early return becomes one expression:
+ *
+ *   if (!(await advertised())) return softSkip('inapplicable', 'host does not advertise X');
+ *   if (res.status === 404) return softSkip('blocked', 'seam /v1/host/sample/... not mounted');
+ *
+ * `setup.ts` reads the notes when it records the file: a file whose passes are
+ * all zero-assertion takes the noted disposition (`inapplicable` / `skipped` /
+ * `blocked`, worst-first if mixed) with the joined reasons; a file with real
+ * assertions is `executed-pass` regardless of notes. A zero-assertion file with
+ * NO note at all is recorded `blocked` — "unclassified return; RFC 0148 §A
+ * resolves it to blocked" — and stays UNCLASSIFIED for certification (a floor
+ * row with that disposition still rejects), so the honest bundle row and the
+ * pressure to say why both survive.
+ */
+
+import { expect } from 'vitest';
+import { basename } from 'node:path';
+
+export type SoftSkipKind = 'inapplicable' | 'skipped' | 'blocked';
+
+/** Detail marker the runner writes for a zero-assertion file that noted nothing. */
+export const UNCLASSIFIED_RETURN_DETAIL = 'every test returned early with zero assertions and no recorded reason — unclassified return; RFC 0148 §A resolves it to blocked (add softSkip(kind, reason) at the early return)';
+
+const notes = new Map<string, Array<{ kind: SoftSkipKind; reason: string }>>();
+
+function currentFile(): string | null {
+  try {
+    const p = (expect.getState() as { testPath?: string }).testPath;
+    return typeof p === 'string' && p.length > 0 ? basename(p) : null;
+  } catch {
+    return null;
+  }
+}
+
+/** Note an early return for the current file. Returns undefined so `return softSkip(...)` reads naturally. */
+export function softSkip(kind: SoftSkipKind, reason: string): undefined {
+  const file = currentFile();
+  if (file === null) return undefined;
+  const arr = notes.get(file) ?? [];
+  if (!arr.some((n) => n.kind === kind && n.reason === reason)) arr.push({ kind, reason });
+  notes.set(file, arr);
+  return undefined;
+}
+
+/**
+ * An advertised capability whose observation seam is absent or refused
+ * (404 / 403 / `null` from a seam helper): the host made a claim the suite
+ * cannot check. Default mode notes `blocked` with the reason (RFC 0148 §A);
+ * under `OPENWOP_REQUIRE_BEHAVIOR=true` it FAILS (RFC 0148 §B / RFC 0139 G14
+ * flip) — advertised behaviour MUST be present. Use as `return seamAbsent(...)`.
+ */
+export function seamAbsent(reason: string): undefined {
+  if (process.env['OPENWOP_REQUIRE_BEHAVIOR'] === 'true') {
+    throw new Error(`RFC 0148 §B: advertised behaviour is not observable — ${reason} (OPENWOP_REQUIRE_BEHAVIOR=true fails an advertised-missing seam)`);
+  }
+  return softSkip('blocked', reason);
+}
+
+const RANK: Record<SoftSkipKind, number> = { blocked: 0, skipped: 1, inapplicable: 2 };
+
+/**
+ * The noted disposition for a file, worst-first when mixed (`blocked` beats
+ * `skipped` beats `inapplicable` — a file that could not check one thing is
+ * not certifiable on the strength of another thing being inapplicable), with
+ * the reasons joined. `null` when nothing was noted.
+ */
+export function softSkipDisposition(file: string): { kind: SoftSkipKind; reason: string } | null {
+  const arr = notes.get(file);
+  if (arr === undefined || arr.length === 0) return null;
+  const kind = [...arr].sort((a, b) => RANK[a.kind] - RANK[b.kind])[0]!.kind;
+  const reason = arr.map((n) => (arr.length > 1 ? `[${n.kind}] ${n.reason}` : n.reason)).join('; ');
+  return { kind, reason };
+}
+
+/** Test hook. */
+export function resetSoftSkips(): void {
+  notes.clear();
+}