@openwop/openwop-conformance 1.10.0 → 1.11.0

package/src/scenarios/runtime-requires-shape.test.ts

@@ -0,0 +1,134 @@
+/**
+ * Pack runtime-requirements vocabulary + shape — `node-packs.md`
+ * §"Runtime platform requirements" + `schemas/node-pack-manifest.schema.json`
+ * `$defs/Runtime.requires` (RFC 0076 §A).
+ *
+ * Server-free schema-validation scenario. The `runtime.requires[]` field is an
+ * OPTIONAL, closed, runtime-agnostic vocabulary a pack uses to declare the
+ * platform primitives its code exercises, so a sandbox host can gate at install
+ * time instead of trial-load. This file exercises the schema layer (the §A
+ * "vocabulary-validation" normative behavior — a raw builtin name is rejected —
+ * plus the additive/empty-array shape contract):
+ *
+ *   1. Positive: a manifest declaring valid primitives validates cleanly.
+ *   2. Positive: the field is OPTIONAL — a manifest omitting it validates.
+ *   3. Positive: an empty array (`requires: []`) validates and is equivalent to
+ *      omission (no host may read a distinct meaning into it; §A).
+ *   4. Positive: every one of the 8 vocabulary tokens individually validates.
+ *   5. Negative — raw builtin name: `"node:dns/promises"` (the value that
+ *      motivated the abstract vocabulary) is rejected; the registry/host
+ *      surfaces this as `invalid_manifest`.
+ *   6. Negative — duplicate token: `uniqueItems` is enforced.
+ *
+ * The install-time GATE behavior (grant / refuse → `pack_runtime_requirement_unmet`,
+ * and the non-sandbox-host SHOULD-projection) is host behavior and lives in the
+ * seam-gated `runtime-requires-install-gate.test.ts`.
+ *
+ * @see spec/v1/node-packs.md §"Runtime platform requirements"
+ * @see spec/v1/registry-operations.md §"Runtime-requirement install gate"
+ * @see schemas/node-pack-manifest.schema.json
+ * @see RFCS/0076-pack-runtime-requirements-and-host-safe-fetch.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 addFormats from 'ajv-formats';
+import type { ErrorObject, ValidateFunction } from 'ajv';
+import { SCHEMAS_DIR } from '../lib/paths.js';
+
+const SCHEMA_PATH = join(SCHEMAS_DIR, 'node-pack-manifest.schema.json');
+
+const VOCABULARY = [
+  'net.dns',
+  'net.outbound',
+  'crypto',
+  'subprocess',
+  'fs.read',
+  'fs.write',
+  'env.read',
+  'clock',
+] as const;
+
+function manifest(requires?: unknown) {
+  const runtime: Record<string, unknown> = { language: 'javascript', entry: 'index.mjs' };
+  if (requires !== undefined) runtime.requires = requires;
+  return {
+    name: 'vendor.example.http',
+    version: '1.0.0',
+    engines: { openwop: '>=1.1 <2.0.0' },
+    runtime,
+    nodes: [{ typeId: 'vendor.example.http.fetch', version: '1.0.0', category: 'integration', role: 'side-effect' }],
+  };
+}
+
+describe('category: runtime.requires vocabulary + shape (RFC 0076 §A)', () => {
+  const ajv = new Ajv2020({ allErrors: true, strict: false });
+  addFormats(ajv);
+  // Register every schema first so cross-$refs resolve (node-pack-manifest
+  // references agent-manifest.schema.json for its agents[] branch). addSchema
+  // registers without compiling; the target compiles below.
+  for (const file of readdirSync(SCHEMAS_DIR)) {
+    if (!file.endsWith('.schema.json')) continue;
+    try {
+      ajv.addSchema(JSON.parse(readFileSync(join(SCHEMAS_DIR, file), 'utf8')) as Record<string, unknown>);
+    } catch {
+      /* duplicate/already-registered — the target is compiled below */
+    }
+  }
+  const schema = JSON.parse(readFileSync(SCHEMA_PATH, 'utf8'));
+  const validate = (ajv.getSchema(schema['$id'] as string) ?? ajv.compile(schema)) as ValidateFunction;
+
+  const errorsOn = (m: unknown): ErrorObject[] => {
+    expect(validate(m)).toBe(false);
+    return validate.errors ?? [];
+  };
+
+  it('positive: a manifest declaring valid primitives validates cleanly', () => {
+    const ok = validate(manifest(['net.dns', 'net.outbound']));
+    expect(
+      ok,
+      `node-packs.md §"Runtime platform requirements": a well-formed runtime.requires MUST validate. Errors: ${JSON.stringify(validate.errors)}`,
+    ).toBe(true);
+  });
+
+  it('positive: runtime.requires is OPTIONAL — a manifest omitting it validates (additive)', () => {
+    expect(
+      validate(manifest(undefined)),
+      'node-pack-manifest.schema.json: runtime.requires is additive/OPTIONAL — packs predating RFC 0076 validate unchanged',
+    ).toBe(true);
+  });
+
+  it('positive: an empty requires[] validates (equivalent to omission per §A)', () => {
+    expect(
+      validate(manifest([])),
+      'node-packs.md §"Runtime platform requirements": runtime.requires:[] is valid and equivalent to omission',
+    ).toBe(true);
+  });
+
+  it('positive: every vocabulary token individually validates', () => {
+    for (const token of VOCABULARY) {
+      expect(
+        validate(manifest([token])),
+        `node-pack-manifest.schema.json: "${token}" is in the RFC 0076 §A vocabulary. Errors: ${JSON.stringify(validate.errors)}`,
+      ).toBe(true);
+    }
+  });
+
+  it('negative: a raw builtin name (node:dns/promises) is rejected (→ invalid_manifest)', () => {
+    const errs = errorsOn(manifest(['node:dns/promises']));
+    expect(
+      errs.some((e) => e.instancePath.includes('/runtime/requires')),
+      'node-packs.md §"Runtime platform requirements": raw language builtin names are NOT in the closed vocabulary — the abstract net.dns is the portable equivalent; the registry/host surfaces this as invalid_manifest',
+    ).toBe(true);
+  });
+
+  it('negative: a duplicate token is rejected (uniqueItems)', () => {
+    const errs = errorsOn(manifest(['net.dns', 'net.dns']));
+    expect(
+      errs.some((e) => e.keyword === 'uniqueItems'),
+      'node-pack-manifest.schema.json: runtime.requires has uniqueItems:true',
+    ).toBe(true);
+  });
+});

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

