@openwop/openwop-conformance 1.106.1 → 1.124.0

package/schemas/workflow-chain-pack-manifest.schema.json

@@ -171,6 +171,93 @@
             "$ref": "#/$defs/ProducedVariable"
           },
           "description": "RFC 0133 §2.2. OPTIONAL. Run-scoped values a node writes to the executor's variable bag during the run and downstream nodes read by name via a `{ type:\"variable\", variableName }` input binding — where the value is NOT an author-time `parameter` and rides no typed output port. Prefer edges (a typed `sourceOutput`→`targetInput` hand-off) wherever a node exposes a value on a port; `producedVariables` is only for values written to the run bag with no typed port. On expansion the host emits these into `WorkflowDefinition.variables[]` as run-scoped entries (name + type, no value). Any `{ type:\"variable\" }` read of an UNDECLARED name (not here and not a materialized parameter) is a `variable_undeclared` manifest error. See `workflow-chain-packs.md` §\"Produced (run-scoped) variables (RFC 0133)\"."
+        },
+        "compensation": {
+          "type": "object",
+          "description": "RFC 0157 (RFC 0013 revision × RFC 0151 §B) — the chain-level compensation POLICY, MIRROR of `compensation-policy.schema.json` (copied inline; a conformance leg asserts equality apart from this description). On expansion it becomes the registered definition's `settings.compensation`: if the parent has none, the host MUST copy it; if the parent already carries one that is not deep-equal, expansion MUST fail `chain_compensation_policy_conflict` — a merged policy nobody wrote is exactly the guess-at-a-contract failure the policy exists to prevent. Absent ⇒ the chain expresses no policy and inherits the parent's (or none).",
+          "additionalProperties": false,
+          "required": [
+            "triggers"
+          ],
+          "properties": {
+            "profileVersion": {
+              "type": "string",
+              "pattern": "^[1-9][0-9]*$",
+              "description": "The RFC 0151 profile version this policy was authored against. OPTIONAL; when present it MUST equal the host's advertised `capabilities.compensation.profileVersion` or registration fails, because `profileVersion` is part of the inverse-action identity (§C) and a workflow authored under one ordering rule MUST NOT mint identities under another."
+            },
+            "orderingModel": {
+              "type": "string",
+              "enum": [
+                "reverse-completion",
+                "dependency-graph"
+              ],
+              "default": "reverse-completion",
+              "description": "RFC 0151 §A/§C. `reverse-completion` (default) orders inverse actions by descending durable forward-completion sequence; `dependency-graph` MUST be a DAG and preserve reverse dependency order. The value MUST be one of the host's advertised `capabilities.compensation.orderingModels[]`; a host MUST refuse the workflow at registration otherwise, so an unwind never discovers at failure time that its ordering rule is unimplemented."
+            },
+            "triggers": {
+              "type": "array",
+              "minItems": 1,
+              "uniqueItems": true,
+              "items": {
+                "type": "string",
+                "enum": [
+                  "node-failure",
+                  "run-cancel",
+                  "cap-breach",
+                  "operator-request"
+                ]
+              },
+              "description": "Which events start an unwind. REQUIRED and closed — a policy that names no trigger is not a policy, and an open string here would let a host and an author disagree about a word. `node-failure`: a node reaches terminal failure after its own RFC 0009 retry policy and the run cannot continue. `run-cancel`: an RFC 0094 cancel is accepted while committed effects exist. `cap-breach`: an RFC 0058 / RFC 0084 `cap.breached` hard stop. `operator-request`: an authorized operator explicitly requests an unwind (§E) — MUST be authorized per RFC 0049, binding tenant, principal, action, and plan version. A trigger not listed here does NOT start an unwind; the run ends with its committed effects in place and `compensationStatus: none`, which is the honest shape — no generic rollback is inferred from an undeclared trigger (RFC 0151 §Compatibility)."
+            },
+            "retry": {
+              "type": "object",
+              "additionalProperties": false,
+              "description": "Defaults for inverse actions whose node-level `compensation.retry` is absent. A node's own bounds always win. Retries reuse the inverse action's stable identity (§C) — never a fresh one, or a transient refund failure mints a second refund.",
+              "properties": {
+                "maxAttempts": {
+                  "type": "integer",
+                  "minimum": 1
+                },
+                "backoffMs": {
+                  "type": "integer",
+                  "minimum": 0
+                }
+              }
+            },
+            "timeoutMs": {
+              "type": "integer",
+              "minimum": 1,
+              "description": "Wall-clock ceiling per inverse-action attempt, in milliseconds. A timed-out attempt counts against `retry.maxAttempts`; it is not a distinct outcome."
+            },
+            "exhaustedDisposition": {
+              "type": "string",
+              "enum": [
+                "record-outcome",
+                "manual-intervention"
+              ],
+              "default": "record-outcome",
+              "description": "RFC 0151 §E — what the host does when an inverse action exhausts its retries. Either way the run MUST route to RFC 0053 dead-letter handling and the run's `compensationStatus` follows the §D fold (`partial` or `failed`). `record-outcome` (default): record the failure and continue unwinding the remaining actions. `manual-intervention`: additionally emit `compensation.manual_intervention_required` and stop issuing further inverse actions until an authorized operator retries, skips with recorded justification, substitutes a registered action, or terminates as uncompensated — the rollup reads `manual` while that is unresolved. Requires `capabilities.compensation.manualIntervention: true`; a host that does not advertise it MUST refuse a policy that selects it."
+            },
+            "approvalScope": {
+              "type": "string",
+              "enum": [
+                "declared",
+                "all"
+              ],
+              "default": "declared",
+              "description": "RFC 0151 §E. `declared` (default): only inverse actions whose node sets `compensation.requiresApproval: true` create an RFC 0051 approval interrupt. `all`: every inverse action does, regardless of the node's declaration. This value can only ESCALATE — there is no `none`, because a policy MUST NOT strip an approval a node declared for itself (RFC 0147 R9: an inverse action can itself be harmful)."
+            },
+            "onParentCancel": {
+              "type": "string",
+              "enum": [
+                "continue",
+                "pause",
+                "manual"
+              ],
+              "default": "continue",
+              "description": "RFC 0151 §C — cancellation of the parent run MUST NOT silently abandon an active compensation. `continue`: the unwind runs to its terminal rollup. `pause`: emit `compensation.paused` and hold for authorized intervention (the run's own `status` carries the wait). `manual`: emit `compensation.manual_intervention_required` and stop; rollup reads `manual`. `pause`/`manual` require `capabilities.compensation.manualIntervention: true`."
+            }
+          }
         }
       },
       "additionalProperties": false,
