@intentius/chant-lexicon-cedar 0.44.8 → 0.44.10

package/src/lint/post-synth/dwdc010.ts

@@ -0,0 +1,62 @@
+/**
+ * DWDC010: a temporal predicate must name an event kind the schema declares
+ *
+ * Upstream rejects this outright — a predicate naming an undeclared kind fails
+ * `dogwood validate` with code `extension`: "predicate
+ * `Drupe::Action::\"Read\"::nosuchkind` does not name a declared event (no
+ * event kind `nosuchkind` derived for action `Read`)". Catching it in
+ * TypeScript is the point of the split epic #1646 drew: everything answerable
+ * without the binary runs always and gates, and this one is answerable.
+ *
+ * The check is on the event *kind*, not the action, and that is not a
+ * shortcut. Upstream's `.dwschema` grammar declares events against a symbolic
+ * action binder — `decision event <A>::request { … }` — so the file names no
+ * actions at all and cannot be asked whether one exists. The action half of
+ * that upstream error comes from the Cedar action schema
+ * (`--policy-schema`), which is #1659's CLI-gated leg.
+ *
+ * Silent when no `.dwschema` was emitted: with none supplied,
+ * `ServiceSchema::defaults()` decides the kinds at the far end, and guessing
+ * that a project's out-of-band schema matches upstream's default would fail
+ * builds for a policy set that is fine.
+ */
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { dogwoodPolicyFiles, dogwoodSchemaFiles, readEventSchema, scanPredicates } from "../../dogwood/scan";
+
+export const dwdc010: PostSynthCheck = {
+  id: "DWDC010",
+  description: "A dogwood temporal predicate names an event kind the emitted .dwschema declares",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const schemas = dogwoodSchemaFiles(ctx);
+    if (schemas.length === 0) return [];
+
+    const declared = new Set<string>();
+    for (const schema of schemas) {
+      for (const kind of readEventSchema(schema.text).kinds) declared.add(kind);
+    }
+    if (declared.size === 0) return [];
+
+    const known = [...declared].sort().join(", ");
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    for (const policies of dogwoodPolicyFiles(ctx)) {
+      const seen = new Set<string>();
+      for (const ref of scanPredicates(policies.text)) {
+        if (declared.has(ref.kind)) continue;
+        const key = `${ref.action}::${ref.kind}`;
+        if (seen.has(key)) continue;
+        seen.add(key);
+        diagnostics.push({
+          checkId: "DWDC010",
+          severity: "error",
+          message: `Dogwood policy set "${policies.source}" has a temporal predicate on ${key}, but the emitted event schema declares no event kind "${ref.kind}" (declared: ${known}).`,
+          entity: policies.source,
+          lexicon: policies.lexicon,
+        });
+      }
+    }
+
+    return diagnostics;
+  },
+};

package/src/lint/post-synth/dwdc011.ts

@@ -0,0 +1,61 @@
+/**
+ * DWDC011: a temporal window must fit inside the schema's `max_window`
+ *
+ * `formerly within 48h` under a 24h cap is an upstream validation error —
+ * "temporal window `48h` exceeds the maximum allowed window `24h` set by the
+ * event schema's `max_window`" — and it is arithmetic, so it needs no binary.
+ *
+ * Unlike DWDC010 this fires with no `.dwschema` emitted, because the cap
+ * applies either way: `ServiceSchema::defaults()` caps look-back at 24h, and
+ * so does an emitted schema that omits the directive. Where several schemas
+ * are emitted the tightest cap wins — a window one consumer accepts and
+ * another rejects is still a window that will be rejected.
+ *
+ * Macro-call intervals count. `once(48h, …)` expands to `formerly within 48h`
+ * through the default library's `within ?w`, so it looks back exactly as far.
+ */
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import {
+  dogwoodPolicyFiles,
+  dogwoodSchemaFiles,
+  effectiveMaxWindowSeconds,
+  readEventSchema,
+  scanWindows,
+} from "../../dogwood/scan";
+
+export const dwdc011: PostSynthCheck = {
+  id: "DWDC011",
+  description: "A dogwood temporal window stays inside the event schema's max_window cap",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const policyFiles = dogwoodPolicyFiles(ctx);
+    if (policyFiles.length === 0) return [];
+
+    const schemas = dogwoodSchemaFiles(ctx).map((s) => readEventSchema(s.text));
+    const cap = effectiveMaxWindowSeconds(schemas);
+    const source =
+      schemas.length === 0
+        ? "upstream's default cap (no event schema was emitted)"
+        : `the emitted event schema's max_window`;
+
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    for (const policies of policyFiles) {
+      const reported = new Set<string>();
+      for (const window of scanWindows(policies.text)) {
+        if (window.seconds <= cap.seconds) continue;
+        if (reported.has(window.text)) continue;
+        reported.add(window.text);
+        diagnostics.push({
+          checkId: "DWDC011",
+          severity: "error",
+          message: `Dogwood policy set "${policies.source}" looks back ${window.text}, past the ${cap.text} allowed by ${source}. Raise max_window in the event schema, or shorten the window.`,
+          entity: policies.source,
+          lexicon: policies.lexicon,
+        });
+      }
+    }
+
+    return diagnostics;
+  },
+};

