@intentius/chant 0.124.13 → 0.124.14

package/dist/pseudo-parameter.js

@@ -0,0 +1,40 @@
+/**
+ * Generic pseudo-parameter class for lexicon-provided global named references.
+ *
+ * AWS uses "AWS::StackName", Terraform has "path.module", Azure has
+ * "subscription().id" — every format needs the same class that serializes
+ * to a Ref-like structure and has the INTRINSIC_MARKER.
+ */
+var _a;
+import { INTRINSIC_MARKER } from "./intrinsic.js";
+export class PseudoParameter {
+    constructor(refName) {
+        this[_a] = true;
+        this.refName = refName;
+    }
+    toJSON() {
+        return { Ref: this.refName };
+    }
+    toString() {
+        return `\${${this.refName}}`;
+    }
+}
+_a = INTRINSIC_MARKER;
+/**
+ * Create a namespace of pseudo-parameters from a name map.
+ *
+ * @example
+ * ```ts
+ * export const { StackName, Region } = createPseudoParameters({
+ *   StackName: "AWS::StackName",
+ *   Region: "AWS::Region",
+ * });
+ * ```
+ */
+export function createPseudoParameters(nameMap) {
+    const result = {};
+    for (const [key, refName] of Object.entries(nameMap)) {
+        result[key] = new PseudoParameter(refName);
+    }
+    return result;
+}

package/dist/reconcile.js

