@intentius/chant-lexicon-cedar 0.124.31 → 0.124.33

package/dist/dogwood/temporal.js

@@ -0,0 +1,354 @@
+/**
+ * Typed builders for dogwood's temporal sub-language.
+ *
+ * These target the **parser primitives**, not the named aggregates. The #1657
+ * verification (and the correction comment on epic #1646) is explicit about
+ * why: `formerly`, `previous`, `since`, `exists`, `tp()`, `count for … where`
+ * and `sum … for … where` are the only temporal keywords in upstream's
+ * `extension/temporal/grammar.pest`. `count_within`, `sum_within`,
+ * `count_distinct_within` and `bind` are macros in `default_macros.dw` — a
+ * swappable standard library that a caller passing `--macros` replaces
+ * wholesale — and `once` is not even in that library, only in the examples.
+ *
+ * So the aggregates are expressible here as macro *calls* ({@link call}, and
+ * the convenience wrappers in `./macros.ts`), never as first-class operators.
+ * A call that resolves to nothing at the other end is a missing macro, which
+ * is a comprehensible failure; a first-class builder that silently emits a
+ * name the callee's library does not define is not.
+ *
+ * Everything below renders to the surface syntax the pest grammar accepts.
+ * Where the grammar's precedence would bind differently from the tree the
+ * author built, the renderer parenthesises — it never relies on the reader
+ * knowing that `!` binds tighter than `since`, or that an aggregate's `where`
+ * body is greedy.
+ */
+import { escapeCedarString } from "../policy-text.js";
+import { renderWindow, renderWindowValue, window, windowValue, } from "./window.js";
+// ── Names ─────────────────────────────────────────────────────────
+/** A bare binder or field name. */
+const IDENT = /^[A-Za-z_][A-Za-z0-9_]*$/;
+/** `?p` (call-site value splice) or `$t` (macro-introduced fresh binder). */
+const SIGIL = /^[?$][A-Za-z_][A-Za-z0-9_]*$/;
+/** `input.user`, `output.result` — the dotted path a predicate argument names. */
+const FIELD_PATH = /^[A-Za-z_][A-Za-z0-9_]*(\.[A-Za-z_][A-Za-z0-9_]*)*$/;
+/** `Drupe::Action::"Read"` — a qualified action with a quoted id. */
+const QUALIFIED_ACTION = /^[A-Za-z_][A-Za-z0-9_]*(::[A-Za-z_][A-Za-z0-9_]*)*::"[^"]*"$/;
+/** `String`, `Long`, `Timepoint`, `MyApp::OAuthUser`. */
+const TYPE_NAME = /^[A-Za-z_][A-Za-z0-9_]*(::[A-Za-z_][A-Za-z0-9_]*)*$/;
+function assertName(pattern, value, what) {
+    if (!pattern.test(value))
+        throw new Error(`dogwood: ${what} — got "${value}"`);
+    return value;
+}
+/**
+ * A binder position: a plain identifier, or a macro sigil.
+ *
+ * The sigils are legal only inside a macro body; upstream's well-formedness
+ * pass rejects them elsewhere. `./macros.ts` is where they belong, and it is
+ * what carries that warning to the author.
+ */
+export function binderName(value) {
+    if (IDENT.test(value) || SIGIL.test(value))
+        return value;
+    throw new Error(`dogwood: a binder must be an identifier, or a "?param"/"$binder" sigil inside a macro body — got "${value}"`);
+}
+/** `(t: Timepoint)`, `(amount: Long)`, `($t: Timepoint)` inside a macro. */
+export function typedBinder(name, type) {
+    return { name: binderName(name), type: assertName(TYPE_NAME, type, "a binder type must be a Cedar type name") };
+}
+function liftTerm(value) {
+    if (typeof value === "number")
+        return int(value);
+    if (typeof value === "boolean")
+        return bool(value);
+    return value;
+}
+/** A raw term, emitted verbatim. The escape hatch for a shape not modelled here. */
+export function term(text) {
+    return { op: "term", text };
+}
+/** A Cedar string literal: `"alice"`. */
+export function str(value) {
+    return term(`"${escapeCedarString(value)}"`);
+}
+/** An integer literal. Upstream's grammar admits a leading `-`. */
+export function int(value) {
+    if (!Number.isInteger(value)) {
+        throw new Error(`dogwood: an integer term must be a whole number — use decimalOf() for ${value}`);
+    }
+    return term(String(value));
+}
+/** `true` / `false`. */
+export function bool(value) {
+    return term(value ? "true" : "false");
+}
+/** `decimal("1.50")` — Cedar's decimal constructor, which dogwood admits as a term. */
+export function decimalOf(value) {
+    return term(`decimal("${escapeCedarString(value)}")`);
+}
+/** `context.input.user` — a field of the request context record. */
+export function ctx(path) {
+    assertName(FIELD_PATH, path, "a context path must be dotted identifiers");
+    return term(`context.${path}`);
+}
+/** `principal`, `resource`, `principal.dept` — the request scope entities. */
+export function scopeRef(root, ...attrs) {
+    for (const attr of attrs)
+        assertName(IDENT, attr, "a scope attribute must be an identifier");
+    return term([root, ...attrs].join("."));
+}
+/** `Drupe::OAuthUser::"alice"` — an entity UID literal. */
+export function entityUid(uid) {
+    assertName(QUALIFIED_ACTION, uid, 'an entity UID looks like Ns::Type::"id"');
+    return term(uid);
+}
+/** A bare binder reference — a `for`-declared variable, or a macro sigil. */
+export function varRef(name) {
+    return term(binderName(name));
+}
+/** `*` — the grammar's wildcard term. */
+export function wildcard() {
+    return term("*");
+}
+/** `[a, b]`. */
+export function arrayOf(...items) {
+    return { op: "array", items: items.map(liftTerm) };
+}
+/**
+ * `count for (t: Timepoint). where φ` — the primitive behind `count_within`.
+ *
+ * The `for` list is the aggregation domain and is mandatory in the grammar,
+ * so it is a required argument here too.
+ */
+export function count(binders, where) {
+    if (binders.length === 0)
+        throw new Error("dogwood: count needs at least one typed binder in its for-list");
+    return { op: "count", binders, where };
+}
+/** `sum a for (a: Long), (t: Timepoint). where φ` — the primitive behind `sum_within`. */
+export function sum(over, binders, where) {
+    if (binders.length === 0)
+        throw new Error("dogwood: sum needs at least one typed binder in its for-list");
+    return { op: "sum", over: binderName(over), binders, where };
+}
+// ── Condition builders ────────────────────────────────────────────
+/**
+ * `Ns::Action::"Name"::kind{ field: term, … }`.
+ *
+ * The event kind is mandatory in the grammar and author-defined in practice —
+ * `request`/`response`/`error` are the conventional kinds the default event
+ * schema declares, not a fixed set. Which kinds are legal for a given policy
+ * set is the emitted `.dwschema`'s business, and DWDC010's.
+ */
+export function predicate(action, kind, args = {}) {
+    assertName(QUALIFIED_ACTION, action, 'a predicate action looks like Ns::Action::"Name"');
+    assertName(IDENT, kind, "an event kind must be an identifier");
+    return {
+        op: "predicate",
+        action,
+        kind,
+        args: Object.entries(args).map(([path, value]) => ({
+            path: assertName(FIELD_PATH, path, "a predicate field path must be dotted identifiers"),
+            value: liftTerm(value),
+        })),
+    };
+}
+/** `formerly within <w> φ` — held at some point in the window. */
+export function formerly(w, body) {
+    return { op: "formerly", window: windowValue(w), body };
+}
+/** `previous within <w> φ` — held at the immediately preceding timepoint in the window. */
+export function previous(w, body) {
+    return { op: "previous", window: windowValue(w), body };
+}
+/** `φ since within <w> ψ` — φ has held continuously since ψ, inside the window. */
+export function since(left, w, right) {
+    return { op: "since", left, window: windowValue(w), right };
+}
+/** `exists (name: Type). φ`. */
+export function exists(binder, body) {
+    return { op: "exists", binder, body };
+}
+/** `tp(t)`. */
+export function tp(binder) {
+    return { op: "tp", binder: binderName(binder) };
+}
+/** `φ && ψ && …`. A single operand collapses to itself. */
+export function and(...operands) {
+    if (operands.length === 0)
+        throw new Error("dogwood: and() needs at least one operand");
+    if (operands.length === 1)
+        return operands[0];
+    return { op: "and", operands };
+}
+/** `!φ`. */
+export function not(body) {
+    return { op: "not", body };
+}
+/** `a <op> b`. */
+export function compare(left, operator, right) {
+    return { op: "compare", left: liftTerm(left), operator, right: liftTerm(right) };
+}
+/**
+ * A macro invocation.
+ *
+ * Nothing here checks that the macro exists: the library is `--macros`, chosen
+ * by whoever runs `dogwood validate`, and chant is not that. `./macros.ts`
+ * carries typed wrappers for the four the default library ships.
+ */
+export function call(name, args = []) {
+    assertName(IDENT, name, "a macro name must be an identifier");
+    return { op: "call", name, args };
+}
+/** `1h` in macro-call argument position — the interval without the `within`. */
+export function interval(w) {
+    return { op: "interval", window: window(w) };
+}
+/** Temporal source text, passed through untouched. See {@link RawCondition}. */
+export function raw(text) {
+    return { op: "raw", text };
+}
+/** `?s` in condition position. See {@link SigilCondition}. */
+export function sigilCondition(param) {
+    if (!SIGIL.test(param))
+        throw new Error(`dogwood: a condition sigil looks like "?s" — got "${param}"`);
+    return { op: "sigil", param };
+}
+// ── Rendering ─────────────────────────────────────────────────────
+function isTerm(node) {
+    return node.op === "term" || node.op === "array" || node.op === "count" || node.op === "sum";
+}
+function isAggregate(t) {
+    return t.op === "count" || t.op === "sum";
+}
+/** Render a term. */
+export function renderTerm(t) {
+    switch (t.op) {
+        case "term":
+            return t.text;
+        case "array":
+            return `[${t.items.map(renderTerm).join(", ")}]`;
+        case "count":
+            return `count ${renderForBinders(t.binders)} where ${renderCondition(t.where)}`;
+        case "sum":
+            return `sum ${t.over} ${renderForBinders(t.binders)} where ${renderCondition(t.where)}`;
+        case "call":
+            return renderCall(t);
+    }
+}
+function renderForBinders(binders) {
+    return `for ${binders.map((b) => `(${b.name}: ${b.type})`).join(", ")}.`;
+}
+/**
+ * A comparison operand.
+ *
+ * An aggregate's `where` body is greedy, so `count for (…). where φ == 3`
+ * reads `== 3` as part of φ. Upstream's `paren_agg` rule exists for exactly
+ * this and is always legal, so aggregates and macro calls are parenthesised on
+ * both sides rather than only where the greed would actually bite — the
+ * emitted text should not depend on which side of the operator it landed on.
+ */
+function renderComparisonOperand(t) {
+    return isAggregate(t) || t.op === "call" ? `(${renderTerm(t)})` : renderTerm(t);
+}
+function renderCall(node) {
+    const args = node.args.map((arg) => {
+        if (arg.op === "interval")
+            return renderWindow(arg.window);
+        if (isTerm(arg))
+            return renderTerm(arg);
+        return renderCondition(arg);
+    });
+    return `${node.name}(${args.join(", ")})`;
+}
+/**
+ * An `atom` — the operand of `formerly`, `previous` and the right of `since`.
+ *
+ * The grammar's `atom` is `"(" condition ")" | tp_op | call | refinable |
+ * comparison`; everything else has to be parenthesised.
+ */
+function renderAtom(node) {
+    switch (node.op) {
+        case "predicate":
+        case "sigil":
+        case "tp":
+        case "call":
+        case "compare":
+            return renderCondition(node);
+        default:
+            return `(${renderCondition(node)})`;
+    }
+}
+/**
+ * A `neg_conjunct` — what `!` negates, and what sits left of `since`.
+ *
+ * `!` binds tighter than `since` and `&&`, so `!a since within W b` negates
+ * only `a`. Anything looser gets parentheses.
+ */
+function renderNegConjunct(node) {
+    switch (node.op) {
+        case "and":
+        case "since":
+        case "exists":
+            return `(${renderCondition(node)})`;
+        default:
+            return renderCondition(node);
+    }
+}
+/**
+ * A `conjunct_or_since` — one operand of an `&&` chain.
+ *
+ * `since` is allowed here bare (it is part of the same rule). `exists` binds
+ * maximally to the right, so an unparenthesised one would swallow every
+ * operand after it.
+ */
+function renderConjunct(node) {
+    switch (node.op) {
+        case "and":
+        case "exists":
+            return `(${renderCondition(node)})`;
+        default:
+            return renderCondition(node);
+    }
+}
+/** Render a temporal condition to the surface syntax the pest grammar accepts. */
+export function renderCondition(node) {
+    switch (node.op) {
+        case "raw":
+            return node.text;
+        case "sigil":
+            return node.param;
+        case "predicate": {
+            const args = node.args.map((a) => `${a.path}: ${renderTerm(a.value)}`).join(", ");
+            return `${node.action}::${node.kind}{${args.length > 0 ? ` ${args} ` : ""}}`;
+        }
+        case "formerly":
+            return `formerly within ${renderWindowValue(node.window)} ${renderAtom(node.body)}`;
+        case "previous":
+            return `previous within ${renderWindowValue(node.window)} ${renderAtom(node.body)}`;
+        case "since":
+            return `${renderNegConjunct(node.left)} since within ${renderWindowValue(node.window)} ${renderAtom(node.right)}`;
+        case "exists":
+            return `exists (${node.binder.name}: ${node.binder.type}). ${renderCondition(node.body)}`;
+        case "tp":
+            return `tp(${node.binder})`;
+        case "and":
+            return node.operands.map(renderConjunct).join(" && ");
+        case "not":
+            return `!${renderNegConjunct(node.body)}`;
+        case "compare":
+            return `${renderComparisonOperand(node.left)} ${node.operator} ${renderComparisonOperand(node.right)}`;
+        case "call":
+            return renderCall(node);
+    }
+}
+/**
+ * `temporal { … }` — the extension marker.
+ *
+ * It is a `primary` in the Cedar expression grammar as well as a clause tag,
+ * so this is also how a temporal condition is embedded mid-expression:
+ * `when { is_small(context.input.shares) && temporal { once(1h, …) } }`.
+ */
+export function temporalMarker(condition) {
+    return `temporal { ${renderCondition(condition)} }`;
+}

