@intentius/chant-lexicon-cedar 0.124.31 → 0.124.32

package/dist/dogwood/index.js

@@ -0,0 +1,32 @@
+/**
+ * The dogwood temporal dialect (#1658, epic #1646).
+ *
+ * A dialect of the cedar lexicon, not a lexicon of its own: `.dw` policies are
+ * Cedar policies with temporal clauses, their entity and action schemas are
+ * Cedar schemas, and the rendering is shared with the `.cedar` leg. Checks
+ * ship under the `DWD` id family, declared on the cedar serializer's
+ * `extraRulePrefixes`.
+ *
+ * Pre-release. Upstream (dogwood-policy/dogwood, Apache-2.0) is a read-only
+ * squash-sync mirror with no tags, no releases and no stability statement, and
+ * calls itself "NOT intended for production use". The surface here is built
+ * against the revision recorded in `./upstream.ts` and re-verified per
+ * sub-issue.
+ */
+export { DEFAULT_MAX_WINDOW, isWindowParam, renderWindow, renderWindowValue, window, windowParam, windowSeconds, windowValue, } from "./window.js";
+export { and, arrayOf, binderName, bool, call, compare, count, ctx, decimalOf, entityUid, exists, formerly, int, interval, not, predicate, previous, raw, renderCondition, renderTerm, scopeRef, sigilCondition, since, str, sum, temporalMarker, term, tp, typedBinder, varRef, wildcard, } from "./temporal.js";
+export { DEFAULT_MACRO_NAMES, bind, countDistinctWithin, countWithin, defCedarMacro, defTemporalMacro, defaultMacroLibrary, macroCondition, macroTerm, macroWindow, renderMacroDefinition, renderMacroLibrary, sumWithin, } from "./macros.js";
+export { concrete, declaredEventKinds, defaultEventSchema, eventDeclaration, eventSchema, field, pinContext, pinPrincipal, pinResource, pinnedField, principalType, record, renderEventSchema, resourceType, spreadInputs, spreadOutputs, } from "./event-schema.js";
+export { DOGWOOD_EVENT_SCHEMA_FILENAME, DOGWOOD_EVENT_SCHEMA_TYPE, DOGWOOD_LEXICON, DOGWOOD_MACRO_FILENAME, DOGWOOD_MACRO_LIBRARY_TYPE, DOGWOOD_POLICY_FILENAME, DOGWOOD_POLICY_TYPE, TemporalEventSchema, TemporalMacroLibrary, TemporalPolicy, } from "./policy.js";
+export { DOGWOOD_EVENT_SCHEMA_SUFFIX, DOGWOOD_POLICY_SUFFIX, dogwoodPolicyRecords, renderTemporalPolicyText, serializeDogwood, } from "./serialize.js";
+export { blankComments, dogwoodPolicyFiles, dogwoodSchemaFiles, effectiveMaxWindowSeconds, readEventSchema, scanPredicates, scanWindowlessOperators, scanWindows, temporalRegions, } from "./scan.js";
+export { DOGWOOD_UPSTREAM } from "./upstream.js";
+export { DOGWOOD_BINARY_ENV, DOGWOOD_BINARY_NAME, DOGWOOD_SEARCH_ORDER, configureDogwoodCli, findDogwoodBinary, formatDogwoodDiagnostic, parseLowerOutput, parseReplayOutput, parseValidateOutput, resetDogwoodCli, runDogwoodLower, runDogwoodReplay, runDogwoodValidate, } from "./cli.js";
+// 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.js";
+// 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.js";
+// The PolicyReplayOp composite and its typed step builders (#1661).
+export { DEFAULT_REPLAY_REPORT_PATH, PolicyReplayOp, dogwoodReplayReportStep, dogwoodReplayStep, } from "./replay-op.js";

package/dist/dogwood/macros.js

