@aventara/core 1.0.0-rc.1 → 1.0.0-rc.11

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,19 @@
+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 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,75 @@
+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 { isRecord } from "../runtime/record.guard.js";
+import { CORE_VERSION } from "./core-version.generated.js";
+import { listedNames, prebuiltHeaderChanges, prebuiltInputChanges, } from "./prebuilt-changes.js";
+import { PREBUILT_FORMAT } from "./prebuilt-contracts.js";
+import { prebuiltInputsFingerprint, prebuiltPartFingerprints, } from "./prebuilt-inputs.fingerprint.js";
+const PREBUILT_STALE_WARNING = "AVENTARA_PREBUILT_STALE";
+async function changedInputs(stored, model, config) {
+    const changes = prebuiltInputChanges(stored, await prebuiltPartFingerprints(model, config));
+    return changes.length === 0
+        ? "its fingerprint does not match the configuration and model"
+        : `${listedNames(changes)} 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" };
+    }
+    const [header] = prebuiltHeaderChanges(prebuilt, {
+        format: PREBUILT_FORMAT,
+        core: CORE_VERSION,
+        protocol: AVENTARA_PROTOCOL_VERSION,
+    });
+    if (header !== undefined) {
+        return { ok: false, reason: header };
+    }
+    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>;

package/dist/prebuilt/prebuilt-inputs.fingerprint.js

@@ -0,0 +1,227 @@
+import { avzCheckOf } from "../avz/avz-check.registry.js";
+import { jsonShapeOf } from "../avz/json-shape.registry.js";
+import { hashCanonicalContractText } from "../contracts/contract-hash.js";
+import { AVENTARA_PROTOCOL_VERSION } from "../contracts/contract-protocol.js";
+import { isRecord } from "../runtime/record.guard.js";
+import { CORE_VERSION } from "./core-version.generated.js";
+import { PREBUILT_FORMAT } from "./prebuilt-contracts.js";
+const LAYERS = ["root", "application", "client", "agent"];
+const NOT_INPUTS = new Set(["adapter", "prebuilt"]);
+const PER_RESOURCE = "#resources";
+function sortedRecord(record) {
+    const keys = Object.keys(record);
+    const prototype = Object.getPrototypeOf(record);
+    const plain = prototype === Object.prototype || prototype === null;
+    let written = plain;
+    for (let index = 0; written && index < keys.length; index += 1) {
+        const key = keys[index];
+        written =
+            !key.startsWith("#") &&
+                (index === 0 || keys[index - 1] < key);
+    }
+    if (written) {
+        return record;
+    }
+    const sorted = {};
+    if (!plain) {
+        const name = record.constructor?.name;
+        sorted["#class"] = typeof name === "string" ? name : "";
+    }
+    for (const key of keys.sort()) {
+        sorted[key.startsWith("#") ? `#${key}` : key] = record[key];
+    }
+    return sorted;
+}
+function inputMember(key, value) {
+    const raw = this[key];
+    switch (typeof raw) {
+        case "string":
+            return raw.startsWith("#") ? `#${raw}` : raw;
+        case "number":
+            return Number.isFinite(raw) ? raw : `#number(${raw})`;
+        case "bigint":
+            return `#bigint(${raw})`;
+        case "function":
+            return "#function";
+        case "symbol":
+            return `#symbol(${String(raw.description)})`;
+        case "undefined":
+            return "#undefined";
+        case "boolean":
+            return raw;
+    }
+    if (raw === null) {
+        return value;
+    }
+    const check = avzCheckOf(raw);
+    if (check !== undefined) {
+        return `#avz(${inputText(check)})`;
+    }
+    const shape = jsonShapeOf(raw);
+    if (shape !== undefined) {
+        return `#shape(${inputText(shape.schema)})`;
+    }
+    if (raw instanceof Date) {
+        return `#date(${Number.isNaN(raw.getTime()) ? "invalid" : raw.toISOString()})`;
+    }
+    if (raw instanceof RegExp) {
+        return `#regexp(${JSON.stringify(raw.source)},${raw.flags})`;
+    }
+    if (raw instanceof Map || raw instanceof Set) {
+        return `#${raw instanceof Map ? "map" : "set"}(${inputText([...raw])})`;
+    }
+    if (value !== raw) {
+        return `#json(${inputText(value)})`;
+    }
+    return Array.isArray(raw) ? raw : sortedRecord(raw);
+}
+function inputText(value) {
+    return JSON.stringify(value, inputMember);
+}
+function modelText(value) {
+    try {
+        return JSON.stringify(value) ?? "#undefined";
+    }
+    catch {
+        return inputText(value);
+    }
+}
+function recordAt(value, key) {
+    if (!isRecord(value) || !Object.hasOwn(value, key)) {
+        return undefined;
+    }
+    const member = value[key];
+    return isRecord(member) ? member : undefined;
+}
+function layerOf(config, layer) {
+    return layer === "root"
+        ? config
+        : Object.hasOwn(config, layer)
+            ? config[layer]
+            : undefined;
+}
+function sharedLayer(layer) {
+    if (!isRecord(layer)) {
+        return layer;
+    }
+    const shared = { ...layer };
+    if (isRecord(layer.resources)) {
+        shared.resources = PER_RESOURCE;
+    }
+    const exemptions = layer.exemptions;
+    if (isRecord(exemptions) && isRecord(exemptions.resources)) {
+        shared.exemptions = { ...exemptions, resources: PER_RESOURCE };
+    }
+    return shared;
+}
+function policyInput(policy) {
+    if (!isRecord(policy) || !Object.hasOwn(policy, "engine")) {
+        return policy;
+    }
+    const engine = policy.engine;
+    const governed = engine !== null && typeof engine === "object"
+        ? engine.governed
+        : undefined;
+    return { ...policy, engine: { governed: governed ?? null } };
+}
+function accessInput(access) {
+    if (!isRecord(access)) {
+        return access;
+    }
+    const engine = access.policy;
+    const governed = engine !== null && typeof engine === "object"
+        ? engine.governed
+        : undefined;
+    const policy = { policy: { governed: governed ?? null } };
+    return access.client === undefined
+        ? policy
+        : { ...policy, client: accessClientInput(access.client) };
+}
+function accessClientInput(client) {
+    if (!isRecord(client)) {
+        return client;
+    }
+    const verbs = isRecord(client.verbs)
+        ? Object.fromEntries(Object.entries(client.verbs).map(([name, verb]) => [
+            name,
+            isRecord(verb)
+                ? {
+                    method: verb.method,
+                    path: verb.path,
+                    args: verb.args,
+                    result: verb.result,
+                }
+                : verb,
+        ]))
+        : client.verbs;
+    return { url: client.url, verbs };
+}
+function authoredInputs(config) {
+    const authored = config;
+    const root = {};
+    for (const key of Object.keys(authored)) {
+        if (!NOT_INPUTS.has(key)) {
+            root[key] =
+                key === "policy"
+                    ? policyInput(authored[key])
+                    : key === "access"
+                        ? accessInput(authored[key])
+                        : authored[key];
+        }
+    }
+    return root;
+}
+const HEADER = `aventara-prebuilt format ${PREBUILT_FORMAT} core ${CORE_VERSION} protocol ${AVENTARA_PROTOCOL_VERSION}`;
+export function prebuiltInputsFingerprint(model, config) {
+    return hashCanonicalContractText(`${HEADER}\n${inputText(authoredInputs(config))}\n${modelText(model)}`);
+}
+export async function prebuiltPartFingerprints(model, config) {
+    const root = authoredInputs(config);
+    const names = new Set(Object.keys(model.resources));
+    for (const layer of LAYERS) {
+        const value = layerOf(root, layer);
+        for (const name of Object.keys(recordAt(value, "resources") ?? {})) {
+            names.add(name);
+        }
+        const exemptions = recordAt(value, "exemptions");
+        for (const name of Object.keys(recordAt(exemptions, "resources") ?? {})) {
+            names.add(name);
+        }
+    }
+    const sharedRoot = sharedLayer(root);
+    for (const layer of LAYERS) {
+        if (layer !== "root" && Object.hasOwn(root, layer)) {
+            sharedRoot[layer] = sharedLayer(root[layer]);
+        }
+    }
+    const { resources: _resources, ...sharedModel } = model;
+    const shared = hashCanonicalContractText(`${HEADER}\n${inputText(sharedRoot)}\n${modelText(sharedModel)}`);
+    const sorted = [...names].sort();
+    const parts = sorted.map((name) => {
+        const entries = {};
+        for (const layer of LAYERS) {
+            const value = layerOf(root, layer);
+            const resources = recordAt(value, "resources");
+            const exemptions = recordAt(recordAt(value, "exemptions"), "resources");
+            const entry = {};
+            if (resources !== undefined && Object.hasOwn(resources, name)) {
+                entry.resources = resources[name];
+            }
+            if (exemptions !== undefined && Object.hasOwn(exemptions, name)) {
+                entry.exemptions = exemptions[name];
+            }
+            if (Object.keys(entry).length > 0) {
+                entries[layer] = entry;
+            }
+        }
+        const modelPart = Object.hasOwn(model.resources, name)
+            ? modelText(model.resources[name])
+            : "#absent";
+        return hashCanonicalContractText(`${inputText(entries)}\n${modelPart}`);
+    });
+    const hashes = await Promise.all(parts);
+    return {
+        shared: await shared,
+        resources: Object.fromEntries(sorted.map((name, index) => [name, hashes[index]])),
+    };
+}

