@openwop/openwop-conformance 1.141.0 → 1.144.0

package/README.md

@@ -94,7 +94,7 @@ Exit code is non-zero on any failed assertion. `--certify` distinguishes: `0`
 
 ## What's Covered
 
-The current suite has 465 scenario files under `src/scenarios/`.
+The current suite has 467 scenario files under `src/scenarios/`.
 - 2026-08-19 (suite `1.137.0 → 1.138.0`): NEW `durability-poison-exhaustion.test.ts` — RFC 0158 §C.8, the FIRST row of that RFC's conformance table to land. Asserts what `failure-path.test.ts` cannot: not just that deterministically failing work reaches terminal, but that attempts STOP — counted on the log, re-counted after a scaled quiet window, asserted unchanged. A host still redelivering records more. Seam-gated on the existing event-log seam (`blocked` = unobservable, not unmet) and outside every profile floor.
 - 2026-08-19 (suite `1.136.15 → 1.137.0`): NEW `replay-fanout-suppression.test.ts` — capability-gated on `webhooks.supported`, **outside every profile floor**; witnesses `replay.md` §"Host-initiated fan-out is an external effect", which was the largest normative MUST NOT on the replay surface with no scenario and no SECURITY invariant. Three legs in ONE `it` against ONE receiver and ONE subscription — a positive control, the MUST NOT, and a `branch` boundary leg — because "no delivery arrived" passes identically when delivery never worked, so absence is asserted only after presence is proven on that exact wiring. A host with an SSRF guard correctly refuses the loopback receiver and records `blocked`: **unobservable, not unmet.**
 - 2026-08-18 (suite `1.136.7 → 1.136.8`, SP-04): NEW `spec-section-citations.test.ts` — server-free; a `<doc>.md §"<Section>"` citation of a checked doc MUST resolve to a heading that exists. `storage-adapters.md §"Claim acquisition"` was cited by four artifacts, including a normative MUST in `production-profile.md` §Durability, and the section did not exist for the life of RFC 0009. Scoped to the docs whose section citations carry the durability contract; a corpus-wide sweep finds ~260 unresolved citations that need triage before they can gate.
@@ -438,7 +438,7 @@ Server-required (added in 1.7.0):
 | ------------- | ----------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | **Redaction** | [`capabilities.md`](../spec/v1/capabilities.md) §"Secrets" + NFR-7 + §"aiProviders" | Vendor-neutral assertions that the server doesn't leak secret material. Three scenario groups: (a) discovery shape contract — `secrets` + `aiProviders` advertisements are well-formed regardless of `secrets.supported`; when `supported === true`, scopes MUST be non-empty + `resolution === 'host-managed'`; `byok ⊆ supported`. (b) bearer-token redaction — invalid Bearer canary in `Authorization` header is not echoed in the 401 response body. (c) credentialRef echo control — gated on `secrets.supported === true`; canary planted in `configurable.ai.credentialRef` MUST NOT appear in any RunEvent payload (poll-based capture; transport-agnostic). Uses runtime-built canary fixtures (`lib/canaries.ts`) that defeat static secret scanners. 6 scenarios. |
 
-Current source tree: 465 scenario files. Use [`coverage.md`](./coverage.md) for current grade/gap tracking.
+Current source tree: 467 scenario files. Use [`coverage.md`](./coverage.md) for current grade/gap tracking.
 
 ## Remaining Gaps
 

package/dist/lib/spec-coherence.js

@@ -55,16 +55,29 @@
  * run and fails when the two disagree, which is the only thing that makes a
  * hand-maintained set trustworthy.
  *
- * ## What is deliberately NOT here
+ * ## What is deliberately NOT here — and why it is a Set, not a sentence
  *
