@intentius/chant-lexicon-cedar 0.44.9 → 0.44.12

package/src/codegen/docs.ts

@@ -21,6 +21,13 @@
 import { dirname, join } from "path";
 import { fileURLToPath } from "url";
 import { docsPipeline, writeDocsSite, type DocsConfig } from "@intentius/chant/codegen/docs";
+import {
+  dogwoodEventSchemas,
+  dogwoodOverview,
+  dogwoodReplay,
+  dogwoodTemporalPolicies,
+  dogwoodValidation,
+} from "./docs-dogwood";
 
 const pkgDir = dirname(dirname(dirname(fileURLToPath(import.meta.url))));
 
@@ -67,7 +74,14 @@ any evaluator with chant nowhere in sight.
 There is no \`cedarGate()\` and there will not be one.
 [Organizational policy](/chant/guide/organizational-policy/) in chant is
 TypeScript post-synth checks; a second policy engine would duplicate the lint
-engine. chant compiles *to* Cedar; it is not governed *by* Cedar.`;
+engine. chant compiles *to* Cedar; it is not governed *by* Cedar.
+
+## The dogwood dialect
+
+Cedar with temporal operators, shipping inside this lexicon as a pre-release
+surface under the \`DWD\` id family: a policy that can depend on what already
+happened in a session. Start at [The Dogwood Dialect](./dogwood), which is
+honest about upstream's governance before it shows you a builder.`;
 
 // ── getting-started ───────────────────────────────────────────────
 
@@ -858,6 +872,57 @@ export async function generateDocs(options?: { verbose?: boolean }): Promise<voi
         description: "The AVP statement seam, and the other Cedar evaluators.",
         content: avpPage,
       },
+      // The dogwood dialect (#1662). `sidebar: false` on each, because these
+      // five belong under one group rather than flat after the cedar pages —
+      // the group is declared in `sidebarExtra` below, and `buildSidebar`
+      // would otherwise list them twice.
+      {
+        slug: "dogwood",
+        title: "The Dogwood Dialect",
+        description: "Cedar with temporal operators — what ships, and what pre-release means here.",
+        content: dogwoodOverview,
+        sidebar: false,
+      },
+      {
+        slug: "dogwood-temporal-policies",
+        title: "Temporal Policies",
+        description: "The typed builders, the parser primitives, and which operators are really macros.",
+        content: dogwoodTemporalPolicies,
+        sidebar: false,
+      },
+      {
+        slug: "dogwood-event-schemas",
+        title: "Event Schemas",
+        description: "The .dwschema surface, the callerPrincipal pin, and what opting out of it widens.",
+        content: dogwoodEventSchemas,
+        sidebar: false,
+      },
+      {
+        slug: "dogwood-validation",
+        title: "Dogwood Validation",
+        description: "The DWD walls that always run, and the CLI-gated checks that need the binary.",
+        content: dogwoodValidation,
+        sidebar: false,
+      },
+      {
+        slug: "dogwood-replay",
+        title: "Replay",
+        description: "Typed traces, PolicyReplayOp, and the both-bags trap that makes half a trace pass.",
+        content: dogwoodReplay,
+        sidebar: false,
+      },
+    ],
+    sidebarExtra: [
+      {
+        label: "Dogwood",
+        items: [
+          { label: "The Dialect", slug: "dogwood" },
+          { label: "Temporal Policies", slug: "dogwood-temporal-policies" },
+          { label: "Event Schemas", slug: "dogwood-event-schemas" },
+          { label: "Validation", slug: "dogwood-validation" },
+          { label: "Replay", slug: "dogwood-replay" },
+        ],
+      },
     ],
   };
 

package/src/dogwood/cli.test.ts

@@ -10,7 +10,7 @@
  * sync.
  */
 import { describe, test, expect, afterEach } from "vitest";
-import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "fs";
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "fs";
 import { tmpdir } from "os";
 import { join } from "path";
 import { fileURLToPath } from "url";
