@intentius/chant-lexicon-cedar 0.124.31 → 0.124.32

package/dist/dogwood/cli.js

@@ -0,0 +1,477 @@
+/**
+ * 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.
+ */
+import { spawnSync } from "child_process";
+import { accessSync, constants, existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "fs";
+import { tmpdir } from "os";
+import { delimiter, dirname, isAbsolute, join, resolve } from "path";
+// ── Locating the binary ───────────────────────────────────────────
+/** The executable name looked up on `PATH`. */
+export const DOGWOOD_BINARY_NAME = "dogwood";
+/** Environment override, read before `PATH` and after an explicit config. */
+export const DOGWOOD_BINARY_ENV = "CHANT_DOGWOOD_BINARY";
+let defaults = {};
+/**
+ * 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 function configureDogwoodCli(options) {
+    defaults = { ...defaults, ...options };
+}
+/** Drop every override, including any cached resolution. Test-only. */
+export function resetDogwoodCli() {
+    defaults = {};
+    cachedConfigBinary = undefined;
+}
+let cachedConfigBinary;
+/**
+ * `cedar.dogwood.binary` out of a `chant.config.json`, walking up from `dir`.
+ *
+ * JSON only, and that is a real limitation rather than an oversight. A
+ * `PostSynthCheck.check()` is synchronous — see `@intentius/chant/lint/post-synth`
+ * — while `loadChantConfigUpward` is async and, under `chant build --sandbox`,
+ * evaluates `chant.config.ts` in a child process. Neither is available from
+ * inside a check. `chant.config.json` is data, not code (core says so in
+ * `loadChantConfig`'s own doc), so reading it here executes nothing. A project
+ * on `chant.config.ts` sets {@link DOGWOOD_BINARY_ENV} or calls
+ * {@link configureDogwoodCli} instead.
+ */
+function configuredBinary(startDir) {
+    if (cachedConfigBinary && cachedConfigBinary.dir === startDir)
+        return cachedConfigBinary.value;
+    let value;
+    let dir = startDir;
+    for (;;) {
+        const path = join(dir, "chant.config.json");
+        if (existsSync(path)) {
+            try {
+                const parsed = JSON.parse(readFileSync(path, "utf-8"));
+                const binary = readPath(parsed, ["cedar", "dogwood", "binary"]);
+                if (typeof binary === "string" && binary.length > 0) {
+                    value = isAbsolute(binary) ? binary : resolve(dir, binary);
+                    break;
+                }
+            }
+            catch {
+                // An unreadable or malformed config is every other command's error to
+                // report first; a missing dogwood binary is not the place to raise it.
+            }
+        }
+        const parent = dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    cachedConfigBinary = { dir: startDir, value };
+    return value;
+}
+function readPath(value, path) {
+    let current = value;
+    for (const key of path) {
+        if (typeof current !== "object" || current === null)
+            return undefined;
+        current = current[key];
+    }
+    return current;
+}
+function executable(path) {
+    try {
+        accessSync(path, constants.X_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** The first `dogwood` on `PATH`, by an access check rather than by running it. */
+function onPath(name) {
+    for (const entry of (process.env.PATH ?? "").split(delimiter)) {
+        if (!entry)
+            continue;
+        const candidate = join(entry, name);
+        if (executable(candidate))
+            return candidate;
+    }
+    return undefined;
+}
+/**
+ * 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 function findDogwoodBinary(cwd = process.cwd()) {
+    if (defaults.binary === null)
+        return undefined;
+    if (typeof defaults.binary === "string")
+        return { path: defaults.binary, source: "override" };
+    const fromEnv = process.env[DOGWOOD_BINARY_ENV];
+    if (fromEnv && executable(fromEnv))
+        return { path: fromEnv, source: "env" };
+    const fromConfig = configuredBinary(cwd);
+    if (fromConfig && executable(fromConfig))
+        return { path: fromConfig, source: "config" };
+    const found = onPath(DOGWOOD_BINARY_NAME);
+    return found ? { path: found, source: "path" } : undefined;
+}
+/** Where chant looked, for an advisory that has to be actionable. */
+export const DOGWOOD_SEARCH_ORDER = `$${DOGWOOD_BINARY_ENV}, then cedar.dogwood.binary in chant.config.json, then \`${DOGWOOD_BINARY_NAME}\` on PATH`;
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+ * Strip an internal `at line N column M` tail.
+ *
+ * Same reasoning as `wasm-helpers.ts`'s `call()`: a position that indexes a
+ * representation the reader never saw is worse than no position, because it
+ * looks like it points at their policy. The byte-offset labels are the
+ * positions this module does surface, and those genuinely index the `.dw`
+ * source chant wrote.
+ */
+function scrubPosition(message) {
+    return message.replace(/\s+at line \d+ column \d+\.?$/, "");
+}
+function parseDiagnostic(value) {
+    if (!isRecord(value) || typeof value.message !== "string")
+        return undefined;
+    const labels = [];
+    if (Array.isArray(value.labels)) {
+        for (const raw of value.labels) {
+            if (!isRecord(raw) || typeof raw.start !== "number" || typeof raw.len !== "number")
+                continue;
+            labels.push({
+                start: raw.start,
+                len: raw.len,
+                ...(typeof raw.message === "string" ? { message: raw.message } : {}),
+            });
+        }
+    }
+    return {
+        severity: typeof value.severity === "string" ? value.severity : "error",
+        ...(typeof value.code === "string" ? { code: value.code } : {}),
+        message: scrubPosition(value.message),
+        labels,
+        ...(typeof value.help === "string" ? { help: value.help } : {}),
+        spanned: value.spanned === true || labels.length > 0,
+    };
+}
+function parseDiagnostics(value) {
+    if (!Array.isArray(value))
+        return [];
+    const out = [];
+    for (const entry of value) {
+        const parsed = parseDiagnostic(entry);
+        if (parsed)
+            out.push(parsed);
+    }
+    return out;
+}
+/**
+ * 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 function formatDogwoodDiagnostic(diagnostic) {
+    const parts = [];
+    if (diagnostic.code)
+        parts.push(`[${diagnostic.code}]`);
+    parts.push(diagnostic.message);
+    if (diagnostic.help)
+        parts.push(`(${diagnostic.help})`);
+    if (diagnostic.labels.length > 0) {
+        const spans = diagnostic.labels
+            .map((l) => {
+            const range = `bytes ${l.start}-${l.start + l.len}`;
+            return l.message ? `${range}: ${l.message}` : range;
+        })
+            .join("; ");
+        parts.push(`at ${spans}`);
+    }
+    return parts.join(" ");
+}
+function unusable(reason) {
+    return { kind: "unusable", reason };
+}
+/** A short, single-line tail of whatever the process said, for an unusable run. */
+function streamNote(run) {
+    const text = (run.stderr || run.stdout).trim().split("\n").slice(0, 2).join(" ").trim();
+    const clipped = text.length > 200 ? `${text.slice(0, 200)}…` : text;
+    return clipped ? `: ${clipped}` : "";
+}
+function fatalFrom(parsed) {
+    const error = parseDiagnostic(parsed);
+    if (!error)
+        return undefined;
+    return { kind: "fatal", error, related: parseDiagnostics(parsed.related) };
+}
+/**
+ * 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 function parseValidateOutput(run) {
+    if (run.error)
+        return unusable(`the dogwood binary could not be run: ${run.error}`);
+    const parsed = readJson(run.stdout);
+    if (!parsed) {
+        return unusable(`\`dogwood validate --format json\` exited ${String(run.status)} without a JSON report on stdout, which is how an unknown flag or a rejected invocation surfaces${streamNote(run)}`);
+    }
+    if (typeof parsed.passed === "boolean") {
+        const errors = parseDiagnostics(parsed.errors);
+        const warnings = parseDiagnostics(parsed.warnings);
+        // The report wins over the exit code in both directions: a `passed: false`
+        // with a zero exit is still a rejection, and the reverse is still a pass.
+        if (parsed.passed && errors.length === 0)
+            return { kind: "passed", warnings };
+        return { kind: "rejected", errors, warnings };
+    }
+    const fatal = fatalFrom(parsed);
+    if (fatal)
+        return fatal;
+    return unusable(`\`dogwood validate --format json\` returned JSON in neither the report nor the error shape`);
+}
+/** Read a `lower --format json` run. Same two-shape discipline as validate. */
+export function parseLowerOutput(run) {
+    if (run.error)
+        return unusable(`the dogwood binary could not be run: ${run.error}`);
+    const parsed = readJson(run.stdout);
+    if (!parsed) {
+        return unusable(`\`dogwood lower --format json\` exited ${String(run.status)} without JSON on stdout${streamNote(run)}`);
+    }
+    if (typeof parsed.cedar_policies === "string" && typeof parsed.cedar_schema === "string") {
+        return {
+            kind: "lowered",
+            value: {
+                cedarPolicies: parsed.cedar_policies,
+                cedarSchema: parsed.cedar_schema,
+                cedarSchemaJson: typeof parsed.cedar_schema_json === "string" ? parsed.cedar_schema_json : "",
+                selfContained: parsed.self_contained === true,
+                temporalFields: stringList(parsed.temporal_fields),
+                providerFields: stringList(parsed.provider_fields),
+                decisionKinds: stringList(parsed.decision_kinds),
+            },
+        };
+    }
+    const fatal = fatalFrom(parsed);
+    if (fatal)
+        return fatal;
+    return unusable("`dogwood lower --format json` returned JSON in neither the artifact nor the error shape");
+}
+/**
+ * Read a `replay --format json` run.
+ *
+ * The one place the exit-code discipline matters most: **replay exits 0 even
+ * when every verdict is DENY.** A nonzero exit means the trace or the policy
+ * set failed to load, never that a policy denied — so a caller that read the
+ * exit code as a verdict would report a working deny-by-default policy set as
+ * a broken one. As everywhere else in this module, the JSON decides: a body
+ * carrying `verdicts` is the report, a body carrying `message` is the fatal
+ * `OpError` (a malformed trace line lands here), anything else is unusable.
+ */
+export function parseReplayOutput(run) {
+    if (run.error)
+        return unusable(`the dogwood binary could not be run: ${run.error}`);
+    const parsed = readJson(run.stdout);
+    if (!parsed) {
+        return unusable(`\`dogwood replay --format json\` exited ${String(run.status)} without JSON on stdout${streamNote(run)}`);
+    }
+    if (Array.isArray(parsed.verdicts)) {
+        return { kind: "replayed", verdicts: parseVerdicts(parsed.verdicts) };
+    }
+    const fatal = fatalFrom(parsed);
+    if (fatal)
+        return fatal;
+    return unusable("`dogwood replay --format json` returned JSON in neither the verdict nor the error shape");
+}
+function parseVerdicts(value) {
+    const out = [];
+    value.forEach((raw, position) => {
+        if (!isRecord(raw))
+            return;
+        // `allow`/`deny` lowercase, as upstream serializes the enum. Anything else
+        // is read as a deny rather than dropped: an unrecognised verdict is not a
+        // permission, and dropping the entry would shift every later index.
+        const verdict = raw.verdict === "allow" ? "allow" : "deny";
+        out.push({
+            index: typeof raw.index === "number" ? raw.index : position,
+            timestamp: typeof raw.timestamp === "number" ? raw.timestamp : 0,
+            verdict,
+            determiningRules: Array.isArray(raw.determining_rules)
+                ? raw.determining_rules.filter((r) => typeof r === "number")
+                : [],
+            errors: errorList(raw.errors),
+        });
+    });
+    return out;
+}
+/** Per-evaluation errors, tolerating both a string list and a diagnostic list. */
+function errorList(value) {
+    if (!Array.isArray(value))
+        return [];
+    const out = [];
+    for (const entry of value) {
+        if (typeof entry === "string")
+            out.push(entry);
+        else if (isRecord(entry) && typeof entry.message === "string")
+            out.push(scrubPosition(entry.message));
+    }
+    return out;
+}
+function stringList(value) {
+    return Array.isArray(value) ? value.filter((v) => typeof v === "string") : [];
+}
+function readJson(text) {
+    const trimmed = text.trim();
+    if (!trimmed)
+        return undefined;
+    try {
+        const parsed = JSON.parse(trimmed);
+        return isRecord(parsed) ? parsed : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+const defaultRunner = (binary, args) => {
+    const result = spawnSync(binary, args, {
+        encoding: "utf-8",
+        timeout: 60000,
+        maxBuffer: 32 * 1024 * 1024,
+    });
+    return {
+        status: result.status,
+        stdout: result.stdout ?? "",
+        stderr: result.stderr ?? "",
+        ...(result.error ? { error: result.error.message } : {}),
+    };
+};
+/**
+ * Materialize a bundle into a scratch directory and run one subcommand.
+ *
+ * Files rather than stdin because only the policy set can come from `-`; the
+ * schema flags all take paths. The directory is removed in a `finally`, so a
+ * throwing runner does not leave one behind.
+ */
+function runBundle(binary, subcommand, bundle, extras = []) {
+    const runner = defaults.runner ?? defaultRunner;
+    const dir = mkdtempSync(join(tmpdir(), "chant-dogwood-"));
+    try {
+        const policies = join(dir, "policies.dw");
+        const policySchema = join(dir, "schema.cedarschema");
+        writeFileSync(policies, bundle.policies, "utf-8");
+        writeFileSync(policySchema, bundle.policySchema, "utf-8");
+        const args = [subcommand, policies, "--policy-schema", policySchema];
+        if (bundle.eventSchema !== undefined) {
+            const path = join(dir, "events.dwschema");
+            writeFileSync(path, bundle.eventSchema, "utf-8");
+            args.push("--event-schema", path);
+        }
+        if (bundle.macros !== undefined) {
+            const path = join(dir, "macros.dw");
+            writeFileSync(path, bundle.macros, "utf-8");
+            args.push("--macros", path);
+        }
+        if (bundle.providers !== undefined) {
+            const path = join(dir, "providers.json");
+            writeFileSync(path, bundle.providers, "utf-8");
+            args.push("--providers", path);
+        }
+        for (const extra of extras) {
+            const path = join(dir, extra.filename);
+            writeFileSync(path, extra.content, "utf-8");
+            args.push(extra.flag, path);
+        }
+        // No `--emit`: it is ignored under `--format json`, which returns all three
+        // lowered artifacts regardless. Passing it would imply a choice that the
+        // CLI does not honour.
+        args.push("--format", "json");
+        return runner(binary, args);
+    }
+    finally {
+        rmSync(dir, { recursive: true, force: true });
+    }
+}
+/** Run `dogwood validate` over a bundle. Never throws. */
+export function runDogwoodValidate(binary, bundle) {
+    try {
+        return parseValidateOutput(runBundle(binary, "validate", bundle));
+    }
+    catch (err) {
+        return unusable(`the dogwood validate run failed: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+/** Run `dogwood lower` over a bundle. Never throws. */
+export function runDogwoodLower(binary, bundle) {
+    try {
+        return parseLowerOutput(runBundle(binary, "lower", bundle));
+    }
+    catch (err) {
+        return unusable(`the dogwood lower run failed: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+/**
+ * Run `dogwood replay` over a bundle and a trace. Never throws.
+ *
+ * The trace is materialized beside the bundle's own files and passed as
+ * `--trace`; the same scratch directory is removed in the same `finally`, so a
+ * trace carrying a session's request payloads does not outlive the run.
+ */
+export function runDogwoodReplay(binary, bundle, trace) {
+    try {
+        return parseReplayOutput(runBundle(binary, "replay", bundle, [{ flag: "--trace", filename: "trace.log", content: trace }]));
+    }
+    catch (err) {
+        return unusable(`the dogwood replay run failed: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}

package/dist/dogwood/event-schema.js

@@ -0,0 +1,219 @@
+/**
+ * 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 { renderWindow, window } from "./window.js";
+const IDENT = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const TYPE_NAME = /^[A-Za-z_][A-Za-z0-9_]*(::[A-Za-z_][A-Za-z0-9_]*)*$/;
+function assertIdent(value, what) {
+    if (!IDENT.test(value))
+        throw new Error(`dogwood: ${what} must be an identifier — got "${value}"`);
+    return value;
+}
+/** `principalType(A)` — the action's principal entity type. */
+export function principalType() {
+    return { type: "selector", selector: "principalType" };
+}
+/** `resourceType(A)` — the action's resource entity type. */
+export function resourceType() {
+    return { type: "selector", selector: "resourceType" };
+}
+/** `String`, `Long`, `MyApp::OAuthUser` — a concrete (possibly qualified) type. */
+export function concrete(name) {
+    if (!TYPE_NAME.test(name))
+        throw new Error(`dogwood: a field type must be a Cedar type name — got "${name}"`);
+    return { type: "concrete", name };
+}
+/** `{ … }` — the named field becomes a group addressed as `name.member`. */
+export function record(fields) {
+    return { type: "record", fields };
+}
+/** `= principal`, or `= principal.dept`. */
+export function pinPrincipal(...attrs) {
+    for (const a of attrs)
+        assertIdent(a, "a pin attribute");
+    return { ref: "principal", attrs };
+}
+/** `= resource`, or `= resource.owner`. */
+export function pinResource(...attrs) {
+    for (const a of attrs)
+        assertIdent(a, "a pin attribute");
+    return { ref: "resource", attrs };
+}
+/** `= context.input.user`. At least one path segment; `context` alone is not a pin. */
+export function pinContext(path) {
+    const segments = path.split(".");
+    if (segments.length === 0 || segments[0] === "") {
+        throw new Error("dogwood: a context pin needs at least one path segment (context.<field>)");
+    }
+    for (const s of segments)
+        assertIdent(s, "a context pin segment");
+    return { ref: "context", path: segments };
+}
+/** `...inputs(A)`. */
+export function spreadInputs() {
+    return { field: "spread", selector: "inputs" };
+}
+/** `...outputs(A)`. */
+export function spreadOutputs() {
+    return { field: "spread", selector: "outputs" };
+}
+/** `name: <type>` — an injected field with an explicit type. */
+export function field(name, type) {
+    return { field: "named", name: assertIdent(name, "a field name"), type };
+}
+/**
+ * `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 function pinnedField(name, type, target) {
+    if (type.type === "record") {
+        throw new Error(`dogwood: a pinned field must be a leaf, and "${name}" is a record type`);
+    }
+    return { field: "named", name: assertIdent(name, "a field name"), type, pin: target };
+}
+/** One `event` declaration. */
+export function eventDeclaration(kind, fields, options = {}) {
+    return { kind: assertIdent(kind, "an event kind"), fields, decision: options.decision, comment: options.comment };
+}
+/** Assemble a schema, defaulting the action binder to `A`. */
+export function eventSchema(events, options = {}) {
+    if (events.length === 0)
+        throw new Error("dogwood: an event schema declares at least one event kind");
+    const kinds = new Set();
+    for (const e of events) {
+        if (kinds.has(e.kind))
+            throw new Error(`dogwood: event kind "${e.kind}" is declared twice`);
+        kinds.add(e.kind);
+    }
+    return {
+        maxWindow: options.maxWindow === undefined ? undefined : window(options.maxWindow),
+        binder: assertIdent(options.binder ?? "A", "an action binder"),
+        events,
+        comment: options.comment,
+    };
+}
+/**
+ * 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 function defaultEventSchema(options = {}) {
+    const pinned = options.pinCallerPrincipal !== false;
+    const principalField = options.principalField ?? "callerPrincipal";
+    const common = () => [
+        pinned
+            ? pinnedField(principalField, principalType(), pinPrincipal())
+            : field(principalField, principalType()),
+        field("callerResource", resourceType()),
+        field("requestId", concrete("String")),
+        field("sessionId", concrete("String")),
+    ];
+    return eventSchema([
+        eventDeclaration("request", [spreadInputs(), ...common()], { decision: true }),
+        eventDeclaration("response", [spreadInputs(), spreadOutputs(), ...common()]),
+        eventDeclaration("error", [spreadInputs(), ...common()]),
+    ], {
+        maxWindow: options.maxWindow,
+        binder: options.binder,
+        comment: pinned
+            ? "The default event-schema shape: request/response/error, each correlated to\nthe deciding request's principal."
+            : `Cross-principal: ${principalField} is NOT pinned, so temporal predicates see\nevents from every principal, not only the deciding request's. This widens\nevery predicate in the policy set and is a deliberate departure from\nupstream's default (see ServiceSchema::defaults).`,
+    });
+}
+// ── Rendering ─────────────────────────────────────────────────────
+function renderPinTarget(target) {
+    return target.ref === "context" ? `context.${target.path.join(".")}` : [target.ref, ...target.attrs].join(".");
+}
+function renderFieldType(type, binder, indent) {
+    switch (type.type) {
+        case "selector":
+            return `${type.selector}(${binder})`;
+        case "concrete":
+            return type.name;
+        case "record":
+            return `{\n${renderFields(type.fields, binder, indent + "    ")}\n${indent}}`;
+    }
+}
+function renderFields(fields, binder, indent) {
+    return fields
+        .map((f) => {
+        if (f.field === "spread")
+            return `${indent}...${f.selector}(${binder}),`;
+        const pin = f.pin ? ` = ${renderPinTarget(f.pin)}` : "";
+        return `${indent}${f.pin ? "pin " : ""}${f.name}: ${renderFieldType(f.type, binder, indent)}${pin},`;
+    })
+        .join("\n");
+}
+function renderComment(comment) {
+    return comment.split("\n").map((line) => `// ${line}`.trimEnd());
+}
+/** Render a schema to `.dwschema` text. */
+export function renderEventSchema(schema) {
+    const lines = [];
+    if (schema.comment)
+        lines.push(...renderComment(schema.comment), "");
+    if (schema.maxWindow) {
+        lines.push(`max_window = ${renderWindow(schema.maxWindow)}`, "");
+    }
+    for (const [index, event] of schema.events.entries()) {
+        if (index > 0)
+            lines.push("");
+        if (event.comment)
+            lines.push(...renderComment(event.comment));
+        lines.push(`${event.decision ? "decision " : ""}event <${schema.binder}>::${event.kind} {`);
+        if (event.fields.length > 0)
+            lines.push(renderFields(event.fields, schema.binder, "    "));
+        lines.push("}");
+    }
+    return lines.join("\n") + "\n";
+}
+/** Every event kind a schema declares, in declaration order. */
+export function declaredEventKinds(schema) {
+    return schema.events.map((e) => e.kind);
+}