@aventara/core 1.0.0-rc.0 → 1.0.0-rc.10

package/dist/policy/policy-write.runtime.js

@@ -0,0 +1,532 @@
+import { adapterPrimaryIdentifier } from "../adapters/adapter-identifier.js";
+import { lookupField, lookupResource } from "../contracts/contract-lookup.js";
+import { uniqueMissFailure } from "../runtime/outcome-mapper.js";
+import { frozenCopy } from "../runtime/readonly-value.js";
+import { policyRefusal } from "./policy-admission.js";
+import { afterCheckFields, afterUpdate, beforeFields, beforeUnreadable, checkChanged, coveredBefore, rowsBefore, unchangedSince, } from "./policy-after-update.runtime.js";
+import { allOf, everyOf, noneOf, someOf, whereOf, } from "./policy-condition.js";
+import { planNestedWrites, writesNested, } from "./policy-nested-write.runtime.js";
+import { enforceReadPolicy, identifiedRows, returnedRowChecks, } from "./policy-read.runtime.js";
+import { heldReferences, } from "./policy-reference-write.runtime.js";
+function heldUnchanged(core, model, resource, checks, run, before) {
+    if (!checks.before || before.length === 0) {
+        return run;
+    }
+    const condition = unchangedSince(core, model, resource, before);
+    if (typeof condition === "boolean") {
+        return run;
+    }
+    const args = isRecord(run.arguments) ? run.arguments : {};
+    const where = isRecord(args.where) ? args.where : {};
+    const and = where.AND === undefined
+        ? []
+        : Array.isArray(where.AND)
+            ? where.AND
+            : [where.AND];
+    return {
+        ...run,
+        arguments: { ...args, where: { ...where, AND: [...and, condition] } },
+    };
+}
+function whereOfRun(run) {
+    const where = isRecord(run.arguments) ? run.arguments.where : undefined;
+    return isRecord(where) ? where : true;
+}
+function fewerChanged(resource, checks, before, changed) {
+    return checks.before && changed < before.rows.length
+        ? policyRefusal(`The policy checks this update on Resource "${resource}" against the rows as they were before it, and ${before.rows.length - changed} of the ${before.rows.length} rows it read changed before it ran (a concurrent write), so it was not applied.`)
+        : undefined;
+}
+const UNVERIFIABLE = "cannot be verified on this database: it has no interactive transaction to roll the write back in";
+function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function refused(message) {
+    return { kind: "refused", response: policyRefusal(message) };
+}
+function rowOf(core, resource, record) {
+    const owner = lookupResource(core, resource);
+    const row = {};
+    if (isRecord(record)) {
+        for (const [field, value] of Object.entries(record)) {
+            if (value !== undefined &&
+                lookupField(owner, field)?.kind !== "relation") {
+                row[field] = value;
+            }
+        }
+    }
+    return frozenCopy(row);
+}
+function rowsOf(data) {
+    if (Array.isArray(data)) {
+        return data.filter(isRecord);
+    }
+    return isRecord(data) ? [data] : [];
+}
+function offers(core, resource, family, variant) {
+    const operations = lookupResource(core, resource)?.operations;
+    return operations?.[family]?.[variant] !== undefined;
+}
+function missOf(session, request, selector) {
+    return async () => {
+        const read = await session.scope(request.resource, "read");
+        const reach = allOf(isRecord(selector) ? selector : true, read);
+        if (reach !== false &&
+            (await session.renewed().exists(request.resource, whereOf(reach)))) {
+            return policyRefusal(`The policy does not allow ${request.family} on this row of Resource "${request.resource}".`);
+        }
+        return (uniqueMissFailure(request, null) ??
+            policyRefusal(`The policy does not allow ${request.family} on this row of Resource "${request.resource}".`));
+    };
+}
+async function checkCreated(session, core, model, resource, grants, created) {
+    if (created.length === 0) {
+        return undefined;
+    }
+    const these = identifiedRows(core, adapterPrimaryIdentifier(model, resource), resource, created);
+    const missed = allOf(these, someOf([...grants.values()].map(noneOf)));
+    if (missed !== false &&
+        (await session.renewed().exists(resource, whereOf(missed)))) {
+        return policyRefusal(`The policy does not allow writing ${fieldNames(grants)} of Resource "${resource}" on the row this request creates.`);
+    }
+    return undefined;
+}
+function fieldNames(grants) {
+    return [...grants.keys()].map((field) => `"${field}"`).join(", ");
+}
+function uncheckableCreate(model, request, grants, inTransaction) {
+    if (grants.size === 0) {
+        return undefined;
+    }
+    const what = `The policy allows writing ${fieldNames(grants)} of Resource "${request.resource}" on some rows only, and checks the row this request creates against them after the insert`;
+    if (!inTransaction) {
+        return refused(`${what}, which ${UNVERIFIABLE}.`);
+    }
+    if (request.variant === "count" ||
+        adapterPrimaryIdentifier(model, request.resource).length === 0) {
+        return refused(`${what}, and this create does not return the rows it creates to check by.`);
+    }
+    return undefined;
+}
+function unverifiable(read, request, inTransaction) {
+    if (inTransaction || read.kind !== "run") {
+        return undefined;
+    }
+    const rootChecked = request.family !== "delete" && read.checks.root.length > 0;
+    return rootChecked || read.checks.nested
+        ? refused(`The policy checks the rows this ${request.family} on Resource "${request.resource}" returns after it runs, which ${UNVERIFIABLE}. Select fewer fields or relations, or read them in a request of their own.`)
+        : undefined;
+}
+async function nestedWritesOf(session, core, model, request, record, parent, inTransaction) {
+    if (!isRecord(record) || !writesNested(core, request.resource, record)) {
+        return undefined;
+    }
+    if (!inTransaction) {
+        return {
+            kind: "refused",
+            response: policyRefusal(`The policy checks the nested writes of this ${request.family} on Resource "${request.resource}" inside its transaction, which ${UNVERIFIABLE}. Write the related rows in their own operations.`),
+        };
+    }
+    return planNestedWrites(session, core, model, request.resource, record, parent);
+}
+function withNestedWrites(run, key, nested) {
+    const runArguments = isRecord(run.arguments) ? run.arguments : {};
+    const narrowed = runArguments[key] === nested.record
+        ? run
+        : { ...run, arguments: { ...runArguments, [key]: nested.record } };
+    return withChangedRows(narrowed, (data) => nested.after(rowsOf(data)));
+}
+function linkRefused(held) {
+    if (held?.kind !== "held" || !held.linked) {
+        return undefined;
+    }
+    return async (error) => isRecord(error) && error.code === "A4002"
+        ? policyRefusal("The policy does not allow this write to link a row outside what the caller may read.")
+        : undefined;
+}
+function withHeldReferences(run, held, keys) {
+    if (!held.linked) {
+        return run;
+    }
+    const runArguments = isRecord(run.arguments) ? run.arguments : {};
+    const linked = { ...runArguments };
+    for (const [key, stage] of keys) {
+        if (Object.hasOwn(runArguments, key)) {
+            linked[key] = held.apply(runArguments[key], stage);
+        }
+    }
+    return { ...run, arguments: linked };
+}
+function countOf(run) {
+    return {
+        ...run,
+        settle: async (data) => {
+            const settled = await run.settle(data);
+            return settled.ok ? { ok: true, data: rowsOf(data).length } : settled;
+        },
+    };
+}
+function withoutCarried(run, asked, carried) {
+    if (carried === undefined || !Array.isArray(asked.select)) {
+        return run;
+    }
+    const kept = asked.select;
+    const dropped = carried.filter((field) => !kept.includes(field));
+    if (dropped.length === 0) {
+        return run;
+    }
+    const trimmed = (row) => {
+        if (!isRecord(row)) {
+            return row;
+        }
+        const answer = {};
+        for (const key of Object.keys(row)) {
+            if (!dropped.includes(key)) {
+                answer[key] = row[key];
+            }
+        }
+        return answer;
+    };
+    return {
+        ...run,
+        settle: async (data) => {
+            const settled = await run.settle(data);
+            if (!settled.ok) {
+                return settled;
+            }
+            return {
+                ok: true,
+                data: Array.isArray(settled.data)
+                    ? settled.data.map(trimmed)
+                    : trimmed(settled.data),
+            };
+        },
+    };
+}
+function withChangedRows(read, check) {
+    return {
+        ...read,
+        settle: async (data) => {
+            const settled = await read.settle(data);
+            if (!settled.ok) {
+                return settled;
+            }
+            const response = await check(data);
+            return response === undefined ? settled : { ok: false, response };
+        },
+    };
+}
+export async function writeNeedsTransaction(session, core, request, planned, adapterArguments) {
+    switch (request.family) {
+        case "find":
+            return false;
+        case "update":
+        case "upsert":
+            return true;
+        case "create": {
+            const args = isRecord(adapterArguments) ? adapterArguments : {};
+            if (session.createGrants().size > 0 ||
+                (isRecord(args.data) && writesNested(core, request.resource, args.data))) {
+                return true;
+            }
+            break;
+        }
+        case "delete":
+            break;
+    }
+    const plan = planned();
+    const checks = await returnedRowChecks(session, core, plan);
+    return [...checks.keys()].some((level) => level !== plan.projection || request.family !== "delete");
+}
+export async function enforceWritePolicy(session, core, model, request, plan, adapterArguments, inTransaction) {
+    const args = isRecord(adapterArguments) ? adapterArguments : {};
+    switch (request.family) {
+        case "create":
+            return enforceCreate(session, core, model, request, plan, adapterArguments, args, inTransaction);
+        case "update":
+        case "delete":
+            return enforceScopedWrite(session, core, model, request, plan, adapterArguments, args, inTransaction);
+        case "upsert":
+            return enforceUpsert(session, core, model, request, plan, adapterArguments, args, inTransaction);
+        case "find":
+            return enforceReadPolicy(session, core, model, request, plan, adapterArguments);
+    }
+}
+async function enforceCreate(session, core, model, request, plan, adapterArguments, args, inTransaction) {
+    const resource = request.resource;
+    const records = Array.isArray(args.data) ? args.data : [args.data];
+    const nested = await nestedWritesOf(session, core, model, request, args.data, { kind: "new" }, inTransaction);
+    if (nested?.kind === "refused") {
+        return nested;
+    }
+    if (nested === undefined) {
+        const answers = await Promise.all(records
+            .filter(isRecord)
+            .map((record) => session.can(resource, "create", rowOf(core, resource, record))));
+        if (answers.includes(false)) {
+            return refused(`The policy does not allow creating this row of Resource "${resource}".`);
+        }
+    }
+    const grants = session.createGrants();
+    const uncheckable = uncheckableCreate(model, request, grants, inTransaction);
+    if (uncheckable !== undefined) {
+        return uncheckable;
+    }
+    const held = await heldReferences(session, core, model, request, [
+        { stage: "create", records },
+    ]);
+    if (held.kind === "refused") {
+        return held;
+    }
+    const read = await enforceReadPolicy(session, core, model, request, plan, adapterArguments, { scope: undefined, identified: grants.size > 0 || nested !== undefined });
+    const blocked = unverifiable(read, request, inTransaction);
+    if (blocked !== undefined || read.kind !== "run") {
+        return blocked ?? read;
+    }
+    let run = read;
+    if (grants.size > 0) {
+        run = withChangedRows(run, (data) => checkCreated(session, core, model, resource, grants, rowsOf(data)));
+    }
+    if (nested !== undefined) {
+        run = withNestedWrites(run, "data", nested);
+    }
+    run = withHeldReferences(run, held, [["data", "create"]]);
+    const failed = linkRefused(held);
+    return failed === undefined ? run : { ...run, failed };
+}
+async function enforceScopedWrite(session, core, model, request, plan, adapterArguments, args, inTransaction) {
+    const resource = request.resource;
+    const action = request.family === "delete" ? "delete" : "update";
+    const scope = allOf(await session.scope(resource, action), await session.scope(resource, "read"));
+    const changes = action === "update"
+        ? await afterUpdate(session, core, model, resource, args.data, inTransaction)
+        : undefined;
+    if (changes !== undefined && !inTransaction) {
+        return refused(`The policy checks this update on Resource "${resource}" after it runs (${changes.after ? "its grant's after condition" : "whether it moves a row out of what the caller may read"}), which ${UNVERIFIABLE}.`);
+    }
+    if (changes !== undefined &&
+        adapterPrimaryIdentifier(model, resource).length === 0) {
+        return refused(`The policy checks this update on Resource "${resource}" after it runs, and the Resource has no identifier to find the changed rows by.`);
+    }
+    const unreadable = beforeUnreadable(core, resource, changes);
+    if (unreadable !== undefined) {
+        return { kind: "refused", response: unreadable };
+    }
+    const held = action === "update"
+        ? await heldReferences(session, core, model, request, [
+            { stage: "update", records: [args.data] },
+        ])
+        : undefined;
+    if (held?.kind === "refused") {
+        return held;
+    }
+    const nested = action === "update"
+        ? await nestedWritesOf(session, core, model, request, args.data, {
+            kind: "existing",
+            reach: allOf(isRecord(args.where) ? args.where : true, scope),
+        }, inTransaction)
+        : undefined;
+    if (nested?.kind === "refused") {
+        return nested;
+    }
+    const miss = request.variant === "unique"
+        ? missOf(session, request, args.where)
+        : undefined;
+    const linked = held?.kind === "held" && held.linked;
+    const failedMiss = miss !== undefined && (nested !== undefined || linked)
+        ? async () => {
+            const reach = allOf(isRecord(args.where) ? args.where : true, scope);
+            return reach !== false &&
+                (await session.renewed().exists(resource, whereOf(reach)))
+                ? undefined
+                : miss();
+        }
+        : undefined;
+    const failedLink = linkRefused(held);
+    const failed = nested === undefined && failedLink === undefined
+        ? failedMiss
+        : async (error) => (await failedMiss?.()) ??
+            (await failedLink?.(error)) ??
+            (await nested?.failed());
+    const misses = {
+        ...(miss === undefined ? {} : { miss }),
+        ...(failed === undefined ? {} : { failed }),
+    };
+    const carried = changes?.after === true
+        ? afterCheckFields(core, model, resource)
+        : undefined;
+    const read = await enforceReadPolicy(session, core, model, request, plan, adapterArguments, {
+        scope,
+        identified: changes !== undefined || nested !== undefined,
+        ...(carried === undefined ? {} : { carried }),
+    });
+    const blocked = unverifiable(read, request, inTransaction);
+    if (blocked !== undefined) {
+        return blocked;
+    }
+    if (read.kind !== "run") {
+        return { ...read, ...misses };
+    }
+    let run = read;
+    if (action === "delete" && run.checks.root.length > 0) {
+        const where = isRecord(run.arguments) ? run.arguments.where : undefined;
+        const reach = allOf(isRecord(where) ? where : true, someOf(run.checks.root));
+        if (reach !== false && (await session.exists(resource, whereOf(reach)))) {
+            return refused("The policy does not allow reading every row or field this request returns.");
+        }
+    }
+    if (changes !== undefined) {
+        const reach = allOf(isRecord(args.where) ? args.where : true, scope);
+        let changed;
+        const counted = request.variant === "count";
+        if (counted && offers(core, resource, "update", "many")) {
+            const runArgs = isRecord(run.arguments) ? run.arguments : {};
+            const asMany = {
+                ...run,
+                identity: { family: "update", variant: "many" },
+                arguments: {
+                    ...runArgs,
+                    select: changes.after
+                        ? [...afterCheckFields(core, model, resource)]
+                        : [...adapterPrimaryIdentifier(model, resource)],
+                },
+            };
+            const before = await rowsBefore(session, core, model, resource, changes, whereOfRun(run));
+            run = withChangedRows(heldUnchanged(core, model, resource, changes, asMany, before.rows), async (data) => fewerChanged(resource, changes, before, rowsOf(data).length) ??
+                checkChanged(session, core, model, resource, changes, rowsOf(data), changes.after, before));
+            if (nested !== undefined) {
+                run = withNestedWrites(run, "data", nested);
+            }
+            if (held?.kind === "held") {
+                run = withHeldReferences(run, held, [["data", "update"]]);
+            }
+            return countOf(run);
+        }
+        if (counted) {
+            const runArgs = isRecord(run.arguments) ? run.arguments : {};
+            const identifier = adapterPrimaryIdentifier(model, resource);
+            changed = await session.rows(resource, isRecord(runArgs.where) ? runArgs.where : {}, beforeFields(core, model, resource, changes));
+            if (changed.length === 0) {
+                return { kind: "empty", data: 0 };
+            }
+            const these = identifiedRows(core, identifier, resource, changed);
+            run = {
+                ...run,
+                arguments: {
+                    ...runArgs,
+                    where: everyOf([
+                        these,
+                        isRecord(runArgs.where) ? runArgs.where : true,
+                    ]),
+                },
+            };
+        }
+        const known = changed;
+        const before = known === undefined
+            ? await rowsBefore(session, core, model, resource, changes, request.variant === "unique" ? reach : whereOfRun(run))
+            : await coveredBefore(session, core, model, resource, changes, known);
+        const several = request.variant === "many" || request.variant === "count";
+        run = heldUnchanged(core, model, resource, changes, run, before.rows);
+        run = withChangedRows(run, async (data) => (several
+            ? fewerChanged(resource, changes, before, known === undefined
+                ? rowsOf(data).length
+                : typeof data === "number"
+                    ? data
+                    : known.length)
+            : undefined) ??
+            checkChanged(session, core, model, resource, changes, known ?? rowsOf(data), known === undefined && changes.after, before));
+    }
+    if (nested !== undefined) {
+        run = withNestedWrites(run, "data", nested);
+    }
+    if (held?.kind === "held") {
+        run = withHeldReferences(run, held, [["data", "update"]]);
+    }
+    run = withoutCarried(run, args, carried);
+    return { ...run, ...misses };
+}
+async function enforceUpsert(session, core, model, request, plan, adapterArguments, args, inTransaction) {
+    const resource = request.resource;
+    const selector = isRecord(args.where) ? args.where : true;
+    const scope = allOf(await session.scope(resource, "update"), await session.scope(resource, "read"));
+    const within = allOf(selector, scope);
+    const updates = within !== false && (await session.exists(resource, whereOf(within)));
+    let changes;
+    let grants = new Map();
+    const exists = !updates && (await session.exists(resource, whereOf(selector)));
+    const nested = exists
+        ? undefined
+        : await nestedWritesOf(session, core, model, request, updates ? args.update : args.create, updates ? { kind: "existing", reach: within } : { kind: "new" }, inTransaction);
+    if (nested?.kind === "refused") {
+        return nested;
+    }
+    if (updates) {
+        changes = await afterUpdate(session, core, model, resource, args.update, inTransaction);
+        const unreadable = beforeUnreadable(core, resource, changes);
+        if (unreadable !== undefined) {
+            return { kind: "refused", response: unreadable };
+        }
+        if (changes !== undefined && !inTransaction) {
+            return refused(`The policy checks this upsert's update on Resource "${resource}" after it runs (${changes.after ? "its grant's after condition" : "whether it moves a row out of what the caller may read"}), which ${UNVERIFIABLE}.`);
+        }
+    }
+    else if (exists) {
+        return refused(`The policy does not allow update on this row of Resource "${resource}".`);
+    }
+    else if (nested === undefined &&
+        !(await session.can(resource, "create", rowOf(core, resource, args.create)))) {
+        return refused(`The policy does not allow creating this row of Resource "${resource}".`);
+    }
+    else {
+        grants = session.createGrants();
+        const uncheckable = uncheckableCreate(model, request, grants, inTransaction);
+        if (uncheckable !== undefined) {
+            return uncheckable;
+        }
+    }
+    const held = await heldReferences(session, core, model, request, [
+        { stage: "create", records: [args.create] },
+        { stage: "update", records: [args.update] },
+    ]);
+    if (held.kind === "refused") {
+        return held;
+    }
+    const carried = changes?.after === true
+        ? afterCheckFields(core, model, resource)
+        : undefined;
+    const read = await enforceReadPolicy(session, core, model, request, plan, adapterArguments, {
+        scope: undefined,
+        identified: changes !== undefined || grants.size > 0 || nested !== undefined,
+        ...(carried === undefined ? {} : { carried }),
+    });
+    const blocked = unverifiable(read, request, inTransaction);
+    if (blocked !== undefined || read.kind !== "run") {
+        return blocked ?? read;
+    }
+    let run = read;
+    const checks = changes;
+    if (checks !== undefined) {
+        const before = await rowsBefore(session, core, model, resource, checks, within);
+        run = withChangedRows(run, (data) => checkChanged(session, core, model, resource, checks, rowsOf(data), checks.after, before));
+    }
+    const created = grants;
+    if (created.size > 0) {
+        run = withChangedRows(run, (data) => checkCreated(session, core, model, resource, created, rowsOf(data)));
+    }
+    if (nested !== undefined) {
+        run = withNestedWrites(run, updates ? "update" : "create", nested);
+    }
+    run = withHeldReferences(run, held, [
+        ["create", "create"],
+        ["update", "update"],
+    ]);
+    run = withoutCarried(run, args, carried);
+    const failedLink = linkRefused(held);
+    if (nested === undefined && failedLink === undefined) {
+        return run;
+    }
+    return {
+        ...run,
+        failed: async (error) => (await failedLink?.(error)) ?? (await nested?.failed()),
+    };
+}