@@ -0,0 +1,99 @@
+/**
+ * Host-provided safe-fetch behavior — `host-capabilities.md` §host.http
+ * (`ctx.http.safeFetch`) + RFC 0076 §B.
+ *
+ * Seam-gated behavioral scenarios for the pack-facing `ctx.http.safeFetch`. When
+ * a host advertises `capabilities.httpClient.safeFetch.supported`, the
+ * host-mediated fetch MUST apply the §host.http SSRF guard (resolve→pin→connect)
+ * so a pack can do outbound HTTP without reaching for `node:dns` / raw sockets:
+ *
+ *   1. SSRF block — a loopback / RFC 1918 / cloud-metadata target ⇒
+ *      `{ outcome: "blocked", blocked: "ssrf" }`; the host MUST NOT connect.
+ *   2. DNS-rebinding — a public name re-resolving to a blocked address
+ *      (`simulateRebindTo`) ⇒ also blocked (the resolved IP is pinned).
+ *   3. Connection-upgrade refusal — `Connection: upgrade` ⇒
+ *      `{ outcome: "blocked", blocked: "upgrade" }` (no 101 socket-hijack escape).
+ *   4. Audit-when-both — when `toolHooks.prePostEvents` is also advertised, a
+ *      fetched call emits the `agent.toolCalled` / `agent.toolReturned` pair
+ *      (`transport: "http"`).
+ *
+ * All drive `POST /v1/host/sample/http/safe-fetch` and soft-skip when the host
+ * doesn't advertise `safeFetch` or doesn't wire the seam (404). Behavior grade
+ * is `host-pending` until a `safeFetch` host lights it up. The SSRF *guarantee*
+ * reuses the `http-client-ssrf-guard` SECURITY invariant — no new invariant.
+ *
+ * @see spec/v1/host-capabilities.md §host.http
+ * @see spec/v1/host-sample-test-seams.md §"Open seams"
+ * @see RFCS/0076-pack-runtime-requirements-and-host-safe-fetch.md §B
+ * @see SECURITY/invariants.yaml id: http-client-ssrf-guard
+ */
+
+import { describe, it, expect } from 'vitest';
+import { driver } from '../lib/driver.js';
+import { isSafeFetchSupported, isToolHookAuditOn, safeFetch } from '../lib/safeFetch.js';
+
+describe('safefetch-behavior (RFC 0076 §B / §host.http)', () => {
+  it('blocks a metadata-endpoint target (SSRF guard)', async () => {
+    if (!(await isSafeFetchSupported())) return; // capability absent — soft-skip
+    const res = await safeFetch({ url: 'http://169.254.169.254/latest/meta-data/' });
+    if (res === null) return; // seam absent — soft-skip
+    expect(
+      res.outcome,
+      driver.describe('host-capabilities.md §host.http', 'safeFetch MUST NOT connect to a cloud-metadata address'),
+    ).toBe('blocked');
+    expect(
+      res.blocked,
+      driver.describe('host-capabilities.md §host.http', 'a blocked SSRF target reports blocked:"ssrf" (http-client-ssrf-guard invariant)'),
+    ).toBe('ssrf');
+  });
+
+  it('blocks a loopback target (SSRF guard)', async () => {
+    if (!(await isSafeFetchSupported())) return;
+    const res = await safeFetch({ url: 'http://127.0.0.1:6379/' });
+    if (res === null) return;
+    expect(
+      res.outcome,
+      driver.describe('host-capabilities.md §host.http', 'safeFetch MUST NOT connect to loopback'),
+    ).toBe('blocked');
+  });
+
+  it('blocks DNS-rebinding (resolved IP is pinned for the connection)', async () => {
+    if (!(await isSafeFetchSupported())) return;
+    const res = await safeFetch({ url: 'http://example.com/', simulateRebindTo: '169.254.169.254' });
+    if (res === null) return;
+    expect(
+      res.outcome,
+      driver.describe('host-capabilities.md §host.http', 'a public name that re-resolves to a blocked address MUST be blocked (rebinding defeat)'),
+    ).toBe('blocked');
+  });
+
+  it('refuses a Connection: upgrade request (no 101 socket-hijack escape)', async () => {
+    if (!(await isSafeFetchSupported())) return;
+    const res = await safeFetch({ url: 'https://example.com/', init: { headers: { Connection: 'upgrade' } } });
+    if (res === null) return;
+    expect(
+      res.outcome,
+      driver.describe('host-capabilities.md §host.http', 'safeFetch MUST refuse a connection-upgrade attempt'),
+    ).toBe('blocked');
+    expect(
+      res.blocked,
+      driver.describe('host-capabilities.md §host.http', 'a refused upgrade reports blocked:"upgrade"'),
+    ).toBe('upgrade');
+  });
+
+  it('emits the tool-hooks audit pair when prePostEvents is also advertised', async () => {
+    if (!(await isSafeFetchSupported())) return;
+    if (!(await isToolHookAuditOn())) return; // audit MUST applies only when both advertised
+    const res = await safeFetch({ url: 'https://example.com/' });
+    if (res === null) return;
+    if (res.outcome !== 'fetched') return; // only a completed call carries the pair
+    expect(
+      res.toolCalled !== undefined && res.toolReturned !== undefined,
+      driver.describe('host-capabilities.md §host.http', 'when toolHooks.prePostEvents + safeFetch are both advertised, a safeFetch call MUST emit the agent.toolCalled/agent.toolReturned pair'),
+    ).toBe(true);
+    expect(
+      (res.toolCalled as { transport?: string } | undefined)?.transport,
+      driver.describe('host-capabilities.md §host.http', 'the audit pair carries transport:"http"'),
+    ).toBe('http');
+  });
+});

