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

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

@@ -0,0 +1,77 @@
+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 { listedNames, prebuiltHeaderChanges, prebuiltInputChanges, } from "./prebuilt-changes.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);
+}
+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,192 @@
+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 { 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 isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+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 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]) : 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

@@ -2,7 +2,7 @@ import type { AvContracts } from "../compiler/contract.compiler.js";
 import type { RemoteRequestOrigin } from "../config/config-layer.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";
@@ -36,7 +36,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,14 +44,14 @@ 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;
+export declare function transactionsRouteFailure(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;

package/dist/protocol/http-request.decoder.d.ts

@@ -1,7 +1,7 @@
 import type { AvContracts } from "../compiler/contract.compiler.js";
 import type { RemoteRequestOrigin } from "../config/config-layer.js";
 import type { RemoteOperationRequest } from "../runtime/operation-request.js";
-import type { AgentTransactionRequest, ClientTransactionRequest } from "../transactions/transaction-request.js";
+import type { AvAgentTransactionRequest, AvClientTransactionRequest } from "../transactions/transaction-request.js";
 import type { AvProtocolResponse } from "./http-response.encoder.js";
 /** One HTTP request as a host hands it to the protocol. */
 export type AvProtocolRequest = {
@@ -56,7 +56,7 @@ export type DecodedOperationRequest = Extract<DecodedOperation, {
     ok: true;
 }>;
 /** What `protocol.decodeTransaction` answers. */
-export type DecodedTransaction = Decoded<ClientTransactionRequest | AgentTransactionRequest>;
+export type DecodedTransaction = Decoded<AvClientTransactionRequest | AvAgentTransactionRequest>;
 /**
  * `protocol.decodeOperation(request)` — one operation route's HTTP request as
  * the client-origin request `framework.execute` takes, or its answer.

package/dist/protocol/http-request.reader.d.ts

@@ -1,4 +1,4 @@
-import type { ClientProtocolIdentity } from "../runtime/operation-request.js";
+import type { AvRequestProtocol } from "../runtime/operation-request.js";
 import type { OperationRouteSegments } from "./absent-route.responder.js";
 import type { AvProtocolRequest } from "./http-request.decoder.js";
 import type { AvProtocolResponse } from "./http-response.encoder.js";
@@ -25,7 +25,7 @@ export type ReadRequest = {
     /** Adopted from `Aventara-Request-Id`, else minted. */
     readonly requestId: string;
     /** `undefined` when either identity header is absent (`A2000`). */
-    readonly protocol: ClientProtocolIdentity | undefined;
+    readonly protocol: AvRequestProtocol | undefined;
 };
 /** What a value that is not an `AvProtocolRequest` reads as. */
 export type UnreadableRequest = {

package/dist/protocol/protocol-headers.d.ts

@@ -1,4 +1,4 @@
-import type { ClientProtocolIdentity } from "../runtime/operation-request.js";
+import type { AvRequestProtocol } from "../runtime/operation-request.js";
 /** `AvProtocol.headers` — the header names the protocol owns, as passive data. */
 export declare const headers: Readonly<{
     readonly protocolVersion: "Aventara-Protocol-Version";
@@ -22,11 +22,11 @@ export declare function normalizeHeaders(received: ReceivedHeaders): Readonly<Re
  */
 export declare function headerValue(normalized: Readonly<Record<string, string>>, name: string): string | undefined;
 /**
- * The identity headers as the `ClientProtocolIdentity` core checks, or `undefined`
+ * The identity headers as the `AvRequestProtocol` core checks, or `undefined`
  * when either is ABSENT — a request without them is malformed: it does not say which
  * protocol and ClientContract it speaks, so there is nothing to compare.
  */
-export declare function protocolIdentityOf(normalized: Readonly<Record<string, string>>): ClientProtocolIdentity | undefined;
+export declare function protocolIdentityOf(normalized: Readonly<Record<string, string>>): AvRequestProtocol | undefined;
 /**
  * The identity headers a request did not send, in the order the framework sends them —
  * what the `A2000` answering it names. Empty exactly when {@link protocolIdentityOf}

package/dist/runtime/computed-read-runtime.d.ts

@@ -21,6 +21,11 @@ export type PlannedReadOperation = {
     readonly projection: ReadProjectionPlan | undefined;
     readonly materialize: boolean;
 };
+/**
+ * The fields a level returns when it states no projection: every scalar of the
+ * active Contract whose `select` is `true` and that is not governed.
+ */
+export declare function defaultProjectionFields(active: AvContract, resourceName: string): readonly string[];
 /**
  * Clone the caller projection into the internal Adapter projection: the read
  * set the Adapter is asked for, always explicit for a projecting variant, plus
@@ -33,5 +38,5 @@ export declare function planReadOperation(core: AvContractCore, model: AvAdapter
  * Materialize computed scalar reads and remove internal dependency fields,
  * against `active` — the Contract `planReadOperation` was given as `active`.
  */
-export declare function materializeReadOperation(active: AvContract, compute: ResolvedComputeConfig | undefined, request: OperationExecutionRequest, plan: PlannedReadOperation, value: unknown, contextFactory: ContextFactory): Promise<unknown>;
+export declare function materializeReadOperation(active: AvContract, compute: ResolvedComputeConfig | undefined, _request: OperationExecutionRequest, plan: PlannedReadOperation, value: unknown, contextFactory: ContextFactory): Promise<unknown>;
 export {};