package/src/lint/post-synth/dwdc012.ts

@@ -0,0 +1,46 @@
+/**
+ * DWDC012: `formerly`, `previous` and `since` carry a mandatory window
+ *
+ * Upstream's grammar makes `within` non-optional on all three:
+ *
+ * ```
+ * once_op     = { "formerly" ~ within ~ atom }
+ * previous_op = { "previous" ~ within ~ atom }
+ * conjunct_or_since = { neg_conjunct ~ ("since" ~ within ~ atom)? }
+ * ```
+ *
+ * The typed builders make this unrepresentable — `formerly(window, body)` has
+ * nowhere to put a missing window — which is most of the fix. This check is
+ * the other part: `raw()` exists as an escape hatch, a hand-written `.dw` can
+ * be built by any other tool, and `chant audit` runs over files chant never
+ * emitted. A wall that only holds for the path that cannot breach it is not
+ * a wall.
+ */
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { dogwoodPolicyFiles, scanWindowlessOperators } from "../../dogwood/scan";
+
+export const dwdc012: PostSynthCheck = {
+  id: "DWDC012",
+  description: "A dogwood formerly/previous/since operator carries its mandatory within window",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    for (const policies of dogwoodPolicyFiles(ctx)) {
+      const seen = new Set<string>();
+      for (const operator of scanWindowlessOperators(policies.text)) {
+        if (seen.has(operator)) continue;
+        seen.add(operator);
+        diagnostics.push({
+          checkId: "DWDC012",
+          severity: "error",
+          message: `Dogwood policy set "${policies.source}" uses \`${operator}\` with no \`within\` window. All three past-only operators require one — write \`${operator} within <n><s|m|h|d> …\`.`,
+          entity: policies.source,
+          lexicon: policies.lexicon,
+        });
+      }
+    }
+
+    return diagnostics;
+  },
+};

package/src/lint/post-synth/dwdc013.ts

@@ -0,0 +1,64 @@
+/**
+ * DWDC013: a temporal statement embedded in AgentCore needs its event schema
+ * registered
+ *
+ * `AWS::BedrockAgentCore::Policy` carries one string. When that string is `.dw`
+ * text — `Definition.Policy.Statement`, the language-agnostic arm — the policy
+ * engine at the other end has to know what an event *is* before any temporal
+ * predicate in it can match: which kinds exist, what fields they carry, and
+ * what is pinned to the deciding request. That is the `.dwschema` half of the
+ * schema, and the resource has no property to put it in.
+ *
+ * So a build that embeds temporal text and emits no event schema has shipped
+ * half a policy. Nothing fails: the statement deploys, the predicates match
+ * nothing, and a `formerly`-guarded permit stops granting — or a
+ * `formerly`-guarded forbid stops denying, which is the direction that
+ * matters. That is the silent trap this check exists for — the emitted schema
+ * is the artifact that makes the other half reviewable, whether it is
+ * registered with the engine out of band or shipped to a `dogwood validate`
+ * run.
+ *
+ * Warning rather than error, because "not emitted here" is not the same as
+ * "does not exist": a project may register the service schema through a
+ * separate pipeline, and failing that build would be chant asserting a fact it
+ * cannot check. Emitting one with `TemporalEventSchema` silences it and makes
+ * the assumption visible in the diff.
+ *
+ * The complement of DWDC010, which asks whether the kinds a `.dw` file names
+ * are declared. This one asks the prior question, and only of statements that
+ * left the `.dw` file behind.
+ */
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { embeddedAgentCorePolicyStatements } from "../../agentcore/scan";
+import { dogwoodSchemaFiles, temporalRegions } from "../../dogwood/scan";
+
+export const dwdc013: PostSynthCheck = {
+  id: "DWDC013",
+  description: "An embedded AgentCore temporal statement has its event schema emitted beside it",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    if (dogwoodSchemaFiles(ctx).length > 0) return [];
+
+    const diagnostics: PostSynthDiagnostic[] = [];
+    const seen = new Set<string>();
+
+    for (const embedded of embeddedAgentCorePolicyStatements(ctx)) {
+      if (temporalRegions(embedded.statement).length === 0) continue;
+
+      const named = embedded.logicalId ?? embedded.source;
+      const key = `${embedded.lexicon}:${embedded.source}:${named}`;
+      if (seen.has(key)) continue;
+      seen.add(key);
+
+      diagnostics.push({
+        checkId: "DWDC013",
+        severity: "warning",
+        message: `AgentCore policy "${named}" in "${embedded.source}" carries temporal text in Definition.Policy.Statement, but the build emitted no .dwschema event schema. The policy engine needs the event kinds and their pins registered before any temporal predicate can match; without them the clause never fires and the policy silently stops doing its job. Declare a TemporalEventSchema, or record where the service schema is registered.`,
+        entity: named,
+        lexicon: embedded.lexicon,
+      });
+    }
+
+    return diagnostics;
+  },
+};