package/src/scenarios/safefetch-live-audit.test.ts

@@ -0,0 +1,175 @@
+/**
+ * Live-run safe-fetch audit emission — `host-capabilities.md` §host.http
+ * (`ctx.http.safeFetch`) + RFC 0076 §B + RFC 0064 §B.
+ *
+ * Closes the seam-vs-production gap left by `safefetch-behavior.test.ts`. That
+ * scenario drives `POST /v1/host/sample/http/safe-fetch` and reads the audit
+ * pair the SEAM returns INLINE — it never proves the *production* per-ctx
+ * `ctx.http.safeFetch` (the client injected into a real run) emits anything. A
+ * host can co-advertise `toolHooks.prePostEvents` + `httpClient.safeFetch`,
+ * pass the seam, and still ship a production `createSafeFetch()` with no audit
+ * hooks — the "quiet bypass" §host.http line "centralizing egress in the host
+ * must increase auditability, not become a quiet bypass" forbids.
+ *
+ * The normative MUST (host-capabilities.md §host.http; RFC 0076 §B):
+ *   When `toolHooks.prePostEvents: true` AND `httpClient.safeFetch.supported:
+ *   true` are BOTH advertised, the host MUST emit the `agent.toolCalled` /
+ *   `agent.toolReturned` pair (`transport: "http"`) **for every `safeFetch`
+ *   invocation** — including a *refused* one (a blocked egress attempt is
+ *   exactly the security-relevant event the audit log must capture).
+ *
+ * This scenario verifies that MUST against the DURABLE run event log, not the
+ * seam's inline echo, and does so **without depending on outbound egress** so
+ * the bar can never pass vacuously:
+ *   1. EGRESS-FREE FLOOR (required): drive one `ctx.http.safeFetch` to a
+ *      guaranteed-blocked link-local / cloud-metadata URL inside a REAL run via
+ *      `POST /v1/host/sample/http/safe-fetch-run`. A conformant SSRF guard
+ *      refuses it on every host with zero connectivity, yet the production
+ *      injection + auditHooks path is still exercised, so the durable pair MUST
+ *      be present. This removes the "no public egress ⇒ green-but-proves-nothing"
+ *      hole that a `fetched`-only assertion left.
+ *   2. SUCCESS-PATH COVERAGE (best-effort): drive a public URL; when it actually
+ *      `fetched`, assert the same durable pair (catches a host that audits only
+ *      the reject path). Skipped — not failed — where the environment has no
+ *      public egress; the floor already proved emission.
+ *   3. Read each run's persisted events via the test event-log seam
+ *      (`GET /v1/host/sample/test/runs/:runId/events`) and assert a `callId`-
+ *      paired `agent.toolCalled` (`transport:"http"`) / `agent.toolReturned`.
+ *
+ * Gating: `behaviorGate('openwop-safefetch-live-audit', <both flags>)` — NOT an
+ * inline soft-skip. So it skips-with-reason in default mode but FAILS under
+ * `OPENWOP_REQUIRE_BEHAVIOR=true` when a host advertises both flags yet does not
+ * emit. This is the RFC 0076 §B → Accepted bar a non-steward host validates
+ * against. The run seam itself (`safe-fetch-run`) is host-pending: a 404 from a
+ * not-yet-wired seam soft-skips even in strict mode (the seam is test-only
+ * infrastructure, distinct from the advertised production capability).
+ * The SSRF guarantee reuses the existing `http-client-ssrf-guard` invariant —
+ * no new SECURITY invariant; the audit MUST is RFC 0064's existing posture.
+ *
+ * @see spec/v1/host-capabilities.md §host.http
+ * @see spec/v1/host-sample-test-seams.md §"Open seams" (safe-fetch-run)
+ * @see RFCS/0076-pack-runtime-requirements-and-host-safe-fetch.md §B
+ * @see RFCS/0064-tool-invocation-hooks-and-authorization.md §B
+ */
+
+import { describe, it, expect } from 'vitest';
+import { driver } from '../lib/driver.js';
+import { behaviorGate } from '../lib/behavior-gate.js';
+import { isSafeFetchLiveAuditAdvertised, safeFetchViaRun } from '../lib/safeFetch.js';
+import { queryTestEvents } from '../lib/event-log-query.js';
+
+const PROFILE = 'openwop-safefetch-live-audit';
+const CITE = 'host-capabilities.md §host.http';
+
+// A link-local / cloud-metadata URL the SSRF guard MUST refuse — reachable on
+// EVERY host regardless of outbound egress, so the durable-pair assertion never
+// passes vacuously. Per §host.http the audit MUST is per-invocation: a *blocked*
+// safeFetch still emits the agent.toolCalled/agent.toolReturned pair (the
+// toolReturned carries the forbidden status). cf. `http-client-ssrf-guard`.
+const BLOCKED_URL = 'http://169.254.169.254/latest/meta-data/';
+// A public URL the guard SHOULD allow — best-effort coverage of the *success*
+// path; skipped (not failed) where the environment has no public egress.
+const FETCH_URL = 'https://example.com/';
+
+/**
+ * Read the durable run event log for `runId` and assert a `callId`-paired
+ * `agent.toolCalled` (`transport:"http"`) / `agent.toolReturned` exists, with
+ * the RFC 0002 §B causation chain tolerated when the host surfaces it. Returns
+ * `false` (caller treats as host-pending soft-skip) only when the event-log
+ * query seam is unavailable; otherwise asserts and returns `true`.
+ */
+async function assertDurableHttpPair(runId: string, label: string): Promise<boolean> {
+  const calledQ = await queryTestEvents(runId, { type: 'agent.toolCalled' });
+  const returnedQ = await queryTestEvents(runId, { type: 'agent.toolReturned' });
+  if (!calledQ.ok || !returnedQ.ok) {
+    // eslint-disable-next-line no-console
+    console.warn(`[${PROFILE}] event-log query seam unavailable; host-pending — skipping`);
+    return false;
+  }
+
+  // The HTTP-transport tool call: a durable agent.toolCalled with transport:"http".
+  const httpCall = calledQ.events.find((e) => (e.payload as { transport?: string }).transport === 'http');
+  expect(
+    httpCall !== undefined,
+    driver.describe(
+      CITE,
+      `(${label}) when toolHooks.prePostEvents + safeFetch are both advertised, a production ctx.http.safeFetch call MUST persist an agent.toolCalled with transport:"http" to the durable run event log (not just the seam echo), for EVERY invocation incl. blocked ones`,
+    ),
+  ).toBe(true);
+  if (!httpCall) return true;
+
+  const callId = (httpCall.payload as { callId?: string }).callId;
+  expect(
+    typeof callId === 'string' && callId.length > 0,
+    driver.describe(CITE, `(${label}) the persisted agent.toolCalled MUST carry the required callId (run-event-payloads.schema.json §agentToolCalled)`),
+  ).toBe(true);
+
+  // The paired agent.toolReturned — matched by the required callId (RFC 0002 §B pairing).
+  const paired = returnedQ.events.find((e) => (e.payload as { callId?: string }).callId === callId);
+  expect(
+    paired !== undefined,
+    driver.describe(CITE, `(${label}) the agent.toolCalled MUST be followed by a callId-paired agent.toolReturned in the durable log (no quiet bypass)`),
+  ).toBe(true);
+
+  // Stricter, when the host surfaces causation: RFC 0002 §B says
+  // toolReturned.causationId === the paired toolCalled.eventId. Tolerate
+  // hosts that omit causationId (callId pairing already proven above).
+  if (paired && typeof paired.causationId === 'string') {
+    expect(
+      paired.causationId,
+      driver.describe('RFC 0002 §B', 'agent.toolReturned.causationId MUST equal the paired agent.toolCalled.eventId when surfaced'),
+    ).toBe(httpCall.eventId);
+  }
+  return true;
+}
+
+describe('safefetch-live-audit (RFC 0076 §B / RFC 0064 §B — production path, durable log)', () => {
+  it('a BLOCKED real-run safeFetch emits the durable agent.toolCalled/agent.toolReturned pair (transport:"http") — egress-free floor', async () => {
+    const advertised = await isSafeFetchLiveAuditAdvertised();
+    if (!behaviorGate(PROFILE, advertised)) return; // default-skip; strict-fail when both flags advertised
+
+    // Run seam is host-pending infrastructure — soft-skip (even in strict mode)
+    // until a safeFetch host wires it. behaviorGate above already enforced the
+    // capability co-advertisement; this only gates on the test vehicle.
+    const run = await safeFetchViaRun({ url: BLOCKED_URL });
+    if (run === null) {
+      // eslint-disable-next-line no-console
+      console.warn(`[${PROFILE}] safe-fetch-run seam unwired (404); host-pending — skipping`);
+      return;
+    }
+
+    // The metadata IP MUST be refused by a conformant SSRF guard
+    // (http-client-ssrf.test.ts owns that contract). Regardless of the exact
+    // outcome, the production injection path ran, so the durable audit pair MUST
+    // exist — this is the egress-independent floor that makes the bar non-vacuous.
+    expect(
+      typeof run.runId === 'string' && (run.runId as string).length > 0,
+      driver.describe(CITE, 'the safe-fetch-run seam MUST return the runId of the real run it executed the safeFetch in'),
+    ).toBe(true);
+    await assertDurableHttpPair(run.runId as string, 'blocked');
+  });
+
+  it('a FETCHED real-run safeFetch also emits the durable pair (success-path coverage — skipped without public egress)', async () => {
+    const advertised = await isSafeFetchLiveAuditAdvertised();
+    if (!behaviorGate(PROFILE, advertised)) return;
+
+    const run = await safeFetchViaRun({ url: FETCH_URL });
+    if (run === null) return; // seam unwired — already warned by the floor test
+
+    if (run.outcome !== 'fetched') {
+      // No public egress in this environment — the blocked-path floor already
+      // proved the production audit path emits. Skip success-path coverage
+      // rather than fail; this is coverage, not the floor.
+      // eslint-disable-next-line no-console
+      console.warn(
+        `[${PROFILE}] ${FETCH_URL} did not fetch (outcome=${run.outcome ?? 'n/a'}); no public egress — success-path coverage skipped (the blocked floor covers emission)`,
+      );
+      return;
+    }
+    expect(
+      typeof run.runId === 'string' && (run.runId as string).length > 0,
+      driver.describe(CITE, 'the safe-fetch-run seam MUST return the runId of the real run it executed the fetch in'),
+    ).toBe(true);
+    await assertDurableHttpPair(run.runId as string, 'fetched');
+  });
+});

