feat(testing): fold field_absent + envelope_field_absent into #1045

Per @bokelley's review comment: both checks share the same handler path
as `envelope_field_present`, so the runtime delta is a single
`validateFieldAbsent` function and two `case` entries in the switch.

- `field_absent` / `envelope_field_absent` added to
  `StoryboardValidationCheck` type union
- `validateFieldAbsent`: passes when path is absent (undefined/null),
  fails when present — mirrors `validateFieldPresent` semantics inverted
- Drift detector: both checks collected by `collectFieldValidations` but
  skip reachability assertions (absence checks have no schema target)
- 6 new tests in `storyboard-validations.test.js` (pass/fail/no-path
  for both `field_absent` and `envelope_field_absent`)
- Changeset updated to list all five new check types; removes the
  "future PR" note since they ship here

Unlocks the `v3-envelope-integrity.yaml` TODO block's MUST-NOT
assertions (`task_status`/`response_status`) without a second SDK
release.

https://claude.ai/code/session_01R6VkP124L1RGqVART85gxo

Author: claude

.changeset/envelope-field-present.md

@@ -6,20 +6,20 @@ feat(testing): add envelope-scoped storyboard validation checks
 
 Storyboards that assert v3 envelope-level fields (`status`, `task_id`, `message`, `replayed`, `governance_context`, `timestamp`, `context_id`, `push_notification_config`) need a way to tell static drift detection to walk `protocol-envelope.json` instead of the per-tool response schema. The previous un-prefixed checks pointed at the inner response schema, which doesn't contain envelope fields, so the `v3-envelope-integrity.yaml` storyboard required a `VERIFIER_UNREACHABLE` exemption.
 
-Adds three envelope-scoped `StoryboardValidationCheck` values:
+Adds five new `StoryboardValidationCheck` values:
 
+- `field_absent` — passes when the path is absent; fails when present (companion to `field_present`)
+- `envelope_field_absent` — envelope-scoped companion to `field_absent`; signals drift detection to walk `protocol-envelope.json`; absence checks skip reachability assertions by design
 - `envelope_field_present` — companion to `field_present`
 - `envelope_field_value` — companion to `field_value`
 - `envelope_field_value_or_absent` — companion to `field_value_or_absent`
 
 **Runtime**: identical semantics to the un-prefixed checks — `TaskResult` already exposes envelope fields at its surface (`data.status`, `data.task_id`, etc.), so the dispatcher passes through to the existing handlers. Result objects report the original check name verbatim so reporters can distinguish. The same passthrough lands in `scripts/conformance-replay.ts` so storyboard replay grades the new checks.
 
-**Drift detection**: walks `ProtocolEnvelopeSchema` (from `core/protocol-envelope.json`) instead of `TOOL_RESPONSE_SCHEMAS[task]` for envelope-scoped entries. The existing un-prefixed checks stay pinned to inner-response schemas.
+**Drift detection**: walks `ProtocolEnvelopeSchema` (from `core/protocol-envelope.json`) instead of `TOOL_RESPONSE_SCHEMAS[task]` for envelope-scoped entries. `field_absent` and `envelope_field_absent` are collected by the drift detector but skip reachability assertions — absence checks have no schema target by design.
 
 **Not envelope fields**: `errors` lives inside `payload` (per the per-tool response schema), and `adcp_version` / `adcp_major_version` are request-side only — these stay on the un-prefixed checks.
 
-Forward-compatible with the current 3.0.1 storyboards (no consumers yet). Lights up when the upstream PR migrates `v3-envelope-integrity.yaml` from `field_present: status` to `envelope_field_present: status` (the `VERIFIER_UNREACHABLE` exemption gets dropped after the next `npm run sync-schemas` post-3.0.2).
-
-A future PR will add `field_absent` + `envelope_field_absent` runner support so `v3-envelope-integrity.yaml` can land its currently-TODO `task_status` / `response_status` MUST-NOT assertions.
+Forward-compatible with the current 3.0.1 storyboards. Lights up when the upstream PR migrates `v3-envelope-integrity.yaml` from `field_present: status` to `envelope_field_present: status` (the `VERIFIER_UNREACHABLE` exemption gets dropped after the next `npm run sync-schemas` post-3.0.2). The `task_status` / `response_status` MUST-NOT assertions in `v3-envelope-integrity.yaml` can now land using `field_absent` / `envelope_field_absent` without a further SDK release.
 
 Refs adcp#3429.

src/lib/testing/storyboard/types.ts