- * Seven scenarios gate on `V1_DIR` **and** drive the host
- * (`replay-side-effect-suppression`, `data-residency-admission`,
- * `profile-discovery-core-alias`, `workflow-variable-format`,
- * `workflow-chain-deferred-parameters`, `artifact-type-store-emission`,
- * `artifact-type-registration-source`). Those assert advertised host behaviour
- * that could not be exercised because a dependency was unavailable — which is
- * `blocked`, exactly as §A defines it. Classifying them `inapplicable` would
- * tell a host "this does not apply to you" about a requirement that does.
+ * Seven scenarios gate on `V1_DIR` **and** drive the host. They assert
+ * advertised host behaviour that could not be exercised because a dependency
+ * was unavailable — `blocked`, exactly as §A defines it. Classifying them
+ * `inapplicable` would tell a host "this does not apply to you" about a
+ * requirement that does.
+ *
+ * They are listed in `SPEC_COHERENCE_EXCLUDED` below rather than named in this
+ * prose, because naming them here made this file lie to a reasonable reader.
+ * A peer checking membership with `grep -c "<scenario>" spec-coherence.ts` got
+ * **1 hit for all three** of the ones the prose named — from this very
+ * paragraph — and was one step from reporting that host-behaviour rows had
+ * been downgraded to "does not apply to you" as a credit. They caught it only
+ * because two counts disagreed: 28 members and those 7 included cannot both be
+ * true.
+ *
+ * **A text search over this file still matches both sets** — that is inherent
+ * to any file that names what it excludes. So the exclusions are now an
+ * exported Set with the same standing as the inclusions: membership has a
+ * programmatic answer, `spec-coherence-registry.test.ts` asserts the two are
+ * disjoint and jointly exhaustive over the `V1_DIR`-gated files, and a comment
+ * is no longer the only place the exclusion reason lives.
  */
 /** Scenarios whose subject is the corpus. Kept honest by `spec-coherence-registry.test.ts`. */
 export const SPEC_COHERENCE_SCENARIOS = new Set([
@@ -97,6 +110,20 @@ export const SPEC_COHERENCE_SCENARIOS = new Set([
     'workflow-chain-internal-flag.test.ts',
     'workload-identity-profile.test.ts',
 ]);
+/**
+ * Scenarios that gate on `V1_DIR` **and** drive the host, so their `blocked` is
+ * honest: advertised behaviour a missing dependency prevented exercising.
+ * Exported so membership is checkable in code rather than inferred from prose.
+ */
+export const SPEC_COHERENCE_EXCLUDED = new Set([
+    'artifact-type-registration-source.test.ts',
+    'artifact-type-store-emission.test.ts',
+    'data-residency-admission.test.ts',
+    'profile-discovery-core-alias.test.ts',
+    'replay-side-effect-suppression.test.ts',
+    'workflow-chain-deferred-parameters.test.ts',
+    'workflow-variable-format.test.ts',
+]);
 /** The reason recorded on such a row, written for the host operator reading it. */
 export const SPEC_COHERENCE_DETAIL = 'inapplicable to any host: this scenario reads spec/v1/ to check the SPEC corpus is internally coherent and asserts nothing about a host. '
     + 'The published tarball does not bundle spec/v1/ (see lib/paths.ts), so it does not run here. '

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openwop/openwop-conformance",
-  "version": "1.141.0",
+  "version": "1.144.0",
   "description": "Production-ready black-box conformance suite for OpenWOP v1.0 compliant servers.",
   "repository": {
     "type": "git",

package/schemas/CORPUS-STAMP.json

@@ -1,5 +1,5 @@
 {
   "_comment": "Provenance of this vendored schemas/ copy. See conformance/README.md \u00a7\"Resolving the contract\". Compare against the stamp in your installed @openwop/openwop-conformance to detect a stale hand-copied contract.",
-  "suiteVersion": "1.141.0",
-  "corpusCommit": "de70377b76d34fdec3b1f4b7e27b8ade95a9ba27"
+  "suiteVersion": "1.144.0",
+  "corpusCommit": "1aca8bb8ebdfaf23b33283f9c313aacfebfd4f07"
 }

package/schemas/capabilities.schema.json

@@ -3691,6 +3691,10 @@
           "uniqueItems": true,
           "description": "Auth profiles the host claims. Canonical ids: `openwop-audit-log-integrity` (auth-profiles.md \u00a7Audit-log integrity), `openwop-auth-api-key-rotation`, `openwop-auth-oauth2-client-credentials`, `openwop-auth-oidc-user-bearer`, `openwop-auth-mtls`, `openwop-auth-saml` + `openwop-auth-scim` + `openwop-auth-ldap` (RFC 0050 enterprise identity). Clients SHOULD tolerate unknown profile ids."
         },
+        "subjectLinking": {
+          "type": "boolean",
+          "description": "RFC 0159 (auth-profiles.md \u00a7Subject linking). When true, this host advertises BOTH `openwop-auth-saml` and `openwop-auth-scim` AND honours the cross-profile subject-linking obligation: it links the SAML and SCIM principals of one human on an opaque, IdP-stable subject id (SCIM `externalId` \u2194 persistent SAML `NameID`), same-tenant only, and on SCIM deactivation fail-closes the linked SAML identity too (composing RFC 0049 \u00a7C) \u2014 so a provisioned leaver cannot still SSO in. The link key MUST NOT be a mutable/PII attribute (email, userName). Optional; absent/false means the SAML and SCIM lanes are independent and the combined leaver guarantee is NOT claimed. A host MUST NOT set this true unless both profiles are advertised and the obligation holds."
+        },
         "rotation": {
           "type": "object",
           "description": "API-key rotation advertisement (auth-profiles.md \u00a7`openwop-auth-api-key-rotation`).",

package/src/lib/spec-coherence-registry.test.ts

@@ -14,7 +14,7 @@
 import { describe, expect, it } from 'vitest';
 import { readFileSync, readdirSync } from 'node:fs';
 import { join } from 'node:path';
-import { SPEC_COHERENCE_SCENARIOS, SPEC_COHERENCE_DETAIL } from './spec-coherence.js';
+import { SPEC_COHERENCE_SCENARIOS, SPEC_COHERENCE_DETAIL, SPEC_COHERENCE_EXCLUDED } from './spec-coherence.js';
 import { resolveFileRecord } from './scenario-disposition.js';
 
 const SCENARIOS = new URL('../scenarios/', import.meta.url).pathname;
@@ -41,6 +41,27 @@ describe('SPEC_COHERENCE_SCENARIOS is derivable, not asserted', () => {
     expect(listed.filter((f) => !pure.includes(f)), 'in the registry but no longer qualifies — it now drives a host, or stopped reading spec/v1').toEqual([]);
   });
 
+  it('the EXCLUDED set is exactly the host-touching ones — the exclusions are checked, not asserted in prose', () => {
+    // These used to live only in a docblock sentence. A peer grepping this file
+    // for membership matched that sentence and read all three named scenarios
+    // as members — the opposite of the truth, and the dangerous direction: it
+    // would mean host-behaviour rows downgraded to "does not apply to you" as a
+    // credit. Naming them in prose made the file lie to a reasonable reader.
+    const { hostTouching } = derive();
+    expect([...SPEC_COHERENCE_EXCLUDED].sort()).toEqual(hostTouching);
+  });
+
+  it('the two sets are disjoint and jointly exhaustive over the V1_DIR-gated files', () => {
+    // Disjoint: no scenario can be both "does not apply to any host" and
+    // "applies but was unwitnessable". Exhaustive: every V1_DIR-gated file has
+    // a decided disposition, so none falls back to the unclassified marker.
+    const { pure, hostTouching } = derive();
+    const overlap = [...SPEC_COHERENCE_SCENARIOS].filter((f) => SPEC_COHERENCE_EXCLUDED.has(f));
+    expect(overlap, 'a scenario cannot be both inapplicable-to-all-hosts and blocked-for-this-host').toEqual([]);
+    const union = new Set([...SPEC_COHERENCE_SCENARIOS, ...SPEC_COHERENCE_EXCLUDED]);
+    expect([...union].sort()).toEqual([...pure, ...hostTouching].sort());
+  });
+
   it('excludes the host-touching ones, which are honestly `blocked`', () => {
     // These assert ADVERTISED behaviour that a missing dependency prevented
     // exercising — RFC 0148 §A's definition of `blocked`, verbatim. Calling

package/src/lib/spec-coherence.ts

@@ -55,16 +55,29 @@
  * run and fails when the two disagree, which is the only thing that makes a
  * hand-maintained set trustworthy.
  *
- * ## What is deliberately NOT here
+ * ## What is deliberately NOT here — and why it is a Set, not a sentence
  *
- * Seven scenarios gate on `V1_DIR` **and** drive the host
- * (`replay-side-effect-suppression`, `data-residency-admission`,
- * `profile-discovery-core-alias`, `workflow-variable-format`,
- * `workflow-chain-deferred-parameters`, `artifact-type-store-emission`,
- * `artifact-type-registration-source`). Those assert advertised host behaviour
- * that could not be exercised because a dependency was unavailable — which is
- * `blocked`, exactly as §A defines it. Classifying them `inapplicable` would
- * tell a host "this does not apply to you" about a requirement that does.
+ * Seven scenarios gate on `V1_DIR` **and** drive the host. They assert
+ * advertised host behaviour that could not be exercised because a dependency
+ * was unavailable — `blocked`, exactly as §A defines it. Classifying them
+ * `inapplicable` would tell a host "this does not apply to you" about a
+ * requirement that does.
+ *
+ * They are listed in `SPEC_COHERENCE_EXCLUDED` below rather than named in this
+ * prose, because naming them here made this file lie to a reasonable reader.
+ * A peer checking membership with `grep -c "<scenario>" spec-coherence.ts` got
+ * **1 hit for all three** of the ones the prose named — from this very
+ * paragraph — and was one step from reporting that host-behaviour rows had
+ * been downgraded to "does not apply to you" as a credit. They caught it only
+ * because two counts disagreed: 28 members and those 7 included cannot both be
+ * true.
+ *
+ * **A text search over this file still matches both sets** — that is inherent
+ * to any file that names what it excludes. So the exclusions are now an
+ * exported Set with the same standing as the inclusions: membership has a
+ * programmatic answer, `spec-coherence-registry.test.ts` asserts the two are
+ * disjoint and jointly exhaustive over the `V1_DIR`-gated files, and a comment
+ * is no longer the only place the exclusion reason lives.
  */
 
 /** Scenarios whose subject is the corpus. Kept honest by `spec-coherence-registry.test.ts`. */
@@ -99,6 +112,21 @@ export const SPEC_COHERENCE_SCENARIOS: ReadonlySet<string> = new Set([
   'workload-identity-profile.test.ts',
 ]);
 
+/**
+ * Scenarios that gate on `V1_DIR` **and** drive the host, so their `blocked` is
+ * honest: advertised behaviour a missing dependency prevented exercising.
+ * Exported so membership is checkable in code rather than inferred from prose.
+ */
+export const SPEC_COHERENCE_EXCLUDED: ReadonlySet<string> = new Set([
+  'artifact-type-registration-source.test.ts',
+  'artifact-type-store-emission.test.ts',
+  'data-residency-admission.test.ts',
+  'profile-discovery-core-alias.test.ts',
+  'replay-side-effect-suppression.test.ts',
+  'workflow-chain-deferred-parameters.test.ts',
+  'workflow-variable-format.test.ts',
+]);
+
 /** The reason recorded on such a row, written for the host operator reading it. */
 export const SPEC_COHERENCE_DETAIL =
   'inapplicable to any host: this scenario reads spec/v1/ to check the SPEC corpus is internally coherent and asserts nothing about a host. '

package/src/scenarios/auth-subject-link.test.ts

@@ -0,0 +1,152 @@
+/**
+ * auth-subject-link — RFC 0159: SCIM ⟷ SAML subject linking (the combined
+ * leaver contract).
+ *
+ * Status: DRAFT. RFC 0159 is `Active` (amends RFC 0050). The obligation is
+ * documented in `auth-profiles.md` §"Subject linking (SAML ⟷ SCIM)" and is
+ * discoverable via `capabilities.auth.subjectLinking`.
+ *
+ * Advertisement shape runs unconditionally when the flag is set. The
+ * cross-lane behavioral legs (a SCIM deactivation fail-closing the linked SAML
+ * identity; a mutable-key link never producing a cross-lane pass) are opt-in
+ * via `OPENWOP_TEST_SAML_IDP_URL` + `OPENWOP_TEST_SCIM_URL` (operator-supplied
+ * endpoints), following the `auth-scim-profile.test.ts` opt-in precedent.
+ * Soft-skips otherwise; soft-skips `blocked` until the host wires the seam.
+ *
+ * @see RFCS/0159-scim-saml-subject-linking.md
+ * @see spec/v1/auth-profiles.md §"Subject linking (SAML ⟷ SCIM)"
+ */
+
+import { describe, it, expect } from 'vitest';
+import { softSkip } from '../lib/soft-skip.js';
+import { driver } from '../lib/driver.js';
+import { capabilityFamily } from '../lib/discovery-capabilities.js';
+
+const SAML_PROFILE = 'openwop-auth-saml';
+const SCIM_PROFILE = 'openwop-auth-scim';
+
+interface DiscoveryAuth {
+  profiles?: string[];
+  subjectLinking?: boolean;
+}
+
+interface DiscoveryDoc {
+  capabilities?: { auth?: DiscoveryAuth };
+  extensions?: { auth?: DiscoveryAuth };
+}
+
+async function readAuth(): Promise<DiscoveryAuth | null> {
+  const res = await driver.get('/.well-known/openwop');
+  const body = res.json as DiscoveryDoc | undefined;
+  return capabilityFamily<DiscoveryAuth>(body, 'auth') ?? body?.extensions?.auth ?? null;
+}
+
+describe('auth-subject-link: advertisement shape (RFC 0159 §B)', () => {
+  it('subjectLinking:true is only claimed alongside both SAML and SCIM profiles', async () => {
+    const auth = await readAuth();
+    if (auth === null || auth.subjectLinking !== true) {
+      return softSkip('inapplicable', 'auth.subjectLinking not claimed');
+    }
+    const profiles = auth.profiles ?? [];
+    expect(
+      profiles.includes(SAML_PROFILE) && profiles.includes(SCIM_PROFILE),
+      driver.describe(
+        'auth-profiles.md §Subject linking',
+        'a host MUST NOT set capabilities.auth.subjectLinking:true unless BOTH openwop-auth-saml and openwop-auth-scim are advertised',
+      ),
+    ).toBe(true);
+  });
+});
+
+describe('auth-subject-link: cross-lane deactivation (RFC 0159 §A.3 — opt-in)', () => {
+  const idpUrl = process.env.OPENWOP_TEST_SAML_IDP_URL;
+  const scimUrl = process.env.OPENWOP_TEST_SCIM_URL;
+
+  it('a SCIM deactivation fail-closes the linked SAML identity', async () => {
+    const auth = await readAuth();
+    if (auth === null || auth.subjectLinking !== true) return softSkip('inapplicable', 'capability-gated');
+    if (!idpUrl || !scimUrl) return softSkip('inapplicable', 'opt-in: SAML IdP and/or SCIM endpoint not provided');
+
+    // 1. Provision a SCIM user carrying an opaque, IdP-stable externalId.
+    const externalId = 'idp-op-8f3a';
+    const provision = await driver.post('/v1/host/sample/auth/scim/provision', {
+      scimUrl,
+      op: 'create-user',
+      externalId,
+      userName: 'r.smith',
+    });
+    if (provision.status === 404) return softSkip('blocked', 'seam unwired');
+    expect(provision.status, driver.describe('auth-profiles.md §Subject linking', 'SCIM provisioning MUST succeed')).toBeLessThan(400);
+
+    // 2. A valid SAML assertion whose persistent NameID equals the externalId
+    //    links to the same subject and authenticates.
+    const before = await driver.post('/v1/host/sample/auth/saml/validate', { idpUrl, variant: 'valid', nameId: externalId });
+    if (before.status === 404) return softSkip('blocked', 'seam unwired');
+    expect(
+      (before.json as { authenticated?: boolean } | undefined)?.authenticated,
+      driver.describe('auth-profiles.md §Subject linking', 'a valid linked SAML assertion authenticates before deactivation'),
+    ).toBe(true);
+
+    // 3. SCIM-deactivate the provisioned user.
+    const deactivate = await driver.post('/v1/host/sample/auth/scim/provision', { scimUrl, op: 'deactivate-user', externalId });
+    expect(deactivate.status, driver.describe('auth-profiles.md §Subject linking', 'SCIM deactivation MUST succeed')).toBeLessThan(400);
+
+    // 4. THE CONTRACT: a subsequent SAML assertion for the linked subject MUST
+    //    NOT yield an authorized decision (fail-closed across the link).
+    const after = await driver.post('/v1/host/sample/auth/saml/validate', { idpUrl, variant: 'valid', nameId: externalId });
+    expect(
+      (after.json as { authenticated?: boolean } | undefined)?.authenticated === true,
+      driver.describe(
+        'auth-profiles.md §Subject linking',
+        'RFC 0159 §A.3: after a SCIM deactivation the LINKED SAML identity MUST be denied (a provisioned leaver cannot still SSO in)',
+      ),
+    ).toBe(false);
+  });
+});
+
+describe('auth-subject-link: link-key hygiene (RFC 0159 §A.2 — opt-in)', () => {
+  const idpUrl = process.env.OPENWOP_TEST_SAML_IDP_URL;
+  const scimUrl = process.env.OPENWOP_TEST_SCIM_URL;
+
+  it('a mutable/PII link key (email) never produces a cross-lane pass', async () => {
+    const auth = await readAuth();
+    if (auth === null || auth.subjectLinking !== true) return softSkip('inapplicable', 'capability-gated');
+    if (!idpUrl || !scimUrl) return softSkip('inapplicable', 'opt-in: SAML IdP and/or SCIM endpoint not provided');
+
+    // Attempt to form the cross-lane link on email (a mutable/PII attribute).
+    // §A.2 forbids it: the host MUST reject the mutable-key link (4xx) OR
+    // decline to apply any cross-lane effect from it. Either way, an email
+    // "link" MUST NOT yield an authorized cross-lane pass after a deactivation.
+    const link = await driver.post('/v1/host/sample/auth/scim/provision', {
+      scimUrl,
+      op: 'link',
+      linkKey: 'email',
+      email: 'r.smith@example.test',
+    });
+    if (link.status === 404) return softSkip('blocked', 'seam unwired');
+
+    if (link.status >= 400) {
+      // Conforming: the host rejected a mutable-key link outright.
+      expect(
+        link.status,
+        driver.describe('auth-profiles.md §Subject linking', 'RFC 0159 §A.2: a link on a mutable/PII key (email) MUST be rejected'),
+      ).toBeGreaterThanOrEqual(400);
+      return;
+    }
+
+    // If the host accepted the request, it MUST NOT have formed a cross-lane
+    // link on email: a deactivation via the email "link" MUST NOT deny (or
+    // otherwise act on) an unrelated SAML subject, and MUST NOT let a mutable
+    // key authorize one. Probe: deactivate by email, then a SAML assertion for
+    // a DIFFERENT opaque subject MUST be unaffected by the email operation.
+    await driver.post('/v1/host/sample/auth/scim/provision', { scimUrl, op: 'deactivate-user', email: 'r.smith@example.test' });
+    const other = await driver.post('/v1/host/sample/auth/saml/validate', { idpUrl, variant: 'valid', nameId: 'idp-op-DIFFERENT' });
+    expect(
+      (other.json as { linkedDenied?: boolean } | undefined)?.linkedDenied === true,
+      driver.describe(
+        'auth-profiles.md §Subject linking',
+        'RFC 0159 §A.2: a mutable-key (email) operation MUST NOT drive a cross-lane deny on any opaque subject',
+      ),
+    ).toBe(false);
+  });
+});

package/src/scenarios/tool-hooks-failure-honesty.test.ts

@@ -0,0 +1,62 @@
+/**
+ * tool-hooks-failure-honesty — RFC 0064 §F. A tool failure MUST be
+ * self-describing on the wire: a non-success `agent.toolReturned` MUST carry a
+ * failure discriminator — `error` populated (the `_errorObject`) and, when the
+ * host advertises `prePostEvents`, `status: 'error'` — and MUST NOT be
+ * represented as a bare/empty success. Closes the gap where a failed tool is
+ * indistinguishable from one that succeeded-empty (host-program WFAU-4).
+ *
+ * Gated on `capabilities.toolHooks.supported` + the tool-hooks seam. Drives the
+ * seam's `simulateToolError` arm; a host that advertises tool-hooks but has not
+ * wired that arm soft-skips (`blocked`) rather than failing — §F and the seam
+ * arm land together, so hosts wire it on adoption (the same soft-skip-until-wired
+ * discipline the other tool-hooks scenarios use).
+ *
+ * @see RFCS/0064-tool-invocation-hooks-and-authorization.md §F
+ */
+
+import { describe, it, expect } from 'vitest';
+import { softSkip } from '../lib/soft-skip.js';
+import { driver } from '../lib/driver.js';
+import { readToolHooksCap, invokeToolHook } from '../lib/toolHooks.js';
+
+describe('tool-hooks-failure-honesty (RFC 0064 §F)', () => {
+  it('a failing tool yields a populated error, never a bare success', async () => {
+    const cap = await readToolHooksCap();
+    if (cap?.supported !== true) return softSkip('inapplicable', 'capability or profile not advertised by this host — gate `cap?.supported !== true` returned early');
+    const res = await invokeToolHook({ principal: 'core.system', toolName: 'web.search', simulateToolError: true });
+    if (res === null) return softSkip('blocked', 'tool-hooks seam absent — soft-skip');
+
+    const returned = res.toolReturned ?? {};
+    const errRaw = returned['error'];
+    const err = errRaw != null && typeof errRaw === 'object' ? (errRaw as Record<string, unknown>) : undefined;
+    const isErrorStatus = returned['status'] === 'error';
+
+    // A host that has not wired the §F simulateToolError arm answers with a
+    // success (status 'ok' / an outcome). Soft-skip rather than red-light an
+    // honest pre-§F host — the prose MUST and this seam arm adopt together.
+    if (err === undefined && !isErrorStatus) {
+      return softSkip('blocked', 'host has not wired the RFC 0064 §F simulateToolError arm — soft-skip until adopted');
+    }
+
+    // §F: the failure carries a populated `_errorObject { code, message }`.
+    expect(
+      err !== undefined && typeof err['code'] === 'string' && (err['code'] as string).length > 0 && typeof err['message'] === 'string',
+      driver.describe('RFC 0064 §F', 'a failed tool MUST populate error {code, message} on agent.toolReturned'),
+    ).toBe(true);
+
+    // §F: `error` and `outcome` are mutually exclusive.
+    expect(
+      returned['outcome'] === undefined,
+      driver.describe('RFC 0064 §F', 'error and outcome are mutually exclusive on a failed tool-return'),
+    ).toBe(true);
+
+    // §F: a host advertising `prePostEvents` MUST also set `status: 'error'`.
+    if (cap['prePostEvents'] === true) {
+      expect(
+        returned['status'] === 'error',
+        driver.describe('RFC 0064 §F', 'a host advertising prePostEvents MUST set status:"error" on a tool failure'),
+      ).toBe(true);
+    }
+  });
+});