package/src/scenarios/spec-corpus-validity.test.ts

@@ -384,16 +384,32 @@ function extractReadmeDocumentIndex(readme: string): string {
   return readme.slice(start, end);
 }
 
-function listMarkdownFilesRecursive(dir: string): string[] {
+function listMarkdownFilesRecursive(dir: string, repoRoot: string = dir): string[] {
   const ignoredDirs = new Set(['.git', 'node_modules', 'dist']);
+  // Repo-relative directory paths to prune. These are subtrees whose
+  // content shouldn't be link-checked because either (a) they're
+  // generated build output (`site/out`) or (b) they're a vendored
+  // mirror of a canonical source whose READMEs use links relative to
+  // the canonical path, not the vendored path:
+  //
+  //  - `apps/workflow-engine/packs/` mirrors repo-root `packs/`, synced
+  //    via `apps/workflow-engine/scripts/sync-packs.sh` so the Cloud
+  //    Run image's `apps/workflow-engine/` build context can ship them.
+  //    Pack READMEs use `../../RFCS/...` / `../../spec/v1/...` links
+  //    that resolve from the canonical location (which this walker
+  //    DOES check) but break from the deeper vendored path. The
+  //    canonical copies are authoritative; the vendored copies are
+  //    byte-for-byte identical via cp -R.
+  const prunedRepoRelative = new Set(['site/out', 'apps/workflow-engine/packs']);
   const files: string[] = [];
 
   for (const entry of readdirSync(dir, { withFileTypes: true })) {
     if (entry.isDirectory()) {
       if (ignoredDirs.has(entry.name)) continue;
       const child = join(dir, entry.name);
-      if (relative(dir, child).startsWith('site/out')) continue;
-      files.push(...listMarkdownFilesRecursive(child));
+      const repoRelChild = relative(repoRoot, child);
+      if (prunedRepoRelative.has(repoRelChild)) continue;
+      files.push(...listMarkdownFilesRecursive(child, repoRoot));
       continue;
     }
     if (entry.isFile() && entry.name.endsWith('.md')) {

package/src/scenarios/tool-descriptor-shape.test.ts

@@ -0,0 +1,133 @@
+/**
+ * Portable tool catalog — descriptor + capability + session-event shapes (RFC 0078).
+ *
+ * Always-on, server-free schema-shape probe. Verifies that:
+ *   - `tool-descriptor.schema.json` compiles and round-trips a conforming
+ *     `ToolDescriptor`, and rejects a descriptor missing the REQUIRED
+ *     `safetyTier`.
+ *   - the §C-1 / §F-4 cross-field MUST is enforced: a `safetyTier: "exec"`
+ *     descriptor MUST carry `source: "host-extension"` (RFC 0069 — exec is never
+ *     protocol-tier); an `exec` + `node-pack` descriptor is rejected, an `exec`
+ *     + `host-extension` descriptor is accepted.
+ *   - `capabilities.toolCatalog` is declared with its `supported` / `sources` /
+ *     `sessionLifecycle` sub-flags.
+ *   - the `tool.session.opened` / `tool.session.closed` payload $defs validate
+ *     conforming content-free records and reject malformed ones (a `closed`
+ *     missing `outcome`; an out-of-enum `outcome`), and both event names appear
+ *     in the RunEventType enum.
+ *
+ * Behavioral assertions (a live `GET /v1/tools` returning authorization-scoped
+ * descriptors, the `404` non-disclosure, the `tool.session.*` bracket ordering)
+ * are gated on `capabilities.toolCatalog.supported` and land in
+ * `tool-catalog-projection.test.ts` + `tool-session-lifecycle.test.ts` (deferred
+ * per RFC 0078 §Conformance — reference host deferred). This scenario asserts the
+ * wire contract, not host behavior.
+ *
+ * Spec references:
+ *   - https://github.com/openwop/openwop/blob/main/spec/v1/tool-catalog.md
+ *   - https://github.com/openwop/openwop/blob/main/RFCS/0078-portable-tool-catalog-and-tool-session-contract.md
+ *   - https://github.com/openwop/openwop/blob/main/RFCS/0069-exec-class-tool-host-extension-safety-contract.md (exec ⇒ host-extension)
+ */
+
+import { describe, it, expect } from 'vitest';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import Ajv2020 from 'ajv/dist/2020.js';
+import addFormats from 'ajv-formats';
+import { SCHEMAS_DIR } from '../lib/paths.js';
+
+const why = (specRef: string, requirement: string): string => `${specRef} — ${requirement}`;
+
+function loadSchema(name: string): Record<string, unknown> {
+  return JSON.parse(readFileSync(join(SCHEMAS_DIR, name), 'utf8')) as Record<string, unknown>;
+}
+
+describe('tool-descriptor-shape: ToolDescriptor (RFC 0078 §C, server-free)', () => {
+  const ajv = addFormats(new Ajv2020({ strict: false }));
+  const validate = ajv.compile(loadSchema('tool-descriptor.schema.json'));
+
+  it('a conforming descriptor validates', () => {
+    expect(
+      validate({
+        toolId: 'mcp:fs.read', source: 'mcp', title: 'Read file',
+        inputSchema: { type: 'object' }, auth: { scopes: ['tools:fs:read'] },
+        egress: 'none', approval: 'never', replayPolicy: 'idempotent',
+        safetyTier: 'read', costHint: 'low', latencyHint: 'low',
+      }),
+      why('tool-catalog.md §C', 'a conforming ToolDescriptor MUST validate'),
+    ).toBe(true);
+  });
+
+  it('a descriptor missing the REQUIRED safetyTier is rejected', () => {
+    expect(
+      validate({ toolId: 'x', source: 'mcp' }),
+      why('tool-catalog.md §C', 'safetyTier is REQUIRED'),
+    ).toBe(false);
+  });
+
+  it('enforces exec ⇒ host-extension (RFC 0069; §C-1/§F-4)', () => {
+    expect(
+      validate({ toolId: 'x-host-acme-shell', source: 'host-extension', safetyTier: 'exec', approval: 'always', egress: 'host-owned' }),
+      why('tool-catalog.md §C-1', 'an exec tool sourced from host-extension MUST validate'),
+    ).toBe(true);
+    expect(
+      validate({ toolId: 'openwop:run-shell', source: 'node-pack', safetyTier: 'exec' }),
+      why('tool-catalog.md §C-1 / RFC 0069', 'an exec tool MUST NOT be protocol-tier (node-pack)'),
+    ).toBe(false);
+  });
+
+  it('rejects an unknown property (additionalProperties:false)', () => {
+    expect(
+      validate({ toolId: 'x', source: 'mcp', safetyTier: 'read', danger: true }),
+      why('tool-catalog.md §C', 'ToolDescriptor MUST be additionalProperties:false'),
+    ).toBe(false);
+  });
+});
+
+describe('tool-descriptor-shape: capability advertisement (RFC 0078 §A, server-free)', () => {
+  it('capabilities.toolCatalog is declared with its sub-flags', () => {
+    const caps = loadSchema('capabilities.schema.json');
+    const toolCatalog = (caps.properties as Record<string, { properties?: Record<string, unknown> }>).toolCatalog;
+    expect(
+      toolCatalog,
+      why('capabilities.md §toolCatalog', 'capabilities.toolCatalog MUST be declared'),
+    ).toBeDefined();
+    for (const flag of ['supported', 'sources', 'sessionLifecycle']) {
+      expect(
+        toolCatalog?.properties?.[flag],
+        why('tool-catalog.md §A', `capabilities.toolCatalog.${flag} MUST be declared`),
+      ).toBeDefined();
+    }
+  });
+});
+
+describe('tool-descriptor-shape: session lifecycle events (RFC 0078 §D, server-free)', () => {
+  const payloads = loadSchema('run-event-payloads.schema.json');
+  const ajv = addFormats(new Ajv2020({ strict: false }));
+  const compile = (defName: string) => ajv.compile({
+    $schema: 'https://json-schema.org/draft/2020-12/schema',
+    $defs: (payloads as { $defs: Record<string, unknown> }).$defs,
+    $ref: `#/$defs/${defName}`,
+  } as Record<string, unknown>);
+
+  it('tool.session.opened validates a content-free record', () => {
+    const v = compile('toolSessionOpened');
+    expect(v({ sessionId: 's1', toolId: 'mcp:fs.read' }), why('tool-catalog.md §D', 'opened MUST validate')).toBe(true);
+    expect(v({ toolId: 'mcp:fs.read' }), why('tool-catalog.md §D', 'opened requires sessionId')).toBe(false);
+  });
+
+  it('tool.session.closed validates + enforces the closed outcome enum', () => {
+    const v = compile('toolSessionClosed');
+    expect(v({ sessionId: 's1', toolId: 'mcp:fs.read', outcome: 'completed' }), why('tool-catalog.md §D', 'closed MUST validate')).toBe(true);
+    expect(v({ sessionId: 's1', toolId: 'mcp:fs.read' }), why('tool-catalog.md §D', 'closed requires outcome')).toBe(false);
+    expect(v({ sessionId: 's1', toolId: 'mcp:fs.read', outcome: 'exploded' }), why('tool-catalog.md §D', 'outcome is a closed enum')).toBe(false);
+  });
+
+  it('both session event names appear in the RunEventType enum', () => {
+    const runEvent = loadSchema('run-event.schema.json');
+    const enumVals = ((runEvent.$defs as Record<string, { enum?: string[] }>).RunEventType?.enum) ?? [];
+    for (const name of ['tool.session.opened', 'tool.session.closed']) {
+      expect(enumVals.includes(name), why('run-event.schema.json', `${name} MUST be in the RunEventType enum`)).toBe(true);
+    }
+  });
+});