package/src/lint/post-synth/dwde-post-synth.test.ts

@@ -0,0 +1,368 @@
+/**
+ * The CLI-gated DWDE checks (#1659).
+ *
+ * Every case injects a runner, and the absent-binary case forces absence
+ * rather than hoping the machine has none — a developer with `dogwood` built
+ * locally must see the same result as CI. The one test that touches a real
+ * binary is opt-in and skipped by default; nothing in gating depends on it.
+ *
+ * The lowered fixture is adapted from
+ * dogwood-policy/dogwood@5063bcc2d6d6cf5024d1b0498e6cc8ef52cbcf0c (Apache-2.0),
+ * `dogwood-docs/examples/read_after_login` — the same bundle the #1657
+ * verification put through this exact path.
+ */
+import { describe, test, expect, afterEach } from "vitest";
+import { readFileSync } from "fs";
+import { join } from "path";
+import { fileURLToPath } from "url";
+import type { PostSynthContext } from "@intentius/chant/lint/post-synth";
+import type { SerializerResult } from "@intentius/chant/serializer";
+import { postSynthChecks } from "./index";
+import { dwde010 } from "./dwde010";
+import { dwde011 } from "./dwde011";
+import { looksLikeMacroLibrary, planDogwoodRuns } from "./dogwood-helpers";
+import { cedarAuditCatalog } from "../audit-catalog";
+import { configureDogwoodCli, findDogwoodBinary, resetDogwoodCli, type DogwoodRun } from "../../dogwood/cli";
+
+const TESTDATA = join(fileURLToPath(new URL("../..", import.meta.url)), "dogwood/testdata");
+
+const POLICIES = readFileSync(join(TESTDATA, "read-after-login.dw"), "utf-8");
+const ACTION_SCHEMA = readFileSync(join(TESTDATA, "read-after-login.cedarschema"), "utf-8");
+const EVENT_SCHEMA = readFileSync(join(TESTDATA, "pinned.dwschema"), "utf-8");
+const MACROS = readFileSync(join(TESTDATA, "default-macros.dw"), "utf-8");
+const LOWERED = JSON.parse(readFileSync(join(TESTDATA, "lowered-read-after-login.json"), "utf-8")) as Record<
+  string,
+  unknown
+>;
+
+afterEach(() => resetDogwoodCli());
+
+function ctxOf(files: Record<string, string>): PostSynthContext {
+  const output: SerializerResult = { primary: "", files };
+  const outputs = new Map<string, string | SerializerResult>([["cedar", output]]);
+  return {
+    outputs,
+    entities: new Map(),
+    buildResult: { outputs, entities: new Map(), warnings: [], errors: [], sourceFileCount: 1 },
+  };
+}
+
+/** The shape a real build emits: policies, action schema, event schema, macros. */
+function fullBuild(): PostSynthContext {
+  return ctxOf({
+    "policies.dw": POLICIES,
+    "macros.dw": MACROS,
+    "app.cedarschema": ACTION_SCHEMA,
+    "events.dwschema": EVENT_SCHEMA,
+  });
+}
+
+function run(over: Partial<DogwoodRun>): DogwoodRun {
+  return { status: 0, stdout: "", stderr: "", ...over };
+}
+
+const PASSING = run({
+  status: 0,
+  stdout: JSON.stringify({ passed: true, passed_without_warnings: true, errors: [], warnings: [] }),
+});
+
+/** Answer `validate` one way and `lower` another, from the subcommand argv[0]. */
+function bySubcommand(answers: Record<string, DogwoodRun>) {
+  return (_binary: string, args: string[]): DogwoodRun => answers[args[0]] ?? run({ status: 0, stdout: "" });
+}
+
+// ── The planner ────────────────────────────────────────────────────
+
+describe("planning what to run", () => {
+  test("a macro library is told from a policy set by structure, not by filename", () => {
+    expect(looksLikeMacroLibrary(MACROS)).toBe(true);
+    expect(looksLikeMacroLibrary(POLICIES)).toBe(false);
+    // A library under a non-default filename is still a library.
+    expect(looksLikeMacroLibrary("def temporal once(?w, ?s) { formerly within ?w ?s };")).toBe(true);
+  });
+
+  test("one bundle per policy set, with the macro libraries folded into one --macros file", () => {
+    const plan = planDogwoodRuns(fullBuild());
+    expect(plan.hasPolicies).toBe(true);
+    expect(plan.bundles).toHaveLength(1);
+    const [only] = plan.bundles;
+    expect(only.source).toBe("policies.dw");
+    expect(only.policySchemaSource).toBe("app.cedarschema");
+    expect(only.eventSchemaSource).toBe("events.dwschema");
+    expect(only.bundle.macros).toContain("def temporal");
+  });
+
+  test("several event schemas mean several runs, each naming its own schema", () => {
+    const ctx = ctxOf({
+      "policies.dw": POLICIES,
+      "app.cedarschema": ACTION_SCHEMA,
+      "events.dwschema": EVENT_SCHEMA,
+      "gateway.dwschema": EVENT_SCHEMA,
+    });
+    const plan = planDogwoodRuns(ctx);
+    expect(plan.bundles.map((b) => b.eventSchemaSource)).toEqual(["events.dwschema", "gateway.dwschema"]);
+  });
+
+  test("no .dw policy set means nothing to plan, even with a schema emitted", () => {
+    expect(planDogwoodRuns(ctxOf({ "events.dwschema": EVENT_SCHEMA })).hasPolicies).toBe(false);
+    expect(planDogwoodRuns(ctxOf({ "macros.dw": MACROS })).hasPolicies).toBe(false);
+  });
+
+  test("policies with no action schema are blocked, because --policy-schema is not optional", () => {
+    const plan = planDogwoodRuns(ctxOf({ "policies.dw": POLICIES }));
+    expect(plan.hasPolicies).toBe(true);
+    expect(plan.bundles).toEqual([]);
+    expect(plan.blocked).toContain("--policy-schema");
+  });
+});
+
+// ── DWDE010 ────────────────────────────────────────────────────────
+
+describe("DWDE010 — full .dw validation, when the binary is there", () => {
+  test("a passing validate is silent", () => {
+    configureDogwoodCli({ binary: "/opt/dogwood", runner: () => PASSING });
+    expect(dwde010.check(fullBuild())).toEqual([]);
+  });
+
+  test("a rejection becomes one error per finding, with the code and the byte span", () => {
+    const rejected = run({
+      status: 2,
+      stdout: JSON.stringify({
+        passed: false,
+        passed_without_warnings: false,
+        errors: [
+          {
+            severity: "error",
+            code: "extension",
+            message:
+              'predicate `Drupe::Action::"NoSuchAction"::request` does not name a declared event (no event kind `request` derived for action `NoSuchAction`)',
+            labels: [{ start: 210, len: 46 }],
+            spanned: true,
+          },
+        ],
+        warnings: [],
+      }),
+    });
+    configureDogwoodCli({ binary: "/opt/dogwood", runner: () => rejected });
+
+    const [finding, ...rest] = dwde010.check(fullBuild());
+    expect(rest).toEqual([]);
+    expect(finding.severity).toBe("error");
+    expect(finding.checkId).toBe("DWDE010");
+    expect(finding.message).toContain("[extension]");
+    expect(finding.message).toContain("bytes 210-256");
+    expect(finding.message).toContain('"policies.dw"');
+    expect(finding.message).toContain('against "app.cedarschema"');
+    expect(finding.entity).toBe("policies.dw");
+  });
+
+  test("a fatal parse error comes through the other JSON shape and is still an error", () => {
+    const fatal = run({
+      status: 2,
+      stdout: JSON.stringify({
+        severity: "error",
+        message: "unknown macro `once`",
+        labels: [{ start: 12, len: 4 }],
+        spanned: true,
+        related: [{ severity: "error", message: "a second parse error", spanned: false }],
+      }),
+    });
+    configureDogwoodCli({ binary: "/opt/dogwood", runner: () => fatal });
+
+    const findings = dwde010.check(fullBuild());
+    expect(findings).toHaveLength(2);
+    expect(findings.every((f) => f.severity === "error")).toBe(true);
+    expect(findings[0].message).toContain("could not be parsed or lowered");
+    expect(findings[0].message).toContain("unknown macro `once`");
+  });
+
+  test("upstream's warnings ride along at warning severity and do not fail the build", () => {
+    const warned = run({
+      status: 0,
+      stdout: JSON.stringify({
+        passed: true,
+        passed_without_warnings: false,
+        errors: [],
+        warnings: [{ severity: "warning", message: "policy is impossible", labels: [], spanned: false }],
+      }),
+    });
+    configureDogwoodCli({ binary: "/opt/dogwood", runner: () => warned });
+
+    const [finding] = dwde010.check(fullBuild());
+    expect(finding.severity).toBe("warning");
+    expect(finding.message).toContain("policy is impossible");
+  });
+
+  test("the exit-2 ambiguity is a warning about the run, never an error about the policy", () => {
+    // An unknown flag and a rejected policy set share exit 2. Reading the code
+    // alone would turn a flag rename in an upstream sync into a failed build.
+    const usage = run({
+      status: 2,
+      stdout: "",
+      stderr: "error: unexpected argument '--nosuchflag' found",
+    });
+    configureDogwoodCli({ binary: "/opt/dogwood", runner: () => usage });
+
+    const [finding, ...rest] = dwde010.check(fullBuild());
+    expect(rest).toEqual([]);
+    expect(finding.severity).toBe("warning");
+    expect(finding.message).toContain("neither accepted nor rejected");
+  });
+
+  test("no binary is exactly one info advisory naming the binary and the issue", () => {
+    configureDogwoodCli({ binary: null });
+    const [finding, ...rest] = dwde010.check(fullBuild());
+    expect(rest).toEqual([]);
+    expect(finding.severity).toBe("info");
+    expect(finding.message).toContain("dogwood");
+    expect(finding.message).toContain("chant #1659");
+    expect(finding.message).toContain("CHANT_DOGWOOD_BINARY");
+    expect(finding.lexicon).toBe("cedar");
+  });
+
+  test("the advisory does not fire on a build with no .dw output at all", () => {
+    configureDogwoodCli({ binary: null });
+    expect(dwde010.check(ctxOf({ "policies.cedar.json": "{}" }))).toEqual([]);
+  });
+
+  test("a binary with nothing to validate against says so rather than passing quietly", () => {
+    configureDogwoodCli({ binary: "/opt/dogwood", runner: () => PASSING });
+    const [finding] = dwde010.check(ctxOf({ "policies.dw": POLICIES }));
+    expect(finding.severity).toBe("info");
+    expect(finding.message).toContain("--policy-schema");
+  });
+});
+
+// ── DWDE011 ────────────────────────────────────────────────────────
+
+describe("DWDE011 — the lowered Cedar through Cedar's own validator", () => {
+  test("the lowered read_after_login bundle validates clean end to end", () => {
+    configureDogwoodCli({
+      binary: "/opt/dogwood",
+      runner: bySubcommand({
+        validate: PASSING,
+        lower: run({ status: 0, stdout: JSON.stringify(LOWERED) }),
+      }),
+    });
+    expect(dwde011.check(fullBuild())).toEqual([]);
+  });
+
+  test("a lowered body naming a slot the augmented schema lacks fails Cedar validation", () => {
+    // The same artifacts with the policy pointed at a context field the
+    // augmented schema never grew — what a lowering/schema mismatch looks like
+    // from Cedar's side.
+    const drifted = {
+      ...LOWERED,
+      cedar_policies: (LOWERED.cedar_policies as string).replace(
+        "policy_0__temporal_0",
+        "policy_9__temporal_9",
+      ),
+    };
+    configureDogwoodCli({
+      binary: "/opt/dogwood",
+      runner: bySubcommand({ validate: PASSING, lower: run({ status: 0, stdout: JSON.stringify(drifted) }) }),
+    });
+
+    const findings = dwde011.check(fullBuild());
+    expect(findings.length).toBeGreaterThan(0);
+    expect(findings[0].severity).toBe("error");
+    expect(findings[0].checkId).toBe("DWDE011");
+    expect(findings[0].message).toContain("fails Cedar validation");
+    expect(findings[0].entity).toBe("policies.dw");
+  });
+
+  test("findings are sorted, so a build's output does not shuffle between runs", () => {
+    const twoBad = {
+      ...LOWERED,
+      cedar_policies: `permit (principal, action == Drupe::Action::"Read", resource) when { context.zzz };\npermit (principal, action == Drupe::Action::"Read", resource) when { context.aaa };\n`,
+    };
+    configureDogwoodCli({
+      binary: "/opt/dogwood",
+      runner: bySubcommand({ validate: PASSING, lower: run({ status: 0, stdout: JSON.stringify(twoBad) }) }),
+    });
+
+    const messages = dwde011.check(fullBuild()).map((f) => f.message);
+    expect(messages).toEqual([...messages].sort());
+  });
+
+  test("silent when the binary is absent — DWDE010's advisory covers that once", () => {
+    configureDogwoodCli({ binary: null });
+    expect(dwde011.check(fullBuild())).toEqual([]);
+  });
+
+  test("silent when no action schema was emitted, for the same reason", () => {
+    configureDogwoodCli({ binary: "/opt/dogwood", runner: () => PASSING });
+    expect(dwde011.check(ctxOf({ "policies.dw": POLICIES }))).toEqual([]);
+  });
+
+  test("a fatal lower stays quiet — the validate leg owns the parse/lower channel", () => {
+    configureDogwoodCli({
+      binary: "/opt/dogwood",
+      runner: bySubcommand({
+        validate: PASSING,
+        lower: run({
+          status: 2,
+          stdout: JSON.stringify({ severity: "error", message: "unknown macro `once`", spanned: false }),
+        }),
+      }),
+    });
+    expect(dwde011.check(fullBuild())).toEqual([]);
+  });
+
+  test("a lower that could not be run is a warning about the run", () => {
+    configureDogwoodCli({
+      binary: "/opt/dogwood",
+      runner: bySubcommand({ validate: PASSING, lower: run({ status: 2, stdout: "", stderr: "usage" }) }),
+    });
+    const [finding] = dwde011.check(fullBuild());
+    expect(finding.severity).toBe("warning");
+    expect(finding.message).toContain("not checked by Cedar's validator");
+  });
+});
+
+// ── Registration ───────────────────────────────────────────────────
+
+describe("registration", () => {
+  test("both checks reach the committed barrel", () => {
+    const ids = postSynthChecks.map((c) => c.id);
+    expect(ids).toContain("DWDE010");
+    expect(ids).toContain("DWDE011");
+  });
+
+  test("both are catalogued, so `chant audit` can title them", () => {
+    for (const id of ["DWDE010", "DWDE011"]) {
+      const meta = cedarAuditCatalog[id];
+      expect(meta, `${id} is catalogued`).toBeDefined();
+      expect(meta.title.length).toBeGreaterThan(0);
+      expect(meta.remediation.length).toBeGreaterThan(0);
+    }
+  });
+
+  test("the helper module contributes no check of its own", () => {
+    // `dogwood-helpers.ts` is excluded from discovery by the "helper" filename
+    // filter, the same way `wasm-helpers.ts` is.
+    expect(postSynthChecks.filter((c) => c.id.startsWith("DWD"))).toHaveLength(7);
+  });
+});
+
+// ── Opt-in: a real binary ──────────────────────────────────────────
+
+/**
+ * Runs only when `CHANT_DOGWOOD_E2E=1` *and* a binary resolves. Never gates:
+ * the epic's rule is that nothing in gating CI executes the dogwood binary,
+ * and this exists so someone who has built one can confirm the adapter reads
+ * the real thing the way the fixtures say it does.
+ */
+const haveRealBinary = process.env.CHANT_DOGWOOD_E2E === "1" && findDogwoodBinary() !== undefined;
+
+describe.skipIf(!haveRealBinary)("against a real dogwood binary (opt-in)", () => {
+  test("the upstream read_after_login bundle validates clean", () => {
+    resetDogwoodCli();
+    expect(dwde010.check(fullBuild())).toEqual([]);
+  });
+
+  test("and its lowered Cedar validates clean through cedar-wasm", () => {
+    resetDogwoodCli();
+    expect(dwde011.check(fullBuild())).toEqual([]);
+  });
+});