@intentius/chant-lexicon-cedar 0.124.31 → 0.124.32

package/dist/dogwood/replay-op.js

@@ -0,0 +1,134 @@
+/**
+ * `PolicyReplayOp` — replay a declared `.dw` set against a recorded event
+ * trace and report divergence (#1661, epic #1646).
+ *
+ * Shape follows `WorkflowAuditOp`: an observe-dial Op whose last phase is a
+ * finding mode (`report | issue | pull-request`). What it observes is not a
+ * moving upstream but a moving *history* — a policy set that was correct
+ * against last week's traffic can decide differently against this week's, and
+ * the deterministic build cannot see that.
+ *
+ * ## Packaging: the composite ships from cedar
+ *
+ * It hands back an Op and nothing else, so it imports `@intentius/chant/op`
+ * only, exactly as the fly lexicon's `flyDeploy` composite does. cedar keeps
+ * zero runtime dependency on any hosting lexicon.
+ *
+ * The cadence is a `schedule` on the Op itself (#2120) — runtime-neutral data
+ * the reader decides what to do with, the same field `WatchOp` and
+ * `ConvergeOp` set:
+ *
+ * ```ts
+ * export const { op } = PolicyReplayOp({
+ *   name: "policy-replay",
+ *   schedule: "0 6 * * *",
+ *   …
+ * });
+ * ```
+ *
+ * `chant operator` ticks it locally, the github/gitlab/forgejo lexicons render
+ * it as a CI cron, a hosting lexicon hands it to its own scheduler, and the
+ * one-shot executor behind `chant run policy-replay` ignores it.
+ * `examples/policy-replay` is the worked recipe.
+ *
+ * ## Phases
+ *
+ * ```
+ * Artifacts  chantBuild — emit policies.dw, the .cedarschema and the
+ *            .dwschema the replay reads (skippable when they are checked in)
+ * Replay     dogwoodReplay — run `dogwood replay --format json` over the
+ *            bundle and the trace, write the divergence report
+ * Report     dogwoodReplayReport — read that report and act on the mode
+ * ```
+ *
+ * The report file is the seam between the last two phases, the same way
+ * `dist/fly.json` is the seam between `build:fly` and `flyApply`: Op steps do
+ * not pass return values to one another, so a phase boundary needs an artifact
+ * to be a real boundary rather than a cosmetic one.
+ */
+import { Op, activity, build, phase } from "@intentius/chant/op";
+/** Where the Replay phase writes its report by default. */
+export const DEFAULT_REPLAY_REPORT_PATH = "dist/dogwood-replay.json";
+/**
+ * Replay a policy bundle against a trace — the typed twin of `flyApplyStep`.
+ *
+ * Resolves to the `dogwoodReplay` activity by name, which `loadActivities`
+ * binds when the project lists the `cedar` lexicon. Defaults to the
+ * `policyCheck` profile.
+ */
+export const dogwoodReplayStep = (opts) => {
+    const { profile, ...args } = opts;
+    return activity("dogwoodReplay", args, profile ?? "policyCheck");
+};
+/** Read a written replay report and act on its finding mode. */
+export const dogwoodReplayReportStep = (opts = {}) => {
+    const { profile, ...args } = opts;
+    return activity("dogwoodReplayReport", args, profile ?? "fastIdempotent");
+};
+/**
+ * Assemble the replay Op: emit the artifacts, replay them, act on the finding.
+ *
+ * @example
+ * ```typescript
+ * export const { op } = PolicyReplayOp({
+ *   name: "policy-replay",
+ *   tracePath: "trace/read-after-login.log",
+ *   expect: [
+ *     { timestamp: 10, verdict: "allow", determiningRules: [0] },
+ *     { timestamp: 7200, verdict: "deny", note: "the login is two hours stale" },
+ *   ],
+ *   onFinding: "issue",
+ * });
+ * ```
+ */
+export function PolicyReplayOp(config) {
+    const path = config.path ?? ".";
+    const mode = config.onFinding ?? "report";
+    const reportPath = config.reportPath ?? DEFAULT_REPLAY_REPORT_PATH;
+    const phases = [];
+    if (config.buildScript !== false) {
+        phases.push(phase("Artifacts", [build(path, { script: config.buildScript ?? "build" })]));
+    }
+    phases.push(phase("Replay", [
+        {
+            ...dogwoodReplayStep({
+                cwd: path,
+                policiesPath: config.policiesPath ?? "dist/policies.dw",
+                policySchemaPath: config.policySchemaPath ?? "dist/app.cedarschema",
+                ...(config.eventSchemaPath ? { eventSchemaPath: config.eventSchemaPath } : {}),
+                ...(config.macrosPath ? { macrosPath: config.macrosPath } : {}),
+                ...(config.providersPath ? { providersPath: config.providersPath } : {}),
+                tracePath: config.tracePath,
+                ...(config.expect ? { expect: config.expect } : {}),
+                mode,
+                ...(config.binary ? { binary: config.binary } : {}),
+                reportPath,
+            }),
+            // The divergence count as the run's `Divergences` outcome on the run
+            // ledger, so the replays that found something are readable from the
+            // ledger rather than out of a log.
+            outcomeAttribute: { name: "Divergences", from: "findings" },
+        },
+    ]), phase("Report", [
+        dogwoodReplayReportStep({
+            cwd: path,
+            reportPath,
+            mode,
+            ...(config.title ? { title: config.title } : {}),
+            ...(config.failOnDivergence ? { failOnDivergence: true } : {}),
+        }),
+    ]));
+    return {
+        op: Op({
+            name: config.name,
+            overview: config.overview ??
+                "Replay the declared dogwood policy set against a recorded event trace and report divergence",
+            labels: {
+                Audit: "true",
+                Surface: "cedar-dogwood",
+            },
+            ...(config.schedule ? { schedule: { cron: config.schedule, overlap: "skip" } } : {}),
+            phases,
+        }),
+    };
+}

