@intentius/chant-lexicon-cedar 0.44.8 → 0.44.10

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

@@ -0,0 +1,130 @@
+/**
+ * DWDE010: the emitted `.dw` set validates clean under `dogwood validate`
+ *
+ * The CLI-gated half of the epic's validation split. Everything the DWDC walls
+ * ask is answerable in TypeScript and gates unconditionally; everything else —
+ * macro expansion, the temporal type checker, the Cedar body checked against
+ * the action schema *through upstream's own frontend* — needs upstream's Rust
+ * frontend, which ships as a binary and nothing else. No npm package, no wasm
+ * build, no bindings.
+ *
+ * So this check has two modes and says which one it is in:
+ *
+ * - **Binary present.** Runs `dogwood validate --format json` over each
+ *   emitted policy set and reports every finding as an error. Byte-offset
+ *   labels come through as byte offsets — see `../../dogwood/cli.ts` for why
+ *   they are not converted to line/column.
+ * - **Binary absent.** Exactly one `info` finding naming the binary, where
+ *   chant looked, and this issue. The epic's words are "an explicit,
+ *   issue-linked exception, not a silent one" — a check that quietly passes
+ *   when it could not run is claiming a guarantee it did not make, which is
+ *   the same failure CEDE010's no-schema advisory exists to avoid.
+ *
+ * A run that could not be made at all — a spawn failure, an unknown flag, JSON
+ * in a shape this adapter does not know — is `warning`, not `error`. Upstream
+ * is a read-only squash-sync mirror with no tags and no changelog, and a flag
+ * rename in a sync would otherwise fail every build that has the binary
+ * installed. The adapter never reads exit 2 as "rejected" on its own for the
+ * same reason: clap spends that code on usage errors too.
+ */
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import {
+  DOGWOOD_BINARY_NAME,
+  DOGWOOD_SEARCH_ORDER,
+  findDogwoodBinary,
+  formatDogwoodDiagnostic,
+  runDogwoodValidate,
+} from "../../dogwood/cli";
+import { describeBundle, planDogwoodRuns } from "./dogwood-helpers";
+
+export const dwde010: PostSynthCheck = {
+  id: "DWDE010",
+  description: "Emitted dogwood policy sets validate clean under `dogwood validate`, when the binary is available",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const plan = planDogwoodRuns(ctx);
+    if (!plan.hasPolicies) return [];
+
+    const binary = findDogwoodBinary();
+    if (!binary) {
+      return [
+        {
+          checkId: "DWDE010",
+          severity: "info",
+          message: `This build emitted dogwood .dw policies, but no \`${DOGWOOD_BINARY_NAME}\` binary was found, so full .dw validation did not run — the DWDC walls checked what TypeScript can answer and nothing checked macro expansion, the temporal type check, or the Cedar body against the action schema. chant looked at ${DOGWOOD_SEARCH_ORDER}. See chant #1659.`,
+          lexicon: plan.lexicon,
+        },
+      ];
+    }
+
+    if (plan.blocked) {
+      return [
+        {
+          checkId: "DWDE010",
+          severity: "info",
+          message: `This build emitted dogwood .dw policies and \`${DOGWOOD_BINARY_NAME}\` is available, but ${plan.blocked}, so full .dw validation did not run. See chant #1659.`,
+          lexicon: plan.lexicon,
+        },
+      ];
+    }
+
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    for (const prepared of plan.bundles) {
+      const where = describeBundle(prepared);
+      const result = runDogwoodValidate(binary.path, prepared.bundle);
+
+      if (result.kind === "unusable") {
+        diagnostics.push({
+          checkId: "DWDE010",
+          severity: "warning",
+          message: `Dogwood policy set ${where} could not be validated — ${result.reason}. The policy set was neither accepted nor rejected.`,
+          entity: prepared.source,
+          lexicon: prepared.lexicon,
+        });
+        continue;
+      }
+
+      if (result.kind === "fatal") {
+        for (const finding of [result.error, ...result.related]) {
+          diagnostics.push({
+            checkId: "DWDE010",
+            severity: "error",
+            message: `Dogwood policy set ${where} could not be parsed or lowered: ${formatDogwoodDiagnostic(finding)}`,
+            entity: prepared.source,
+            lexicon: prepared.lexicon,
+          });
+        }
+        continue;
+      }
+
+      if (result.kind === "rejected") {
+        for (const finding of result.errors) {
+          diagnostics.push({
+            checkId: "DWDE010",
+            severity: "error",
+            message: `Dogwood policy set ${where} fails \`dogwood validate\`: ${formatDogwoodDiagnostic(finding)}`,
+            entity: prepared.source,
+            lexicon: prepared.lexicon,
+          });
+        }
+      }
+
+      // Upstream's own warnings ride along at warning severity. They do not
+      // fail `dogwood validate` (`passed` ignores them), and they should not
+      // fail a build either — but dropping them would throw away the half of
+      // the report that says a policy is legal and pointless.
+      for (const finding of result.warnings) {
+        diagnostics.push({
+          checkId: "DWDE010",
+          severity: "warning",
+          message: `Dogwood policy set ${where} draws a \`dogwood validate\` warning: ${formatDogwoodDiagnostic(finding)}`,
+          entity: prepared.source,
+          lexicon: prepared.lexicon,
+        });
+      }
+    }
+
+    return diagnostics;
+  },
+};

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