@@ -0,0 +1,175 @@
+/**
+ * Macro authoring, and the default library as calls rather than operators.
+ *
+ * Upstream's policy grammar carries the macro system in the parser, not in the
+ * docs:
+ *
+ * ```
+ * def_decl = { kw_def ~ def_kind ~ ident ~ "(" ~ param_list? ~ ")" ~ "{" ~ block_inner ~ "}" ~ ";" }
+ * def_kind = { kw_def_cedar | kw_def_temporal }
+ * ```
+ *
+ * A `cedar` macro's body is a Cedar expression; a `temporal` macro's body is a
+ * temporal condition *or* a bare aggregation value (upstream's
+ * `temporal_macro_body_entry` tries `agg_expr` first, which is why
+ * `count_within` can expand into a `count …` that the call site compares).
+ *
+ * Two sigils, and they are not interchangeable. `?p` splices the call-site
+ * argument literally. `$t` is a fresh binder the macro introduces, gensym'd at
+ * every expansion. Both are legal *only* inside a macro body — upstream's
+ * well-formedness pass rejects them anywhere else — which is why they are
+ * validated here at definition time rather than at render time.
+ *
+ * The four wrappers at the bottom are the default library
+ * (`configuration/default_macros.dw`). They are calls, not operators. A caller
+ * who passes `--macros` replaces that library entirely, so a policy built on
+ * them is built on an assumption about the other end; {@link defaultMacroLibrary}
+ * exists so a project can emit the same definitions itself and stop assuming.
+ */
+import { call, interval, renderCondition, renderTerm, sigilCondition, varRef, } from "./temporal.js";
+import { windowParam } from "./window.js";
+/** `?w` — a value parameter, spliced from the call site. */
+const PARAM = /^\?[A-Za-z_][A-Za-z0-9_]*$/;
+const IDENT = /^[A-Za-z_][A-Za-z0-9_]*$/;
+function assertMacroName(name) {
+    if (!IDENT.test(name))
+        throw new Error(`dogwood: a macro name must be an identifier — got "${name}"`);
+    return name;
+}
+function assertParams(params) {
+    for (const p of params) {
+        if (!PARAM.test(p)) {
+            throw new Error(`dogwood: a macro parameter carries the "?" sigil — got "${p}" (write "?${p.replace(/^\?/, "")}")`);
+        }
+    }
+    return params;
+}
+/**
+ * `def temporal name(?a, ?b) { … };`
+ *
+ * The body may be a condition or an aggregation term, matching upstream's
+ * `temporal_macro_body_entry`; `sum_within` is an aggregation-bodied macro and
+ * `once` is a condition-bodied one.
+ */
+export function defTemporalMacro(name, params, body, comment) {
+    return {
+        kind: "temporal",
+        name: assertMacroName(name),
+        params: assertParams(params),
+        body: isTermBody(body) ? renderTerm(body) : renderCondition(body),
+        comment,
+    };
+}
+function isTermBody(body) {
+    return body.op === "term" || body.op === "array" || body.op === "count" || body.op === "sum";
+}
+/**
+ * `def cedar name(?a) { … };` — the body is Cedar expression text.
+ *
+ * Cedar's expression grammar is the policy language itself, so it stays a
+ * string here for the same reason `Cedar::Policy`'s `when` does.
+ */
+export function defCedarMacro(name, params, body, comment) {
+    return { kind: "cedar", name: assertMacroName(name), params: assertParams(params), body, comment };
+}
+// ── The sigils, in the three positions they appear ────────────────
+/**
+ * `within ?w` — the window a macro body defers to its call site.
+ *
+ * The call site supplies a bare interval (`once(1h, …)`), not a `within`
+ * clause: the keyword belongs to the operator, so it stays in the body.
+ */
+export function macroWindow(param) {
+    return windowParam(param);
+}
+/** `?s` standing for an entire condition, spliced from the call site. */
+export function macroCondition(param) {
+    if (!PARAM.test(param))
+        throw new Error(`dogwood: a condition parameter carries the "?" sigil — got "${param}"`);
+    return sigilCondition(param);
+}
+/** `?a` / `$t` in term or binder position. */
+export function macroTerm(sigil) {
+    if (!/^[?$][A-Za-z_][A-Za-z0-9_]*$/.test(sigil)) {
+        throw new Error(`dogwood: a macro term carries a "?" or "$" sigil — got "${sigil}"`);
+    }
+    return varRef(sigil);
+}
+/** One definition as `.dw` source. */
+export function renderMacroDefinition(def) {
+    const lines = [];
+    if (def.comment) {
+        for (const line of def.comment.split("\n"))
+            lines.push(`// ${line}`.trimEnd());
+    }
+    lines.push(`def ${def.kind} ${def.name}(${def.params.join(", ")}) {`);
+    lines.push(`    ${def.body}`);
+    lines.push("};");
+    return lines.join("\n");
+}
+/** A whole library — the file `--macros` points at, or a policy set's own prelude. */
+export function renderMacroLibrary(defs) {
+    return defs.map(renderMacroDefinition).join("\n\n") + "\n";
+}
+// ── The default library, as calls ─────────────────────────────────
+/** The macro names `configuration/default_macros.dw` ships at the pinned revision. */
+export const DEFAULT_MACRO_NAMES = ["count_within", "sum_within", "count_distinct_within", "bind"];
+/**
+ * `count_within(?w, ?s)` — timepoints in the window at which `?s` held.
+ *
+ * A default-library call, not an operator. See this module's header.
+ */
+export function countWithin(w, condition) {
+    return call("count_within", [interval(w), condition]);
+}
+/** `sum_within(?a, ?w, ?body)` — `over` names the sum's bound variable. */
+export function sumWithin(over, w, body) {
+    return call("sum_within", [varRef(over), interval(w), body]);
+}
+/** `count_distinct_within(?k, ?w, ?s)` — distinct String keys `k` for which `s` held. */
+export function countDistinctWithin(key, w, condition) {
+    return call("count_distinct_within", [varRef(key), interval(w), condition]);
+}
+/** `bind(?n, ?A, ?B)` — names an aggregate result so it can be compared. */
+export function bind(name, aggregate, body) {
+    return call("bind", [varRef(name), aggregate, body]);
+}
+/**
+ * The default library's four definitions, verbatim from upstream's
+ * `dogwood-language/configuration/default_macros.dw` at the pinned revision.
+ *
+ * Emitting these into a project's own `macros.dw` turns an assumption about
+ * the callee's `--macros` into a file the project controls.
+ */
+export function defaultMacroLibrary() {
+    return [
+        {
+            kind: "temporal",
+            name: "count_within",
+            params: ["?w", "?s"],
+            body: "count for ($t: Timepoint). where (formerly within ?w (?s && tp($t)))",
+            comment: "Counts the timepoints within window `?w` at which condition `?s` held.",
+        },
+        {
+            kind: "temporal",
+            name: "sum_within",
+            params: ["?a", "?w", "?body"],
+            body: "sum ?a for (?a: Long), ($t: Timepoint). where (formerly within ?w (?body && tp($t)))",
+            comment: "Sums the numeric value `?a` over occurrences of `?body` within window `?w`.",
+        },
+        {
+            kind: "temporal",
+            name: "count_distinct_within",
+            params: ["?k", "?w", "?s"],
+            body: "count for (?k: String). where (formerly within ?w ?s)",
+            comment: "Counts the distinct key values `?k` for which `?s` held within window `?w`.",
+        },
+        {
+            kind: "temporal",
+            name: "bind",
+            params: ["?n", "?A", "?B"],
+            body: "exists (?n: Long). (?A == ?n && ?B)",
+            comment: 'A "let"-style binder: names an aggregate result `?n` and uses it in `?B`.',
+        },
+    ];
+}