@@ -0,0 +1,450 @@
+/**
+ * Provider-agnostic reconcile primitive.
+ *
+ * The reusable machinery behind a declarative reconcile loop, with NO knowledge
+ * of any specific provider (GitHub, GitLab, a cloud, …): the change-set model,
+ * the generic collection diff (selective-by-omission + ownership-gated deletes),
+ * the plan renderer, and the guardrail framework (rename resolution + a removal
+ * cap + a pluggable check runner).
+ *
+ * A consumer application (e.g. github-warden) builds its provider-specific resource diffing,
+ * live-state types, and domain guardrails on top of this, and drives them with
+ * the generic `runReconcile` loop + `Cycle` interface (below). It complements
+ * chant's `ownership.ts` marker contract: ownership markers make a `delete`
+ * precise; this module decides *which* entries are creates / updates / deletes
+ * in the first place.
+ *
+ * Consumed as `@intentius/chant/reconcile`. The diff and guardrail primitives
+ * are pure and clock-free; `runReconcile` is the orchestration loop and is the
+ * only part that drives I/O (through the provider's `Cycle` implementations).
+ */
+import { GOVERNANCE_VERBS } from "./governance.js";
+// ---------------------------------------------------------------------------
+// Generic field/value diffing
+// ---------------------------------------------------------------------------
+/** Deep value equality via JSON for plain data (config/live snapshots). */
+export function deepEqual(a, b) {
+    if (a === b)
+        return true;
+    if (a === null || b === null)
+        return false;
+    if (typeof a !== "object" || typeof b !== "object")
+        return false;
+    return JSON.stringify(a) === JSON.stringify(b);
+}
+/**
+ * Diff fields of `desired` against `live`, returning one `FieldChange` per
+ * differing field. When `keys` is given, only those keys are compared (and only
+ * when present in `desired`); otherwise every key in `desired` is compared.
+ * Selective-by-omission: keys absent from `desired` are never compared.
+ */
+export function diffFields(desired, live, keys) {
+    const fields = [];
+    const compareKeys = keys ?? Object.keys(desired);
+    for (const key of compareKeys) {
+        if (keys && !Object.prototype.hasOwnProperty.call(desired, key))
+            continue;
+        const dv = desired[key];
+        const lv = live[key];
+        if (!deepEqual(dv, lv))
+            fields.push({ field: key, before: lv, after: dv });
+    }
+    return fields;
+}
+/**
+ * The generic managed-collection diff: creates for desired-not-live, updates
+ * when `compareFields` reports differences, and ownership-gated deletes for
+ * live-not-desired. This is the selective-by-omission + ownership-gated-delete
+ * pattern shared by every keyed-collection diff.
+ *
+ * Returns the live entry count for this collection, so the diff layer can sum
+ * `ChangeSet.managedCount` across the collections it diffs (#2067).
+ */
+export function diffCollection(params) {
+    const { resourceType, keyPrefix = "", desired, live, compareFields, createAfter, updateAfter, opts, out, } = params;
+    for (const [key, d] of desired) {
+        const entryKey = `${keyPrefix}${key}`;
+        const l = live.get(key);
+        if (l === undefined) {
+            out.push({
+                kind: "create",
+                resourceType,
+                key: entryKey,
+                after: createAfter ? createAfter(key, d) : d,
+            });
+            continue;
+        }
+        const fields = compareFields(d, l);
+        if (fields.length > 0) {
+            out.push({
+                kind: "update",
+                resourceType,
+                key: entryKey,
+                before: l,
+                after: updateAfter ? updateAfter(key, d, l) : d,
+                fields,
+            });
+        }
+    }
+    for (const [key, l] of live) {
+        if (desired.has(key))
+            continue;
+        const entryKey = `${keyPrefix}${key}`;
+        if (opts.isOwned?.(resourceType, entryKey)) {
+            out.push({ kind: "delete", resourceType, key: entryKey, before: l });
+        }
+    }
+    return live.size;
+}
+// ---------------------------------------------------------------------------
+// Summary / rendering
+// ---------------------------------------------------------------------------
+/** Count entries per change kind. */
+export function summarizeChangeSet(cs) {
+    const counts = { create: 0, update: 0, delete: 0 };
+    for (const e of cs.entries)
+        counts[e.kind]++;
+    return counts;
+}
+/** Human-readable plan summary for dry-run output. Pure. */
+export function renderChangeSet(cs) {
+    const counts = summarizeChangeSet(cs);
+    const header = `Plan for ${cs.org}: ${counts.create} to create, ${counts.update} to update, ${counts.delete} to delete`;
+    if (cs.entries.length === 0)
+        return `${header}\nNo changes.`;
+    const lines = [header];
+    const byKind = { create: [], update: [], delete: [] };
+    for (const e of cs.entries)
+        byKind[e.kind].push(e);
+    const ORDER = ["create", "update", "delete"];
+    for (const kind of ORDER) {
+        let group = byKind[kind];
+        if (group.length === 0)
+            continue;
+        // Verb-aware grouping: when entries carry governance verbs, order
+        // each section by verb (vocabulary order, unverbed entries last) so mixed
+        // plans read category-by-category. Stable, and line format is unchanged —
+        // a verbless change set renders exactly as before.
+        if (group.some((e) => e.verb)) {
+            const rank = (e) => e.verb ? GOVERNANCE_VERBS.indexOf(e.verb) : GOVERNANCE_VERBS.length;
+            group = [...group].sort((a, b) => rank(a) - rank(b));
+        }
+        lines.push(`\n${kind.toUpperCase()}:`);
+        for (const e of group) {
+            lines.push(`  [${e.resourceType}] ${e.key}`);
+            for (const f of e.fields ?? []) {
+                lines.push(`    ${f.field}: ${fmt(f.before)} → ${fmt(f.after)}`);
+            }
+        }
+    }
+    return lines.join("\n");
+}
+function fmt(v) {
+    if (v === undefined)
+        return "<unset>";
+    if (typeof v === "string")
+        return v.length > 60 ? `${v.slice(0, 57)}...` : v;
+    const json = JSON.stringify(v);
+    return json.length > 60 ? `${json.slice(0, 57)}...` : json;
+}
+/**
+ * Resolve rename aliases. A create entry carrying a `previously` key matching a
+ * delete entry's key OF THE SAME RESOURCE TYPE is collapsed into an update,
+ * removing the delete. Matching across resource types would let e.g. a team
+ * create with `previously: "old"` swallow an unrelated member delete keyed
+ * "old", hiding a real delete from guardrail counting. Returns a new ChangeSet
+ * with renames resolved. Provider-agnostic — works on any entry whose
+ * `after.previously` is a string.
+ */
+export function resolveRenames(changeSet) {
+    // Keys and resource types are both free-form strings, so scope the lookup
+    // with an unambiguous composite key ("\u0000" cannot appear in either).
+    const typedKey = (resourceType, key) => `${resourceType}\u0000${key}`;
+    const deleteEntries = new Map();
+    for (const e of changeSet.entries) {
+        if (e.kind === "delete")
+            deleteEntries.set(typedKey(e.resourceType, e.key), e);
+    }
+    const resolvedDeletes = new Set();
+    const resolvedCreates = new Set();
+    const syntheticUpdates = [];
+    for (const e of changeSet.entries) {
+        if (e.kind !== "create")
+            continue;
+        const after = e.after;
+        if (!after)
+            continue;
+        const previously = after["previously"];
+        if (typeof previously !== "string")
+            continue;
+        const deleted = deleteEntries.get(typedKey(e.resourceType, previously));
+        if (!deleted)
+            continue;
+        resolvedDeletes.add(typedKey(e.resourceType, previously));
+        resolvedCreates.add(typedKey(e.resourceType, e.key));
+        syntheticUpdates.push({
+            kind: "update",
+            resourceType: e.resourceType,
+            key: e.key,
+            before: deleted.before,
+            after: e.after,
+            fields: [{ field: "key", before: previously, after: e.key }],
+        });
+    }
+    if (resolvedDeletes.size === 0)
+        return changeSet;
+    const filteredEntries = changeSet.entries.filter((e) => !(e.kind === "delete" && resolvedDeletes.has(typedKey(e.resourceType, e.key))) &&
+        !(e.kind === "create" && resolvedCreates.has(typedKey(e.resourceType, e.key))));
+    return { ...changeSet, entries: [...filteredEntries, ...syntheticUpdates] };
+}
+/**
+ * Refuse if deletes exceed `maxFraction` of the pre-existing managed entries
+ * (deletes + updates; creates excluded so a flood of new entries can't dilute
+ * the delete fraction). Guards against a typo wiping the config in one apply.
+ *
+ * With per-type live counts (`opts.managedTotals`, else
+ * `changeSet.managedCounts`) the cap is evaluated PER RESOURCE TYPE: for each
+ * type with deletes, that type's deletes divide by that type's live count when
+ * present and positive, else by that type's own plan non-creates. Any type
+ * over `maxFraction` blocks, and the diagnostic names the worst offender. The
+ * pooled denominator this replaces was unsafe — live entries of one type
+ * (team members, repos) diluted a wipe of another (teams, org secrets) below
+ * the cap.
+ *
+ * With only a pooled live denominator (`opts.managedTotal`, else
+ * `changeSet.managedCount`; #2067) deletes are measured against the pooled
+ * live entries under management — so a converged cycle's plan of exactly one
+ * stale delete does not trip at 1/1 = 100%. Without either, behavior is
+ * plan-relative as before.
+ *
+ * Throws on a `maxFraction` outside (0,1] (NaN included) — fail closed, never
+ * silently disable the cap.
+ *
+ * CONTRACT: pass a RENAME-RESOLVED change set (see {@link resolveRenames}).
+ */
+export function removalDeltaCap(changeSet, opts = {}) {
+    const maxFraction = opts.maxFraction ?? 0.25;
+    if (!(maxFraction > 0 && maxFraction <= 1)) {
+        // The negated form catches NaN too. A bad cap must never pass silently:
+        // maxFraction: 5 would otherwise wave every wipe through.
+        throw new Error(`removalDeltaCap: maxFraction must be in (0, 1], got ${String(maxFraction)}`);
+    }
+    const managedTotals = opts.managedTotals ?? changeSet.managedCounts;
+    if (managedTotals !== undefined) {
+        return removalDeltaCapPerType(changeSet, managedTotals, maxFraction);
+    }
+    const deletes = changeSet.entries.filter((e) => e.kind === "delete").length;
+    const managedTotal = opts.managedTotal ?? changeSet.managedCount;
+    if (managedTotal !== undefined && managedTotal > 0) {
+        const fraction = deletes / managedTotal;
+        if (fraction > maxFraction) {
+            return {
+                guardrail: "removalDeltaCap",
+                message: `${deletes} of ${managedTotal} live managed entries (${Math.round(fraction * 100)}%) would be deleted, ` +
+                    `exceeding the ${Math.round(maxFraction * 100)}% threshold. ` +
+                    `Check for typos in config or raise maxFraction to proceed.`,
+            };
+        }
+        return null;
+    }
+    const total = changeSet.entries.filter((e) => e.kind !== "create").length;
+    if (total === 0)
+        return null;
+    const fraction = deletes / total;
+    if (fraction > maxFraction) {
+        return {
+            guardrail: "removalDeltaCap",
+            message: `${deletes} of ${total} managed entries (${Math.round(fraction * 100)}%) would be deleted, ` +
+                `exceeding the ${Math.round(maxFraction * 100)}% threshold. ` +
+                `Check for typos in config or raise maxFraction to proceed.`,
+        };
+    }
+    return null;
+}
+/**
+ * Per-resource-type evaluation for {@link removalDeltaCap}. Each type with
+ * deletes gets its own denominator: the type's live count from `managedTotals`
+ * when present and positive, else that type's plan non-creates (the same
+ * plan-relative rule as the typeless cap, scoped to the type). Blocks when ANY
+ * type exceeds `maxFraction`; the message leads with the worst offender and
+ * lists the rest.
+ */
+function removalDeltaCapPerType(changeSet, managedTotals, maxFraction) {
+    const deletesByType = new Map();
+    const nonCreatesByType = new Map();
+    for (const e of changeSet.entries) {
+        if (e.kind === "create")
+            continue;
+        nonCreatesByType.set(e.resourceType, (nonCreatesByType.get(e.resourceType) ?? 0) + 1);
+        if (e.kind === "delete") {
+            deletesByType.set(e.resourceType, (deletesByType.get(e.resourceType) ?? 0) + 1);
+        }
+    }
+    const tripping = [];
+    for (const [resourceType, deletes] of deletesByType) {
+        const liveCount = managedTotals[resourceType];
+        // A zero (or negative) live count means "no live info for this type",
+        // never a looser or divide-by-zero cap — same rule as the pooled total.
+        const live = liveCount !== undefined && liveCount > 0;
+        const total = live ? liveCount : nonCreatesByType.get(resourceType);
+        const fraction = deletes / total;
+        if (fraction > maxFraction)
+            tripping.push({ resourceType, deletes, total, fraction, live });
+    }
+    if (tripping.length === 0)
+        return null;
+    // Worst offender first; deterministic tie-break by delete count then name.
+    tripping.sort((a, b) => b.fraction - a.fraction ||
+        b.deletes - a.deletes ||
+        a.resourceType.localeCompare(b.resourceType));
+    const [worst, ...rest] = tripping;
+    const pct = (f) => Math.round(f * 100);
+    const describe = (t) => `${t.deletes} of ${t.total} ${t.live ? "live" : "planned"} ${t.resourceType} entries (${pct(t.fraction)}%)`;
+    return {
+        guardrail: "removalDeltaCap",
+        message: `${describe(worst)} would be deleted, exceeding the ${pct(maxFraction)}% threshold. ` +
+            (rest.length > 0 ? `Also over the cap: ${rest.map(describe).join(", ")}. ` : "") +
+            `Check for typos in config or raise maxFraction to proceed.`,
+    };
+}
+/**
+ * Run a set of guardrail checks against a change set. Resolves renames ONCE,
+ * then runs every check on the resolved set, aggregating any diagnostics. The
+ * caller composes provider-specific checks (e.g. an admin floor) as closures.
+ * `ctx` (optional, #2067) threads live context — e.g. the managed-live count —
+ * to every check; single-argument checks ignore it.
+ */
+export function runGuardrailChecks(changeSet, checks, ctx) {
+    const resolved = resolveRenames(changeSet);
+    const diagnostics = [];
+    for (const check of checks) {
+        const d = check(resolved, ctx);
+        if (d)
+            diagnostics.push(d);
+    }
+    return diagnostics.length > 0 ? { ok: false, diagnostics } : { ok: true };
+}
+/** Thrown when a cycle or apply step attempts to use an exhausted budget. */
+export class BudgetExhaustedError extends Error {
+    constructor(message = "rate budget exhausted") {
+        super(message);
+        this.name = "BudgetExhaustedError";
+    }
+}
+class MutableRateBudget {
+    constructor(initial) {
+        this._remaining = initial;
+    }
+    get remaining() {
+        return this._remaining;
+    }
+    get exhausted() {
+        return this._remaining <= 0;
+    }
+    use(n = 1) {
+        if (this.exhausted)
+            throw new BudgetExhaustedError();
+        this._remaining = Math.max(0, this._remaining - n);
+    }
+}
+function errMsg(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+/**
+ * Run the reconcile loop. For each scope in `scopes` and each cycle:
+ *   1. fetchLive  2. buildDesired  3. diff  4. guardrails
+ *   5a. dry-run: record the plan  5b. apply: apply each entry (if guardrails pass)
+ *
+ * Budget-aware (stops cleanly + records deferred work on exhaustion) and
+ * fault-tolerant (a cycle that errors is recorded and the run continues).
+ * Returns a structured `ReconcileResult`.
+ */
+export async function runReconcile(opts) {
+    const { scopes, client, cycles, scope, mode = "dry-run", diff: diffFn, guardrails = () => ({ ok: true }), diffOptions = {}, allowGuardrailOverride = false, requestBudget = 1000, } = opts;
+    const budget = new MutableRateBudget(requestBudget);
+    const cycleResults = [];
+    const erroredCycles = [];
+    const deferred = { skippedCycles: [], skippedEntries: [] };
+    const scopeEntries = Object.entries(scopes);
+    for (const cycle of cycles) {
+        for (const [scopeId, scopeConfig] of scopeEntries) {
+            if (budget.exhausted) {
+                deferred.skippedCycles.push(`${cycle.name}@${scopeId}`);
+                continue;
+            }
+            let live;
+            try {
+                live = await cycle.fetchLive(client, scopeId, scope, budget);
+            }
+            catch (err) {
+                if (err instanceof BudgetExhaustedError) {
+                    deferred.skippedCycles.push(`${cycle.name}@${scopeId}`);
+                    continue;
+                }
+                erroredCycles.push({ name: cycle.name, org: scopeId, stage: "fetchLive", error: errMsg(err) });
+                continue;
+            }
+            let desired;
+            try {
+                desired = cycle.buildDesired(scopeConfig, scopeId, scope);
+            }
+            catch (err) {
+                erroredCycles.push({ name: cycle.name, org: scopeId, stage: "buildDesired", error: errMsg(err) });
+                continue;
+            }
+            const changeSet = diffFn(scopeId, desired, live, diffOptions);
+            // Stamp the cycle's governance verb onto entries that don't
+            // carry one, so provider diffs stay verb-unaware.
+            if (cycle.verb) {
+                for (const e of changeSet.entries)
+                    e.verb ?? (e.verb = cycle.verb);
+            }
+            const guardrailResult = guardrails(changeSet, live);
+            const counts = { create: 0, update: 0, delete: 0 };
+            for (const e of changeSet.entries)
+                counts[e.kind]++;
+            const cycleResult = {
+                name: cycle.name,
+                verb: cycle.verb,
+                org: scopeId,
+                counts,
+                guardrails: guardrailResult,
+                applied: [],
+                failed: [],
+                plan: renderChangeSet(changeSet),
+                guardrailBlocked: false,
+            };
+            if (mode === "dry-run") {
+                cycleResults.push(cycleResult);
+                continue;
+            }
+            if (!guardrailResult.ok && !allowGuardrailOverride) {
+                cycleResult.guardrailBlocked = true;
+                cycleResults.push(cycleResult);
+                continue;
+            }
+            for (const entry of changeSet.entries) {
+                if (budget.exhausted) {
+                    deferred.skippedEntries.push({ cycleName: cycle.name, entry });
+                    continue;
+                }
+                try {
+                    await cycle.apply(client, entry, scopeId, scope, budget);
+                    cycleResult.applied.push(entry);
+                }
+                catch (err) {
+                    if (err instanceof BudgetExhaustedError) {
+                        deferred.skippedEntries.push({ cycleName: cycle.name, entry });
+                        continue;
+                    }
+                    cycleResult.failed.push({ entry, error: errMsg(err) });
+                }
+            }
+            cycleResults.push(cycleResult);
+        }
+    }
+    const completed = deferred.skippedCycles.length === 0 &&
+        deferred.skippedEntries.length === 0 &&
+        erroredCycles.length === 0;
+    return { mode, completed, cycles: cycleResults, errored: erroredCycles, deferred, budgetRemaining: budget.remaining };
+}

package/dist/resource-attributes.js

@@ -0,0 +1,33 @@
+/**
+ * Utilities for resolving resource-level attributes (DependsOn, Condition, etc.).
+ *
+ * Shared by lexicon serializers — the DependsOn resolution logic converts
+ * Declarable object references to logical names.
+ */
+/**
+ * Resolve a DependsOn value (Declarable, string, or mixed array) into
+ * an array of logical resource names.
+ *
+ * - Strings pass through as-is (user-specified logical names)
+ * - Declarable objects are looked up in the entityNames map
+ * - Unknown values emit a console warning and are skipped
+ */
+export function resolveDependsOn(deps, entityNames, resourceName) {
+    const items = Array.isArray(deps) ? deps : [deps];
+    const resolved = [];
+    for (const dep of items) {
+        if (typeof dep === "string") {
+            resolved.push(dep);
+        }
+        else if (typeof dep === "object" && dep !== null && "entityType" in dep) {
+            const depName = entityNames.get(dep);
+            if (depName) {
+                resolved.push(depName);
+            }
+            else {
+                console.warn(`[chant] warning: DependsOn in "${resourceName}" references a declarable not found in the build — is the target resource exported?`);
+            }
+        }
+    }
+    return resolved;
+}

package/dist/runtime-adapter.js

@@ -0,0 +1,77 @@
+/**
+ * Runtime adapter — abstracts child-process and filesystem APIs for chant.
+ *
+ * The `target` parameter (from config) controls what commands get spawned
+ * (node/npx/npm), not which adapter class is used.
+ */
+import { dirname } from "path";
+import { fileURLToPath } from "url";
+import { createHash } from "crypto";
+import { execFile } from "child_process";
+// @ts-ignore — picomatch has no types declaration
+import picomatch from "picomatch";
+// ── Node adapter ─────────────────────────────────────────────────
+class NodeRuntimeAdapter {
+    constructor() {
+        this.name = "node";
+        this.hashAlgorithm = "sha256";
+        this.commands = { runner: "node", exec: "npx", packCmd: ["npm", "pack"] };
+    }
+    hash(content) {
+        return createHash("sha256").update(content).digest("hex");
+    }
+    globMatch(pattern, filePath) {
+        return picomatch(pattern)(filePath);
+    }
+    async spawn(cmd, opts) {
+        return new Promise((resolve) => {
+            const child = execFile(cmd[0], cmd.slice(1), {
+                cwd: opts?.cwd,
+                maxBuffer: 10 * 1024 * 1024,
+                ...(opts?.env ? { env: { ...process.env, ...opts.env } } : {}),
+            }, (err, stdout, stderr) => {
+                resolve({
+                    stdout: stdout ?? "",
+                    stderr: stderr ?? "",
+                    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                    exitCode: err ? err.code ?? 1 : 0,
+                });
+            });
+            // Content is written verbatim (utf-8) — no shell involved, so nothing
+            // reinterprets backslash-escape sequences or needs quote-escaping.
+            // The error handler is load-bearing: a child that exits without reading
+            // stdin (any command that ignores it) makes this write race the pipe
+            // teardown, and an unhandled EPIPE 'error' event crashes the process.
+            if (child.stdin) {
+                child.stdin.on("error", () => {
+                    /* EPIPE: child exited without consuming stdin — harmless */
+                });
+                child.stdin.end(opts?.stdin ?? "");
+            }
+        });
+    }
+}
+// ── Singleton ────────────────────────────────────────────────────
+let _runtime;
+/**
+ * Initialize the runtime adapter singleton.
+ */
+export function initRuntime() {
+    _runtime = new NodeRuntimeAdapter();
+    return _runtime;
+}
+/**
+ * Get the runtime adapter. Lazily initializes if not yet set.
+ */
+export function getRuntime() {
+    if (!_runtime) {
+        return initRuntime();
+    }
+    return _runtime;
+}
+/**
+ * Convert `import.meta.url` to a directory path.
+ */
+export function moduleDir(importMetaUrl) {
+    return dirname(fileURLToPath(importMetaUrl));
+}

package/dist/runtime.js

@@ -0,0 +1,66 @@
+/**
+ * Runtime factory constructors for generated resource and property classes.
+ *
+ * Creates classes that implement the Declarable interface with DECLARABLE_MARKER,
+ * lexicon, entityType, kind, and attribute references.
+ */
+import { DECLARABLE_MARKER } from "./declarable.js";
+import { AttrRef } from "./attrref.js";
+/**
+ * Create a resource class for a given type.
+ * The returned constructor creates Declarable objects with:
+ * - DECLARABLE_MARKER for type identification
+ * - lexicon identifier
+ * - entityType set to the resource type
+ * - kind "resource"
+ * - props stored from constructor argument
+ * - AttrRef instances for each attribute
+ */
+export function createResource(type, lexicon, attrMap) {
+    const ResourceClass = function (props, attributes) {
+        Object.defineProperty(this, DECLARABLE_MARKER, { value: true, enumerable: false });
+        Object.defineProperty(this, "lexicon", { value: lexicon, enumerable: false });
+        Object.defineProperty(this, "entityType", { value: type, enumerable: false });
+        Object.defineProperty(this, "kind", { value: "resource", enumerable: false });
+        Object.defineProperty(this, "props", { value: props ?? {}, enumerable: false, configurable: true });
+        Object.defineProperty(this, "attributes", { value: attributes ?? {}, enumerable: false, configurable: true });
+        // Ref returns the resource instance itself — the serializer walker
+        // detects Declarable objects and emits { Ref: logicalName }
+        Object.defineProperty(this, "Ref", { value: this, enumerable: false });
+        // Create AttrRef instances for each attribute
+        // Must be enumerable so getAttributes() can discover them for resolveAttrRefs()
+        for (const [camelName, attrName] of Object.entries(attrMap)) {
+            Object.defineProperty(this, camelName, {
+                value: new AttrRef(this, attrName),
+                enumerable: true,
+                writable: false,
+            });
+        }
+    };
+    // Set the constructor name for debugging
+    Object.defineProperty(ResourceClass, "name", { value: type.split("::").pop() ?? type });
+    return ResourceClass;
+}
+/**
+ * Create a property-kind class for a given property type.
+ *
+ * Instances carry DECLARABLE_MARKER/lexicon/entityType/kind at runtime (set
+ * via defineProperty below), so they already satisfy `Declarable` — the
+ * return type just needs to say so. Before this, the signature was
+ * `Record<string, unknown>` with no `Declarable`, so any composite that
+ * returned a property-kind instance as a top-level member only type-checked
+ * by accident: either the caller went through an untyped `require()` (losing
+ * the type entirely) or never assigned the instance where its `Declarable`-ness
+ * was checked statically. See chant #1068.
+ */
+export function createProperty(type, lexicon) {
+    const PropertyClass = function (props) {
+        Object.defineProperty(this, DECLARABLE_MARKER, { value: true, enumerable: false });
+        Object.defineProperty(this, "lexicon", { value: lexicon, enumerable: false });
+        Object.defineProperty(this, "entityType", { value: type, enumerable: false });
+        Object.defineProperty(this, "kind", { value: "property", enumerable: false });
+        Object.defineProperty(this, "props", { value: props ?? {}, enumerable: false, configurable: true });
+    };
+    Object.defineProperty(PropertyClass, "name", { value: type.split(".").pop() ?? type });
+    return PropertyClass;
+}