@@ -401,6 +401,7 @@ export interface StoryboardStep {
 export type StoryboardValidationCheck =
   | 'response_schema'
   | 'field_present'
+  | 'field_absent'
   // Envelope-scoped variants — the asserted path lives on the v3 protocol
   // envelope (`status`, `task_id`, `message`, `replayed`, `governance_context`,
   // `timestamp`, `context_id`, `push_notification_config`) rather than the
@@ -409,6 +410,7 @@ export type StoryboardValidationCheck =
   // for static drift detection, which walks `protocol-envelope.json` instead
   // of the per-tool response schema. Added per adcp#3429.
   | 'envelope_field_present'
+  | 'envelope_field_absent'
   | 'envelope_field_value'
   | 'envelope_field_value_or_absent'
   | 'field_value'

src/lib/testing/storyboard/validations.ts

@@ -112,7 +112,10 @@ function runValidation(validation: StoryboardValidation, ctx: ValidationContext)
       // field_present runs against either MCP task result data OR an HTTP probe body —
       // the storyboard's probe_protected_resource validates fields in the RFC 9728 JSON.
       return validateFieldPresent(validation, resolveTarget(ctx));
+    case 'field_absent':
+      return validateFieldAbsent(validation, resolveTarget(ctx));
     case 'envelope_field_present':
+    case 'envelope_field_absent':
     case 'envelope_field_value':
     case 'envelope_field_value_or_absent':
       // Envelope-scoped variants — runtime semantics identical to the
@@ -121,6 +124,7 @@ function runValidation(validation: StoryboardValidation, ctx: ValidationContext)
       // exist primarily so static drift detection can walk the envelope
       // schema instead of the per-tool response. See adcp#3429.
       if (validation.check === 'envelope_field_present') return validateFieldPresent(validation, resolveTarget(ctx));
+      if (validation.check === 'envelope_field_absent') return validateFieldAbsent(validation, resolveTarget(ctx));
       if (validation.check === 'envelope_field_value') return validateFieldValue(validation, resolveTarget(ctx));
       return validateFieldValueOrAbsent(validation, resolveTarget(ctx));
     case 'field_value':
@@ -550,6 +554,57 @@ function validateFieldPresent(validation: StoryboardValidation, taskResult: Task
   };
 }
 
+// ────────────────────────────────────────────────────────────
+// field_absent / envelope_field_absent: check a path does NOT exist
+//
+// Pass when the field is absent (undefined or null). Fail when the field
+// is present with any value. The `envelope_field_absent` variant carries
+// the same runtime semantics but signals to the drift detector that the
+// path lives on the v3 envelope schema rather than the per-tool response.
+// Added per adcp#3429 alongside the `envelope_field_present` family.
+// ────────────────────────────────────────────────────────────
+
+function validateFieldAbsent(validation: StoryboardValidation, taskResult: TaskResult): ValidationResult {
+  const checkName = validation.check;
+  if (!validation.path) {
+    return {
+      check: checkName,
+      passed: false,
+      description: validation.description,
+      path: validation.path,
+      error: `No path specified for ${checkName} validation`,
+      json_pointer: null,
+      expected: 'path must be set in storyboard validation entry',
+      actual: null,
+    };
+  }
+
+  const value = resolvePath(taskResult.data, validation.path);
+  const absent = value === undefined || value === null;
+  const pointer = toJsonPointer(validation.path);
+
+  if (absent) {
+    return {
+      check: checkName,
+      passed: true,
+      description: validation.description,
+      path: validation.path,
+      json_pointer: pointer,
+    };
+  }
+
+  return {
+    check: checkName,
+    passed: false,
+    description: validation.description,
+    path: validation.path,
+    error: `Field found at path: ${validation.path} (expected absent)`,
+    json_pointer: pointer,
+    expected: null,
+    actual: value,
+  };
+}
+
 // ────────────────────────────────────────────────────────────
 // field_value: check a path equals expected value
 // ────────────────────────────────────────────────────────────

test/lib/storyboard-drift.test.js

