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

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,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";
+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,229 @@
+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 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

@@ -2,8 +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 AvOperationFailureResponse } from "../runtime/operation-response.js";
+import type { AvRequestProtocol } from "../runtime/operation-request.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";
@@ -21,37 +20,13 @@ export type OperationRouteSegments = {
     readonly family: string;
     readonly variant: string;
 };
-/** What a route check resolves to: the operation it names, or the answer that refuses it. */
-export type OperationRouteResolution = {
-    readonly ok: true;
-    readonly operation: AvOperationIdentity;
-} | {
-    readonly ok: false;
-    readonly failure: AvOperationFailureResponse;
-};
-/**
- * An operation route `/_resources/<resource>/<family>/<variant>` under one client
- * protocol identity: version → hash → Resource → operation. A Resource key is matched
- * exactly and only as the ClientContract's own key; a family/variant pair only when it
- * is a standard operation the Resource advertises, read through
- * `isOperationVariantAvailable` alone.
- */
-export declare function resolveOperationRoute(contracts: AvContracts, protocol: ClientProtocolIdentity, 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
- * is `"interactive"` — tested against the value itself, as `protocol.surface()` tests
- * 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;
 /**
  * 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;
@@ -75,6 +50,13 @@ export declare function checkOperationRoute(contracts: AvContracts, read: ReadRe
  * method (`A2012`, `Allow: POST`).
  */
 export declare function checkTransactionsRoute(contracts: AvContracts, read: ReadRequest, origin?: RemoteRequestOrigin): RouteCheck<object>;
+/**
+ * `/_access/can`'s checks before its body: the path (`A2000` unless exactly
+ * `/_access/can`), the identity headers' presence (`A2000`), then
+ * {@link accessCanRouteFailure} — version, hash, the `access` section — and the
+ * method (`A2012`, `Allow: POST`).
+ */
+export declare function checkAccessCanRoute(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

package/dist/protocol/absent-route.responder.js

@@ -3,17 +3,18 @@ import { isOperationVariantAvailable, } from "../contracts/resource-operations.j
 import { parseOperationIdentity, } from "../operations/operation-identity.js";
 import { operationUnavailableIssue } from "../operations/operation-validator.js";
 import { resourceUnavailableIssue } from "../operations/operation-validator-core.js";
+import { validationIssue } from "../operations/validation-code.js";
 import { createReporter, } from "../runtime/diagnostics-reporter.js";
 import { INTERNAL_FAILURE_MESSAGE, operationFailure, } from "../runtime/operation-response.js";
 import { protocolIdentityFailure } from "../runtime/operation-runtime.js";
 import { mapValidationOutcome } from "../runtime/outcome-mapper.js";
 import { transactionsUnavailableFailure } from "../transactions/transaction-plan-validator.js";
-import { CONTRACT_ROUTE, GET_ONLY, isProtocolPath, operationRouteSegments, POST_ONLY, readRequest, TRANSACTIONS_ROUTE, } from "./http-request.reader.js";
+import { ACCESS_CAN_ROUTE, CONTRACT_ROUTE, GET_ONLY, isProtocolPath, operationRouteSegments, POST_ONLY, readRequest, TRANSACTIONS_ROUTE, } from "./http-request.reader.js";
 import { encodeOperationResponse, } from "./http-response.encoder.js";
 import { identityHeadersMissing, transportFailure, } from "./protocol-failure.js";
 import { missingIdentityHeaders } from "./protocol-headers.js";
 import { AvUnmountedRouteError } from "./unmounted-route.error.js";
-export function resolveOperationRoute(contracts, protocol, route, origin = "client") {
+function resolveOperationRoute(contracts, protocol, route, origin = "client") {
     const identityFailure = protocolIdentityFailure(contracts, protocol, origin);
     if (identityFailure !== undefined) {
         return { ok: false, failure: identityFailure };
@@ -38,12 +39,25 @@ export function resolveOperationRoute(contracts, protocol, route, origin = "clie
     }
     return { ok: true, operation };
 }
-export function transactionsRouteFailure(contracts, protocol, origin = "client") {
+function transactionsRouteFailure(contracts, protocol, origin = "client") {
     return (protocolIdentityFailure(contracts, protocol, origin) ??
         (contracts[origin].transactions === "interactive"
             ? undefined
             : transactionsUnavailableFailure()));
 }
+function accessCanUnavailableFailure() {
+    const message = "Access questions are not available on the active Contract.";
+    return operationFailure("A2002", {
+        message,
+        issues: [validationIssue("V1006", ["questions"], message)],
+    });
+}
+function accessCanRouteFailure(contracts, protocol, origin = "client") {
+    return (protocolIdentityFailure(contracts, protocol, origin) ??
+        (contracts[origin].access === undefined
+            ? accessCanUnavailableFailure()
+            : undefined));
+}
 export function checkOperationRoute(contracts, read, origin = "client") {
     const segments = operationRouteSegments(read.request.path);
     if (segments === undefined) {
@@ -80,6 +94,21 @@ export function checkTransactionsRoute(contracts, read, origin = "client") {
         ? { ok: true, protocol: read.protocol }
         : refusedWith(transportFailure("A2012", read.requestId, POST_ONLY));
 }
+export function checkAccessCanRoute(contracts, read, origin = "client") {
+    if (read.request.path !== ACCESS_CAN_ROUTE) {
+        return refusedWith(transportFailure("A2000", read.requestId));
+    }
+    if (read.protocol === undefined) {
+        return refusedWith(identityFailureOf(read));
+    }
+    const absent = accessCanRouteFailure(contracts, read.protocol, origin);
+    if (absent !== undefined) {
+        return refusedWith(encodeOperationResponse(absent, read.requestId));
+    }
+    return read.request.method === "POST"
+        ? { ok: true, protocol: read.protocol }
+        : refusedWith(transportFailure("A2012", read.requestId, POST_ONLY));
+}
 function identityFailureOf(read) {
     return identityHeadersMissing(missingIdentityHeaders(read.headers), read.requestId);
 }
@@ -100,6 +129,10 @@ export function answerAbsentRequest(contracts, received, sink, origin = "client"
             ? unmounted(read.requestId)
             : transportFailure("A2012", read.requestId, GET_ONLY);
     }
+    if (path === ACCESS_CAN_ROUTE) {
+        const route = checkAccessCanRoute(contracts, read, origin);
+        return route.ok ? unmounted(read.requestId) : route.response;
+    }
     if (path === TRANSACTIONS_ROUTE) {
         const route = checkTransactionsRoute(contracts, read, origin);
         if (!route.ok) {

package/dist/protocol/contract-document.responder.d.ts

@@ -6,7 +6,7 @@ import type { AvProtocolResponse } from "./http-response.encoder.js";
  * entity tag, the quoted contract hash. The bytes include `protocol.hash`, although
  * the hash's own input excludes it.
  */
-export type ContractDocument = {
+type ContractDocument = {
     readonly body: string;
     readonly etag: string;
 };
@@ -17,3 +17,4 @@ export declare function contractDocumentOf(client: AvContractClient): ContractDo
  * order:
  */
 export declare function encodeContractRequest(document: ContractDocument, received: AvProtocolRequest): AvProtocolResponse;
+export {};

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 { AvRequestProtocol, RemoteOperationRequest } from "../runtime/operation-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.
@@ -71,6 +71,22 @@ export declare function decodeOperationRequest(contracts: AvContracts, received:
  * say otherwise. The body is the plan verbatim.
  */
 export declare function decodeTransactionRequest(contracts: AvContracts, received: AvProtocolRequest, origin?: RemoteRequestOrigin): DecodedTransaction;
+/** A `/_access/can` request as core answers it: its origin, identity and body. */
+type DecodedCanRequest = {
+    readonly origin: RemoteRequestOrigin;
+    readonly requestId: string;
+    readonly protocol: AvRequestProtocol;
+    /** The body, a JSON object: `{ questions }`, read by core. */
+    readonly body: object;
+};
+/**
+ * The `/_access/can` request as the request core answers, or its answer: the same
+ * steps as {@link decodeTransactionRequest}, with the path exactly `/_access/can`
+ * and its absence being a Contract without its `access` section. The body is read
+ * as a JSON object and handed to core verbatim; its `questions` are core's to
+ * judge.
+ */
+export declare function decodeCanRequest(contracts: AvContracts, received: AvProtocolRequest, origin?: RemoteRequestOrigin): Decoded<DecodedCanRequest>;
 /**
  * Whether `value` is a body this decoder parsed from raw content. Only the protocol's
  * own shortcuts ask, about a request they have just decoded, before any host code

package/dist/protocol/http-request.decoder.js

@@ -1,4 +1,4 @@
-import { checkOperationRoute, checkTransactionsRoute, } from "./absent-route.responder.js";
+import { checkAccessCanRoute, checkOperationRoute, checkTransactionsRoute, } from "./absent-route.responder.js";
 import { readRequest } from "./http-request.reader.js";
 import { transportFailure, } from "./protocol-failure.js";
 import { headerValue } from "./protocol-headers.js";
@@ -52,6 +52,29 @@ export function decodeTransactionRequest(contracts, received, origin = "client")
         }
         : refused(body.response, read.requestId);
 }
+export function decodeCanRequest(contracts, received, origin = "client") {
+    const read = readRequest(received);
+    if (!read.ok) {
+        return read;
+    }
+    const route = checkAccessCanRoute(contracts, read, origin);
+    if (!route.ok) {
+        return refused(route.response, read.requestId);
+    }
+    const body = readBody(read, contracts, origin);
+    return body.ok
+        ? {
+            ok: true,
+            request: {
+                origin,
+                requestId: read.requestId,
+                protocol: route.protocol,
+                body: body.value,
+            },
+            requestId: read.requestId,
+        }
+        : refused(body.response, read.requestId);
+}
 function refused(response, requestId) {
     return { ok: false, response, requestId };
 }