package/dist/dogwood/trace.js

@@ -0,0 +1,269 @@
+/**
+ * Typed construction of dogwood replay traces (#1661, epic #1646).
+ *
+ * A trace is one event per line, and the line grammar recorded by the #1657
+ * verification (§6, read from `dogwood-language/src/interpreter/log_parse.rs`
+ * at the pinned SHA) is:
+ *
+ * ```
+ * @<timestamp> [scope(principal: <uid>, resource: <uid>)]
+ *              [entities(<uid>: { <attrs> } [in [<uid>, …]], …)]
+ *              [request_context(<group>: { … }, …)]
+ *              <Ns>::Action::"<Name>"::<kind>(<field>: <value>, …)
+ * ```
+ *
+ * The three envelopes are optional and must appear in that order; the trailing
+ * group is the logged record. There is no comment syntax — a `//` is an
+ * ordinary part of a value, so URLs survive — blank lines are skipped, and a
+ * leading BOM is stripped.
+ *
+ * Two things in that format silently weaken a replay rather than failing it,
+ * and both are what this module exists to make hard:
+ *
+ * 1. **`request_context(…)` and the logged record are different bags.** The
+ *    Cedar request is built from the first; temporal predicates match against
+ *    the second. A field needed by both and supplied to only one weakens
+ *    either the Cedar check or the temporal check, and the replay still exits
+ *    0 with a verdict that looks authoritative. So {@link traceEvent} writes a
+ *    `context` group into *both* bags by default, and dropping one is an
+ *    explicit per-event `bags` opt-out that has to be typed out.
+ * 2. **Actions must be fully qualified.** `Drupe::Action::"Transfer"`, never
+ *    `Transfer` — a short name leaves the temporal predicate unmatched while
+ *    Cedar still authorizes. {@link traceEvent} rejects anything that is not
+ *    `Ns::…::"Name"` at construction.
+ *
+ * {@link auditTrace} is the same two checks applied to a trace this module did
+ * not build — the AgentCore session history #1661 leaves to the aws lexicon,
+ * or a `.log` recorded by hand. A trace is a trace, wherever it came from.
+ */
+import { escapeCedarString } from "../policy-text.js";
+// ── Names ─────────────────────────────────────────────────────────
+/** `Drupe::Action::"Read"`, `Drupe::OAuthUser::"alice"` — a qualified uid. */
+const QUALIFIED_UID = /^[A-Za-z_][A-Za-z0-9_]*(::[A-Za-z_][A-Za-z0-9_]*)+::"[^"]*"$/;
+/** A bare field, group or event-kind name. */
+const IDENT = /^[A-Za-z_][A-Za-z0-9_]*$/;
+function assertUid(value, what) {
+    if (!QUALIFIED_UID.test(value)) {
+        throw new Error(`dogwood: ${what} must be fully qualified, like Ns::Type::"id" — got "${value}"`);
+    }
+    return value;
+}
+function assertIdent(value, what) {
+    if (!IDENT.test(value))
+        throw new Error(`dogwood: ${what} must be an identifier — got "${value}"`);
+    return value;
+}
+/** `Ns::Type::"id"`. Validated at construction, so a short name cannot slip through. */
+export function entityRef(uid) {
+    return { traceValue: "entity", uid: assertUid(uid, "an entity reference") };
+}
+/** A Cedar decimal, written as it should appear (`"1.50"`). */
+export function decimalValue(text) {
+    if (!/^-?\d+\.\d+$/.test(text)) {
+        throw new Error(`dogwood: a trace decimal looks like "1.50" — got "${text}"`);
+    }
+    return { traceValue: "decimal", text };
+}
+/** Surface text, rendered verbatim. For values this module has no shape for. */
+export function rawValue(text) {
+    return { traceValue: "raw", text };
+}
+function isTagged(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value) && "traceValue" in value;
+}
+/** Render one value in the Cedar surface form the trace parser reads. */
+export function renderTraceValue(value) {
+    if (typeof value === "string")
+        return `"${escapeCedarString(value)}"`;
+    if (typeof value === "boolean")
+        return value ? "true" : "false";
+    if (typeof value === "number") {
+        if (!Number.isInteger(value)) {
+            throw new Error(`dogwood: ${String(value)} is not an integer — a trace decimal must be written with decimalValue("1.50") so its scale survives`);
+        }
+        return String(value);
+    }
+    if (Array.isArray(value))
+        return `[${value.map(renderTraceValue).join(", ")}]`;
+    if (isTagged(value)) {
+        if (value.traceValue === "entity")
+            return value.uid;
+        if (value.traceValue === "decimal")
+            return value.text;
+        return value.text;
+    }
+    return renderTraceFields(value);
+}
+/** `{ a: 1, b: "x" }` — a record body, braces included. */
+export function renderTraceFields(fields) {
+    const parts = Object.entries(fields).map(([key, value]) => `${assertIdent(key, "a trace field name")}: ${renderTraceValue(value)}`);
+    return `{ ${parts.join(", ")} }`;
+}
+/** `Ns::Type::"id": { … } in [ … ]`. */
+export function traceEntity(uid, attrs, parents) {
+    return {
+        uid: assertUid(uid, "an entity declaration"),
+        ...(attrs ? { attrs } : {}),
+        ...(parents ? { parents: parents.map((p) => assertUid(p, "an entity parent")) } : {}),
+    };
+}
+/**
+ * Build one trace event with both bags populated.
+ *
+ * Every `context` group is written to the `request_context` envelope *and*
+ * merged into the logged record, because that is the only combination in which
+ * the Cedar check and the temporal check both see the field. Dropping one is a
+ * typed decision (`bags`), not an omission.
+ */
+export function traceEvent(input) {
+    const action = assertUid(input.action, "a trace action");
+    const kind = assertIdent(input.kind ?? "request", "an event kind");
+    const bags = input.bags ?? "both";
+    const groups = input.context ?? {};
+    for (const group of Object.keys(groups))
+        assertIdent(group, "a request-context group");
+    const record = {};
+    if (bags !== "context-only")
+        Object.assign(record, groups);
+    Object.assign(record, input.record ?? {});
+    const context = {};
+    if (bags !== "record-only")
+        Object.assign(context, groups);
+    return {
+        timestamp: input.timestamp,
+        action,
+        kind,
+        record,
+        ...(Object.keys(context).length > 0 ? { requestContext: context } : {}),
+        ...(input.scope
+            ? {
+                scope: {
+                    principal: assertUid(input.scope.principal, "a scope principal"),
+                    resource: assertUid(input.scope.resource, "a scope resource"),
+                },
+            }
+            : {}),
+        ...(input.entities && input.entities.length > 0 ? { entities: input.entities } : {}),
+    };
+}
+// ── Rendering ─────────────────────────────────────────────────────
+function renderScope(scope) {
+    return `scope(principal: ${scope.principal}, resource: ${scope.resource})`;
+}
+function renderEntities(entities) {
+    const parts = entities.map((e) => {
+        const attrs = renderTraceFields(e.attrs ?? {});
+        const parents = e.parents && e.parents.length > 0 ? ` in [${e.parents.join(", ")}]` : "";
+        return `${e.uid}: ${attrs}${parents}`;
+    });
+    return `entities(${parts.join(", ")})`;
+}
+function renderGroups(fields) {
+    const parts = Object.entries(fields).map(([group, value]) => `${assertIdent(group, "a request-context group")}: ${renderTraceValue(value)}`);
+    return `request_context(${parts.join(", ")})`;
+}
+/** One event as the single line the trace parser reads. Never ends in a newline. */
+export function renderTraceLine(event) {
+    if (!Number.isInteger(event.timestamp)) {
+        throw new Error(`dogwood: a trace timestamp is an i64 — got ${String(event.timestamp)}`);
+    }
+    const parts = [`@${event.timestamp}`];
+    if (event.scope)
+        parts.push(renderScope(event.scope));
+    if (event.entities && event.entities.length > 0)
+        parts.push(renderEntities(event.entities));
+    if (event.requestContext && Object.keys(event.requestContext).length > 0) {
+        parts.push(renderGroups(event.requestContext));
+    }
+    const record = Object.entries(event.record).map(([key, value]) => `${assertIdent(key, "a trace field name")}: ${renderTraceValue(value)}`);
+    parts.push(`${event.action}::${event.kind}(${record.join(", ")})`);
+    return parts.join(" ");
+}
+/** A whole trace, one event per line, newline-terminated. */
+export function renderTrace(events) {
+    return events.map(renderTraceLine).join("\n") + "\n";
+}
+/**
+ * The both-bags and ordering checks, applied to any trace.
+ *
+ * Every finding here is something that makes a replay *weaker* rather than
+ * something that makes it fail — which is exactly the class a green replay run
+ * hides. A trace built by {@link traceEvent} produces none of them unless a
+ * `bags` opt-out was taken deliberately.
+ */
+export function auditTrace(events, options = {}) {
+    const issues = [];
+    const decisionKinds = new Set(options.decisionKinds ?? ["request"]);
+    let previous;
+    events.forEach((event, index) => {
+        const at = { index, timestamp: event.timestamp };
+        const context = event.requestContext ?? {};
+        const contextKeys = Object.keys(context);
+        const decides = decisionKinds.has(event.kind);
+        if (decides && contextKeys.length === 0) {
+            issues.push({
+                ...at,
+                kind: "no-request-context",
+                message: `${event.action}::${event.kind} has no request_context envelope, so the Cedar request it is evaluated against carries no context — every context.* test in a policy silently misses`,
+            });
+        }
+        for (const group of contextKeys) {
+            if (!(group in event.record)) {
+                issues.push({
+                    ...at,
+                    kind: "single-bag",
+                    message: `${event.action}::${event.kind} puts "${group}" in request_context but not in the logged record, so temporal predicates over ${group}.* silently miss`,
+                });
+            }
+        }
+        for (const group of Object.keys(event.record)) {
+            // Only groups (records) are candidates for the Cedar side; the event
+            // schema's own scalar injections (callerPrincipal, requestId, …) belong
+            // to the logged record alone and are not a single-bag finding.
+            const value = event.record[group];
+            const isGroup = typeof value === "object" && value !== null && !Array.isArray(value) && !isTagged(value);
+            if (decides && isGroup && contextKeys.length > 0 && !(group in context)) {
+                issues.push({
+                    ...at,
+                    kind: "single-bag",
+                    message: `${event.action}::${event.kind} puts "${group}" in the logged record but not in request_context, so context.${group}.* is absent from the Cedar request`,
+                });
+            }
+        }
+        if (Object.keys(event.record).length === 0) {
+            issues.push({
+                ...at,
+                kind: "empty-record",
+                message: `${event.action}::${event.kind} logs no fields at all, so no temporal predicate can match it`,
+            });
+        }
+        if (previous !== undefined && event.timestamp < previous) {
+            issues.push({
+                ...at,
+                kind: "out-of-order",
+                message: `timestamp ${event.timestamp} follows ${previous} — the interpreter accumulates history in file order, so an out-of-order line changes what a window sees`,
+            });
+        }
+        previous = event.timestamp;
+    });
+    return issues;
+}
+/**
+ * Assemble events into trace text, refusing to produce a weakened one.
+ *
+ * The inversion of the trap: the default is a trace that populates both bags,
+ * and every way of getting a weaker one — a `bags` opt-out on an event, a
+ * hand-normalized event with an empty record — has to be named in `allow`
+ * before this will hand it back.
+ */
+export function traceFixture(events, options = {}) {
+    const allow = new Set(options.allow ?? []);
+    const issues = auditTrace(events, options);
+    const blocking = issues.filter((i) => !allow.has(i.kind));
+    if (blocking.length > 0) {
+        const detail = blocking.map((i) => `  [${i.kind}] @${i.timestamp}: ${i.message}`).join("\n");
+        throw new Error(`dogwood: this trace would weaken its own replay rather than fail it:\n${detail}\n` +
+            `Fix the events, or pass { allow: [${[...new Set(blocking.map((i) => `"${i.kind}"`))].join(", ")}] } to say the weakening is the point.`);
+    }
+    return { events, text: renderTrace(events), issues };
+}