@@ -20,9 +20,11 @@ import {
   findDogwoodBinary,
   formatDogwoodDiagnostic,
   parseLowerOutput,
+  parseReplayOutput,
   parseValidateOutput,
   resetDogwoodCli,
   runDogwoodLower,
+  runDogwoodReplay,
   runDogwoodValidate,
   type DogwoodRun,
   type DogwoodRunner,
@@ -261,6 +263,125 @@ describe("parseLowerOutput", () => {
   });
 });
 
+// ── replay ─────────────────────────────────────────────────────────
+
+describe("parseReplayOutput", () => {
+  /** The stream #1657 recorded for `read_after_login`, exit 0. */
+  const RECORDED = {
+    verdicts: [
+      { index: 0, timestamp: 0, verdict: "deny", determining_rules: [], errors: [] },
+      { index: 1, timestamp: 10, verdict: "allow", determining_rules: [0], errors: [] },
+      { index: 2, timestamp: 7200, verdict: "deny", determining_rules: [], errors: [] },
+    ],
+  };
+
+  test("reads the verdict stream, rules included", () => {
+    const result = parseReplayOutput(json(RECORDED));
+    expect(result.kind).toBe("replayed");
+    if (result.kind !== "replayed") return;
+    expect(result.verdicts).toHaveLength(3);
+    expect(result.verdicts[1]).toEqual({
+      index: 1,
+      timestamp: 10,
+      verdict: "allow",
+      determiningRules: [0],
+      errors: [],
+    });
+  });
+
+  test("every verdict DENY at exit 0 is a result, not a failure", () => {
+    // The sharpest edge in the replay contract: a nonzero exit means the trace
+    // or the policy set failed to load, never that a policy denied.
+    const allDeny = { verdicts: RECORDED.verdicts.map((v) => ({ ...v, verdict: "deny" })) };
+    const result = parseReplayOutput(json(allDeny));
+    expect(result.kind).toBe("replayed");
+  });
+
+  test("an unrecognised verdict reads as a deny rather than being dropped", () => {
+    // Dropping it would shift every later index; treating it as a permit would
+    // be a permission upstream never granted.
+    const result = parseReplayOutput(json({ verdicts: [{ index: 0, timestamp: 0, verdict: "maybe" }] }));
+    expect(result.kind).toBe("replayed");
+    if (result.kind !== "replayed") return;
+    expect(result.verdicts[0].verdict).toBe("deny");
+  });
+
+  test("a malformed trace line comes back through the fatal channel", () => {
+    const result = parseReplayOutput(
+      json({ severity: "error", message: "trace parse: line 1: timepoint must start with `@`", spanned: false }, 2),
+    );
+    expect(result.kind).toBe("fatal");
+    if (result.kind !== "fatal") return;
+    expect(result.error.message).toMatch(/timepoint must start with/);
+  });
+
+  test("no JSON at all is unusable, never a verdict", () => {
+    const result = parseReplayOutput(run({ status: 2, stderr: "error: unexpected argument '--nope'" }));
+    expect(result.kind).toBe("unusable");
+  });
+
+  test("per-evaluation errors are carried through in either shape", () => {
+    const result = parseReplayOutput(
+      json({
+        verdicts: [
+          { index: 0, timestamp: 0, verdict: "deny", determining_rules: [], errors: ["no script"] },
+          {
+            index: 1,
+            timestamp: 1,
+            verdict: "deny",
+            determining_rules: [],
+            errors: [{ message: "provider failed at line 1 column 4" }],
+          },
+        ],
+      }),
+    );
+    expect(result.kind).toBe("replayed");
+    if (result.kind !== "replayed") return;
+    expect(result.verdicts[0].errors).toEqual(["no script"]);
+    // The internal position is scrubbed for the same reason as everywhere else.
+    expect(result.verdicts[1].errors).toEqual(["provider failed"]);
+  });
+});
+
+describe("runDogwoodReplay", () => {
+  test("passes the trace as --trace beside the bundle, and asks for JSON", () => {
+    let seen: { args: string[]; trace: string } | undefined;
+    const runner: DogwoodRunner = (_binary, args) => {
+      const at = args.indexOf("--trace");
+      seen = { args, trace: readFileSync(args[at + 1], "utf-8") };
+      return run({ status: 0, stdout: JSON.stringify({ verdicts: [] }) });
+    };
+    configureDogwoodCli({ runner });
+
+    const result = runDogwoodReplay("/bin/dogwood", { policies: "p", policySchema: "s" }, "@0 A::Action::\"B\"::request()");
+    expect(result.kind).toBe("replayed");
+    expect(seen?.args[0]).toBe("replay");
+    expect(seen?.args.slice(-2)).toEqual(["--format", "json"]);
+    expect(seen?.trace).toBe('@0 A::Action::"B"::request()');
+  });
+
+  test("the scratch directory, trace included, does not outlive the run", () => {
+    let tracePath = "";
+    const runner: DogwoodRunner = (_binary, args) => {
+      tracePath = args[args.indexOf("--trace") + 1];
+      return run({ status: 0, stdout: JSON.stringify({ verdicts: [] }) });
+    };
+    configureDogwoodCli({ runner });
+    runDogwoodReplay("/bin/dogwood", { policies: "p", policySchema: "s" }, "@0 A::Action::\"B\"::request()");
+    expect(existsSync(tracePath)).toBe(false);
+  });
+
+  test("a throwing runner is an unusable run, not an exception", () => {
+    configureDogwoodCli({
+      runner: () => {
+        throw new Error("spawn blew up");
+      },
+    });
+    const result = runDogwoodReplay("/bin/dogwood", { policies: "p", policySchema: "s" }, "@0 x");
+    expect(result.kind).toBe("unusable");
+  });
+});
+
 // ── Invocation ─────────────────────────────────────────────────────
 
 describe("the invocation itself", () => {

package/src/dogwood/cli.ts

@@ -347,6 +347,29 @@ export interface DogwoodLowered {
 
 export type DogwoodLowerResult = { kind: "lowered"; value: DogwoodLowered } | DogwoodFatal | DogwoodUnusable;
 
+/**
+ * One decision point out of `replay --format json`.
+ *
+ * `index` is the 0-based position in the *decision* stream, not the trace line
+ * number: a history-only event (any kind the event schema does not mark
+ * `decision`) contributes history and no verdict, so the two do not line up.
+ */
+export interface DogwoodVerdict {
+  index: number;
+  /** The `@<timestamp>` of the line that produced this decision. */
+  timestamp: number;
+  verdict: "allow" | "deny";
+  /** `.dw` rule indices that determined the decision — upstream's `[rules: 0, 2]`. */
+  determiningRules: number[];
+  /** Per-evaluation errors, such as a provider with no inlined Rhai script. */
+  errors: string[];
+}
+
+export type DogwoodReplayResult =
+  | { kind: "replayed"; verdicts: DogwoodVerdict[] }
+  | DogwoodFatal
+  | DogwoodUnusable;
+
 function unusable(reason: string): DogwoodUnusable {
   return { kind: "unusable", reason };
 }
@@ -430,6 +453,69 @@ export function parseLowerOutput(run: DogwoodRun): DogwoodLowerResult {
   return unusable("`dogwood lower --format json` returned JSON in neither the artifact nor the error shape");
 }
 
+/**
+ * Read a `replay --format json` run.
+ *
+ * The one place the exit-code discipline matters most: **replay exits 0 even
+ * when every verdict is DENY.** A nonzero exit means the trace or the policy
+ * set failed to load, never that a policy denied — so a caller that read the
+ * exit code as a verdict would report a working deny-by-default policy set as
+ * a broken one. As everywhere else in this module, the JSON decides: a body
+ * carrying `verdicts` is the report, a body carrying `message` is the fatal
+ * `OpError` (a malformed trace line lands here), anything else is unusable.
+ */
+export function parseReplayOutput(run: DogwoodRun): DogwoodReplayResult {
+  if (run.error) return unusable(`the dogwood binary could not be run: ${run.error}`);
+
+  const parsed = readJson(run.stdout);
+  if (!parsed) {
+    return unusable(
+      `\`dogwood replay --format json\` exited ${String(run.status)} without JSON on stdout${streamNote(run)}`,
+    );
+  }
+
+  if (Array.isArray(parsed.verdicts)) {
+    return { kind: "replayed", verdicts: parseVerdicts(parsed.verdicts) };
+  }
+
+  const fatal = fatalFrom(parsed);
+  if (fatal) return fatal;
+
+  return unusable("`dogwood replay --format json` returned JSON in neither the verdict nor the error shape");
+}
+
+function parseVerdicts(value: unknown[]): DogwoodVerdict[] {
+  const out: DogwoodVerdict[] = [];
+  value.forEach((raw, position) => {
+    if (!isRecord(raw)) return;
+    // `allow`/`deny` lowercase, as upstream serializes the enum. Anything else
+    // is read as a deny rather than dropped: an unrecognised verdict is not a
+    // permission, and dropping the entry would shift every later index.
+    const verdict = raw.verdict === "allow" ? "allow" : "deny";
+    out.push({
+      index: typeof raw.index === "number" ? raw.index : position,
+      timestamp: typeof raw.timestamp === "number" ? raw.timestamp : 0,
+      verdict,
+      determiningRules: Array.isArray(raw.determining_rules)
+        ? raw.determining_rules.filter((r): r is number => typeof r === "number")
+        : [],
+      errors: errorList(raw.errors),
+    });
+  });
+  return out;
+}
+
+/** Per-evaluation errors, tolerating both a string list and a diagnostic list. */
+function errorList(value: unknown): string[] {
+  if (!Array.isArray(value)) return [];
+  const out: string[] = [];
+  for (const entry of value) {
+    if (typeof entry === "string") out.push(entry);
+    else if (isRecord(entry) && typeof entry.message === "string") out.push(scrubPosition(entry.message));
+  }
+  return out;
+}
+
 function stringList(value: unknown): string[] {
   return Array.isArray(value) ? value.filter((v): v is string => typeof v === "string") : [];
 }
@@ -481,6 +567,13 @@ const defaultRunner: DogwoodRunner = (binary, args) => {
   };
 };
 
+/** An extra file+flag pair a subcommand needs — `replay`'s `--trace`, today. */
+interface ExtraInput {
+  flag: string;
+  filename: string;
+  content: string;
+}
+
 /**
  * Materialize a bundle into a scratch directory and run one subcommand.
  *
@@ -488,7 +581,12 @@ const defaultRunner: DogwoodRunner = (binary, args) => {
  * schema flags all take paths. The directory is removed in a `finally`, so a
  * throwing runner does not leave one behind.
  */
-function runBundle(binary: string, subcommand: string, bundle: DogwoodBundle): DogwoodRun {
+function runBundle(
+  binary: string,
+  subcommand: string,
+  bundle: DogwoodBundle,
+  extras: ExtraInput[] = [],
+): DogwoodRun {
   const runner = defaults.runner ?? defaultRunner;
   const dir = mkdtempSync(join(tmpdir(), "chant-dogwood-"));
   try {
@@ -515,6 +613,12 @@ function runBundle(binary: string, subcommand: string, bundle: DogwoodBundle): D
       args.push("--providers", path);
     }
 
+    for (const extra of extras) {
+      const path = join(dir, extra.filename);
+      writeFileSync(path, extra.content, "utf-8");
+      args.push(extra.flag, path);
+    }
+
     // No `--emit`: it is ignored under `--format json`, which returns all three
     // lowered artifacts regardless. Passing it would imply a choice that the
     // CLI does not honour.
@@ -543,3 +647,20 @@ export function runDogwoodLower(binary: string, bundle: DogwoodBundle): DogwoodL
     return unusable(`the dogwood lower run failed: ${err instanceof Error ? err.message : String(err)}`);
   }
 }
+
+/**
+ * Run `dogwood replay` over a bundle and a trace. Never throws.
+ *
+ * The trace is materialized beside the bundle's own files and passed as
+ * `--trace`; the same scratch directory is removed in the same `finally`, so a
+ * trace carrying a session's request payloads does not outlive the run.
+ */
+export function runDogwoodReplay(binary: string, bundle: DogwoodBundle, trace: string): DogwoodReplayResult {
+  try {
+    return parseReplayOutput(
+      runBundle(binary, "replay", bundle, [{ flag: "--trace", filename: "trace.log", content: trace }]),
+    );
+  } catch (err) {
+    return unusable(`the dogwood replay run failed: ${err instanceof Error ? err.message : String(err)}`);
+  }
+}

package/src/dogwood/index.ts

@@ -149,10 +149,11 @@ export type { EventSchemaProps, MacroLibraryProps, TemporalPolicyProps } from ".
 export {
   DOGWOOD_EVENT_SCHEMA_SUFFIX,
   DOGWOOD_POLICY_SUFFIX,
+  dogwoodPolicyRecords,
   renderTemporalPolicyText,
   serializeDogwood,
 } from "./serialize";
-export type { DogwoodSerializeResult } from "./serialize";
+export type { DogwoodPolicyRecord, DogwoodSerializeResult } from "./serialize";
 
 export {
   blankComments,
@@ -177,9 +178,11 @@ export {
   findDogwoodBinary,
   formatDogwoodDiagnostic,
   parseLowerOutput,
+  parseReplayOutput,
   parseValidateOutput,
   resetDogwoodCli,
   runDogwoodLower,
+  runDogwoodReplay,
   runDogwoodValidate,
 } from "./cli";
 export type {
@@ -191,8 +194,78 @@ export type {
   DogwoodLabel,
   DogwoodLowerResult,
   DogwoodLowered,
+  DogwoodReplayResult,
   DogwoodRun,
   DogwoodRunner,
   DogwoodUnusable,
   DogwoodValidateResult,
+  DogwoodVerdict,
 } from "./cli";
+
+// Replay traces (#1661) — typed construction of the §6 line grammar, with
+// both-bag population as the default and the weakening as an opt-out.
+export {
+  auditTrace,
+  decimalValue,
+  entityRef,
+  rawValue,
+  renderTrace,
+  renderTraceFields,
+  renderTraceLine,
+  renderTraceValue,
+  traceEntity,
+  traceEvent,
+  traceFixture,
+} from "./trace";
+export type {
+  TraceAuditOptions,
+  TraceBags,
+  TraceDecimal,
+  TraceEntityDecl,
+  TraceEntityRef,
+  TraceEvent,
+  TraceEventInput,
+  TraceFields,
+  TraceFixture,
+  TraceFixtureOptions,
+  TraceIssue,
+  TraceIssueKind,
+  TraceRaw,
+  TraceScope,
+  TraceTagged,
+  TraceValue,
+} from "./trace";
+
+// The replay activities (#1661). Contributed by name through
+// `src/op/activities/index.ts`; the helpers are here for direct use.
+export {
+  compareVerdicts,
+  dogwoodReplay,
+  dogwoodReplayReport,
+  renderReplaySummary,
+  resolveReplayInputs,
+} from "./replay-activity";
+export type {
+  DogwoodReplayArgs,
+  DogwoodReplayReportArgs,
+  ExpectedVerdict,
+  PolicyReplayDispatch,
+  PolicyReplayMode,
+  PolicyReplayReport,
+  ReplayDivergence,
+  ReplayExpectation,
+} from "./replay-activity";
+
+// The PolicyReplayOp composite and its typed step builders (#1661).
+export {
+  DEFAULT_REPLAY_REPORT_PATH,
+  PolicyReplayOp,
+  dogwoodReplayReportStep,
+  dogwoodReplayStep,
+} from "./replay-op";
+export type {
+  DogwoodReplayReportStepOpts,
+  DogwoodReplayStepOpts,
+  PolicyReplayOpConfig,
+  PolicyReplayOpResources,
+} from "./replay-op";