@@ -365,6 +452,44 @@
           "description": "Per-port input wiring. String values MAY contain `{{params.<name>}}` placeholders.",
           "additionalProperties": true,
           "$comment": "Open by design — port shapes are per-typeId, same reasoning as `config` above."
+        },
+        "compensation": {
+          "type": "object",
+          "description": "RFC 0157 (RFC 0013 revision × RFC 0151 §B) — MIRROR of `workflow-definition.schema.json#/$defs/WorkflowNode/properties/compensation`, copied inline so this manifest stays self-contained (no cross-file `$ref`); a conformance leg asserts the two stay byte-equal apart from this description. The inverse action for this fragment node. `nodeTypeId` MUST resolve at expansion (step 3) exactly as `typeId` does — `chain_unresolvable_typeid`; `inputMapping` strings MAY carry `{{params.<name>}}` and MUST be substituted at expansion (step 5); node-id references inside `inputMapping` MUST be rewritten with the expansion prefix (step 6). Survives expansion verbatim into the registered `WorkflowNode.compensation`.",
+          "additionalProperties": false,
+          "required": [
+            "nodeTypeId"
+          ],
+          "properties": {
+            "nodeTypeId": {
+              "type": "string",
+              "minLength": 1,
+              "description": "Node type implementing the inverse action. MUST resolve at registration time."
+            },
+            "inputMapping": {
+              "type": "object",
+              "description": "Derived from recorded facts only — node outputs and run inputs already in the event log.",
+              "additionalProperties": true
+            },
+            "retry": {
+              "type": "object",
+              "additionalProperties": false,
+              "properties": {
+                "maxAttempts": {
+                  "type": "integer",
+                  "minimum": 1
+                },
+                "backoffMs": {
+                  "type": "integer",
+                  "minimum": 0
+                }
+              }
+            },
+            "requiresApproval": {
+              "type": "boolean",
+              "description": "RFC 0151 §C — an inverse action can itself be harmful (RFC 0147 R9), so it may be gated behind the same approval surface as a forward effect."
+            }
+          }
         }
       },
       "additionalProperties": false