@@ -0,0 +1,108 @@
+/**
+ * DWDE011: the lowered Cedar body validates clean under Cedar's own validator
+ *
+ * The epic's stated design for the non-temporal half: chant does not
+ * re-implement lowering — `dogwood lower` produces the analyzable plain-Cedar
+ * form, and a reimplementation would drift — but once that form exists, Cedar's
+ * own validator is the thing that judges it. The #1657 verification put all 86
+ * upstream example bundles through this exact path and every one parsed and
+ * validated clean in strict mode, which is what makes a finding here mean
+ * something: the lowered output is genuinely plain Cedar, so a validation error
+ * is the policy's, not the pipeline's.
+ *
+ * What this catches that DWDE010 does not is narrow but real. `dogwood
+ * validate` type-checks through upstream's vendored Cedar; this runs the
+ * *published* `@cedar-policy/cedar-wasm` over the same artifacts. A body that
+ * upstream's pinned Cedar accepts and the Cedar the rest of chant validates
+ * against rejects is exactly the drift the pin exists to make visible — and the
+ * augmented schema, with its hoisted `context.*` temporal slots, is the form a
+ * downstream Cedar policy store will actually receive.
+ *
+ * The cedar-wasm traps from #1648 all apply and are handled in
+ * `./wasm-helpers.ts`: `type: "success"` means validation *ran*, not that it
+ * passed; `validationErrors` comes back in a different order almost every call
+ * and is sorted before anything reads it; a malformed call throws rather than
+ * returning a failure answer.
+ *
+ * Silent when `lower` did not run — the binary is absent, or no action schema
+ * was emitted. Both cases are DWDE010's advisory to report, once, rather than
+ * twice in different words.
+ */
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { findDogwoodBinary, runDogwoodLower } from "../../dogwood/cli";
+import { describeBundle, planDogwoodRuns } from "./dogwood-helpers";
+import { loadWasm, validatePolicySet } from "./wasm-helpers";
+
+export const dwde011: PostSynthCheck = {
+  id: "DWDE011",
+  description: "The Cedar `dogwood lower` produces validates clean against the augmented schema (cedar-wasm validate)",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const plan = planDogwoodRuns(ctx);
+    if (!plan.hasPolicies || plan.blocked || plan.bundles.length === 0) return [];
+
+    const binary = findDogwoodBinary();
+    if (!binary) return [];
+
+    // A missing validator is not this check's finding to report; the cedar leg
+    // says so already through CEDC010.
+    const wasm = loadWasm();
+    if (!wasm) return [];
+
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    for (const prepared of plan.bundles) {
+      const where = describeBundle(prepared);
+      const lowered = runDogwoodLower(binary.path, prepared.bundle);
+
+      if (lowered.kind === "unusable") {
+        diagnostics.push({
+          checkId: "DWDE011",
+          severity: "warning",
+          message: `Dogwood policy set ${where} could not be lowered to Cedar — ${lowered.reason}. Its non-temporal body was not checked by Cedar's validator.`,
+          entity: prepared.source,
+          lexicon: prepared.lexicon,
+        });
+        continue;
+      }
+
+      if (lowered.kind === "fatal") {
+        // The same fatal DWDE010 reports from its own run. Saying it twice
+        // helps nobody, so this arm stays quiet and lets the validate leg own
+        // the parse/lower channel.
+        continue;
+      }
+
+      const { cedarPolicies, cedarSchema } = lowered.value;
+
+      // The lowered policies go in as Cedar text. cedar-wasm synthesizes ids
+      // (`policy0`, `policy1`) for a bare-string set and does not read `@id`
+      // annotations as ids (#1648), so a finding names the .dw file it came
+      // from as well as the id the validator used.
+      const outcome = validatePolicySet(wasm, { staticPolicies: cedarPolicies }, cedarSchema);
+
+      if (outcome.failure) {
+        diagnostics.push({
+          checkId: "DWDE011",
+          severity: "error",
+          message: `The Cedar lowered from dogwood policy set ${where} could not be validated: ${outcome.failure}`,
+          entity: prepared.source,
+          lexicon: prepared.lexicon,
+        });
+        continue;
+      }
+
+      for (const finding of outcome.errors) {
+        diagnostics.push({
+          checkId: "DWDE011",
+          severity: "error",
+          message: `The Cedar lowered from dogwood policy set ${where} fails Cedar validation (lowered policy "${finding.policyId}"): ${finding.message}`,
+          entity: prepared.source,
+          lexicon: prepared.lexicon,
+        });
+      }
+    }
+
+    return diagnostics;
+  },
+};

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