@@ -214,7 +214,9 @@ function collectFieldValidations(storyboards) {
         for (const v of step.validations) {
           if (
             (v.check === 'field_present' ||
+              v.check === 'field_absent' ||
               v.check === 'envelope_field_present' ||
+              v.check === 'envelope_field_absent' ||
               v.check === 'field_value' ||
               v.check === 'envelope_field_value' ||
               v.check === 'field_value_or_absent' ||
@@ -325,13 +327,31 @@ describe('storyboard schema drift', () => {
     }
   });
 
+  describe('field_absent / envelope_field_absent are collected but skip reachability', () => {
+    // Absence checks have no schema target by design — a `field_absent` assertion
+    // validates that a path does NOT exist, so there is no schema field to walk.
+    // We still collect them in collectFieldValidations (above) so a future sweep
+    // can cross-reference storyboard intent, but we do not assert reachability.
+    const absentValidations = fieldValidations.filter(
+      v => v.check === 'field_absent' || v.check === 'envelope_field_absent'
+    );
+    it('absence-check validations are collected without reachability assertions', () => {
+      // Structural smoke-test: if any are present, they must have a path.
+      for (const entry of absentValidations) {
+        assert.ok(entry.path, `${entry.storyboard}/${entry.step}: field_absent entry missing path`);
+      }
+    });
+  });
+
   describe('envelope-scoped validations resolve in the v3 envelope schema', () => {
     // adcp#3429: storyboards assert envelope-level fields (`status`,
     // `task_id`, `message`, `replayed`, `governance_context`, `timestamp`,
     // `context_id`, `push_notification_config`) using the envelope-scoped
     // checks so the drift detector knows to walk `protocol-envelope.json`
     // rather than the per-tool response schema. `errors` and `adcp_version`
     // are NOT envelope fields — keep them on the un-prefixed checks.
+    // `envelope_field_absent` is excluded here — absence checks have no schema
+    // target (see the `field_absent / envelope_field_absent` block above).
     const envelopeValidations = fieldValidations.filter(
       v =>
         v.check === 'envelope_field_present' ||

test/lib/storyboard-validations.test.js

@@ -233,3 +233,73 @@ describe('envelope_field_present (adcp#3429)', () => {
     assert.match(result.error, /No path specified for envelope_field_present/);
   });
 });
+
+describe('field_absent / envelope_field_absent (adcp#3429)', () => {
+  it('passes when the asserted path is absent from the task data', () => {
+    const taskResult = { success: true, data: { status: 'completed' } };
+    const [result] = runOne(
+      [{ check: 'field_absent', path: 'legacy_status', description: 'legacy_status must not appear' }],
+      'get_adcp_capabilities',
+      taskResult
+    );
+    assert.strictEqual(result.passed, true, result.error);
+    assert.strictEqual(result.check, 'field_absent');
+  });
+
+  it('fails when the asserted path is present', () => {
+    const taskResult = { success: true, data: { status: 'completed', legacy_status: 'active' } };
+    const [result] = runOne(
+      [{ check: 'field_absent', path: 'legacy_status', description: 'legacy_status must not appear' }],
+      'get_adcp_capabilities',
+      taskResult
+    );
+    assert.strictEqual(result.passed, false);
+    assert.strictEqual(result.check, 'field_absent');
+    assert.match(result.error, /Field found at path: legacy_status/);
+  });
+
+  it('fails with no-path error when path is missing', () => {
+    const taskResult = { success: true, data: { status: 'completed' } };
+    const [result] = runOne(
+      [{ check: 'field_absent', description: 'no path given' }],
+      'get_adcp_capabilities',
+      taskResult
+    );
+    assert.strictEqual(result.passed, false);
+    assert.match(result.error, /No path specified for field_absent/);
+  });
+
+  it('envelope_field_absent passes when envelope field is absent', () => {
+    const taskResult = { success: true, data: { task_id: 'task-1' } };
+    const [result] = runOne(
+      [{ check: 'envelope_field_absent', path: 'legacy_status', description: 'envelope must not carry legacy_status' }],
+      'get_adcp_capabilities',
+      taskResult
+    );
+    assert.strictEqual(result.passed, true, result.error);
+    assert.strictEqual(result.check, 'envelope_field_absent');
+  });
+
+  it('envelope_field_absent fails when envelope field is present', () => {
+    const taskResult = { success: true, data: { task_id: 'task-1', legacy_status: 'active' } };
+    const [result] = runOne(
+      [{ check: 'envelope_field_absent', path: 'legacy_status', description: 'envelope must not carry legacy_status' }],
+      'get_adcp_capabilities',
+      taskResult
+    );
+    assert.strictEqual(result.passed, false);
+    assert.strictEqual(result.check, 'envelope_field_absent');
+    assert.match(result.error, /Field found at path: legacy_status/);
+  });
+
+  it('envelope_field_absent fails with no-path error when path is missing', () => {
+    const taskResult = { success: true, data: { status: 'completed' } };
+    const [result] = runOne(
+      [{ check: 'envelope_field_absent', description: 'no path given' }],
+      'get_adcp_capabilities',
+      taskResult
+    );
+    assert.strictEqual(result.passed, false);
+    assert.match(result.error, /No path specified for envelope_field_absent/);
+  });
+});