package/schemas/workflow-definition.schema.json

@@ -814,6 +814,10 @@
           "type": "integer",
           "minimum": 1,
           "default": 5
+        },
+        "compensation": {
+          "$ref": "compensation-policy.schema.json",
+          "description": "RFC 0151 §B — the workflow-level compensation policy (WHEN an unwind starts and HOW it runs). OPTIONAL and capability-gated: a host that advertises `capabilities.compensation` MUST validate it at registration; a host that does not MUST refuse the workflow with `capability_required` rather than accept a policy it will never honour. Node-level `nodes[].compensation` declarations remain valid without it — they describe the inverse action; this key requests the unwind."
         }
       }
     }

package/src/cli.ts

@@ -33,10 +33,14 @@ import { tmpdir } from 'node:os';
 import Ajv2020 from 'ajv/dist/2020.js';
 import addFormats from 'ajv-formats';
 import { SCHEMAS_DIR } from './lib/paths.js';
+import { readLedgerFile } from './lib/requirement-ledger.js';
+import { deriveRequirementDispositions } from './lib/scenario-disposition.js';
+import { scrubEvidence, evidenceSecretsFromEnv, verifyBundleV2 } from './lib/certification-bundle-verify.js';
 import {
   deriveProfiles,
   isCoreStandard,
   agentPlatformStatus,
+  DEPRECATED_PROFILE_ALIASES,
   type DiscoveryPayload,
 } from './lib/profiles.js';
 
@@ -284,9 +288,14 @@ async function runCertify(args: ParsedArgs, baseUrl: string, apiKey: string): Pr
   const conformanceRoot = resolvePath(here, '..');
   const reportDir = mkdtempSync(join(tmpdir(), 'owp-certify-'));
   const reportFile = join(reportDir, 'vitest-report.json');
+  // RFC 0148 §A ledger sink (S6): every scenario file records its disposition
+  // (and assertion count) here; the runner reads it after the run so bundle v2
+  // rows come from what scenarios RECORDED, not from per-file pass/fail/skip.
+  const ledgerFile = join(reportDir, 'requirement-ledger.jsonl');
   const env: NodeJS.ProcessEnv = { ...process.env };
   env.OPENWOP_BASE_URL = baseUrl;
   env.OPENWOP_API_KEY = apiKey;
+  env.OPENWOP_LEDGER_PATH = ledgerFile;
   if (args.impl) env.OPENWOP_IMPLEMENTATION_NAME = args.impl;
   if (args.implVersion) env.OPENWOP_IMPLEMENTATION_VERSION = args.implVersion;
 
@@ -307,6 +316,7 @@ async function runCertify(args: ParsedArgs, baseUrl: string, apiKey: string): Pr
   }
 
   let report: VitestJsonReport;