package/dist/dogwood/scan.js

@@ -0,0 +1,234 @@
+/**
+ * Reading the emitted dogwood artifacts back, for the DWD post-synth checks.
+ *
+ * The checks judge the *text*, not the in-memory model, for the same reason
+ * the CED checks judge `policies.cedar.json`: `chant audit` runs over a
+ * checked-in artifact chant did not write, and a wall that only fires on
+ * chant's own output is not a wall. It also means the typed builders and the
+ * walls are independent — DWDC012 catches a windowless `formerly` even though
+ * the builders cannot construct one, because `raw()` and a hand-written `.dw`
+ * both can.
+ *
+ * This is scanning, not parsing. Upstream owns the parser and #1659 owns
+ * shelling to it; what is here is the subset of the surface that answers the
+ * three questions the walls ask, plus enough comment handling not to be fooled
+ * by a commented-out clause.
+ */
+import { DEFAULT_MAX_WINDOW, windowSeconds } from "./window.js";
+import { DOGWOOD_EVENT_SCHEMA_SUFFIX, DOGWOOD_POLICY_SUFFIX } from "./serialize.js";
+/** Every `.dw` policy file in the build output. */
+export function dogwoodPolicyFiles(ctx) {
+    return filesWithSuffix(ctx, DOGWOOD_POLICY_SUFFIX);
+}
+/** Every `.dwschema` event-schema file in the build output. */
+export function dogwoodSchemaFiles(ctx) {
+    return filesWithSuffix(ctx, DOGWOOD_EVENT_SCHEMA_SUFFIX);
+}
+function filesWithSuffix(ctx, suffix) {
+    const found = [];
+    for (const [lexicon, output] of ctx.outputs) {
+        if (typeof output === "string")
+            continue;
+        for (const [filename, content] of Object.entries(output.files ?? {})) {
+            if (typeof content !== "string")
+                continue;
+            if (!filename.endsWith(suffix))
+                continue;
+            found.push({ lexicon, source: filename, text: content });
+        }
+    }
+    return found;
+}
+// ── Comments ──────────────────────────────────────────────────────
+/**
+ * Blank out `//` comments, leaving string literals intact.
+ *
+ * String literals stay because a predicate's action id lives inside one
+ * (`Drupe::Action::"Read"`), and blanking those would blind every scan below.
+ * The walk is string-aware in the other direction too: a `//` inside a quoted
+ * value (a URL, say) is not a comment.
+ *
+ * Comment bytes become spaces so every offset in the result still lines up
+ * with the original file.
+ */
+export function blankComments(text) {
+    const out = text.split("");
+    let inString = false;
+    for (let i = 0; i < text.length; i++) {
+        const ch = text[i];
+        if (inString) {
+            if (ch === "\\") {
+                i++;
+                continue;
+            }
+            if (ch === '"')
+                inString = false;
+            continue;
+        }
+        if (ch === '"') {
+            inString = true;
+            continue;
+        }
+        if (ch === "/" && text[i + 1] === "/") {
+            while (i < text.length && text[i] !== "\n") {
+                out[i] = " ";
+                i++;
+            }
+        }
+    }
+    return out.join("");
+}
+// ── Temporal regions ──────────────────────────────────────────────
+/**
+ * The stretches of a `.dw` file that the temporal sub-parser reads: every
+ * `temporal { … }` marker body, and every `def temporal … { … }` macro body.
+ *
+ * Scanning only these is what keeps a Cedar `when { … }` clause from being
+ * mistaken for temporal source — `context.retryWindow == 3` should not read as
+ * a window, and a Cedar attribute named `since` is not the `since` operator.
+ */
+export function temporalRegions(text) {
+    const source = blankComments(text);
+    const regions = [];
+    const markers = /\btemporal\s*\{/g;
+    for (let m = markers.exec(source); m !== null; m = markers.exec(source)) {
+        const body = matchedBlock(source, m.index + m[0].length - 1);
+        if (body !== undefined)
+            regions.push(body);
+    }
+    const macros = /\bdef\s+temporal\s+[A-Za-z_][A-Za-z0-9_]*\s*\([^)]*\)\s*\{/g;
+    for (let m = macros.exec(source); m !== null; m = macros.exec(source)) {
+        const body = matchedBlock(source, m.index + m[0].length - 1);
+        if (body !== undefined)
+            regions.push(body);
+    }
+    return regions;
+}
+/** The text between `text[open]` (a `{`) and its matching `}`, or undefined. */
+function matchedBlock(text, open) {
+    let depth = 0;
+    let inString = false;
+    for (let i = open; i < text.length; i++) {
+        const ch = text[i];
+        if (inString) {
+            if (ch === "\\")
+                i++;
+            else if (ch === '"')
+                inString = false;
+            continue;
+        }
+        if (ch === '"')
+            inString = true;
+        else if (ch === "{")
+            depth++;
+        else if (ch === "}") {
+            depth--;
+            if (depth === 0)
+                return text.slice(open + 1, i);
+        }
+    }
+    return undefined;
+}
+const PREDICATE = /([A-Za-z_][A-Za-z0-9_]*(?:::[A-Za-z_][A-Za-z0-9_]*)*::"[^"]*")::([A-Za-z_][A-Za-z0-9_]*)/g;
+/** Every temporal predicate head in a `.dw` file, in source order. */
+export function scanPredicates(text) {
+    const refs = [];
+    for (const region of temporalRegions(text)) {
+        for (let m = PREDICATE.exec(region); m !== null; m = PREDICATE.exec(region)) {
+            refs.push({ action: m[1], kind: m[2] });
+        }
+        PREDICATE.lastIndex = 0;
+    }
+    return refs;
+}
+const WITHIN_WINDOW = /\bwithin\s+(\d+)([smhd])\b/g;
+/** A bare interval in macro-call argument position: `once(1h, …)`, `f(a, 30m)`. */
+const ARGUMENT_WINDOW = /[(,]\s*(\d+)([smhd])\s*(?=[,)])/g;
+/**
+ * Every window literal in a `.dw` file's temporal source.
+ *
+ * Both shapes count against `max_window`: a macro-call interval is the window
+ * a `within ?w` in the macro body resolves to, so `once(48h, …)` looks back
+ * exactly as far as `formerly within 48h` does.
+ */
+export function scanWindows(text) {
+    const windows = [];
+    for (const region of temporalRegions(text)) {
+        for (let m = WITHIN_WINDOW.exec(region); m !== null; m = WITHIN_WINDOW.exec(region)) {
+            windows.push(windowRef(m[1], m[2], "within"));
+        }
+        WITHIN_WINDOW.lastIndex = 0;
+        for (let m = ARGUMENT_WINDOW.exec(region); m !== null; m = ARGUMENT_WINDOW.exec(region)) {
+            windows.push(windowRef(m[1], m[2], "argument"));
+        }
+        ARGUMENT_WINDOW.lastIndex = 0;
+    }
+    return windows;
+}
+function windowRef(value, unit, position) {
+    const w = { value: Number(value), unit: unit };
+    return { text: `${w.value}${w.unit}`, seconds: windowSeconds(w), position };
+}
+/**
+ * Every `formerly` / `previous` / `since` that is not followed by a `within`.
+ *
+ * Unrepresentable through the builders — {@link formerly} and its siblings all
+ * take the window as an argument — but reachable through `raw()`, through a
+ * hand-written `.dw`, and through an audit of a file chant never wrote.
+ */
+export function scanWindowlessOperators(text) {
+    const found = [];
+    const pattern = /\b(formerly|previous|since)\b(?!\s+within\b)/g;
+    for (const region of temporalRegions(text)) {
+        for (let m = pattern.exec(region); m !== null; m = pattern.exec(region)) {
+            found.push(m[1]);
+        }
+        pattern.lastIndex = 0;
+    }
+    return found;
+}
+const EVENT_DECL = /\bevent\s*<\s*[A-Za-z_][A-Za-z0-9_]*\s*>\s*::\s*([A-Za-z_][A-Za-z0-9_]*)/g;
+const MAX_WINDOW = /\bmax_window\s*=\s*(\d+)([smhd])\b/;
+const PINNED_FIELD = /\bpin\s+[A-Za-z_][A-Za-z0-9_]*\s*:/;
+/** Read a `.dwschema` file's declarations. */
+export function readEventSchema(text) {
+    const source = blankComments(text);
+    const kinds = [];
+    for (let m = EVENT_DECL.exec(source); m !== null; m = EVENT_DECL.exec(source)) {
+        if (!kinds.includes(m[1]))
+            kinds.push(m[1]);
+    }
+    EVENT_DECL.lastIndex = 0;
+    const max = MAX_WINDOW.exec(source);
+    return {
+        kinds,
+        maxWindowSeconds: max
+            ? windowSeconds({ value: Number(max[1]), unit: max[2] })
+            : windowSeconds(DEFAULT_MAX_WINDOW),
+        maxWindowText: max ? `${max[1]}${max[2]}` : undefined,
+        hasPin: PINNED_FIELD.test(source),
+    };
+}
+/**
+ * The look-back cap in force for a build.
+ *
+ * With no emitted schema, `ServiceSchema::defaults()` applies and the cap is
+ * 24h. With several, the tightest one wins — a window legal under one schema
+ * and not another is a window some consumer will reject.
+ */
+export function effectiveMaxWindowSeconds(schemas) {
+    if (schemas.length === 0) {
+        return {
+            seconds: windowSeconds(DEFAULT_MAX_WINDOW),
+            text: `${DEFAULT_MAX_WINDOW.value}${DEFAULT_MAX_WINDOW.unit}`,
+        };
+    }
+    let tightest = schemas[0];
+    for (const s of schemas)
+        if (s.maxWindowSeconds < tightest.maxWindowSeconds)
+            tightest = s;
+    return {
+        seconds: tightest.maxWindowSeconds,
+        text: tightest.maxWindowText ?? `${DEFAULT_MAX_WINDOW.value}${DEFAULT_MAX_WINDOW.unit}`,
+    };
+}

package/dist/dogwood/serialize.js

@@ -0,0 +1,199 @@
+/**
+ * The `.dw` serializer leg.
+ *
+ * Runs inside the cedar serializer, not beside it: `serializeDogwood` is
+ * called once the cedar policies have been rendered, and its files land in the
+ * same `SerializerResult`. That is the whole point of shipping dogwood as a
+ * dialect — a `.dw` file stripped of Cedar semantics is meaningless, and a
+ * project's temporal policies and its plain Cedar policies are one policy set
+ * with two halves.
+ *
+ * Nothing here re-implements Cedar rendering. The policy head comes from
+ * `../serializer`'s `renderPolicyHead`, the scope forms from its
+ * `renderScope`, and the `when`/`unless` bodies from its `conditionStrings`,
+ * so a change to how a scope is written moves both outputs at once.
+ */
+import { isPropertyDeclarable } from "@intentius/chant/declarable";
+import { walkValue } from "@intentius/chant/serializer-walker";
+import { conditionStrings, getProps, isRecord, renderPolicyHead, resolvePolicyId } from "../policy-text.js";
+import { renderCondition } from "./temporal.js";
+import { renderEventSchema } from "./event-schema.js";
+import { renderMacroLibrary } from "./macros.js";
+import { DOGWOOD_EVENT_SCHEMA_FILENAME, DOGWOOD_EVENT_SCHEMA_TYPE, DOGWOOD_MACRO_FILENAME, DOGWOOD_MACRO_LIBRARY_TYPE, DOGWOOD_POLICY_FILENAME, DOGWOOD_POLICY_TYPE, } from "./policy.js";
+/** Files ending in this carry dogwood policy text. */
+export const DOGWOOD_POLICY_SUFFIX = ".dw";
+/** Files ending in this carry an event schema. */
+export const DOGWOOD_EVENT_SCHEMA_SUFFIX = ".dwschema";
+// ── Clause rendering ──────────────────────────────────────────────
+function temporalConditions(value) {
+    if (value === undefined || value === null)
+        return [];
+    const list = Array.isArray(value) ? value : [value];
+    return list.filter((node) => isRecord(node) && typeof node.op === "string");
+}
+/**
+ * One policy, in `.dw` surface syntax.
+ *
+ * Clause order is fixed rather than authored: every `when` form, then every
+ * `unless` form. Cedar evaluates a policy's conditions as a conjunction, and
+ * so does dogwood, so the order carries no meaning — fixing it means a policy
+ * that gains a temporal clause does not reshuffle the ones already there.
+ */
+export function renderTemporalPolicyText(id, props) {
+    const lines = renderPolicyHead(id, props);
+    for (const clause of conditionStrings(props.when))
+        lines.push(`when { ${clause} }`);
+    for (const clause of conditionStrings(props.whenGuardrails))
+        lines.push(`when guardrails { ${clause} }`);
+    for (const node of temporalConditions(props.whenTemporal)) {
+        lines.push("when temporal {", `    ${renderCondition(node)}`, "}");
+    }
+    for (const clause of conditionStrings(props.unless))
+        lines.push(`unless { ${clause} }`);
+    for (const clause of conditionStrings(props.unlessGuardrails))
+        lines.push(`unless guardrails { ${clause} }`);
+    for (const node of temporalConditions(props.unlessTemporal)) {
+        lines.push("unless temporal {", `    ${renderCondition(node)}`, "}");
+    }
+    return lines.join("\n") + ";";
+}
+// ── The walker ────────────────────────────────────────────────────
+/**
+ * Same visitor contract as the cedar serializer's: a reference collapses to
+ * the text a policy names it by. The temporal AST is plain data, so the walker
+ * passes it through untouched while still resolving any Declarable a scope
+ * position holds.
+ */
+const dogwoodVisitor = {
+    attrRef: (logicalName, attribute) => `${logicalName}.${attribute}`,
+    resourceRef: (logicalName) => logicalName,
+    propertyDeclarable: (entity, walk) => {
+        const out = {};
+        for (const [key, value] of Object.entries(getProps(entity))) {
+            if (key === "entityType" || key === "lexicon")
+                continue;
+            if (value === undefined)
+                continue;
+            out[key] = walk(value);
+        }
+        return out;
+    },
+};
+// ── The leg ───────────────────────────────────────────────────────
+/**
+ * Render every dogwood entity in the build.
+ *
+ * Returns `undefined` when the build holds no temporal policies, event schemas
+ * or macro libraries at all — a cedar-only project sees no `.dw` output and no
+ * behaviour change.
+ *
+ * Ids come from `resolvePolicyId`, the same rule `cedarPolicyRecords` uses, so
+ * a policy's `@id` does not depend on which leg rendered it.
+ */
+export function serializeDogwood(entities) {
+    // Reverse map first: walkValue resolves a Declarable reference by identity,
+    // so every entity has to be known before any of them is walked.
+    const entityNames = new Map();
+    for (const [name, entity] of entities) {
+        entityNames.set(entity, name);
+    }
+    const policyText = [];
+    const inlineMacros = [];
+    const macroFiles = new Map();
+    const schemaFiles = new Map();
+    const warnings = [];
+    for (const [name, entity] of entities) {
+        if (isPropertyDeclarable(entity))
+            continue;
+        if (entity.entityType !== DOGWOOD_POLICY_TYPE &&
+            entity.entityType !== DOGWOOD_EVENT_SCHEMA_TYPE &&
+            entity.entityType !== DOGWOOD_MACRO_LIBRARY_TYPE) {
+            continue;
+        }
+        const props = walkValue(getProps(entity), entityNames, dogwoodVisitor);
+        if (entity.entityType === DOGWOOD_POLICY_TYPE) {
+            policyText.push(renderTemporalPolicyText(resolvePolicyId(name, props), props));
+            continue;
+        }
+        if (entity.entityType === DOGWOOD_MACRO_LIBRARY_TYPE) {
+            const defs = Array.isArray(props.macros) ? props.macros : [];
+            if (defs.length === 0) {
+                warnings.push(`dogwood: macro library "${name}" declares no macros, so nothing was emitted for it`);
+                continue;
+            }
+            if (props.inline === true) {
+                inlineMacros.push(...defs);
+                continue;
+            }
+            const filename = typeof props.filename === "string" ? props.filename : DOGWOOD_MACRO_FILENAME;
+            macroFiles.set(filename, [...(macroFiles.get(filename) ?? []), ...defs]);
+            continue;
+        }
+        // DOGWOOD_EVENT_SCHEMA_TYPE
+        const schema = props.schema;
+        if (!isRecord(schema) || !Array.isArray(schema.events)) {
+            warnings.push(`dogwood: event schema "${name}" has no \`schema\` prop, so no .dwschema was written for it`);
+            continue;
+        }
+        const filename = typeof props.filename === "string" ? props.filename : DOGWOOD_EVENT_SCHEMA_FILENAME;
+        const existing = schemaFiles.get(filename);
+        if (existing) {
+            // Two schemas cannot share a file: `max_window` is a single directive at
+            // the top, so concatenating them would emit something upstream rejects.
+            warnings.push(`dogwood: event schemas "${existing.name}" and "${name}" both target ${filename}; only "${existing.name}" was written — give one of them an explicit \`filename\``);
+            continue;
+        }
+        schemaFiles.set(filename, { name, schema: schema });
+    }
+    // Warnings alone are enough to report: a dogwood entity that produced no
+    // file is exactly the case worth saying out loud, and returning `undefined`
+    // here would swallow the reason.
+    if (policyText.length === 0 &&
+        inlineMacros.length === 0 &&
+        macroFiles.size === 0 &&
+        schemaFiles.size === 0 &&
+        warnings.length === 0) {
+        return undefined;
+    }
+    const files = {};
+    if (policyText.length > 0 || inlineMacros.length > 0) {
+        const sections = [];
+        if (inlineMacros.length > 0)
+            sections.push(renderMacroLibrary(inlineMacros).trimEnd());
+        sections.push(...policyText);
+        files[DOGWOOD_POLICY_FILENAME] = sections.join("\n\n") + "\n";
+    }
+    for (const [filename, defs] of macroFiles) {
+        files[filename] = renderMacroLibrary(defs);
+    }
+    for (const [filename, { schema }] of schemaFiles) {
+        files[filename] = renderEventSchema(schema);
+    }
+    return { files, warnings };
+}
+/**
+ * Every `Dogwood::TemporalPolicy` in a build, with references walked and ids
+ * resolved — the temporal counterpart of `cedarPolicyRecords` (#1660).
+ *
+ * `serializeDogwood` above renders whole *files*; the AgentCore embedding needs
+ * the policies one at a time, because `AWS::BedrockAgentCore::Policy` carries a
+ * single statement and `EnforcementMode` is set per policy. Both paths walk
+ * references through the same visitor, so a scope that names another declared
+ * entity resolves identically whichever one rendered it.
+ */
+export function dogwoodPolicyRecords(entities) {
+    const entityNames = new Map();
+    for (const [name, entity] of entities) {
+        entityNames.set(entity, name);
+    }
+    const records = [];
+    for (const [name, entity] of entities) {
+        if (isPropertyDeclarable(entity))
+            continue;
+        if (entity.entityType !== DOGWOOD_POLICY_TYPE)
+            continue;
+        const props = walkValue(getProps(entity), entityNames, dogwoodVisitor);
+        records.push({ name, id: resolvePolicyId(name, props), props });
+    }
+    return records;
+}