package/dist/dogwood/policy.js

@@ -0,0 +1,58 @@
+/**
+ * The dogwood entity model: a temporal policy, an event schema, a macro library.
+ *
+ * `Dogwood::TemporalPolicy` is `Cedar::Policy` plus the two clause forms
+ * upstream's policy grammar adds. Its head — annotations, effect, the three
+ * scope positions — is Cedar's, byte for byte, which is why `./serialize.ts`
+ * renders it with the cedar serializer's own `renderPolicyHead` rather than a
+ * copy of it. Only the `cond` rule differs:
+ *
+ * ```
+ * cond = { cond_kw ~ (extension_marker | guardrails_tag? ~ "{" ~ expr ~ "}") }
+ * ```
+ *
+ * — so a clause is `when { … }`, `when guardrails { … }`, or
+ * `when temporal { … }`, and the same three under `unless`. `guardrails` is
+ * transparent sugar for a bare Cedar expression (upstream discards the tag
+ * during lowering); `temporal { … }` is a genuine sub-language dispatched to a
+ * different parser.
+ *
+ * These are not schema-driven the way `Cedar::Policy`'s generated class is.
+ * Codegen's input is the project's `.cedarschema`, which says nothing about
+ * event kinds or temporal operators, so the dialect's classes are written here
+ * and typed against the builders in `./temporal.ts`.
+ */
+import { createResource } from "@intentius/chant/runtime";
+/** The lexicon these entities belong to — dogwood is a dialect of cedar, not a lexicon. */
+export const DOGWOOD_LEXICON = "cedar";
+/** The `entityType` of a temporal policy. */
+export const DOGWOOD_POLICY_TYPE = "Dogwood::TemporalPolicy";
+/** The `entityType` of an event schema. */
+export const DOGWOOD_EVENT_SCHEMA_TYPE = "Dogwood::EventSchema";
+/** The `entityType` of a macro library. */
+export const DOGWOOD_MACRO_LIBRARY_TYPE = "Dogwood::MacroLibrary";
+/** The `.dw` policy set written beside the cedar outputs. */
+export const DOGWOOD_POLICY_FILENAME = "policies.dw";
+/** The `.dwschema` event schema — what `dogwood validate --event-schema` reads. */
+export const DOGWOOD_EVENT_SCHEMA_FILENAME = "events.dwschema";
+/** The macro library — what `dogwood validate --macros` reads. */
+export const DOGWOOD_MACRO_FILENAME = "macros.dw";
+/**
+ * A temporal policy. Declare one per policy, the same way as `Cedar::Policy`:
+ *
+ * ```ts
+ * export const readAfterLogin = new TemporalPolicy({
+ *   action: { eq: 'Drupe::Action::"Read"' },
+ *   whenTemporal: [
+ *     formerly("1h", predicate('Drupe::Action::"Login"', "response", {
+ *       "input.user": ctx("input.user"),
+ *     })),
+ *   ],
+ * });
+ * ```
+ */
+export const TemporalPolicy = createResource(DOGWOOD_POLICY_TYPE, DOGWOOD_LEXICON, {});
+/** The service half of the schema, emitted as `.dwschema` text. */
+export const TemporalEventSchema = createResource(DOGWOOD_EVENT_SCHEMA_TYPE, DOGWOOD_LEXICON, {});
+/** A `def cedar` / `def temporal` library, emitted as `.dw` text. */
+export const TemporalMacroLibrary = createResource(DOGWOOD_MACRO_LIBRARY_TYPE, DOGWOOD_LEXICON, {});