+  const ledgerEntries = readLedgerFile(ledgerFile);
   try {
     report = JSON.parse(readFileSync(reportFile, 'utf8')) as VitestJsonReport;
   } catch (err) {
@@ -382,6 +392,21 @@ async function runCertify(args: ParsedArgs, baseUrl: string, apiKey: string): Pr
   // a large `blocked` count and therefore does NOT certify. That is not a defect
   // in the emitter. It is the true state of the evidence, which v1 was unable to
   // represent and therefore reported as a clean skip.
+  // (d1) RFC 0148 acceptance item 2 — requirement-level dispositions from the
+  // ledger, and rejection of unclassified returns for a claimed profile.
+  const derived = deriveRequirementDispositions(states, ledgerEntries, claimedProfiles, document as Record<string, unknown>);
+  const notHeld = new Set(derived.verdicts.filter((v) => v.runtimeDerived && !v.held).map((v) => v.profile));
+  const rejectedProfiles = derived.verdicts.filter((v) => v.unclassified.length > 0);
+  if (rejectedProfiles.length > 0) {
+    process.stderr.write(
+      'openwop-conformance --certify: REJECTING certification — a claimed profile has UNCLASSIFIED floor requirements\n' +
+        '  (no disposition recorded, or an executed-pass with assertionCount 0 — a witness of nothing). RFC 0148 §A\n' +
+        '  resolves an unclassified requirement to `blocked`, never to a pass; the bundle is still written so the\n' +
+        '  evidence is inspectable, but it does not certify and this process exits 3.\n' +
+        rejectedProfiles.map((v) => `  - ${v.profile}: ${v.unclassified.join(', ')}\n`).join(''),
+    );
+  }
+
   if (args.bundleVersion === '2') {
     const scenarioIds = [...passed, ...failed, ...skipped].sort();
     const manifestSha = createHash('sha256').update(scenarioIds.join('\n'), 'utf8').digest('hex');
@@ -392,28 +417,15 @@ async function runCertify(args: ParsedArgs, baseUrl: string, apiKey: string): Pr
       .update(`${args.baseUrl}\n${sha256}\n${process.env['OPENWOP_REQUIRE_BEHAVIOR'] ?? ''}`, 'utf8')
       .digest('hex');
 
-    const requirements = [
-      ...passed.map((f) => ({
-        requirementId: `openwop.scenario.${f.replace(/\.test\.ts$/, '')}`,
-        scenarioId: f,
-        disposition: 'executed-pass' as const,
-      })),
-      ...failed.map((f) => ({
-        requirementId: `openwop.scenario.${f.replace(/\.test\.ts$/, '')}`,
-        scenarioId: f,
-        disposition: 'executed-fail' as const,
-        detail: 'the scenario executed and failed',
-      })),
-      ...skipped.map((f) => ({
-        requirementId: `openwop.scenario.${f.replace(/\.test\.ts$/, '')}`,
-        scenarioId: f,
-        disposition: 'blocked' as const,
-        detail:
-          'runner cannot classify a skipped file: the RFC 0148 §A requirement ledger is not ' +
-          'populated during a run, so skipped/inapplicable/blocked are indistinguishable here. ' +
-          '§A resolves an unclassifiable requirement to `blocked`, never to a pass.',
-      })),
-    ];
+    // Rows come from the ledger (S6). A file that recorded nothing is
+    // `blocked` — unclassified — and, if it sits on a claimed floor, rejected above.
+    const requirements = derived.requirements.map((r) => ({
+      requirementId: r.requirementId,
+      scenarioId: r.scenarioId,
+      disposition: r.disposition,
+      ...(r.detail === undefined ? {} : { detail: r.detail }),
+      ...(r.assertionCount === undefined ? {} : { assertionCount: r.assertionCount }),
+    }));
 
     const v2 = {
       bundleVersion: '2' as const,
@@ -422,48 +434,81 @@ async function runCertify(args: ParsedArgs, baseUrl: string, apiKey: string): Pr
       suite: { package: '@openwop/openwop-conformance' as const, version },
       host,
       discovery: { url: discoveryUrl, sha256, document },
-      claimedProfiles,
+      // RFC 0155 §E: canonical ids only in `claimedProfiles`; a deprecated
+      // alias that also derives (`openwop-core`, always alongside
+      // `openwop-discovery-core`) is reported in `aliases`, never as a claim.
+      // A runtime-derived profile (`PROFILE_FLOOR_SCENARIOS[p].runtimeDerived`,
+      // today `openwop-node-packs`) is claimed only when the host HOLDS it — every
+      // floor row a witnessed pass. Its discovery predicate is `openwop-core`, so
+      // deriving the claim from discovery alone made every core host "claim" a
+      // registry it never advertised (RFC 0025: the read surface has no advert).
+      claimedProfiles: claimedProfiles.filter((p) => !(p in DEPRECATED_PROFILE_ALIASES) && !notHeld.has(p)),
+      ...(claimedProfiles.some((p) => p in DEPRECATED_PROFILE_ALIASES)
+        ? { aliases: claimedProfiles.filter((p) => p in DEPRECATED_PROFILE_ALIASES) }
+        : {}),
       results: {
-        totals: {
-          executedPass: passed.length,
-          executedFail: failed.length,
-          skipped: 0,
-          inapplicable: 0,
-          blocked: skipped.length,
-        },
+        totals: derived.totals,
         requirements,
       },
       scenarioManifestSha256: manifestSha,
       targetConfigurationSha256: configSha,
     };
 
+    // RFC 0148 §C: secret canaries never enter evidence. Scrub the finished
+    // document with the credential this run was handed, every OPENWOP_*
+    // key/token/secret in the environment, and the conformance canary — a
+    // scenario's `detail` string, the captured discovery document, or a host
+    // field could carry any of them, and the emitter is the last place that
+    // can guarantee they do not ship.
+    const secrets = evidenceSecretsFromEnv(process.env, [apiKey]);
+    const scrubbed = scrubEvidence(v2, secrets);
+    const v2Out = scrubbed.value;
+    if (scrubbed.redactedAt.length > 0) {
+      process.stderr.write(
+        `openwop-conformance --certify: REDACTED ${scrubbed.redactedAt.length} evidence field(s) that carried a configured secret or the conformance canary: ${scrubbed.redactedAt.slice(0, 8).join(', ')}${scrubbed.redactedAt.length > 8 ? ', …' : ''}\n`,
+      );
+    }
+    // Self-audit with the consumer verifier: the emitter MUST NOT write a
+    // document the verifier would reject on shape (duplicate rows, totals that
+    // disagree with rows, unknown dispositions, a canary). Rejections scoped to
+    // a claimed profile (unwitnessed / vacuous) are the exit-3 case below and
+    // are reported through `derived`; a bundle-wide rejection here is a bug in
+    // this emitter and exits 2.
+    const selfAudit = verifyBundleV2(v2Out);
+    if (selfAudit.rejections.length > 0) {
+      process.stderr.write(
+        'openwop-conformance --certify: assembled v2 bundle FAILED self-verification (emitter defect):\n' +
+          selfAudit.rejections.map((r) => `  - [${r.kind}] ${r.detail}`).join('\n') +
+          '\n',
+      );
+      process.exit(2);
+    }
+
     const v2Schema = JSON.parse(
       readFileSync(join(SCHEMAS_DIR, 'certification-bundle-v2.schema.json'), 'utf8'),
     ) as Record<string, unknown>;
     const v2Ajv = new Ajv2020({ allErrors: true, strict: false });
     addFormats(v2Ajv);
     const v2Validate = v2Ajv.compile(v2Schema);
-    if (!v2Validate(v2)) {
+    if (!v2Validate(v2Out)) {
       process.stderr.write(
         'openwop-conformance --certify: assembled v2 bundle FAILED schema validation:\n' +
           `${JSON.stringify(v2Validate.errors, null, 2)}\n`,
       );
       process.exit(2);
     }
-    writeFileSync(outPath, `${JSON.stringify(v2, null, 2)}\n`);
+    writeFileSync(outPath, `${JSON.stringify(v2Out, null, 2)}\n`);
     process.stdout.write(
       `openwop-conformance --certify: wrote bundle v2 to ${outPath}\n` +
         `  host: ${host.name}@${host.version}\n` +
-        `  executed-pass ${passed.length} / executed-fail ${failed.length} / blocked ${skipped.length}\n` +
-        (skipped.length > 0
-          ? `  NOTE: ${skipped.length} requirement(s) are 'blocked', not 'skipped'. The runner cannot\n` +
-            `  classify a skipped file until scenarios record into the RFC 0148 §A ledger, and §A\n` +
-            `  resolves an unclassifiable requirement to 'blocked' rather than to a pass. A bundle\n` +
-            `  with blocked > 0 does NOT certify — that is the true state of the evidence, not a\n` +
-            `  defect in this emitter.\n`
-          : ''),
+        `  executed-pass ${derived.totals.executedPass} / executed-fail ${derived.totals.executedFail} / skipped ${derived.totals.skipped} / inapplicable ${derived.totals.inapplicable} / blocked ${derived.totals.blocked}\n` +
+        (derived.ledgerPresent
+          ? `  dispositions come from the RFC 0148 §A ledger (${ledgerEntries.length} entries recorded by the scenarios)\n`
+          : `  NOTE: no ledger was recorded — every skipped file is 'blocked' (unclassifiable), which is the honest reading\n`) +
+        (derived.totals.blocked > 0 ? `  a bundle with blocked > 0 does NOT certify — that is the state of the evidence, not a defect in this emitter\n` : '') +
+        derived.verdicts.map((v) => `  ${v.profile}: ${v.runtimeDerived && !v.held ? `not held (runtime-derived — dropped from claimedProfiles; floor rows not witnessed passes: ${v.blocking.join(', ')})` : v.certifiable ? 'certifiable' : 'NOT certifiable'}${v.unclassified.length > 0 ? ` (unclassified: ${v.unclassified.length})` : ''}\n`).join(''),
     );
-    process.exit(failed.length > 0 ? 1 : 0);
+    process.exit(rejectedProfiles.length > 0 ? 3 : failed.length > 0 ? 1 : 0);
   }
 
   // (e) Validate against the bundle schema BEFORE writing.
@@ -473,7 +518,14 @@ async function runCertify(args: ParsedArgs, baseUrl: string, apiKey: string): Pr
   const ajv = new Ajv2020({ allErrors: true, strict: false });
   addFormats(ajv);
   const validate = ajv.compile(schema);
-  if (!validate(bundle)) {
+  const bundleScrub = scrubEvidence(bundle, evidenceSecretsFromEnv(process.env, [apiKey]));
+  if (bundleScrub.redactedAt.length > 0) {
+    process.stderr.write(
+      `openwop-conformance --certify: REDACTED ${bundleScrub.redactedAt.length} evidence field(s) that carried a configured secret or the conformance canary\n`,
+    );
+  }
+  const bundleOut = bundleScrub.value;
+  if (!validate(bundleOut)) {
     process.stderr.write(
       'openwop-conformance --certify: assembled bundle FAILED schema validation:\n' +
         `${JSON.stringify(validate.errors, null, 2)}\n`,
@@ -481,7 +533,7 @@ async function runCertify(args: ParsedArgs, baseUrl: string, apiKey: string): Pr
     process.exit(2);
   }
 
-  writeFileSync(outPath, `${JSON.stringify(bundle, null, 2)}\n`);
+  writeFileSync(outPath, `${JSON.stringify(bundleOut, null, 2)}\n`);
   process.stdout.write(
     `openwop-conformance --certify: wrote certification bundle to ${outPath}\n` +
       `  host: ${host.name}@${host.version}\n` +
@@ -489,8 +541,10 @@ async function runCertify(args: ParsedArgs, baseUrl: string, apiKey: string): Pr
       `  results: ${passed.length} passed / ${failed.length} failed / ${skipped.length} skipped\n`,
   );
   // Exit code mirrors the suite outcome: a failing run still produces a bundle
-  // (the failures are recorded), but the process exit reflects pass/fail.
-  process.exit(failed.length > 0 ? 1 : 0);
+  // (the failures are recorded), but the process exit reflects pass/fail — and
+  // 3 when a claimed profile has unclassified floor requirements (RFC 0148 §A;
+  // v1 bundles cannot express the distinction, so the exit code carries it).
+  process.exit(rejectedProfiles.length > 0 ? 3 : failed.length > 0 ? 1 : 0);
 }
 
 async function main(): Promise<never> {