package/dist/protocol/absent-route.responder.d.ts

@@ -1,12 +1,14 @@
 import type { AvContracts } from "../compiler/contract.compiler.js";
 import type { RemoteRequestOrigin } from "../config/config-layer.js";
+import type { AvContractClient } from "../contracts/contract.js";
 import { type AvOperationIdentity } from "../operations/operation-identity.js";
 import { type AvDiagnosticsSink } from "../runtime/diagnostics-reporter.js";
-import type { ClientProtocolIdentity } from "../runtime/operation-request.js";
+import type { AvRequestProtocol } from "../runtime/operation-request.js";
 import { type AvOperationFailureResponse } from "../runtime/operation-response.js";
 import type { AvProtocolRequest } from "./http-request.decoder.js";
 import { type ReadRequest } from "./http-request.reader.js";
 import { type AvProtocolResponse } from "./http-response.encoder.js";
+import { type ReadQuery } from "./read-query.codec.js";
 /**
  * The absence answers: the checks a framework route makes before it reads a body, runs
  * a pipeline or reaches an Adapter — the protocol version (`A2006`), the
@@ -22,7 +24,7 @@ export type OperationRouteSegments = {
     readonly variant: string;
 };
 /** What a route check resolves to: the operation it names, or the answer that refuses it. */