package/dist/dogwood/upstream.js

@@ -0,0 +1,40 @@
+/**
+ * The dogwood upstream pin.
+ *
+ * Not a `upstreamPin` on the plugin: that slot belongs to the cedar grammar
+ * (`@cedar-policy/cedar-wasm`, see `../spec/pin.ts`), and self-upgrade tooling
+ * bumps exactly one thing per lexicon. Dogwood's pin is a git SHA recorded by
+ * #1657, because upstream has no version to key off — zero tags, zero
+ * releases, and a workspace version of `1.0.0` that is an Amazon-internal
+ * package artifact every future sync will also report.
+ *
+ * The blob hashes are the narrow content pin the #1657 report recommends. The
+ * whole tree hash moves on every sync including docs-only ones, which makes it
+ * too noisy to gate on; these seven files are the surface chant actually
+ * depends on. The three `.pest` grammars pin the language, `default_macros.dw`
+ * pins the standard aggregate library (which is a file a sync can edit and a
+ * caller can replace with `--macros`), and the three `dogwood-cli/src` files
+ * pin the JSON report structs that are #1659's integration surface.
+ *
+ * Movement risk is structural, not incidental: content arrives as squashed
+ * "Sync from internal source" commits from a publish bot, against a repository
+ * nobody outside Amazon can see, with no changelog and no version bump.
+ */
+/** The pinned upstream revision and the files chant's surface is built against. */
+export const DOGWOOD_UPSTREAM = {
+    owner: "dogwood-policy",
+    repo: "dogwood",
+    /** Default-branch SHA verified in #1657 (committed 2026-08-06). */
+    revision: "5063bcc2d6d6cf5024d1b0498e6cc8ef52cbcf0c",
+    license: "Apache-2.0",
+    /** Git blob hashes at {@link revision} — the narrow content pin. */
+    contents: {
+        "dogwood-language/src/parser/grammar.pest": "adb0801303ee1b735585fe22a5d85175ecf6772c",
+        "dogwood-language/src/extension/temporal/grammar.pest": "dc31fe1634b5c37173f0a999619e9834069b7a22",
+        "dogwood-language/src/event_schema/grammar.pest": "bd3b064447dc0d09cc2f8eb28a7c657e746cc8a2",
+        "dogwood-language/configuration/default_macros.dw": "ecd67e5edcd566aa66b05ad51bc472afbaf22a7a",
+        "dogwood-cli/src/ops.rs": "2924c7eb0e569a745ff19c2d84cbba782fc56502",
+        "dogwood-cli/src/main.rs": "bfd68c9ff05883ed48e5738f658b5925542d817d",
+        "dogwood-cli/src/error.rs": "43f12afbbf25ad94e25130c83227eefd86f8d516",
+    },
+};