package/dist/prebuilt/core-version.generated.d.ts

@@ -0,0 +1,2 @@
+/** The version of this `@aventara/core`. */
+export declare const CORE_VERSION = "1.0.0-rc.10";

package/dist/prebuilt/core-version.generated.js

@@ -0,0 +1 @@
+export const CORE_VERSION = "1.0.0-rc.10";

package/dist/prebuilt/prebuilt-changes.d.ts

@@ -0,0 +1,29 @@
+import type { PrebuiltPartFingerprints } from "./prebuilt-inputs.fingerprint.js";
+/** `a`, `a and b`, `a, b and c`. */
+export declare function listedNames(names: readonly string[]): string;
+/** What a prebuilt file was written in, by and for. */
+type PrebuiltHeader = {
+    readonly format: number;
+    readonly core: string;
+    readonly protocol: number;
+};
+/**
+ * Each way a stored file's header differs from `current`, in the order the
+ * runtime checks them: the file format, the core version, the protocol.
+ */
+export declare function prebuiltHeaderChanges(stored: unknown, current: PrebuiltHeader): readonly string[];
+/**
+ * Each way a stored file's part fingerprints differ from `current`: the
+ * Resources whose inputs changed, the new ones, the gone ones, and, when
+ * `sameHeader`, the inputs that belong to no single Resource.
+ */
+export declare function prebuiltInputChanges(stored: unknown, current: PrebuiltPartFingerprints, sameHeader?: boolean): readonly string[];
+/**
+ * What differs between a stored prebuilt file and `current`, one clause per
+ * difference: its header's, then its inputs' (`… since it was written`).
+ * Empty when the two record the same header and inputs.
+ */
+export declare function prebuiltFileChanges(stored: unknown, current: PrebuiltHeader & {
+    readonly fingerprints: PrebuiltPartFingerprints;
+}): readonly string[];
+export {};