@@ -0,0 +1,46 @@
+/**
+ * DWDS010: an emitted event schema with no pinned field widens every predicate
+ *
+ * The #1657 verification is specific about this one. `ServiceSchema::defaults()`
+ * — what runs when nobody passes `--event-schema` — uses
+ * `configuration/event-schemas/pinned.dwschema`, which carries
+ * `pin callerPrincipal: principalType(A) = principal` on every kind. Every
+ * temporal predicate is therefore correlated to the deciding request's
+ * principal, and events from other principals are invisible.
+ *
+ * Supplying any event schema opts out of that default wholesale. So a schema
+ * emitted without a pin does not merely "not add" a correlation: it removes
+ * one the policy author very likely assumed, and every `formerly` in the set
+ * starts matching other principals' events. That is a legitimate design —
+ * cross-principal correlation is the reason to write your own schema — but it
+ * is a decision, and a decision nobody can see in a diff is one nobody made.
+ *
+ * Report-only: chant does not know which the author wanted, only that it
+ * should be said out loud. `defaultEventSchema({ pinCallerPrincipal: false })`
+ * also stamps the reasoning into the emitted file.
+ */
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { dogwoodSchemaFiles, readEventSchema } from "../../dogwood/scan";
+
+export const dwds010: PostSynthCheck = {
+  id: "DWDS010",
+  description: "An emitted dogwood event schema pins its temporal predicates to a request-side value",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    for (const schema of dogwoodSchemaFiles(ctx)) {
+      const facts = readEventSchema(schema.text);
+      if (facts.kinds.length === 0 || facts.hasPin) continue;
+      diagnostics.push({
+        checkId: "DWDS010",
+        severity: "warning",
+        message: `Dogwood event schema "${schema.source}" declares no pinned field, so temporal predicates correlate across every principal — wider than upstream's default, which pins callerPrincipal to the deciding request's principal. Add a pinned field, or record why cross-principal correlation is wanted.`,
+        entity: schema.source,
+        lexicon: schema.lexicon,
+      });
+    }
+
+    return diagnostics;
+  },
+};

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

