@openwop/openwop-conformance 1.106.1 → 1.124.0

package/src/scenarios/certification-bundle-redaction.test.ts

@@ -0,0 +1,182 @@
+/**
+ * RFC 0148 §C — `certification-bundle-redaction`: secret canaries never enter
+ * evidence (`threat-model-secret-leakage.md` §SR-1 applied to the one
+ * observable channel the suite itself produces).
+ *
+ * A certification bundle captures the discovery document verbatim, host
+ * self-description, and per-requirement `detail` strings written by scenarios
+ * and gates. Any of those can carry a credential — a host that echoes its
+ * bearer token in an error, a scenario that quotes a response body, an
+ * operator secret in an `OPENWOP_*` variable a scenario reports. RFC 0148 §C
+ * says a canary never enters evidence; the only way to make that TRUE rather
+ * than hoped-for is to scrub the finished document at the emitter with every
+ * secret the run was given, and to have the consumer verifier reject the one
+ * canary it can know without knowing any operator secret.
+ *
+ * Legs:
+ *   - `scrubEvidence` replaces every occurrence of every configured secret —
+ *     nested values AND object keys — with a stable non-reversible marker, and
+ *     reports where; empty secrets are ignored (scrubbing "" would blank the
+ *     document); the longest secret wins when one is a prefix of another.
+ *   - `evidenceSecretsFromEnv` selects `OPENWOP_*` key/token/secret/password
+ *     variables and always includes the conformance canary.
+ *   - `verifyBundleV2` REJECTS a bundle carrying the conformance canary
+ *     anywhere (`secret-canary`), and accepts the scrubbed twin.
+ *   - the emitter's own configuration digest is a digest: the API key it was
+ *     handed is not a substring of anything in the document.
+ *
+ * Server-free, always-on; MUST NOT capability-skip (RFC 0148 §Conformance).
+ */
+
+import { describe, it, expect } from 'vitest';
+import { createHash } from 'node:crypto';
+import { PROFILE_FLOOR_SCENARIOS } from '../lib/profiles.js';
+import { requirementIdForScenario, requirementIdForPrefix } from '../lib/requirement-registry.js';
+import {
+  CONFORMANCE_SECRET_CANARY,
+  evidenceSecretsFromEnv,
+  findLiteral,
+  redactionMarker,
+  scrubEvidence,
+  verifyBundleV2,
+  type BundleV2Like,
+  type BundleV2Requirement,
+} from '../lib/certification-bundle-verify.js';
+
+export const HOST_CALLBACK_NOT_REQUIRED = 'server-free: scrubs and verifies bundle documents built in-process; no host is contacted';
+
+const HEX = 'b'.repeat(64);
+const API_KEY = 'sk-live-0123456789abcdefFEDCBA';
+const DISCOVERY = {
+  protocolVersion: '1.0',
+  supportedEnvelopes: ['clarification.request'],
+  supportedTransports: ['rest'],
+  schemaVersions: { workflow: '1.0' },
+  limits: { clarificationRounds: 3, schemaRounds: 3, envelopesPerTurn: 8 },
+};
+
+function rows(): BundleV2Requirement[] {
+  const f = PROFILE_FLOOR_SCENARIOS['openwop-core-standard'];
+  if (f === undefined) throw new Error('core-standard floor missing');
+  const out: BundleV2Requirement[] = f.required.map((file) => ({ requirementId: requirementIdForScenario(file), scenarioId: file, disposition: 'executed-pass', assertionCount: 5 }));
+  for (const p of f.requiredAnyPrefix ?? []) {
+    out.push({ requirementId: `openwop.scenario.${p}alpha`, scenarioId: `${p}alpha.test.ts`, disposition: 'executed-pass', assertionCount: 2 });
+    out.push({ requirementId: requirementIdForPrefix(p), scenarioId: `${p}*`, disposition: 'executed-pass', assertionCount: 2 });
+  }
+  return out;
+}
+
+function bundle(rs: readonly BundleV2Requirement[], host: Record<string, unknown> = { name: 'h', version: '1' }, document: Record<string, unknown> = DISCOVERY): BundleV2Like {
+  const c = (d: string): number => rs.filter((r) => r.disposition === d).length;
+  return {
+    bundleVersion: '2',
+    suite: { package: '@openwop/openwop-conformance', version: '1.114.0' },
+    host,
+    discovery: { url: 'https://example.invalid/.well-known/openwop', sha256: HEX, document },
+    claimedProfiles: ['openwop-core-standard'],
+    results: {
+      totals: { executedPass: c('executed-pass'), executedFail: c('executed-fail'), skipped: c('skipped'), inapplicable: c('inapplicable'), blocked: c('blocked') },
+      requirements: [...rs],
+    },
+    scenarioManifestSha256: HEX,
+    targetConfigurationSha256: createHash('sha256').update(`base-url|${API_KEY}`).digest('hex'),
+  } as BundleV2Like;
+}
+
+describe('RFC 0148 §C — certification-bundle-redaction: secret canaries never enter evidence', () => {
+  it('scrubEvidence replaces every occurrence of every secret in nested values and reports where', () => {
+    const rs = rows();
+    rs[0] = { ...(rs[0] as BundleV2Requirement), disposition: 'executed-fail', assertionCount: 3, detail: `401 body: {"error":"bad key ${API_KEY}"} (canary ${CONFORMANCE_SECRET_CANARY} echoed)` };
+    const b = bundle(rs);
+    const { value, redactedAt } = scrubEvidence(b, [API_KEY, CONFORMANCE_SECRET_CANARY]);
+    expect(findLiteral(value, API_KEY)).toEqual([]);
+    expect(findLiteral(value, CONFORMANCE_SECRET_CANARY)).toEqual([]);
+    expect(redactedAt).toEqual(['$.results.requirements[0].detail']);
+    const detail = value.results.requirements[0]?.detail ?? '';
+    expect(detail).toContain(redactionMarker(API_KEY));
+    expect(detail).toContain(redactionMarker(CONFORMANCE_SECRET_CANARY));
+    // untouched fields are byte-identical
+    expect(value.discovery).toEqual(b.discovery);
+    expect(value.results.totals).toEqual(b.results.totals);
+  });
+
+  it('scrubs the captured discovery document and host self-description too — evidence is the WHOLE document', () => {
+    const b = bundle(rows(), { name: 'h', version: '1', vendor: `acme (token ${API_KEY})` }, { ...DISCOVERY, ['x-host-debug']: { echo: CONFORMANCE_SECRET_CANARY } });
+    const { value, redactedAt } = scrubEvidence(b, [API_KEY, CONFORMANCE_SECRET_CANARY]);
+    expect(findLiteral(value, API_KEY)).toEqual([]);
+    expect(findLiteral(value, CONFORMANCE_SECRET_CANARY)).toEqual([]);
+    expect([...redactedAt].sort()).toEqual(['$.discovery.document.x-host-debug.echo', '$.host.vendor']);
+  });
+
+  it('scrubs object KEYS as well as values — a secret used as a map key is still a secret', () => {
+    const doc = { ...DISCOVERY, ['x-host-keys']: { [API_KEY]: 'tenant-a' } };
+    const { value } = scrubEvidence(bundle(rows(), { name: 'h', version: '1' }, doc), [API_KEY]);
+    expect(findLiteral(value, API_KEY)).toEqual([]);
+    const keys = Object.keys((value.discovery.document as Record<string, Record<string, unknown>>)['x-host-keys'] ?? {});
+    expect(keys).toEqual([redactionMarker(API_KEY)]);
+  });
+
+  it('empty and whitespace-only secrets are ignored (scrubbing "" would blank every string)', () => {
+    const b = bundle(rows());
+    const { value, redactedAt } = scrubEvidence(b, ['', '   ']);
+    expect(value).toEqual(b);
+    expect(redactedAt).toEqual([]);
+  });
+
+  it('when one secret is a prefix of another the longer one is scrubbed whole (no partial marker inside a marker)', () => {
+    const short = 'abc123';
+    const long = 'abc123-longer-secret';
+    const { value } = scrubEvidence({ detail: `x ${long} y ${short} z` }, [short, long]);
+    expect(value.detail).toBe(`x ${redactionMarker(long)} y ${redactionMarker(short)} z`);
+  });
+
+  it('the redaction marker is stable, non-reversible, and does not contain the secret', () => {
+    const m = redactionMarker(API_KEY);
+    expect(m).toBe(redactionMarker(API_KEY));
+    expect(m).not.toContain(API_KEY);
+    expect(m).toMatch(/^«redacted:[0-9a-f]{12}»$/);
+    expect(redactionMarker('other')).not.toBe(m);
+  });
+
+  it('evidenceSecretsFromEnv selects OPENWOP_* key/token/secret/password variables, the handed credential, and ALWAYS the canary', () => {
+    const env = {
+      OPENWOP_API_KEY: 'k1',
+      OPENWOP_MESSAGING_BRIDGE_TOKEN: 't1',
+      OPENWOP_DB_PASSWORD: 'p1',
+      OPENWOP_CLIENT_SECRET: 's1',
+      OPENWOP_BASE_URL: 'https://example.invalid', // not a secret
+      OPENWOP_REQUIRE_BEHAVIOR: 'true',
+      PATH: '/usr/bin',
+      SOME_OTHER_TOKEN: 'not-ours',
+    } as NodeJS.ProcessEnv;
+    const secrets = evidenceSecretsFromEnv(env, [API_KEY, undefined, '']);
+    expect(secrets.sort()).toEqual([API_KEY, 'k1', 'p1', 's1', 't1', CONFORMANCE_SECRET_CANARY].sort());
+  });
+
+  it('verifyBundleV2 REJECTS a bundle carrying the conformance canary anywhere, and accepts the scrubbed twin', () => {
+    const rs = rows();
+    rs[1] = { ...(rs[1] as BundleV2Requirement), detail: `resolved ${CONFORMANCE_SECRET_CANARY} in plain text` };
+    const leaked = bundle(rs);
+    const v = verifyBundleV2(leaked);
+    expect(v.evidenceValid).toBe(false);
+    expect(v.rejections.map((r) => r.kind)).toEqual(['secret-canary']);
+    expect(v.rejections[0]?.detail).toContain('$.results.requirements[1].detail');
+
+    const { value: clean } = scrubEvidence(leaked, [CONFORMANCE_SECRET_CANARY]);
+    const v2 = verifyBundleV2(clean);
+    expect(v2.evidenceValid).toBe(true);
+    expect(v2.certified).toBe(true);
+  });
+
+  it('the canary in a discovery-document KEY is still a rejection (keys are evidence)', () => {
+    const doc = { ...DISCOVERY, [`x-host-${CONFORMANCE_SECRET_CANARY}`]: true };
+    const v = verifyBundleV2(bundle(rows(), { name: 'h', version: '1' }, doc));
+    expect(v.rejections.some((r) => r.kind === 'secret-canary')).toBe(true);
+  });
+
+  it('the target-configuration digest is a digest: the API key is not a substring of any string in the document', () => {
+    const b = bundle(rows());
+    expect((b as unknown as { targetConfigurationSha256: string }).targetConfigurationSha256).toMatch(/^[0-9a-f]{64}$/);
+    expect(findLiteral(b, API_KEY)).toEqual([]);
+  });
+});