package/dist/prebuilt/prebuilt-changes.js

@@ -0,0 +1,65 @@
+function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+export function listedNames(names) {
+    return names.length < 2
+        ? names.join("")
+        : `${names.slice(0, -1).join(", ")} and ${names.at(-1)}`;
+}
+export function prebuiltHeaderChanges(stored, current) {
+    const header = isRecord(stored) ? stored : {};
+    const changes = [];
+    if (header.format !== current.format) {
+        changes.push(`it is written in file format ${String(header.format)}, and this @aventara/core reads format ${current.format}`);
+    }
+    if (header.core !== current.core) {
+        changes.push(`it was built by @aventara/core ${String(header.core)}, and this is ${current.core}`);
+    }
+    if (header.protocol !== current.protocol) {
+        changes.push(`it was built for protocol version ${String(header.protocol)}, and this @aventara/core speaks version ${current.protocol}`);
+    }
+    return changes;
+}
+export function prebuiltInputChanges(stored, current, sameHeader = true) {
+    const storedResources = isRecord(stored) ? stored.resources : undefined;
+    const before = isRecord(storedResources) ? storedResources : {};
+    const changed = [];
+    const added = [];
+    const removed = [];
+    for (const [name, fingerprint] of Object.entries(current.resources)) {
+        if (!Object.hasOwn(before, name)) {
+            added.push(name);
+        }
+        else if (before[name] !== fingerprint) {
+            changed.push(name);
+        }
+    }
+    for (const name of Object.keys(before)) {
+        if (!Object.hasOwn(current.resources, name)) {
+            removed.push(name);
+        }
+    }
+    const resources = (names) => `${names.length === 1 ? "Resource" : "Resources"} ${listedNames(names)}`;
+    const be = (names) => (names.length === 1 ? "is" : "are");
+    const changes = [];
+    if (changed.length > 0) {
+        changes.push(`${resources(changed)} changed`);
+    }
+    if (added.length > 0) {
+        changes.push(`${resources(added)} ${be(added)} new`);
+    }
+    if (removed.length > 0) {
+        changes.push(`${resources(removed)} ${be(removed)} gone`);
+    }
+    if (sameHeader && (!isRecord(stored) || stored.shared !== current.shared)) {
+        changes.push("the configuration or model outside the Resources changed");
+    }
+    return changes;
+}
+export function prebuiltFileChanges(stored, current) {
+    const header = prebuiltHeaderChanges(stored, current);
+    const inputs = prebuiltInputChanges(isRecord(stored) ? stored.fingerprints : undefined, current.fingerprints, header.length === 0);
+    return inputs.length === 0
+        ? header
+        : [...header, `${listedNames(inputs)} since it was written`];
+}