package/dist/dogwood/replay-activity.js

@@ -0,0 +1,313 @@
+/**
+ * `dogwoodReplay` / `dogwoodReplayReport` — the replay half of PolicyReplayOp
+ * (#1661, epic #1646).
+ *
+ * Contributed the way the fly lexicon contributes `flyApply`: a plain exported
+ * async function taking one args object, re-exported from
+ * `src/op/activities/index.ts`, resolved **by name** by core's activity
+ * registry when a project lists the `cedar` lexicon. It imports no runtime of
+ * its own, so the local executor calls it as-is.
+ *
+ * What it does: takes a policy bundle (inline text or paths), an event trace
+ * (typed events, inline text, or a path) and a set of expectations, runs
+ * `dogwood replay --format json` through the existing CLI adapter in
+ * `./cli.ts`, and returns a typed divergence report — expected versus actual
+ * verdict per decision point, with the determining rules and per-evaluation
+ * errors carried through.
+ *
+ * Three contract details from the #1657 verification shape the code:
+ *
+ * - **Replay exits 0 even when every verdict is DENY.** A nonzero exit means
+ *   the trace or the policy set failed to load. `./cli.ts` already refuses to
+ *   read exit codes as verdicts; this module refuses to read a DENY as a
+ *   failure.
+ * - **A run that could not happen is not a run that found nothing.** An
+ *   unusable invocation or a fatal (a malformed trace line, an unparseable
+ *   policy set) throws, so the step fails instead of reporting zero
+ *   divergences.
+ * - **`index` is the decision-stream position, not the trace line number.** A
+ *   history-only event contributes history and no verdict, so expectations
+ *   written against trace lines would silently address the wrong decision.
+ *   Expectations therefore match on `timestamp` by default, and on `index`
+ *   only when the caller says so.
+ *
+ * The trace input is deliberately generic. An AgentCore session/decision
+ * history is the follow-on source (it needs the aws lexicon's activity
+ * surface, out of scope here) — a trace is a trace, wherever it came from.
+ */
+import { readFile, writeFile, mkdir } from "node:fs/promises";
+import { dirname, isAbsolute, resolve } from "node:path";
+import { DOGWOOD_SEARCH_ORDER, findDogwoodBinary, formatDogwoodDiagnostic, runDogwoodReplay, } from "./cli.js";
+import { auditTrace, renderTrace } from "./trace.js";
+async function textOf(inline, path, cwd, what) {
+    if (inline !== undefined)
+        return inline;
+    if (path === undefined)
+        return undefined;
+    const full = isAbsolute(path) ? path : resolve(cwd, path);
+    try {
+        return await readFile(full, "utf-8");
+    }
+    catch (err) {
+        throw new Error(`dogwood replay: could not read ${what} at ${full} — ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+/**
+ * Assemble the bundle and the trace from whichever form the caller supplied.
+ *
+ * Exported because the composite's Artifacts phase writes files and the Replay
+ * phase names them: resolving the same way in a test as in the Op is the point
+ * of having one function do it.
+ */
+export async function resolveReplayInputs(args) {
+    const cwd = args.cwd ?? process.cwd();
+    const policies = await textOf(args.policies, args.policiesPath, cwd, "the .dw policy set");
+    if (policies === undefined) {
+        throw new Error("dogwood replay: no policy set — pass `policies` or `policiesPath`");
+    }
+    const policySchema = await textOf(args.policySchema, args.policySchemaPath, cwd, "the Cedar action schema");
+    if (policySchema === undefined) {
+        throw new Error("dogwood replay: no action schema — `--policy-schema` is not optional to the CLI, so pass `policySchema` or `policySchemaPath`");
+    }
+    const eventSchema = await textOf(args.eventSchema, args.eventSchemaPath, cwd, "the .dwschema event schema");
+    const macros = await textOf(args.macros, args.macrosPath, cwd, "the macro library");
+    const providers = await textOf(args.providers, args.providersPath, cwd, "providers.json");
+    let trace;
+    let traceIssues = [];
+    if (args.traceEvents && args.traceEvents.length > 0) {
+        // Only the typed form can be audited — there is no trace parser on this
+        // side, and guessing one from a regex would report confident nonsense
+        // about a format a sync can retune.
+        traceIssues = auditTrace(args.traceEvents, {
+            ...(args.traceDecisionKinds ? { decisionKinds: args.traceDecisionKinds } : {}),
+        });
+        trace = renderTrace(args.traceEvents);
+    }
+    else {
+        trace = await textOf(args.trace, args.tracePath, cwd, "the event trace");
+    }
+    if (trace === undefined) {
+        throw new Error("dogwood replay: no trace — pass `traceEvents`, `trace` or `tracePath`");
+    }
+    return {
+        bundle: {
+            policies,
+            policySchema,
+            ...(eventSchema !== undefined ? { eventSchema } : {}),
+            ...(macros !== undefined ? { macros } : {}),
+            ...(providers !== undefined ? { providers } : {}),
+        },
+        trace,
+        traceIssues,
+    };
+}
+/**
+ * Match expectations against the decision stream.
+ *
+ * Timestamp matching consumes verdicts left to right, so two expectations at
+ * the same `@n` address the first and second decision there rather than both
+ * addressing the first. A verdict nothing expected is reported too — a policy
+ * set that starts deciding somewhere new is drift, and the usual reason a
+ * replay is being run at all.
+ */
+export function compareVerdicts(verdicts, expectations) {
+    const divergences = [];
+    const claimed = new Set();
+    for (const expectation of expectations) {
+        if (expectation.index === undefined && expectation.timestamp === undefined) {
+            throw new Error("dogwood replay: an expectation needs a `timestamp` or an `index`");
+        }
+        const position = expectation.index !== undefined
+            ? verdicts.findIndex((v) => v.index === expectation.index)
+            : verdicts.findIndex((v, i) => !claimed.has(i) && v.timestamp === expectation.timestamp);
+        if (position === -1) {
+            const where = expectation.index !== undefined ? `decision index ${expectation.index}` : `@${String(expectation.timestamp)}`;
+            divergences.push({
+                index: -1,
+                timestamp: expectation.timestamp ?? -1,
+                expected: expectation.verdict,
+                determiningRules: [],
+                errors: [],
+                detail: `no decision point at ${where} — the trace produced ${verdicts.length} decision(s), and a history-only event produces none`,
+                ...(expectation.note ? { note: expectation.note } : {}),
+            });
+            continue;
+        }
+        claimed.add(position);
+        const actual = verdicts[position];
+        if (actual.verdict !== expectation.verdict) {
+            divergences.push({
+                index: actual.index,
+                timestamp: actual.timestamp,
+                expected: expectation.verdict,
+                actual: actual.verdict,
+                determiningRules: actual.determiningRules,
+                errors: actual.errors,
+                detail: `expected ${expectation.verdict.toUpperCase()}, replayed ${actual.verdict.toUpperCase()}${actual.determiningRules.length > 0 ? ` (rules: ${actual.determiningRules.join(", ")})` : ""}`,
+                ...(expectation.note ? { note: expectation.note } : {}),
+            });
+            continue;
+        }
+        if (expectation.determiningRules !== undefined) {
+            const want = [...expectation.determiningRules].sort((a, b) => a - b).join(", ");
+            const got = [...actual.determiningRules].sort((a, b) => a - b).join(", ");
+            if (want !== got) {
+                divergences.push({
+                    index: actual.index,
+                    timestamp: actual.timestamp,
+                    expected: expectation.verdict,
+                    actual: actual.verdict,
+                    determiningRules: actual.determiningRules,
+                    errors: actual.errors,
+                    detail: `${actual.verdict.toUpperCase()} as expected, but determined by rules [${got}] rather than [${want}] — the decision is right for a different reason`,
+                    ...(expectation.note ? { note: expectation.note } : {}),
+                });
+                continue;
+            }
+        }
+        if (actual.errors.length > 0) {
+            divergences.push({
+                index: actual.index,
+                timestamp: actual.timestamp,
+                expected: expectation.verdict,
+                actual: actual.verdict,
+                determiningRules: actual.determiningRules,
+                errors: actual.errors,
+                detail: `${actual.verdict.toUpperCase()} as expected, but the evaluation errored: ${actual.errors.join("; ")}`,
+                ...(expectation.note ? { note: expectation.note } : {}),
+            });
+        }
+    }
+    verdicts.forEach((verdict, position) => {
+        if (claimed.has(position))
+            return;
+        if (expectations.length === 0)
+            return;
+        divergences.push({
+            index: verdict.index,
+            timestamp: verdict.timestamp,
+            actual: verdict.verdict,
+            determiningRules: verdict.determiningRules,
+            errors: verdict.errors,
+            detail: `an unexpected decision point: @${verdict.timestamp} replayed ${verdict.verdict.toUpperCase()} and nothing expected a decision there`,
+        });
+    });
+    // Errors on decision points nobody wrote an expectation for still matter —
+    // a provider with no inlined Rhai script errors on every evaluation, and a
+    // replay with no expectations at all would otherwise report itself clean.
+    if (expectations.length === 0) {
+        for (const verdict of verdicts) {
+            if (verdict.errors.length === 0)
+                continue;
+            divergences.push({
+                index: verdict.index,
+                timestamp: verdict.timestamp,
+                actual: verdict.verdict,
+                determiningRules: verdict.determiningRules,
+                errors: verdict.errors,
+                detail: `@${verdict.timestamp} evaluated with errors: ${verdict.errors.join("; ")}`,
+            });
+        }
+    }
+    return divergences.sort((a, b) => a.timestamp - b.timestamp || a.index - b.index);
+}
+/** The markdown body — printed in `report` mode, posted in the other two. */
+export function renderReplaySummary(report) {
+    const lines = ["## Policy replay", ""];
+    lines.push(`${report.verdicts.length} decision point(s) replayed; ${report.divergences.length} divergence(s).`, "");
+    if (report.divergences.length > 0) {
+        lines.push("| @ | index | expected | replayed | detail |", "|---|---|---|---|---|");
+        for (const d of report.divergences) {
+            lines.push(`| ${d.timestamp === -1 ? "—" : `@${d.timestamp}`} | ${d.index === -1 ? "—" : d.index} | ${d.expected ?? "—"} | ${d.actual ?? "—"} | ${d.detail}${d.note ? ` — ${d.note}` : ""} |`);
+        }
+        lines.push("");
+    }
+    if (report.traceIssues.length > 0) {
+        lines.push("### Trace weaknesses", "", "These do not fail a replay — they make one report a verdict it did not really test.", "");
+        for (const issue of report.traceIssues) {
+            lines.push(`- \`${issue.kind}\` @${issue.timestamp}: ${issue.message}`);
+        }
+        lines.push("");
+    }
+    if (report.divergences.length === 0 && report.traceIssues.length === 0) {
+        lines.push("Every decision point replayed to the verdict it was expected to reach.", "");
+    }
+    return lines.join("\n");
+}
+/**
+ * Replay a policy bundle against a trace and report divergence.
+ *
+ * Throws when the CLI could not be used or the run was fatal. That is the
+ * distinction `./cli.ts` draws and this preserves: a replay that did not
+ * happen must fail the step, never report zero divergences.
+ */
+export async function dogwoodReplay(args) {
+    const cwd = args.cwd ?? process.cwd();
+    const mode = args.mode ?? "report";
+    const binary = args.binary ?? findDogwoodBinary(cwd)?.path;
+    if (!binary) {
+        throw new Error(`dogwood replay: no \`dogwood\` binary. chant looked at ${DOGWOOD_SEARCH_ORDER}. Upstream ships only a Rust CLI — build it from dogwood-policy/dogwood and point chant at it.`);
+    }
+    const { bundle, trace, traceIssues } = await resolveReplayInputs(args);
+    const result = runDogwoodReplay(binary, bundle, trace);
+    if (result.kind === "unusable") {
+        throw new Error(`dogwood replay: ${result.reason}`);
+    }
+    if (result.kind === "fatal") {
+        const related = result.related.map((d) => `\n  ${formatDogwoodDiagnostic(d)}`).join("");
+        throw new Error(`dogwood replay: ${formatDogwoodDiagnostic(result.error)}${related}`);
+    }
+    const divergences = compareVerdicts(result.verdicts, args.expect ?? []);
+    const partial = {
+        ok: divergences.length === 0,
+        mode,
+        verdicts: result.verdicts,
+        divergences,
+        findings: divergences.length,
+        traceIssues,
+    };
+    const report = { ...partial, summary: renderReplaySummary(partial) };
+    if (args.reportPath) {
+        const full = isAbsolute(args.reportPath) ? args.reportPath : resolve(cwd, args.reportPath);
+        await mkdir(dirname(full), { recursive: true });
+        await writeFile(full, JSON.stringify(report, null, 2) + "\n", "utf-8");
+    }
+    return report;
+}
+/**
+ * Turn a written replay report into the thing the finding mode calls for.
+ *
+ * It renders and returns; it does not open anything. Same as
+ * `workflowSupplyChainAudit`, and for the same reason — the cedar lexicon has
+ * no forge client and should not grow one to reach GitHub, GitLab or Forgejo.
+ * `report` mode prints the body; `issue` and `pull-request` hand back the
+ * title and body for whatever step opens them.
+ */
+export async function dogwoodReplayReport(args) {
+    const cwd = args.cwd ?? process.cwd();
+    let report = args.report;
+    if (!report) {
+        if (!args.reportPath) {
+            throw new Error("dogwood replay report: pass `report` or `reportPath`");
+        }
+        const full = isAbsolute(args.reportPath) ? args.reportPath : resolve(cwd, args.reportPath);
+        try {
+            report = JSON.parse(await readFile(full, "utf-8"));
+        }
+        catch (err) {
+            throw new Error(`dogwood replay report: could not read the replay report at ${full} — ${err instanceof Error ? err.message : String(err)}. The Replay phase writes it; a Report phase that runs without one has nothing to report on.`);
+        }
+    }
+    const mode = args.mode ?? report.mode;
+    const findings = report.findings;
+    const actionable = findings > 0 || report.traceIssues.length > 0;
+    const title = args.title ?? `Policy replay: ${findings} divergence(s)`;
+    if (mode === "report") {
+        // eslint-disable-next-line no-console -- report mode's whole output is this.
+        console.log(report.summary);
+    }
+    if (args.failOnDivergence && findings > 0) {
+        throw new Error(`dogwood replay: ${findings} divergence(s) between the declared policy set and the replayed trace`);
+    }
+    return { mode, findings, title, body: report.summary, actionable };
+}