@@ -10,6 +10,13 @@ import { cede011 } from "./cede011";
 import { ceds010 } from "./ceds010";
 import { ceds011 } from "./ceds011";
 import { ceds012 } from "./ceds012";
+import { dwdc010 } from "./dwdc010";
+import { dwdc011 } from "./dwdc011";
+import { dwdc012 } from "./dwdc012";
+import { dwdc013 } from "./dwdc013";
+import { dwde010 } from "./dwde010";
+import { dwde011 } from "./dwde011";
+import { dwds010 } from "./dwds010";
 
 export const postSynthChecks: PostSynthCheck[] = [
   cedc010,
@@ -22,4 +29,11 @@ export const postSynthChecks: PostSynthCheck[] = [
   ceds010,
   ceds011,
   ceds012,
+  dwdc010,
+  dwdc011,
+  dwdc012,
+  dwdc013,
+  dwde010,
+  dwde011,
+  dwds010,
 ];

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

@@ -12,7 +12,7 @@
 import { describe, test, expect } from "vitest";
 import { createPostSynthContext, makePostSynthCtxFromFiles } from "@intentius/chant-test-utils";
 import type { PostSynthContext } from "@intentius/chant/lint/post-synth";
-import { CEDAR_JSON_FILENAME } from "../../serializer";
+import { CEDAR_JSON_FILENAME, cedarSerializer } from "../../serializer";
 import { postSynthChecks } from ".";
 import { cedc010 } from "./cedc010";
 import { cedc011 } from "./cedc011";
@@ -103,10 +103,14 @@ function ctxWithSchema(
 // ── Barrel ─────────────────────────────────────────────────────────
 
 describe("the cedar post-synth barrel", () => {
-  test("ships every check exactly once, all under the CED prefix", () => {
+  test("ships every check exactly once, under a declared prefix", () => {
+    // Two id families, both declared on the serializer: CED for Cedar itself,
+    // DWD for the dogwood temporal dialect that ships inside this lexicon
+    // (#1658). An id outside both is what `chant dev check-lexicon` fails on.
+    const declared = [cedarSerializer.rulePrefix, ...(cedarSerializer.extraRulePrefixes ?? [])];
     const ids = postSynthChecks.map((c) => c.id);
     expect(new Set(ids).size).toBe(ids.length);
-    expect(ids.every((id) => id.startsWith("CED"))).toBe(true);
+    expect(ids.filter((id) => !declared.some((p) => id.startsWith(p)))).toEqual([]);
     expect(ids.length).toBeGreaterThanOrEqual(10);
   });
 

package/src/op/activities/index.ts

@@ -0,0 +1,27 @@
+/**
+ * cedar Op activities — resolved by the core activity registry when a
+ * project's `chant.config.ts` lists the `cedar` lexicon.
+ *
+ * The registry keys every exported *function* in this module by its name
+ * (`loadActivities` → `collectActivities`), which is why only the activities
+ * themselves are exported here. `dogwoodReplay`'s helpers — the input
+ * resolver, the verdict comparison, the summary renderer — stay importable
+ * from `@intentius/chant-lexicon-cedar/dogwood/replay-activity` rather than
+ * being registered as activities nobody would ever name in a step.
+ *
+ * Contributed the `flyApply` way: a plain async function taking one args
+ * object, with no Temporal import anywhere beneath it, so the local executor
+ * runs it unchanged and a Temporal worker registers the same function.
+ */
+
+export { dogwoodReplay, dogwoodReplayReport } from "../../dogwood/replay-activity";
+export type {
+  DogwoodReplayArgs,
+  DogwoodReplayReportArgs,
+  ExpectedVerdict,
+  PolicyReplayDispatch,
+  PolicyReplayMode,
+  PolicyReplayReport,
+  ReplayDivergence,
+  ReplayExpectation,
+} from "../../dogwood/replay-activity";

package/src/plugin.test.ts

@@ -43,9 +43,9 @@ describe("cedar plugin", () => {
     }
   });
 
-  it("ships three skills whose frontmatter matches their registered name", () => {
+  it("ships four skills whose frontmatter matches their registered name", () => {
     const skills = cedarPlugin.skills?.() ?? [];
-    expect(skills).toHaveLength(3);
+    expect(skills).toHaveLength(4);
 
     for (const skill of skills) {
       // An empty body means the loader could not read the file — the skill
@@ -59,6 +59,7 @@ describe("cedar plugin", () => {
     expect(skills.map((s) => s.name).sort()).toEqual([
       "chant-cedar-authoring",
       "chant-cedar-avp-embedding",
+      "chant-cedar-dogwood",
       "chant-cedar-meta-policy",
     ]);
   });

package/src/plugin.ts

@@ -153,6 +153,36 @@ export const cedarPlugin: LexiconPlugin = {
         },
       ],
     },
+    {
+      file: "chant-cedar-dogwood.md",
+      name: "chant-cedar-dogwood",
+      description:
+        "Author dogwood temporal policies with the typed builders — parser primitives versus default-library macros, the callerPrincipal pin, the CLI-gated validation split, AgentCore embedding and trace replay",
+      triggers: [
+        { type: "file-pattern", value: "**/*.dw" },
+        { type: "file-pattern", value: "**/*.dwschema" },
+        { type: "context", value: "dogwood" },
+        { type: "context", value: "temporal policy" },
+        { type: "context", value: "agentcore policy" },
+        { type: "context", value: "rate limit policy" },
+        { type: "context", value: "policy replay" },
+      ],
+      parameters: [],
+      examples: [
+        {
+          title: "Approval before action",
+          description: "Allow a read only if a login happened inside the window",
+          input: "Only let them read if they logged in within the last hour",
+          output: `whenTemporal: [dogwood.formerly("1h", dogwood.predicate('Drupe::Action::"Login"', "response"))]`,
+        },
+        {
+          title: "The macro caveat",
+          input: "Use count_within for a rate limit",
+          output:
+            "count_within is a default-library macro a --macros caller replaces — emit the call and ship the definition, or build it from `count for … where`",
+        },
+      ],
+    },
   ]),
 
   initTemplates(template?: string): InitTemplateSet {

package/src/policy-text.ts

@@ -0,0 +1,128 @@
+/**
+ * Cedar policy-text rendering, shared by the `.cedar` serializer, the AVP
+ * statement renderer, and the dogwood dialect's `.dw` leg.
+ *
+ * Upstream's dogwood policy grammar is Cedar's shape — `annotation* effect
+ * "(" scope ")" cond* ";"` — and only the `cond` rule differs, gaining
+ * `guardrails { … }` and `temporal { … }` forms. So everything above the first
+ * clause is common, and it lives here rather than being copied into
+ * `./dogwood/serialize.ts`, where a change to how a scope constraint is
+ * written would have had to be made twice.
+ *
+ * `resolvePolicyId` is here for the same reason it was extracted from
+ * `serialize()` by #1652: it is the only rule linking a chant entity to a
+ * policy id, the AVP observation matches against it, and the `.dw` leg has to
+ * derive ids the same way the `.cedar` leg does. One copy, three callers.
+ *
+ * This module is a leaf on purpose: `./serializer.ts` and `./dogwood/*` both
+ * import it, and neither imports the other's rendering.
+ */
+
+import type { Declarable } from "@intentius/chant/declarable";
+import { isResourceDeclarable } from "@intentius/chant/declarable";
+
+/** A plain object — not null, not an array. */
+export function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** The `props` of a resource-kind Declarable, or `{}` for anything else. */
+export function getProps(entity: Declarable): Record<string, unknown> {
+  if (isResourceDeclarable(entity) && isRecord(entity.props)) {
+    return entity.props;
+  }
+  return {};
+}
+
+/** Escape a string for a double-quoted Cedar literal. */
+export function escapeCedarString(value: string): string {
+  return value
+    .replace(/\\/g, "\\\\")
+    .replace(/"/g, '\\"')
+    .replace(/\n/g, "\\n")
+    .replace(/\r/g, "\\r")
+    .replace(/\t/g, "\\t");
+}
+
+/**
+ * Derive a policy id from a logical name: `allowAdminRead` → `allow-admin-read`.
+ * Cedar ids are free-form strings; kebab-case keeps them readable in the
+ * `@id` annotation and stable across a rename-free refactor.
+ */
+export function policyIdFromLogicalName(name: string): string {
+  return name
+    .replace(/([a-z0-9])([A-Z])/g, "$1-$2")
+    .replace(/([A-Z]+)([A-Z][a-z])/g, "$1-$2")
+    .replace(/[\s_]+/g, "-")
+    .toLowerCase();
+}
+
+/**
+ * The Cedar id for a policy: an explicit `annotations.id` when the author gave
+ * one, else derived from the logical name.
+ *
+ * This is the only rule that links a chant entity to a policy in a live AVP
+ * store (#1652) — the observation resolves the same id from the same props and
+ * matches it against the `@id` annotation the statement carries — and it is
+ * also what gives a `.dw` policy the id its `.cedar` sibling would have had.
+ * Two copies of this rule would be a mapping that drifts silently.
+ */
+export function resolvePolicyId(logicalName: string, props: Record<string, unknown>): string {
+  const explicit = isRecord(props.annotations) ? props.annotations.id : undefined;
+  return typeof explicit === "string" && explicit.length > 0
+    ? explicit
+    : policyIdFromLogicalName(logicalName);
+}
+
+function refText(value: unknown): string {
+  return String(value);
+}
+
+/** `principal`, `principal == User::"alice"`, `action in [ … ]`, `resource is Photo`. */
+export function renderScope(variable: string, scope: unknown): string {
+  if (!isRecord(scope)) return variable;
+
+  const parts = [variable];
+  if (typeof scope.is === "string") parts.push(`is ${scope.is}`);
+  if (scope.eq !== undefined) parts.push(`== ${refText(scope.eq)}`);
+  if (scope.in !== undefined) {
+    parts.push(
+      Array.isArray(scope.in)
+        ? `in [${scope.in.map(refText).join(", ")}]`
+        : `in ${refText(scope.in)}`,
+    );
+  }
+  return parts.join(" ");
+}
+
+/** A `when`/`unless` prop as a list of clause bodies — one string, or several. */
+export function conditionStrings(value: unknown): string[] {
+  if (value === undefined || value === null) return [];
+  if (Array.isArray(value)) return value.map(refText);
+  return [refText(value)];
+}
+
+/**
+ * Everything above the first clause: the annotations, the effect, and the
+ * three scope positions.
+ */
+export function renderPolicyHead(id: string, props: Record<string, unknown>): string[] {
+  const lines: string[] = [];
+
+  // @id first, then the author's own annotations in declaration order.
+  const annotations = isRecord(props.annotations) ? props.annotations : {};
+  lines.push(`@id("${escapeCedarString(id)}")`);
+  for (const [key, value] of Object.entries(annotations)) {
+    if (key === "id" || value === undefined || value === null) continue;
+    lines.push(`@${key}("${escapeCedarString(refText(value))}")`);
+  }
+
+  const effect = props.effect === "forbid" ? "forbid" : "permit";
+  lines.push(`${effect} (`);
+  lines.push(`  ${renderScope("principal", props.principal)},`);
+  lines.push(`  ${renderScope("action", props.action)},`);
+  lines.push(`  ${renderScope("resource", props.resource)}`);
+  lines.push(")");
+
+  return lines;
+}