package/dist/prebuilt/prebuilt-contracts.d.ts

@@ -0,0 +1,40 @@
+/** The file format this core writes and reads. */
+export declare const PREBUILT_FORMAT = 1;
+/**
+ * Contracts compiled ahead of time: the value of a generated
+ * `contracts.generated.ts`, passed to `createFramework` as `prebuilt`. The
+ * framework uses them only when they were compiled by the same core, for the
+ * same protocol, from the same configuration and model; otherwise it compiles
+ * live and warns (`AVENTARA_PREBUILT_STALE`). Generated, never written by hand.
+ */
+export type AvPrebuiltContracts = {
+    /** The file format's version. */
+    readonly format: number;
+    /** The version of `@aventara/core` that compiled the Contracts. */
+    readonly core: string;
+    /** The protocol version the Contracts were compiled for. */
+    readonly protocol: number;
+    /**
+     * `sha256:` over every input: the configuration (without `adapter` and
+     * `prebuilt`), the adapter's model, the core version, the protocol version
+     * and the file format.
+     */
+    readonly fingerprint: string;
+    /** The same inputs, fingerprinted in parts, so a stale file can say what changed. */
+    readonly fingerprints: {
+        /** The inputs that belong to no single Resource. */
+        readonly shared: string;
+        /** Each Resource's inputs: its model, and its entries in every layer. */
+        readonly resources: Readonly<Record<string, string>>;
+    };
+    /**
+     * Each Contract's canonical JSON text. The Client and Agent texts carry
+     * their hash and are the bytes `/_contract` serves.
+     */
+    readonly contracts: {
+        readonly core: string;
+        readonly application: string;
+        readonly client: string;
+        readonly agent: string;
+    };
+};