@aventara/core 1.0.0-rc.3 → 1.0.0-rc.4

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

@@ -0,0 +1,394 @@
+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, checkChanged, } 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, identifierOf, returnedRowChecks, } from "./policy-read.runtime.js";
+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, identifierOf(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" ||
+        identifierOf(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 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 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);
+    }
+    return run;
+}
+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 && identifierOf(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 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 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 miss === undefined ? read : { ...read, miss };
+    }
+    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) {
+        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)]
+                        : [...identifierOf(model, resource)],
+                },
+            };
+            run = withChangedRows(asMany, (data) => checkChanged(session, core, model, resource, changes, rowsOf(data), changes.after));
+            if (nested !== undefined) {
+                run = withNestedWrites(run, "data", nested);
+            }
+            return countOf(run);
+        }
+        if (counted) {
+            const runArgs = isRecord(run.arguments) ? run.arguments : {};
+            const identifier = identifierOf(model, resource);
+            changed = await session.rows(resource, isRecord(runArgs.where) ? runArgs.where : {}, identifier);
+            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;
+        run = withChangedRows(run, (data) => checkChanged(session, core, model, resource, changes, known ?? rowsOf(data), known === undefined && changes.after));
+    }
+    if (nested !== undefined) {
+        run = withNestedWrites(run, "data", nested);
+    }
+    run = withoutCarried(run, args, carried);
+    return miss === undefined ? run : { ...run, miss };
+}
+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);
+        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 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) {
+        run = withChangedRows(run, (data) => checkChanged(session, core, model, resource, checks, rowsOf(data), checks.after));
+    }
+    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);
+    }
+    return withoutCarried(run, args, carried);
+}

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.4";

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

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

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;
+    };
+};

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

@@ -0,0 +1,16 @@
+import type { AvAdapterModel } from "../adapters/adapter-model.js";
+import type { AvContracts } from "../compiler/contract.compiler.js";
+import { type AvPrebuiltContracts } from "./prebuilt-contracts.js";
+/**
+ * The prebuilt file's value for Contracts `compileContracts` compiled from
+ * `model` and `config` (the configuration as authored; its `adapter` and
+ * `prebuilt`, if any, are no inputs): each Contract's canonical text, and the
+ * fingerprints of the inputs.
+ */
+export declare function prebuiltContractsOf(model: AvAdapterModel, config: object, contracts: AvContracts): Promise<AvPrebuiltContracts>;
+/**
+ * The generated module that exports `prebuilt` as `aventaraContracts`. Each
+ * Contract stays a string, so loading it is one `JSON.parse`; the type is
+ * imported for checking only.
+ */
+export declare function emitPrebuiltContracts(prebuilt: AvPrebuiltContracts): string;

package/dist/prebuilt/prebuilt-contracts.emitter.js

@@ -0,0 +1,50 @@
+import { canonicalContractTextOf } from "../contracts/contract-canonicalizer.js";
+import { AVENTARA_PROTOCOL_VERSION } from "../contracts/contract-protocol.js";
+import { CORE_VERSION } from "./core-version.generated.js";
+import { PREBUILT_FORMAT, } from "./prebuilt-contracts.js";
+import { prebuiltInputsFingerprint, prebuiltPartFingerprints, } from "./prebuilt-inputs.fingerprint.js";
+export async function prebuiltContractsOf(model, config, contracts) {
+    const [fingerprint, fingerprints] = await Promise.all([
+        prebuiltInputsFingerprint(model, config),
+        prebuiltPartFingerprints(model, config),
+    ]);
+    return {
+        format: PREBUILT_FORMAT,
+        core: CORE_VERSION,
+        protocol: AVENTARA_PROTOCOL_VERSION,
+        fingerprint,
+        fingerprints,
+        contracts: {
+            core: canonicalContractTextOf(contracts.core),
+            application: canonicalContractTextOf(contracts.application),
+            client: canonicalContractTextOf(contracts.client),
+            agent: canonicalContractTextOf(contracts.agent),
+        },
+    };
+}
+const literal = (value) => JSON.stringify(value);
+const key = (name) => name === "__proto__" ? `[${literal(name)}]` : literal(name);
+export function emitPrebuiltContracts(prebuilt) {
+    const resources = Object.entries(prebuilt.fingerprints.resources).map(([name, fingerprint]) => `\t\t\t${key(name)}: ${literal(fingerprint)},\n`);
+    return `// Generated by @aventara/core from the configuration and the adapter's model. Do not edit: regenerate it.
+import type { AvPrebuiltContracts } from "@aventara/core";
+
+export const aventaraContracts: AvPrebuiltContracts = {
+\tformat: ${prebuilt.format},
+\tcore: ${literal(prebuilt.core)},
+\tprotocol: ${prebuilt.protocol},
+\tfingerprint: ${literal(prebuilt.fingerprint)},
+\tfingerprints: {
+\t\tshared: ${literal(prebuilt.fingerprints.shared)},
+\t\tresources: {
+${resources.join("")}\t\t},
+\t},
+\tcontracts: {
+\t\tcore: ${literal(prebuilt.contracts.core)},
+\t\tapplication: ${literal(prebuilt.contracts.application)},
+\t\tclient: ${literal(prebuilt.contracts.client)},
+\t\tagent: ${literal(prebuilt.contracts.agent)},
+\t},
+};
+`;
+}