-export type OperationRouteResolution = {
+type OperationRouteResolution = {
     readonly ok: true;
     readonly operation: AvOperationIdentity;
 } | {
@@ -36,7 +38,7 @@ export type OperationRouteResolution = {
  * is a standard operation the Resource advertises, read through
  * `isOperationVariantAvailable` alone.
  */
-export declare function resolveOperationRoute(contracts: AvContracts, protocol: ClientProtocolIdentity, route: OperationRouteSegments, origin?: RemoteRequestOrigin): OperationRouteResolution;
+export declare function resolveOperationRoute(contracts: AvContracts, protocol: AvRequestProtocol, route: OperationRouteSegments, origin?: RemoteRequestOrigin): OperationRouteResolution;
 /**
  * The `/_transactions` route under one client protocol identity: version → hash → the
  * ClientContract's transaction capability. The route exists only when that capability
@@ -44,37 +46,70 @@ export declare function resolveOperationRoute(contracts: AvContracts, protocol:
  * it — and is otherwise absent with core's own refusal of a plan. `undefined` when the
  * route is there.
  */
-export declare function transactionsRouteFailure(contracts: AvContracts, protocol: ClientProtocolIdentity, origin?: RemoteRequestOrigin): AvOperationFailureResponse | undefined;
+declare function transactionsRouteFailure(contracts: AvContracts, protocol: AvRequestProtocol, origin?: RemoteRequestOrigin): AvOperationFailureResponse | undefined;
+/**
+ * The `/_access/can` route under one client protocol identity: version → hash →
+ * the Contract's `access` section. The route exists only when the section is
+ * there — tested as `protocol.surface()` tests it — and is otherwise absent.
+ * `undefined` when the route is there.
+ */
+declare function accessCanRouteFailure(contracts: AvContracts, protocol: AvRequestProtocol, origin?: RemoteRequestOrigin): AvOperationFailureResponse | undefined;
+/**
+ * The `/_all` route under one client protocol identity: version → hash → whether
+ * the Contract advertises any operation, tested as `protocol.surface()` tests it.
+ * `undefined` when the route is there.
+ */
+declare function allRouteFailure(contracts: AvContracts, protocol: AvRequestProtocol, origin?: RemoteRequestOrigin): AvOperationFailureResponse | undefined;
 /**
  * What a route's checks before its body resolve to: the route a request
  * reaches, or the framework response that answers it instead.
  */
 type RouteCheck<Route> = ({
     readonly ok: true;
-    readonly protocol: ClientProtocolIdentity;
+    readonly protocol: AvRequestProtocol;
 } & Route) | {
     readonly ok: false;
     readonly response: AvProtocolResponse;
 };
+/** A cached read's mark in the Contract a route reads: its `for` and `maxAge`. */
+type ReadCacheMark = NonNullable<NonNullable<AvContractClient["resources"][string]["cache"]>["first" | "unique" | "many" | "count"]>;
 /**
  * An operation route's checks before its body (decoder steps 2–4): the path (`A2000`
  * unless `/_resources/<r>/<f>/<v>`, each segment decodable and none empty), the
- * identity headers' presence (`A2000`), then {@link resolveOperationRoute} — version,
- * hash, Resource, operation — and the method (`A2012`, `Allow: POST`). One sequence
- * for both route styles: `decodeOperation` reads the body only after it passes,
+ * identity — a `GET`'s well-formed `q`/`v` query when it has a query, otherwise
+ * the headers' presence (`A2000`) — then {@link resolveOperationRoute} — version, hash, Resource,
+ * operation — and the method (`A2012`): `POST`, or `GET` for a `find` operation of
+ * read the Contract marks cacheable, whose `Allow` is then `GET, POST`. One sequence for
+ * both route styles: `decodeOperation` reads the body only after it passes,
  * `answerAbsent` never.
  */
-export declare function checkOperationRoute(contracts: AvContracts, read: ReadRequest, origin?: RemoteRequestOrigin): RouteCheck<{
+export declare function checkOperationRoute(contracts: AvContracts, read: ReadRequest, origin?: RemoteRequestOrigin): OperationRouteCheck;
+/** What an operation route's checks resolve to. */
+type OperationRouteCheck = RouteCheck<{
     readonly resource: string;
     readonly operation: AvOperationIdentity;
+    /** The read's cache mark, for a `find` variant the Contract marks. */
+    readonly cache: ReadCacheMark | undefined;
+    /** A `GET`'s query, read; `undefined` without one (`A2000` for a cached read). */
+    readonly query: ReadQuery | undefined;
 }>;
+/** Each fixed `POST` route, by path, and its absence under one protocol identity. */
+declare const POST_ROUTE_FAILURES: {
+    readonly "/_transactions": typeof transactionsRouteFailure;
+    readonly "/_access/can": typeof accessCanRouteFailure;
+    readonly "/_all": typeof allRouteFailure;
+};
+/** `/_transactions`, `/_access/can` or `/_all`. */
+type PostRoute = keyof typeof POST_ROUTE_FAILURES;
 /**
- * `/_transactions`' checks before its body: the path (`A2000` unless exactly
- * `/_transactions`), the identity headers' presence (`A2000`), then
- * {@link transactionsRouteFailure} — version, hash, `"interactive"` — and the
- * method (`A2012`, `Allow: POST`).
+ * A fixed `POST` route's checks before its body: the path (`A2000` unless
+ * exactly `route`), the identity headers' presence (`A2000`), then the route's
+ * own absence — version, hash, and {@link transactionsRouteFailure}'s
+ * `"interactive"`, {@link accessCanRouteFailure}'s `access` section or
+ * {@link allRouteFailure}'s advertised operation — and the method (`A2012`,
+ * `Allow: POST`).
  */
-export declare function checkTransactionsRoute(contracts: AvContracts, read: ReadRequest, origin?: RemoteRequestOrigin): RouteCheck<object>;
+export declare function checkPostRoute(route: PostRoute, contracts: AvContracts, read: ReadRequest, origin?: RemoteRequestOrigin): RouteCheck<object>;
 /**
  * `protocol.answerAbsent(request)` — the fallback a host that mounts one route per
  * `protocol.surface()` entry mounts for every path it did not. Never a catch-all into