@intentius/chant-lexicon-cedar 0.44.8 → 0.44.10

package/dist/config.d.ts

@@ -69,6 +69,31 @@ export declare const cedarConfigSchema: z.ZodObject<{
          */
         requireProjectSchema: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strict>>;
+    /**
+     * The dogwood dialect's CLI-gated leg (#1659).
+     *
+     * `strictObject` again, for the reason the outer one is: a typo here is the
+     * difference between "full .dw validation ran" and "DWDE010 said it could
+     * not run", and the second is easy to skim past.
+     */
+    dogwood: z.ZodOptional<z.ZodObject<{
+        /**
+         * Path to the `dogwood` binary, absolute or relative to the config file.
+         *
+         * Optional, and its absence is not an error: DWDE010 warns-and-skips
+         * with an issue-linked advisory when no binary is found, which is the
+         * epic's explicit exception. Set this when the binary is built somewhere
+         * `PATH` does not reach — the on-demand harness shape the epic borrows
+         * from forgejo-runtime-e2e.
+         *
+         * A `chant.config.ts` cannot be read from inside a post-synth check —
+         * `check()` is synchronous and evaluating project code is not — so this
+         * key is honoured from `chant.config.json` and the `CHANT_DOGWOOD_BINARY`
+         * environment variable covers the TypeScript-config case. See
+         * `src/dogwood/cli.ts`.
+         */
+        binary: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
 }, z.core.$strict>;
 export type CedarConfig = z.infer<typeof cedarConfigSchema>;
 declare module "@intentius/chant/config" {

package/dist/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAE3D;;;;GAIG;AACH,eAAO,MAAM,yBAAyB,uBAAuB,CAAC;AAE9D;;;;GAIG;AACH,eAAO,MAAM,iBAAiB;IAC5B;;;;;;OAMG;;IAGH;;;;OAIG;;QAGC,0EAA0E;;QAE1E;;;WAGG;;;;;;QAEH;;;;;;WAMG;;;kBAIP,CAAC;AAEH,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAE5D,OAAO,QAAQ,yBAAyB,CAAC;IACvC,UAAU,WAAW;QACnB,KAAK,CAAC,EAAE,WAAW,CAAC;KACrB;CACF;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,oBAAoB,GAAG,WAAW,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC,CAAC;AAErE;;;;;;;;;;;;GAYG;AACH,wBAAsB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CAY5E"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAE3D;;;;GAIG;AACH,eAAO,MAAM,yBAAyB,uBAAuB,CAAC;AAE9D;;;;GAIG;AACH,eAAO,MAAM,iBAAiB;IAC5B;;;;;;OAMG;;IAGH;;;;OAIG;;QAGC,0EAA0E;;QAE1E;;;WAGG;;;;;;QAEH;;;;;;WAMG;;;IAKP;;;;;;OAMG;;QAGC;;;;;;;;;;;;;;WAcG;;;kBAIP,CAAC;AAEH,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAE5D,OAAO,QAAQ,yBAAyB,CAAC;IACvC,UAAU,WAAW;QACnB,KAAK,CAAC,EAAE,WAAW,CAAC;KACrB;CACF;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,oBAAoB,GAAG,WAAW,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC,CAAC;AAErE;;;;;;;;;;;;GAYG;AACH,wBAAsB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CAY5E"}

package/dist/dogwood/cli.d.ts

@@ -0,0 +1,247 @@
+/**
+ * The `dogwood` CLI adapter (#1659, epic #1646).
+ *
+ * The epic splits validation by what needs a binary. Everything answerable in
+ * TypeScript — the DWDC walls in `../lint/post-synth/dwdc0*.ts` — runs always
+ * and gates. Full `.dw` validation needs upstream's own frontend, which ships
+ * only as a Rust CLI: no npm package, no wasm build, nothing to link against.
+ * This module is the seam to it, and everything downstream of it treats the
+ * binary as optional.
+ *
+ * Five things about that CLI decide how this is written, all from the #1657
+ * verification report and re-read from the pinned `dogwood-cli/src` sources:
+ *
+ * 1. **Exit codes do not identify the failure.** Exit 2 is both "the policy
+ *    set was rejected" and clap's own usage error for an unknown flag, and the
+ *    published guide claims 1 for the latter. So nothing here branches on the
+ *    exit code: the JSON on stdout decides, and a run that produced no JSON is
+ *    {@link DogwoodUnusable} — reported as "the CLI could not be used", never
+ *    as "your policy is bad".
+ * 2. **There are two JSON shapes, not one.** A type-check finding comes back
+ *    in a `ValidateReport` (`{passed, passed_without_warnings, errors[],
+ *    warnings[]}`); a fatal parse, macro or lowering error replaces the whole
+ *    report with a bare `OpError` — the same diagnostic fields flattened at the
+ *    top level, plus `related[]`. {@link parseValidateOutput} handles both.
+ * 3. **`--format json` writes to stdout for both channels**, success and
+ *    fatal alike, and human-mode errors go to stderr. Every call here passes
+ *    `--format json` and reads stdout; stderr is kept only to explain an
+ *    unusable run.
+ * 4. **`--emit` is ignored under `--format json`** — the JSON always carries
+ *    all three lowered artifacts — so {@link runDogwoodLower} does not pass it.
+ * 5. **Label offsets are bytes into the source**, not line/column. They are
+ *    rendered as byte ranges. The fatal channel's own internal positions are
+ *    never passed through verbatim, for the same reason `wasm-helpers.ts`
+ *    strips cedar-wasm's `at line 1 column 42`: they locate something in a
+ *    representation the reader never saw.
+ *
+ * The runner is injectable ({@link configureDogwoodCli}) so the checks are
+ * testable without the binary. Nothing in gating CI executes it.
+ */
+/** The executable name looked up on `PATH`. */
+export declare const DOGWOOD_BINARY_NAME = "dogwood";
+/** Environment override, read before `PATH` and after an explicit config. */
+export declare const DOGWOOD_BINARY_ENV = "CHANT_DOGWOOD_BINARY";
+/** Where a resolved binary came from — carried so a finding can say. */
+export type DogwoodBinarySource = "override" | "env" | "config" | "path";
+/** A located `dogwood` executable. */
+export interface DogwoodBinary {
+    /** Absolute path, or the configured path as written. */
+    path: string;
+    source: DogwoodBinarySource;
+}
+/**
+ * One process run, reduced to what the adapter reads.
+ *
+ * `error` is set when the process never ran at all (ENOENT, a permission
+ * failure, a timeout) — distinct from a run that exited non-zero.
+ */
+export interface DogwoodRun {
+    status: number | null;
+    stdout: string;
+    stderr: string;
+    error?: string;
+}
+/** Runs `binary args…` and returns the captured streams. Injectable for tests. */
+export type DogwoodRunner = (binary: string, args: string[]) => DogwoodRun;
+interface CliDefaults {
+    /** A path forces that binary; `null` forces "absent"; `undefined` resolves normally. */
+    binary?: string | null;
+    runner?: DogwoodRunner;
+}
+/**
+ * Override binary resolution and the process runner.
+ *
+ * Two callers. Tests inject a runner so no gating check ever depends on a real
+ * binary — including on a developer's machine that happens to have one, which
+ * is why `binary: null` (force-absent) exists as well as `binary: "/path"`.
+ * The on-demand harness — the `forgejo-runtime-e2e` shape the epic names — is
+ * the other: it knows where it built the binary and says so directly rather
+ * than arranging `PATH`.
+ */
+export declare function configureDogwoodCli(options: CliDefaults): void;
+/** Drop every override, including any cached resolution. Test-only. */
+export declare function resetDogwoodCli(): void;
+/**
+ * Locate the `dogwood` binary, or `undefined` when there is none.
+ *
+ * Order: an explicit {@link configureDogwoodCli} override, `$CHANT_DOGWOOD_BINARY`,
+ * `cedar.dogwood.binary` from a `chant.config.json`, then `PATH`. A path from
+ * the environment or the config that is not executable is resolved past rather
+ * than returned to fail later; the advisory that follows names where chant
+ * looked. An explicit override is taken as given — its caller knows.
+ */
+export declare function findDogwoodBinary(cwd?: string): DogwoodBinary | undefined;
+/** Where chant looked, for an advisory that has to be actionable. */
+export declare const DOGWOOD_SEARCH_ORDER = "$CHANT_DOGWOOD_BINARY, then cedar.dogwood.binary in chant.config.json, then `dogwood` on PATH";
+/** One labelled span: byte offsets into the source the CLI was handed. */
+export interface DogwoodLabel {
+    start: number;
+    len: number;
+    message?: string;
+}
+/**
+ * One diagnostic, in upstream's `Diagnostic` shape.
+ *
+ * The same object is the element type of a report's `errors[]`/`warnings[]`
+ * and the whole body of a fatal `OpError`, which is why both channels
+ * normalize into this and nothing downstream has to know which arrived.
+ */
+export interface DogwoodDiagnostic {
+    /** `error`, `warning` or `advice` — upstream lowercases miette's severity. */
+    severity: string;
+    /** A stable code such as `extension` or `cedar`, when the finding has one. */
+    code?: string;
+    message: string;
+    labels: DogwoodLabel[];
+    help?: string;
+    /** False when the finding has no source-anchored span at all. */
+    spanned: boolean;
+}
+/**
+ * One diagnostic as a single line: code, message, help, then the byte ranges.
+ *
+ * Byte offsets rather than line/column because that is what upstream reports
+ * and converting them would mean re-deriving line breaks over a file this
+ * module does not hold — a wrong line number is worse than an honest offset.
+ */
+export declare function formatDogwoodDiagnostic(diagnostic: DogwoodDiagnostic): string;
+/**
+ * The CLI could not be used — a spawn failure, output that is not the JSON
+ * this adapter knows, or the exit-2 ambiguity resolving to neither shape.
+ *
+ * Deliberately its own arm and never folded into "rejected": exit 2 covers an
+ * unknown flag as well as a rejected policy set, so treating a bare non-zero
+ * exit as a policy verdict would fail a build over a flag rename in a sync
+ * upstream can make without notice.
+ */
+export interface DogwoodUnusable {
+    kind: "unusable";
+    reason: string;
+}
+/** A fatal parse, macro or lowering error — upstream's `OpError` channel. */
+export interface DogwoodFatal {
+    kind: "fatal";
+    error: DogwoodDiagnostic;
+    related: DogwoodDiagnostic[];
+}
+export type DogwoodValidateResult = {
+    kind: "passed";
+    warnings: DogwoodDiagnostic[];
+} | {
+    kind: "rejected";
+    errors: DogwoodDiagnostic[];
+    warnings: DogwoodDiagnostic[];
+} | DogwoodFatal | DogwoodUnusable;
+/** The `lower` artifacts. `cedarSchemaJson` is a JSON *string*, as upstream serializes it. */
+export interface DogwoodLowered {
+    cedarPolicies: string;
+    cedarSchema: string;
+    cedarSchemaJson: string;
+    /** False when temporal or provider fields were hoisted — the usual case. */
+    selfContained: boolean;
+    temporalFields: string[];
+    providerFields: string[];
+    decisionKinds: string[];
+}
+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;
+/**
+ * Read a `validate --format json` run.
+ *
+ * The JSON decides, not the exit code. A body carrying `passed` is the report
+ * shape; a body carrying `message` and no `passed` is the fatal `OpError`
+ * shape; anything else means the invocation itself was rejected — which is
+ * where clap's exit-2 usage error lands, with its complaint on stderr and
+ * nothing on stdout.
+ */
+export declare function parseValidateOutput(run: DogwoodRun): DogwoodValidateResult;
+/** Read a `lower --format json` run. Same two-shape discipline as validate. */
+export declare function parseLowerOutput(run: DogwoodRun): DogwoodLowerResult;
+/**
+ * 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 declare function parseReplayOutput(run: DogwoodRun): DogwoodReplayResult;
+/**
+ * The files one CLI invocation needs.
+ *
+ * `policies` and `policySchema` are both required — every pipeline command
+ * takes the policy set positionally and `--policy-schema` is not optional. The
+ * rest are the service half of the schema, each defaulting at the far end.
+ */
+export interface DogwoodBundle {
+    /** `.dw` policy set text. */
+    policies: string;
+    /** Cedar action schema text (`--policy-schema`). */
+    policySchema: string;
+    /** `.dwschema` event-schema text (`--event-schema`). */
+    eventSchema?: string;
+    /** `.dw` macro library text (`--macros`). */
+    macros?: string;
+    /** `providers.json` text (`--providers`). Rhai must be inlined under `implementation.script`. */
+    providers?: string;
+}
+/** Run `dogwood validate` over a bundle. Never throws. */
+export declare function runDogwoodValidate(binary: string, bundle: DogwoodBundle): DogwoodValidateResult;
+/** Run `dogwood lower` over a bundle. Never throws. */
+export declare function runDogwoodLower(binary: string, bundle: DogwoodBundle): DogwoodLowerResult;
+/**
+ * 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 declare function runDogwoodReplay(binary: string, bundle: DogwoodBundle, trace: string): DogwoodReplayResult;
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/dogwood/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../../src/dogwood/cli.ts"],"names":[],"mappings":"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"}

package/dist/dogwood/event-schema.d.ts

@@ -0,0 +1,161 @@
+/**
+ * Typed authoring for the `.dwschema` event-schema DSL.
+ *
+ * The `.dwschema`/`.cedarschema` question the epic flagged was a false alarm
+ * (#1657 §2): they are the two halves of one schema. The required half is the
+ * Cedar action schema (`--policy-schema`); this file is the optional half, the
+ * service side, which says what event *kinds* exist and what fields each one
+ * carries. Upstream's grammar is 136 lines of pest and is purely syntactic —
+ * it never consults an action schema, which is why every declaration is
+ * written against a symbolic action binder `<A>`:
+ *
+ * ```
+ * decision event <A>::request {
+ *     ...inputs(A),
+ *     pin callerPrincipal: principalType(A) = principal,
+ *     callerResource:      resourceType(A),
+ *     requestId:           String,
+ * }
+ * ```
+ *
+ * That symbolic binder is why DWDC010 can check an event *kind* against the
+ * emitted schema but not an action: the schema names no actions at all.
+ *
+ * ## The pin, and why opting out is explicit here
+ *
+ * `ServiceSchema::defaults()` — what runs when no `--event-schema` is passed —
+ * pins `callerPrincipal = principal` on every kind, so every temporal
+ * predicate is correlated to the current request's principal and events from
+ * other principals are invisible. Supplying *any* event schema opts out of the
+ * default wholesale, so a schema emitted without that pin silently widens
+ * every temporal predicate in the policy set to cross-principal.
+ *
+ * {@link defaultEventSchema} therefore carries the pin, and dropping it takes
+ * a named argument (`pinCallerPrincipal: false`) that also stamps a comment
+ * into the emitted file. DWDS010 reports the resulting schema either way, so
+ * the choice is visible in the build and not only in the source.
+ */
+import { type TemporalWindow, type WindowLike } from "./window.js";
+/** The four selectors that read from the bound action. */
+export type EventSelector = "inputs" | "outputs" | "principalType" | "resourceType";
+/** `principalType(A)`, a nested `{ … }` record, or a concrete Cedar type. */
+export type EventFieldType = {
+    readonly type: "selector";
+    readonly selector: EventSelector;
+} | {
+    readonly type: "record";
+    readonly fields: readonly EventField[];
+} | {
+    readonly type: "concrete";
+    readonly name: string;
+};
+/** `principalType(A)` — the action's principal entity type. */
+export declare function principalType(): EventFieldType;
+/** `resourceType(A)` — the action's resource entity type. */
+export declare function resourceType(): EventFieldType;
+/** `String`, `Long`, `MyApp::OAuthUser` — a concrete (possibly qualified) type. */
+export declare function concrete(name: string): EventFieldType;
+/** `{ … }` — the named field becomes a group addressed as `name.member`. */
+export declare function record(fields: EventField[]): EventFieldType;
+/**
+ * The right-hand side of a pin: the request-side value the field is forced to
+ * match. `principal`/`resource` (with an optional attribute tail) or a
+ * `context.<path>`.
+ */
+export type PinTarget = {
+    readonly ref: "principal" | "resource";
+    readonly attrs: readonly string[];
+} | {
+    readonly ref: "context";
+    readonly path: readonly string[];
+};
+/** `= principal`, or `= principal.dept`. */
+export declare function pinPrincipal(...attrs: string[]): PinTarget;
+/** `= resource`, or `= resource.owner`. */
+export declare function pinResource(...attrs: string[]): PinTarget;
+/** `= context.input.user`. At least one path segment; `context` alone is not a pin. */
+export declare function pinContext(path: string): PinTarget;
+/** `...inputs(A)` / `...outputs(A)` — splice every field the selector yields. */
+export interface SpreadField {
+    readonly field: "spread";
+    readonly selector: Extract<EventSelector, "inputs" | "outputs">;
+}
+/** `[pin] name: <type> [= <pin target>]`. */
+export interface NamedField {
+    readonly field: "named";
+    readonly name: string;
+    readonly type: EventFieldType;
+    readonly pin?: PinTarget;
+}
+/** One entry in an event declaration's field list. */
+export type EventField = SpreadField | NamedField;
+/** `...inputs(A)`. */
+export declare function spreadInputs(): SpreadField;
+/** `...outputs(A)`. */
+export declare function spreadOutputs(): SpreadField;
+/** `name: <type>` — an injected field with an explicit type. */
+export declare function field(name: string, type: EventFieldType): NamedField;
+/**
+ * `pin name: <type> = <target>` — a correlation against the decision request.
+ *
+ * Upstream requires the `pin` prefix and the `= …` clause together, and a
+ * pinned field must be a leaf (never a record type), so both are enforced here
+ * rather than deferred to the parser.
+ */
+export declare function pinnedField(name: string, type: EventFieldType, target: PinTarget): NamedField;
+/** `[decision] event <A>::kind { fields }`. */
+export interface EventDeclaration {
+    /** `request`, `response`, `error`, or anything the author chooses. */
+    readonly kind: string;
+    /** True for the kind that carries the authorization decision. */
+    readonly decision?: boolean;
+    readonly fields: readonly EventField[];
+    /** Emitted as `// …` above the declaration. */
+    readonly comment?: string;
+}
+/** One `event` declaration. */
+export declare function eventDeclaration(kind: string, fields: EventField[], options?: {
+    decision?: boolean;
+    comment?: string;
+}): EventDeclaration;
+/** A whole `.dwschema` file. */
+export interface EventSchema {
+    /** `max_window = 30d`. Omitted means upstream's 24h default applies. */
+    readonly maxWindow?: TemporalWindow;
+    /** The action binder name, `A` by convention. */
+    readonly binder: string;
+    readonly events: readonly EventDeclaration[];
+    /** Header comment lines, emitted above everything. */
+    readonly comment?: string;
+}
+/** Assemble a schema, defaulting the action binder to `A`. */
+export declare function eventSchema(events: EventDeclaration[], options?: {
+    maxWindow?: WindowLike;
+    binder?: string;
+    comment?: string;
+}): EventSchema;
+/**
+ * The default event-schema shape: `request` (deciding), `response` and `error`,
+ * each pinned to the request's principal.
+ *
+ * This reproduces `configuration/event-schemas/pinned.dwschema`, which is what
+ * `ServiceSchema::defaults()` uses. Emitting it explicitly is the honest thing
+ * to do the moment a project supplies *any* event schema, because supplying
+ * one opts out of the built-in default entirely.
+ *
+ * @param options.pinCallerPrincipal Drop the pin to allow cross-principal
+ * correlation. A deliberate choice: it widens every temporal predicate in the
+ * policy set, so it stamps a comment into the emitted file and DWDS010 reports
+ * it in the build.
+ */
+export declare function defaultEventSchema(options?: {
+    maxWindow?: WindowLike;
+    pinCallerPrincipal?: boolean;
+    principalField?: string;
+    binder?: string;
+}): EventSchema;
+/** Render a schema to `.dwschema` text. */
+export declare function renderEventSchema(schema: EventSchema): string;
+/** Every event kind a schema declares, in declaration order. */
+export declare function declaredEventKinds(schema: EventSchema): string[];
+//# sourceMappingURL=event-schema.d.ts.map

package/dist/dogwood/event-schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-schema.d.ts","sourceRoot":"","sources":["../../src/dogwood/event-schema.ts"],"names":[],"mappings":"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"}

package/dist/dogwood/index.d.ts

@@ -0,0 +1,39 @@
+/**
+ * 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 type { TemporalWindow, TimeUnit, WindowLike, WindowParam, 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 type { AndNode, ArrayTerm, CallNode, ComparisonNode, ComparisonOperator, CountTerm, ExistsNode, FormerlyNode, IntervalArg, MacroArg, NotNode, PredicateNode, PreviousNode, RawCondition, SigilCondition, SinceNode, SumTerm, TemporalCondition, TemporalTerm, TermInput, TermText, TpNode, TypedBinder, WindowArgument, } from "./temporal.js";
+export { DEFAULT_MACRO_NAMES, bind, countDistinctWithin, countWithin, defCedarMacro, defTemporalMacro, defaultMacroLibrary, macroCondition, macroTerm, macroWindow, renderMacroDefinition, renderMacroLibrary, sumWithin, } from "./macros.js";
+export type { MacroDefinition, MacroKind } 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 type { EventDeclaration, EventField, EventFieldType, EventSchema, EventSelector, NamedField, PinTarget, SpreadField, } 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 type { EventSchemaProps, MacroLibraryProps, TemporalPolicyProps } from "./policy.js";
+export { DOGWOOD_EVENT_SCHEMA_SUFFIX, DOGWOOD_POLICY_SUFFIX, dogwoodPolicyRecords, renderTemporalPolicyText, serializeDogwood, } from "./serialize.js";
+export type { DogwoodPolicyRecord, DogwoodSerializeResult } from "./serialize.js";
+export { blankComments, dogwoodPolicyFiles, dogwoodSchemaFiles, effectiveMaxWindowSeconds, readEventSchema, scanPredicates, scanWindowlessOperators, scanWindows, temporalRegions, } from "./scan.js";
+export type { DogwoodArtifact, EventSchemaFacts, TemporalPredicateRef, WindowRef } 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";
+export type { DogwoodBinary, DogwoodBinarySource, DogwoodBundle, DogwoodDiagnostic, DogwoodFatal, DogwoodLabel, DogwoodLowerResult, DogwoodLowered, DogwoodReplayResult, DogwoodRun, DogwoodRunner, DogwoodUnusable, DogwoodValidateResult, DogwoodVerdict, } from "./cli.js";
+export { auditTrace, decimalValue, entityRef, rawValue, renderTrace, renderTraceFields, renderTraceLine, renderTraceValue, traceEntity, traceEvent, traceFixture, } from "./trace.js";
+export type { TraceAuditOptions, TraceBags, TraceDecimal, TraceEntityDecl, TraceEntityRef, TraceEvent, TraceEventInput, TraceFields, TraceFixture, TraceFixtureOptions, TraceIssue, TraceIssueKind, TraceRaw, TraceScope, TraceTagged, TraceValue, } from "./trace.js";
+export { compareVerdicts, dogwoodReplay, dogwoodReplayReport, renderReplaySummary, resolveReplayInputs, } from "./replay-activity.js";
+export type { DogwoodReplayArgs, DogwoodReplayReportArgs, ExpectedVerdict, PolicyReplayDispatch, PolicyReplayMode, PolicyReplayReport, ReplayDivergence, ReplayExpectation, } from "./replay-activity.js";
+export { DEFAULT_REPLAY_REPORT_PATH, PolicyReplayOp, dogwoodReplayReportStep, dogwoodReplayStep, } from "./replay-op.js";
+export type { DogwoodReplayReportStepOpts, DogwoodReplayStepOpts, PolicyReplayOpConfig, PolicyReplayOpResources, } from "./replay-op.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/dogwood/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/dogwood/index.ts"],"names":[],"mappings":"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"}

package/dist/dogwood/macros.d.ts

@@ -0,0 +1,96 @@
+/**
+ * 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 { type CallNode, type SigilCondition, type TemporalCondition, type TemporalTerm, type TermText } from "./temporal.js";
+import { type WindowLike, type WindowParam } from "./window.js";
+/** Which sub-parser reads the body: Cedar's, or the temporal sub-language's. */
+export type MacroKind = "cedar" | "temporal";
+/** One `def <kind> <name>(<params>) { <body> };` declaration. */
+export interface MacroDefinition {
+    readonly kind: MacroKind;
+    readonly name: string;
+    /** Parameter names, each carrying the `?` sigil. */
+    readonly params: readonly string[];
+    /** Rendered body text. */
+    readonly body: string;
+    /** Emitted as `// …` lines above the definition. */
+    readonly comment?: string;
+}
+/**
+ * `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 declare function defTemporalMacro(name: string, params: string[], body: TemporalCondition | TemporalTerm, comment?: string): MacroDefinition;
+/**
+ * `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 declare function defCedarMacro(name: string, params: string[], body: string, comment?: string): MacroDefinition;
+/**
+ * `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 declare function macroWindow(param: string): WindowParam;
+/** `?s` standing for an entire condition, spliced from the call site. */
+export declare function macroCondition(param: string): SigilCondition;
+/** `?a` / `$t` in term or binder position. */
+export declare function macroTerm(sigil: string): TermText;
+/** One definition as `.dw` source. */
+export declare function renderMacroDefinition(def: MacroDefinition): string;
+/** A whole library — the file `--macros` points at, or a policy set's own prelude. */
+export declare function renderMacroLibrary(defs: readonly MacroDefinition[]): string;
+/** The macro names `configuration/default_macros.dw` ships at the pinned revision. */
+export declare const DEFAULT_MACRO_NAMES: readonly ["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 declare function countWithin(w: WindowLike, condition: TemporalCondition): CallNode;
+/** `sum_within(?a, ?w, ?body)` — `over` names the sum's bound variable. */
+export declare function sumWithin(over: string, w: WindowLike, body: TemporalCondition): CallNode;
+/** `count_distinct_within(?k, ?w, ?s)` — distinct String keys `k` for which `s` held. */
+export declare function countDistinctWithin(key: string, w: WindowLike, condition: TemporalCondition): CallNode;
+/** `bind(?n, ?A, ?B)` — names an aggregate result so it can be compared. */
+export declare function bind(name: string, aggregate: TemporalCondition, body: TemporalCondition): CallNode;
+/**
+ * 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 declare function defaultMacroLibrary(): MacroDefinition[];
+//# sourceMappingURL=macros.d.ts.map

package/dist/dogwood/macros.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"macros.d.ts","sourceRoot":"","sources":["../../src/dogwood/macros.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,EAOL,KAAK,QAAQ,EACb,KAAK,cAAc,EACnB,KAAK,iBAAiB,EACtB,KAAK,YAAY,EACjB,KAAK,QAAQ,EACd,MAAM,YAAY,CAAC;AACpB,OAAO,EAAe,KAAK,UAAU,EAAE,KAAK,WAAW,EAAE,MAAM,UAAU,CAAC;AAM1E,gFAAgF;AAChF,MAAM,MAAM,SAAS,GAAG,OAAO,GAAG,UAAU,CAAC;AAE7C,iEAAiE;AACjE,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,oDAAoD;IACpD,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,0BAA0B;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,oDAAoD;IACpD,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC3B;AAgBD;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,EAAE,EAChB,IAAI,EAAE,iBAAiB,GAAG,YAAY,EACtC,OAAO,CAAC,EAAE,MAAM,GACf,eAAe,CAQjB;AAMD;;;;;GAKG;AACH,wBAAgB,aAAa,CAC3B,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,EAAE,EAChB,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE,MAAM,GACf,eAAe,CAEjB;AAID;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,WAAW,CAEtD;AAED,yEAAyE;AACzE,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,cAAc,CAG5D;AAED,8CAA8C;AAC9C,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,QAAQ,CAKjD;AAED,sCAAsC;AACtC,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,eAAe,GAAG,MAAM,CASlE;AAED,sFAAsF;AACtF,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,SAAS,eAAe,EAAE,GAAG,MAAM,CAE3E;AAID,sFAAsF;AACtF,eAAO,MAAM,mBAAmB,0EAA2E,CAAC;AAE5G;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,UAAU,EAAE,SAAS,EAAE,iBAAiB,GAAG,QAAQ,CAEjF;AAED,2EAA2E;AAC3E,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,CAAC,EAAE,UAAU,EAAE,IAAI,EAAE,iBAAiB,GAAG,QAAQ,CAExF;AAED,yFAAyF;AACzF,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,EAAE,CAAC,EAAE,UAAU,EAAE,SAAS,EAAE,iBAAiB,GAAG,QAAQ,CAEtG;AAED,4EAA4E;AAC5E,wBAAgB,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,iBAAiB,EAAE,IAAI,EAAE,iBAAiB,GAAG,QAAQ,CAElG;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,IAAI,eAAe,EAAE,CA+BvD"}