package/dist/prebuilt/prebuilt-contracts.js

@@ -0,0 +1 @@
+export const PREBUILT_FORMAT = 1;

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

@@ -0,0 +1,21 @@
+import type { AvAdapterModel } from "../adapters/adapter-model.js";
+import { type AvContracts } from "../compiler/contract.compiler.js";
+import type { ResolvedFrameworkConfig } from "../config/config.resolver.js";
+/** The warning's code, as `process.emitWarning` reports it. */
+export declare const PREBUILT_STALE_WARNING = "AVENTARA_PREBUILT_STALE";
+/** The loaded Contracts, or why the file cannot be used. */
+export type PrebuiltLoad = {
+    readonly ok: true;
+    readonly contracts: AvContracts;
+} | {
+    readonly ok: false;
+    readonly reason: string;
+};
+/**
+ * Loads the Contracts of a prebuilt file when it was compiled by this core, for
+ * this protocol, from `config` (as authored) and `model`; binds them to the
+ * runtime pieces of the live `resolved` configuration.
+ */
+export declare function loadPrebuiltContracts<M extends AvAdapterModel>(prebuilt: unknown, model: M, config: object, resolved: ResolvedFrameworkConfig<M>): Promise<PrebuiltLoad>;
+/** Warns, once for the framework being created, that its prebuilt file was not used, and why. */
+export declare function warnStalePrebuilt(reason: string): void;

package/dist/prebuilt/prebuilt-contracts.loader.js