package/src/scenarios/certification-floor-enforcement.test.ts

@@ -38,17 +38,41 @@ const bundleClaiming = (profiles: readonly string[], passed: readonly string[],
 
 describe('RFC 0148 §C — floor enforcement is not vacuous', () => {
   it('a profile with NO floor definition is unprovable, not proven', () => {
-    // `openwop-interrupts` is deliberately untranscribed: its prose section does
-    // not yet name a settled floor set. Claiming it must therefore fail — the
-    // corpus cannot substantiate it, which is a different thing from the host
-    // having failed something.
-    const v = verifyBundleProfile(bundleClaiming(['openwop-interrupts'], []), 'openwop-interrupts');
-    expect(v.floorUnspecified, 'no floor set is defined for openwop-interrupts').toBe(true);
+    // A profile the floor map does not know (here a name outside the catalog;
+    // until 2026-08-16 `openwop-interrupts` played this role — its floor is now
+    // transcribed, RFC 0148 §C G7). Claiming it must fail — the corpus cannot
+    // substantiate it, which is a different thing from the host having failed
+    // something.
+    const v = verifyBundleProfile(bundleClaiming(['openwop-not-in-catalog'], []), 'openwop-not-in-catalog');
+    expect(v.floorUnspecified, 'no floor set is defined for a profile outside the floor map').toBe(true);
     expect(v.floorProven, 'RFC 0148 §C: an undefined floor MUST NOT satisfy the floor condition').toBe(false);
     expect(v.valid).toBe(false);
     expect(v.missingFloor, 'nothing is "missing" — the floor was never evaluable').toEqual([]);
   });
 
+  it('G7: a discovery-conditional floor (openwop-replay-fork) requires the branch the document advertises — and nothing when it advertises none', () => {
+    const doc = (modes: string[]) => ({ protocolVersion: '1.0', supportedEnvelopes: [], schemaVersions: {}, limits: { clarificationRounds: 1, schemaRounds: 1, envelopesPerTurn: 1 }, replay: { supported: true, modes } });
+    const claim = (modes: string[], passed: string[]) => ({ discovery: { document: doc(modes) }, claimedProfiles: ['openwop-replay-fork'], results: { passed, failed: [] } });
+    // replay-only host: replayDeterminism suffices; replay-fork is NOT required
+    let v = verifyBundleProfile(claim(['replay'], ['replayDeterminism.test.ts', 'replay-side-effect-suppression.test.ts']), 'openwop-replay-fork');
+    expect(v.floorUnspecified).toBe(false);
+    expect(v.floorProven).toBe(true);
+    // determinism alone does NOT prove replay mode: caveat 1 (no re-fire) is part of the branch
+    v = verifyBundleProfile(claim(['replay'], ['replayDeterminism.test.ts']), 'openwop-replay-fork');
+    expect(v.floorProven).toBe(false);
+    expect(v.missingFloor).toEqual(['replay-side-effect-suppression.test.ts']);
+    // branch-only host: replay-fork suffices
+    v = verifyBundleProfile(claim(['branch'], ['replay-fork.test.ts']), 'openwop-replay-fork');
+    expect(v.floorProven).toBe(true);
+    // both advertised: both required
+    v = verifyBundleProfile(claim(['replay', 'branch'], ['replay-fork.test.ts', 'replay-side-effect-suppression.test.ts']), 'openwop-replay-fork');
+    expect(v.floorProven).toBe(false);
+    expect(v.missingFloor).toEqual(['replayDeterminism.test.ts']);
+    // a mode the floor does not know: nothing required → unprovable, not proven
+    v = verifyBundleProfile(claim(['exotic'], []), 'openwop-replay-fork');
+    expect(v.floorProven).toBe(false);
+  });
+
   it('a discovery-only profile with an EXPLICIT empty floor is proven by its predicate alone', () => {
     // The distinction the fix turns on: `openwop-fixtures` is discovery-payload
     // -only by `profiles.md`, so an empty floor is a decision on record. Without

package/src/scenarios/chain-compensation-expansion.test.ts

@@ -0,0 +1,243 @@
+/**
+ * RFC 0157 (RFC 0013 revision × RFC 0151 §B) — a chain fragment can carry a
+ * compensator, and the chain-level policy survives expansion.
+ *
+ * Measured before this landed: `workflow-chain-pack-manifest.schema.json`
+ * `$defs.FragmentNode` carried exactly `id/typeId/name/position/config/inputs`
+ * and the manifest mentioned `compensation` nowhere — so on the workflow shape a
+ * chain-first host actually ships, no node could own an inverse action and no
+ * unwind could occur; RFC 0151 §B was reachable only through a hand-authored
+ * `POST /v1/workflows`. The `FragmentNode` description even carried a
+ * maintenance note saying new `WorkflowNode` fields must be mirrored here, and
+ * `compensation` (b4796755) was not.
+ *
+ * What this file pins:
+ *
+ *   - schema: `FragmentNode.compensation` is a byte-mirror of
+ *     `WorkflowNode.compensation` (apart from its own description) and
+ *     `WorkflowChain.compensation` is a byte-mirror of
+ *     `compensation-policy.schema.json` — mirrors, not `$ref`s, so the manifest
+ *     stays self-contained (the S14 lesson: a new cross-file `$ref` breaks every
+ *     fixed-list validator downstream);
+ *   - a manifest with both surfaces validates; a foreign key inside either is
+ *     rejected;
+ *   - expansion (`carryCompensation`, the spec-authoritative reference below the
+ *     mirrored core): the declaration survives verbatim onto the expanded node,
+ *     `{{params.*}}` inside `inputMapping` are substituted, fragment node-id
+ *     references inside `inputMapping` are rewritten with the expansion prefix
+ *     exactly as edge refs are, an unresolvable `compensation.nodeTypeId` fails
+ *     with `chain_unresolvable_typeid` BEFORE any node is emitted, and the
+ *     chain-level policy is copied when the parent has none / accepted when
+ *     equal / refused with `chain_compensation_policy_conflict` otherwise.
+ *
+ * Server-free. The host half (a host's own expander honouring the same rules)
+ * is witnessed by the live `workflow-chain-host-expansion` path once a host
+ * adopts RFC 0157.
+ *
+ * @see spec/v1/workflow-chain-packs.md §"Compensation (RFC 0157)"
+ * @see RFCS/0157-chain-fragments-carry-compensation.md
+ */
+
+import { describe, it, expect } from 'vitest';
+import { readFileSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import Ajv2020 from 'ajv/dist/2020.js';
+import { SCHEMAS_DIR } from '../lib/paths.js';
+import {
+  expandChain,
+  carryCompensation,
+  expandChainWithCompensation,
+  ChainUnresolvableTypeIdError,
+  ChainCompensationPolicyConflictError,
+  type WorkflowChainWithCompensation,
+  type ChainCompensationPolicy,
+  type FragmentNodeCompensation,
+} from '../lib/workflow-chain-expansion.js';
+
+function schema(name: string): Record<string, unknown> {
+  return JSON.parse(readFileSync(join(SCHEMAS_DIR, name), 'utf8')) as Record<string, unknown>;
+}
+function stripDescription(o: unknown): unknown {
+  if (Array.isArray(o)) return o.map(stripDescription);
+  if (o !== null && typeof o === 'object') {
+    const out: Record<string, unknown> = {};
+    for (const [k, v] of Object.entries(o as Record<string, unknown>)) {
+      if (k === 'description' || k === '$schema' || k === '$id' || k === 'title') continue;
+      out[k] = stripDescription(v);
+    }
+    return out;
+  }
+  return o;
+}
+function manifestValidator() {
+  const ajv = new Ajv2020({ strict: false, allErrors: true });
+  for (const f of readdirSync(SCHEMAS_DIR).filter((f) => f.endsWith('.schema.json'))) ajv.addSchema(schema(f), f);
+  return ajv.getSchema('workflow-chain-pack-manifest.schema.json') ?? ajv.compile(schema('workflow-chain-pack-manifest.schema.json'));
+}
+
+const POLICY: ChainCompensationPolicy = { triggers: ['node-failure', 'run-cancel'], approvalScope: 'declared' };
+
+const CHAIN: WorkflowChainWithCompensation = {
+  chainId: 'vendor.shop.reserveAndCharge',
+  version: '1.0.0',
+  label: 'Reserve + charge',
+  description: 'reserve inventory, then charge; both compensable',
+  parameters: { type: 'object', properties: { sku: { type: 'string' } } },
+  dag: {
+    nodes: [
+      {
+        id: 'reserve',
+        typeId: 'vendor.shop.reserve',
+        config: { sku: '{{params.sku}}' },
+        compensation: {
+          nodeTypeId: 'vendor.shop.release',
+          inputMapping: { reservationId: '${nodes.reserve.output.id}', sku: '{{params.sku}}' },
+          retry: { maxAttempts: 3, backoffMs: 250 },
+        },
+      },
+      {
+        id: 'charge',
+        typeId: 'vendor.pay.charge',
+        compensation: { nodeTypeId: 'vendor.pay.refund', inputMapping: { chargeId: 'nodes.charge.output.chargeId' }, requiresApproval: true },
+      },
+      { id: 'notify', typeId: 'core.noop' },
+    ],
+    edges: [
+      { from: 'reserve', to: 'charge' },
+      { from: 'charge', to: 'notify' },
+    ],
+  },
+  compensation: POLICY,
+};
+
+const RESOLVE_ALL = () => true;
+const CTX = { expansionId: 'e1', params: { sku: 'SKU-9' }, isTypeIdResolvable: RESOLVE_ALL };
+
+function manifestWith(chain: unknown) {
+  return {
+    name: 'vendor.shop.chains',
+    version: '1.0.0',
+    kind: 'workflow-chain',
+    description: 'test',
+    engines: { openwop: '>=1.0' },
+    chains: [chain],
+  };
+}
+
+describe('RFC 0157 — schema: the chain manifest mirrors the compensation shapes (self-contained, no cross-file $ref)', () => {
+  it('FragmentNode.compensation is a byte-mirror of WorkflowNode.compensation', () => {
+    const chainSchema = schema('workflow-chain-pack-manifest.schema.json') as {
+      $defs: { FragmentNode: { properties: Record<string, unknown> }; WorkflowChain: { properties: Record<string, unknown> } };
+    };
+    const wd = schema('workflow-definition.schema.json') as { $defs: { WorkflowNode: { properties: Record<string, unknown> } } };
+    expect(chainSchema.$defs.FragmentNode.properties['compensation'], 'FragmentNode MUST carry `compensation`').toBeDefined();
+    expect(stripDescription(chainSchema.$defs.FragmentNode.properties['compensation'])).toEqual(
+      stripDescription(wd.$defs.WorkflowNode.properties['compensation']),
+    );
+  });
+
+  it('WorkflowChain.compensation is a byte-mirror of compensation-policy.schema.json', () => {
+    const chainSchema = schema('workflow-chain-pack-manifest.schema.json') as { $defs: { WorkflowChain: { properties: Record<string, unknown> } } };
+    const policy = schema('compensation-policy.schema.json');
+    expect(chainSchema.$defs.WorkflowChain.properties['compensation'], 'WorkflowChain MUST carry the policy').toBeDefined();
+    expect(stripDescription(chainSchema.$defs.WorkflowChain.properties['compensation'])).toEqual(stripDescription(policy));
+  });
+
+  it('the manifest stays self-contained — no cross-file $ref was introduced', () => {
+    const raw = readFileSync(join(SCHEMAS_DIR, 'workflow-chain-pack-manifest.schema.json'), 'utf8');
+    const refs = [...raw.matchAll(/"\$ref":\s*"([^"]+)"/g)].map((m) => m[1]);
+    for (const r of refs) expect(r.startsWith('#/'), `cross-file $ref ${r} would break fixed-list validators downstream`).toBe(true);
+  });
+
+  it('a manifest declaring both surfaces validates; a foreign key inside either is rejected', () => {
+    const validate = manifestValidator();
+    expect(validate(manifestWith(CHAIN)), JSON.stringify(validate.errors)).toBe(true);
+    const badNode = structuredClone(CHAIN) as unknown as { dag: { nodes: Array<Record<string, unknown>> } };
+    (badNode.dag.nodes[0]!['compensation'] as Record<string, unknown>)['rollback'] = true;
+    expect(validate(manifestWith(badNode)), 'the mirrored node declaration MUST stay closed').toBe(false);
+    const badPolicy = structuredClone(CHAIN) as unknown as { compensation: Record<string, unknown> };
+    badPolicy.compensation['approvalScope'] = 'none';
+    expect(validate(manifestWith(badPolicy)), 'the mirrored policy keeps the escalate-only approval scope').toBe(false);
+    const noTriggers = structuredClone(CHAIN) as unknown as { compensation: Record<string, unknown> };
+    noTriggers.compensation = {};
+    expect(validate(manifestWith(noTriggers)), 'a policy without triggers is not a policy').toBe(false);
+  });
+});
+
+describe('RFC 0157 — expansion carries the declaration and the policy', () => {
+  it('the declaration survives verbatim onto the expanded node, params substituted, node-id refs rewritten', () => {
+    const out = expandChainWithCompensation(CHAIN, CTX);
+    const nodes = out.nodes as ReadonlyArray<(typeof out.nodes)[number] & { compensation?: FragmentNodeCompensation }>;
+    const reserve = nodes.find((n) => n.id.endsWith('_reserve'));
+    const charge = nodes.find((n) => n.id.endsWith('_charge'));
+    const notify = nodes.find((n) => n.id.endsWith('_notify'));
+    expect(reserve?.compensation?.nodeTypeId).toBe('vendor.shop.release');
+    expect(reserve?.compensation?.retry).toEqual({ maxAttempts: 3, backoffMs: 250 });
+    // {{params.sku}} substituted (5b); ${nodes.reserve…} rewritten with the prefix (6b)
+    expect(reserve?.compensation?.inputMapping?.['sku']).toBe('SKU-9');
+    expect(reserve?.compensation?.inputMapping?.['reservationId']).toBe(`\${nodes.${reserve?.id}.output.id}`);
+    expect(charge?.compensation?.inputMapping?.['chargeId']).toBe(`nodes.${charge?.id}.output.chargeId`);
+    expect(charge?.compensation?.requiresApproval).toBe(true);
+    expect(notify?.compensation, 'a node that declared none gains none').toBeUndefined();
+    // the mirrored core is untouched: plain expandChain still knows nothing of it
+    const plain = expandChain(CHAIN, CTX);
+    expect((plain.nodes[0] as { compensation?: unknown }).compensation).toBeUndefined();
+  });
+
+  it('a reference to a NON-fragment node id inside inputMapping passes through unchanged', () => {
+    const chain = structuredClone(CHAIN);
+    (chain.dag.nodes[0]!.compensation as { inputMapping: Record<string, unknown> }).inputMapping = {
+      parentRef: '${nodes.upstream-in-parent.output.x}',
+    };
+    const out = expandChainWithCompensation(chain, CTX);
+    const nodes = out.nodes as ReadonlyArray<(typeof out.nodes)[number] & { compensation?: FragmentNodeCompensation }>;
+    const reserve = nodes.find((n) => n.id.endsWith('_reserve'));
+    expect(reserve?.compensation?.inputMapping?.['parentRef']).toBe('${nodes.upstream-in-parent.output.x}');
+  });
+
+  it('an unresolvable compensation.nodeTypeId fails with chain_unresolvable_typeid before any node is emitted', () => {
+    const resolvable = (t: string) => t !== 'vendor.pay.refund';
+    let thrown: unknown;
+    try {
+      expandChainWithCompensation(CHAIN, { ...CTX, isTypeIdResolvable: resolvable });
+    } catch (e) {
+      thrown = e;
+    }
+    expect(thrown).toBeInstanceOf(ChainUnresolvableTypeIdError);
+    expect((thrown as ChainUnresolvableTypeIdError).typeId).toBe('vendor.pay.refund');
+    expect(String((thrown as Error).message)).toContain('chain_unresolvable_typeid');
+  });
+
+  it('the chain policy becomes settings.compensation when the parent has none', () => {
+    const out = expandChainWithCompensation(CHAIN, CTX);
+    expect(out.settingsCompensation).toEqual(POLICY);
+    expect(out.settingsCompensation, 'a copy, not the same object').not.toBe(POLICY);
+  });
+
+  it('a parent policy that is deep-equal (any key order) is accepted; a differing one is refused, never merged', () => {
+    const sameOtherOrder: ChainCompensationPolicy = { approvalScope: 'declared', triggers: ['node-failure', 'run-cancel'] };
+    expect(expandChainWithCompensation(CHAIN, CTX, sameOtherOrder).settingsCompensation).toEqual(sameOtherOrder);
+    const differs: ChainCompensationPolicy = { triggers: ['node-failure'] };
+    let thrown: unknown;
+    try {
+      expandChainWithCompensation(CHAIN, CTX, differs);
+    } catch (e) {
+      thrown = e;
+    }
+    expect(thrown).toBeInstanceOf(ChainCompensationPolicyConflictError);
+    expect((thrown as ChainCompensationPolicyConflictError).code).toBe('chain_compensation_policy_conflict');
+  });
+
+  it('a chain with no policy inherits the parent policy (or none) and carries no declaration it did not make', () => {
+    const chain = structuredClone(CHAIN);
+    delete (chain as { compensation?: unknown }).compensation;
+    for (const n of chain.dag.nodes as unknown as Array<{ compensation?: unknown }>) delete n.compensation;
+    const parent: ChainCompensationPolicy = { triggers: ['operator-request'] };
+    const withParent = expandChainWithCompensation(chain, CTX, parent);
+    expect(withParent.settingsCompensation).toBe(parent);
+    const nodes = withParent.nodes as ReadonlyArray<{ compensation?: unknown }>;
+    expect(nodes.every((n) => n.compensation === undefined)).toBe(true);
+    const withoutParent = carryCompensation(chain, expandChain(chain, CTX), CTX);
+    expect(withoutParent.settingsCompensation).toBeUndefined();
+  });
+});

package/src/scenarios/commitment-fired.test.ts

@@ -18,6 +18,7 @@
  */
 
 import { describe, it, expect } from 'vitest';
+import { softSkip } from '../lib/soft-skip.js';
 import { driver } from '../lib/driver.js';
 
 interface CommitmentCaps {
@@ -44,14 +45,14 @@ async function commitmentsSupported(): Promise<boolean> {
 
 describe('commitment-fired: fire contract (RFC 0068 §C, capability-gated)', () => {
   it('a fired commitment emits a content-free event with memory provenance, exactly once', async () => {
-    if (!(await commitmentsSupported())) return; // capability absent — gated skip
+    if (!(await commitmentsSupported())) return softSkip('inapplicable', 'capability absent — gated skip');
 
     const res = await driver.post('/v1/host/sample/commitment/fire', {
       memoryRef: 'mem://conformance/commitments',
       condition: 'predicate',
       includeIntentionCanary: true,
     });
-    if (res.status === 404 || res.status === 501) return; // seam not wired — soft-skip
+    if (res.status === 404 || res.status === 501) return softSkip('blocked', 'seam not wired — soft-skip');
 
     expect(res.status, driver.describe('RFC 0068 §C', 'an advertised commitment seam MUST succeed')).toBe(200);
     const r = res.json as FireResult;

package/src/scenarios/compensation-behavior.test.ts

@@ -32,6 +32,11 @@
  *   - **No provider bodies or credentials in events.** §D and §G. These events
  *     land in the durable log, which is the least revocable place a credential
  *     can go.
+ *   - **The snapshot rollup agrees with the events.** §D `compensationStatus` on
+ *     `RunSnapshot` (UQ3 resolved 2026-08-16) is the deterministic fold defined in
+ *     `spec/v1/compensation.md`; an advertising host MUST carry it, and a value
+ *     that disagrees with the emitted events is a projection bug a client would
+ *     act on.
  */
 
 import { describe, it, expect } from 'vitest';
@@ -140,6 +145,64 @@ describe('RFC 0151 §C — compensation lifecycle (capability-gated behavior)',
     ).toBe(0);
   });
 
+  it('the run snapshot carries the §D rollup, and it agrees with the events', async () => {
+    if (!behaviorGate(PROFILE, await advertised())) return;
+    const seam = await driver.post('/v1/host/sample/test/compensation/unwind', {});
+    if (seam.status === 404) return; // covered by the seam assertion above
+    const body = seam.json as { runId?: string; events?: { type: string }[] };
+    expect(
+      typeof body.runId === 'string' && body.runId.length > 0,
+      driver.describe(
+        'host-sample-test-seams.md §21',
+        'the unwind seam MUST return the `runId` it created — without it the §D rollup has no ' +
+          'black-box path to a witness and lands as another shape-only claim',
+      ),
+    ).toBe(true);
+    const snap = await driver.get(`/v1/runs/${encodeURIComponent(body.runId ?? '')}`);
+    expect(snap.status, driver.describe('rest-endpoints.md', 'GET /v1/runs/{runId} for the seam run')).toBe(200);
+    const status = (snap.json as { compensationStatus?: unknown }).compensationStatus;
+    expect(
+      status,
+      driver.describe(
+        'compensation.md §"Run rollup: compensationStatus"',
+        'a host that advertises `compensation` MUST include `compensationStatus` on every snapshot ' +
+          '(`none` when idle) — presence is the wire witness of the advert',
+      ),
+    ).toBeDefined();
+    const types = (body.events ?? []).map((e) => e.type);
+    // The fold, applied to what the seam reports: a clean unwind ends `completed`; a
+    // recorded `manual_intervention_required` dominates; a plan that never started is
+    // `pending`. Anything else the seam produced is a shape this leg cannot judge from
+    // outside, and it says so rather than passing.
+    const expected = types.includes('compensation.manual_intervention_required')
+      ? 'manual'
+      : types.includes('compensation.completed')
+        ? 'completed'
+        : types.includes('compensation.started')
+          ? null
+          : types.includes('compensation.requested')
+            ? 'pending'
+            : 'none';
+    if (expected === null) {
+      expect(
+        ['running', 'partial', 'failed'].includes(String(status)),
+        driver.describe(
+          'compensation.md §"Run rollup: compensationStatus"',
+          'an unwind that started and did not complete MUST report `running`, `partial`, or `failed` ' +
+            `— got ${String(status)}`,
+        ),
+      ).toBe(true);
+      return;
+    }
+    expect(
+      status,
+      driver.describe(
+        'compensation.md §"Run rollup: compensationStatus"',
+        `the rollup MUST be the deterministic fold of the compensation.* events — events ${JSON.stringify(types)} fold to \`${expected}\``,
+      ),
+    ).toBe(expected);
+  });
+
   it('compensation events carry no provider bodies or credentials', async () => {
     if (!behaviorGate(PROFILE, await advertised())) return;
     const seam = await driver.post('/v1/host/sample/test/compensation/unwind', {});