@@ -0,0 +1,122 @@
+import { bindPrebuiltContracts, } from "../compiler/contract.compiler.js";
+import { recordCanonicalContractText } from "../contracts/contract-canonicalizer.js";
+import { AVENTARA_PROTOCOL_VERSION } from "../contracts/contract-protocol.js";
+import { emitFrameworkWarning } from "../runtime/framework-warning.emitter.js";
+import { CORE_VERSION } from "./core-version.generated.js";
+import { PREBUILT_FORMAT } from "./prebuilt-contracts.js";
+import { prebuiltInputsFingerprint, prebuiltPartFingerprints, } from "./prebuilt-inputs.fingerprint.js";
+export const PREBUILT_STALE_WARNING = "AVENTARA_PREBUILT_STALE";
+function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function listed(names) {
+    return names.length < 2
+        ? names.join("")
+        : `${names.slice(0, -1).join(", ")} and ${names.at(-1)}`;
+}
+async function changedInputs(stored, model, config) {
+    const live = await prebuiltPartFingerprints(model, config);
+    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(live.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(live.resources, name)) {
+            removed.push(name);
+        }
+    }
+    const parts = [];
+    if (changed.length > 0) {
+        parts.push(`${changed.length === 1 ? "Resource" : "Resources"} ${listed(changed)} changed`);
+    }
+    if (added.length > 0) {
+        parts.push(`${added.length === 1 ? "Resource" : "Resources"} ${listed(added)} ${added.length === 1 ? "is" : "are"} new`);
+    }
+    if (removed.length > 0) {
+        parts.push(`${removed.length === 1 ? "Resource" : "Resources"} ${listed(removed)} ${removed.length === 1 ? "is" : "are"} gone`);
+    }
+    if (!isRecord(stored) || stored.shared !== live.shared) {
+        parts.push("the configuration or model outside the Resources changed");
+    }
+    return parts.length === 0
+        ? "its fingerprint does not match the configuration and model"
+        : `${listed(parts)} since it was built`;
+}
+function textAt(record, key) {
+    const value = Object.hasOwn(record, key) ? record[key] : undefined;
+    return typeof value === "string" ? value : undefined;
+}
+function parsedContracts(texts) {
+    if (!isRecord(texts)) {
+        return undefined;
+    }
+    const parsed = {};
+    for (const origin of ["core", "application", "client", "agent"]) {
+        const text = textAt(texts, origin);
+        if (text === undefined) {
+            return undefined;
+        }
+        let contract;
+        try {
+            contract = JSON.parse(text);
+        }
+        catch {
+            return undefined;
+        }
+        if (!isRecord(contract)) {
+            return undefined;
+        }
+        parsed[origin] = contract;
+    }
+    const contracts = parsed;
+    recordCanonicalContractText(contracts.client, textAt(texts, "client") ?? "");
+    recordCanonicalContractText(contracts.agent, textAt(texts, "agent") ?? "");
+    return contracts;
+}
+export async function loadPrebuiltContracts(prebuilt, model, config, resolved) {
+    if (!isRecord(prebuilt)) {
+        return { ok: false, reason: "it is not a prebuilt Contracts file" };
+    }
+    if (prebuilt.format !== PREBUILT_FORMAT) {
+        return {
+            ok: false,
+            reason: `it is written in file format ${String(prebuilt.format)}, and this @aventara/core reads format ${PREBUILT_FORMAT}`,
+        };
+    }
+    if (prebuilt.core !== CORE_VERSION) {
+        return {
+            ok: false,
+            reason: `it was built by @aventara/core ${String(prebuilt.core)}, and this is ${CORE_VERSION}`,
+        };
+    }
+    if (prebuilt.protocol !== AVENTARA_PROTOCOL_VERSION) {
+        return {
+            ok: false,
+            reason: `it was built for protocol version ${String(prebuilt.protocol)}, and this @aventara/core speaks version ${AVENTARA_PROTOCOL_VERSION}`,
+        };
+    }
+    if ((await prebuiltInputsFingerprint(model, config)) !== prebuilt.fingerprint) {
+        return {
+            ok: false,
+            reason: await changedInputs(prebuilt.fingerprints, model, config),
+        };
+    }
+    const contracts = parsedContracts(prebuilt.contracts);
+    if (contracts === undefined) {
+        return { ok: false, reason: "its Contracts are not readable JSON objects" };
+    }
+    bindPrebuiltContracts(model, resolved, contracts);
+    return { ok: true, contracts };
+}
+export function warnStalePrebuilt(reason) {
+    emitFrameworkWarning(`prebuilt Contracts are stale and were not used: ${reason}. The Contracts were compiled at startup instead; regenerate the file with aventara-build.`, PREBUILT_STALE_WARNING);
+}

package/dist/prebuilt/prebuilt-inputs.fingerprint.d.ts

@@ -0,0 +1,16 @@
+import type { AvAdapterModel } from "../adapters/adapter-model.js";
+/**
+ * The fingerprint of the inputs Contracts are compiled from: `config` as
+ * authored (its `adapter` and `prebuilt` left out), `model`, this core's
+ * version, the protocol version and the file format.
+ */
+export declare function prebuiltInputsFingerprint(model: AvAdapterModel, config: object): Promise<string>;
+/** The inputs' parts, each fingerprinted on its own: what a file stores to name what changed. */
+export type PrebuiltPartFingerprints = {
+    /** The inputs that belong to no single Resource. */
+    readonly shared: string;
+    /** Each Resource's inputs (its model, and its entries in every layer), by name, sorted. */
+    readonly resources: Readonly<Record<string, string>>;
+};
+/** The parts of the same inputs as {@link prebuiltInputsFingerprint}'s, each fingerprinted. */
+export declare function prebuiltPartFingerprints(model: AvAdapterModel, config: object): Promise<PrebuiltPartFingerprints>;