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

package/dist/config/config.validator.js

@@ -1,10 +1,15 @@
+import { isAccessPath, isAccessUrl } from "../contracts/access-route.rules.js";
 import { TRANSACTION_CAPABILITIES } from "../contracts/transaction-capability.js";
+import { ACCESS_VERB_NAMES, isAccessVerbName, providerVerb, } from "../policy/access-verb.table.js";
 import { normalizeEntrypoint } from "./entrypoint.normalizer.js";
 import { AVZ_FORMATS } from "./framework-field-definition.js";
 const ROOT_ONLY_PROPERTIES = new Set([
     "api",
     "mcp",
     "adapter",
+    "prebuilt",
+    "policy",
+    "access",
     "diagnostics",
     "misuse",
     "application",
@@ -36,6 +41,7 @@ const RESOURCE_PROPERTIES = new Set([
     "operations",
     "transactions",
     "fields",
+    "managedElsewhere",
 ]);
 const FIELD_PROPERTIES = new Set(["definition", "pipelines"]);
 const DEFINITION_PROPERTIES = new Set([
@@ -339,7 +345,16 @@ function validateResource(value, path, resource, isRoot, diagnostics) {
             continue;
         }
         if (!RESOURCE_PROPERTIES.has(key)) {
-            diagnostics.push(diagnostic("CONFIG_UNKNOWN_PROPERTY", keyPath, `unknown Resource property: ${key}; a Resource takes pipelines, operations, transactions and fields`));
+            diagnostics.push(diagnostic("CONFIG_UNKNOWN_PROPERTY", keyPath, `unknown Resource property: ${key}; a Resource takes pipelines, operations, transactions and fields (and managedElsewhere at the root)`));
+            continue;
+        }
+        if (key === "managedElsewhere") {
+            if (!isRoot) {
+                diagnostics.push(diagnostic("CONFIG_FORBIDDEN_IN_OVERLAY", keyPath, `${keyPath}: managedElsewhere is only allowed at root; it states who owns the table, which no layer changes (state it at resources.${resource}.managedElsewhere)`));
+            }
+            else if (typeof child !== "boolean") {
+                diagnostics.push(diagnostic("CONFIG_INVALID_TYPE", keyPath, `${keyPath} must be a boolean`));
+            }
             continue;
         }
         if (key === "pipelines") {
@@ -618,6 +633,20 @@ export function validateFrameworkConfig(value) {
     else {
         validateAdapter(value.adapter, diagnostics);
     }
+    if (Object.hasOwn(value, "prebuilt") &&
+        value.prebuilt !== undefined &&
+        (value.prebuilt === null || typeof value.prebuilt !== "object")) {
+        diagnostics.push(diagnostic("CONFIG_INVALID_TYPE", "prebuilt", "prebuilt must be the generated prebuilt Contracts object when provided"));
+    }
+    if (Object.hasOwn(value, "policy") && value.policy !== undefined) {
+        validatePolicy(value.policy, diagnostics);
+    }
+    if (Object.hasOwn(value, "access") && value.access !== undefined) {
+        validateAccess(value.access, diagnostics);
+        if (Object.hasOwn(value, "policy") && value.policy !== undefined) {
+            diagnostics.push(diagnostic("CONFIG_INVALID_VALUE", "policy", "policy cannot be configured with access: access.policy is the policy engine, and ctx.$state.me the principal; remove policy"));
+        }
+    }
     if (Object.hasOwn(value, "diagnostics") &&
         value.diagnostics !== undefined &&
         typeof value.diagnostics !== "function") {
@@ -639,6 +668,155 @@ export function validateFrameworkConfig(value) {
     }
     return diagnostics;
 }
+const POLICY_PROPERTIES = new Set(["engine", "principal"]);
+function validatePolicy(value, diagnostics) {
+    if (!isPlainRecord(value)) {
+        diagnostics.push(diagnostic("CONFIG_INVALID_TYPE", "policy", "policy must be { engine, principal }"));
+        return;
+    }
+    for (const key of Object.keys(value)) {
+        if (!POLICY_PROPERTIES.has(key)) {
+            diagnostics.push(diagnostic("CONFIG_UNKNOWN_PROPERTY", `policy.${key}`, `unknown policy property: ${key}`));
+        }
+    }
+    if (!Object.hasOwn(value, "principal")) {
+        diagnostics.push(diagnostic("CONFIG_REQUIRED", "policy.principal", "policy.principal is required"));
+    }
+    else if (typeof value.principal !== "function") {
+        diagnostics.push(diagnostic("CONFIG_INVALID_TYPE", "policy.principal", "policy.principal must be a function"));
+    }
+    if (!Object.hasOwn(value, "engine")) {
+        diagnostics.push(diagnostic("CONFIG_REQUIRED", "policy.engine", "policy.engine is required"));
+        return;
+    }
+    validatePolicyEngine(value.engine, "policy.engine", diagnostics);
+}
+function validateAccess(value, diagnostics) {
+    if (value === null || typeof value !== "object") {
+        diagnostics.push(diagnostic("CONFIG_INVALID_TYPE", "access", "access must be an access provider, { policy, state }"));
+        return;
+    }
+    const provider = value;
+    if (typeof provider.state !== "function") {
+        diagnostics.push(diagnostic("CONFIG_INVALID_TYPE", "access.state", "access.state must be a function"));
+    }
+    if (provider.client !== undefined) {
+        validateAccessClient(provider.client, diagnostics);
+    }
+    if (provider.policy === undefined) {
+        diagnostics.push(diagnostic("CONFIG_REQUIRED", "access.policy", "access.policy is required"));
+        return;
+    }
+    validatePolicyEngine(provider.policy, "access.policy", diagnostics);
+}
+function validateAccessClient(value, diagnostics) {
+    if (value === null || typeof value !== "object") {
+        diagnostics.push(diagnostic("CONFIG_INVALID_TYPE", "access.client", "access.client must be an object, { url, verbs }"));
+        return;
+    }
+    const client = value;
+    if (!isAccessUrl(client.url)) {
+        diagnostics.push(diagnostic("CONFIG_INVALID_VALUE", "access.client.url", 'access.client.url must be an absolute http(s) URL or a root-relative path ("/api/auth")'));
+    }
+    const verbs = client.verbs;
+    if (verbs === null || typeof verbs !== "object") {
+        diagnostics.push(diagnostic("CONFIG_INVALID_TYPE", "access.client.verbs", `access.client.verbs must be an object of $access verbs (${ACCESS_VERB_NAMES.join(", ")})`));
+        return;
+    }
+    for (const name of ACCESS_VERB_NAMES) {
+        const verb = providerVerb(verbs, name);
+        if (verb !== undefined) {
+            validateAccessVerb(verb, `access.client.verbs.${name}`, diagnostics);
+        }
+    }
+    for (const name of Object.keys(verbs)) {
+        if (!isAccessVerbName(name)) {
+            diagnostics.push(diagnostic("CONFIG_UNKNOWN_PROPERTY", `access.client.verbs.${name}`, `access.client.verbs.${name} is not a $access verb`));
+        }
+    }
+}
+function validateAccessVerb(value, path, diagnostics) {
+    if (value === null || typeof value !== "object") {
+        diagnostics.push(diagnostic("CONFIG_INVALID_TYPE", path, `${path} must be an object, { method, path, args?, result, call }`));
+        return;
+    }
+    const verb = value;
+    if (verb.method !== "GET" && verb.method !== "POST") {
+        diagnostics.push(diagnostic("CONFIG_INVALID_VALUE", `${path}.method`, `${path}.method must be "GET" or "POST"`));
+    }
+    if (!isAccessPath(verb.path)) {
+        diagnostics.push(diagnostic("CONFIG_INVALID_VALUE", `${path}.path`, `${path}.path must be a path under access.client.url, starting with one "/"`));
+    }
+    for (const schema of ["args", "result"]) {
+        const given = verb[schema];
+        if ((schema === "result" || given !== undefined) && !isPlainRecord(given)) {
+            diagnostics.push(diagnostic("CONFIG_INVALID_TYPE", `${path}.${schema}`, `${path}.${schema} must be a JSON Schema object`));
+        }
+    }
+    if (typeof verb.call !== "function") {
+        diagnostics.push(diagnostic("CONFIG_INVALID_TYPE", `${path}.call`, `${path}.call must be a function`));
+    }
+}
+function validatePolicyEngine(engine, at, diagnostics) {
+    if (engine === null || typeof engine !== "object") {
+        diagnostics.push(diagnostic("CONFIG_INVALID_TYPE", at, `${at} must be an object`));
+        return;
+    }
+    const members = engine;
+    for (const question of ["can", "scopeOf", "fieldsOf"]) {
+        if (typeof members[question] !== "function") {
+            diagnostics.push(diagnostic("CONFIG_INVALID_TYPE", `${at}.${question}`, `${at}.${question} must be a function`));
+        }
+    }
+    for (const optional of ["grantsOf", "hosted"]) {
+        if (members[optional] !== undefined &&
+            typeof members[optional] !== "function") {
+            diagnostics.push(diagnostic("CONFIG_INVALID_TYPE", `${at}.${optional}`, `${at}.${optional} must be a function when present`));
+        }
+    }
+    validatePolicyLists(members.governed, at, "governed", { all: "string lists", one: "a list of strings" }, isStringList, diagnostics);
+    validatePolicyLists(members.paths, at, "paths", {
+        all: "path lists",
+        one: "a list of paths, each a list of strings",
+    }, (paths) => Array.isArray(paths) && paths.every(isStringList), diagnostics);
+    validatePolicyLists(members.afterChecks, at, "afterChecks", { all: "action lists", one: "a list of actions" }, isStringList, diagnostics);
+    validateAfterCheckActions(members.afterChecks, at, diagnostics);
+    if (members.unheld !== undefined && !isStringList(members.unheld)) {
+        diagnostics.push(diagnostic("CONFIG_INVALID_TYPE", `${at}.unheld`, `${at}.unheld must be a list of Resource names when provided`));
+    }
+}
+function validateAfterCheckActions(lists, at, diagnostics) {
+    if (!isPlainRecord(lists)) {
+        return;
+    }
+    for (const [resource, actions] of Object.entries(lists)) {
+        if (!isStringList(actions)) {
+            continue;
+        }
+        for (const action of actions) {
+            if (action !== "update") {
+                diagnostics.push(diagnostic("CONFIG_INVALID_VALUE", `${at}.afterChecks.${resource}`, `${at}.afterChecks.${resource}: "${action}" is no action an after check runs on; only "update" is`));
+            }
+        }
+    }
+}
+function isStringList(value) {
+    return (Array.isArray(value) && value.every((name) => typeof name === "string"));
+}
+function validatePolicyLists(lists, at, list, entry, isEntry, diagnostics) {
+    if (lists === undefined) {
+        return;
+    }
+    if (!isPlainRecord(lists)) {
+        diagnostics.push(diagnostic("CONFIG_INVALID_TYPE", `${at}.${list}`, `${at}.${list} must be an object of ${entry.all} when provided`));
+        return;
+    }
+    for (const [key, value] of Object.entries(lists)) {
+        if (!isEntry(value)) {
+            diagnostics.push(diagnostic("CONFIG_INVALID_TYPE", `${at}.${list}.${key}`, `${at}.${list}.${key} must be ${entry.one}`));
+        }
+    }
+}
 function validateMcp(value, api, diagnostics) {
     if (typeof value === "string") {
         validateMcpPath(value, "mcp", api, diagnostics);
@@ -704,9 +882,10 @@ function validateMcpAuthorization(value, diagnostics) {
     }
     else {
         value.servers.forEach((server, index) => {
-            if (!isHttpsUrl(server)) {
-                const serverPath = `${serversPath}[${index}]`;
-                diagnostics.push(diagnostic("CONFIG_INVALID_VALUE", serverPath, `${serverPath} must be an absolute https URL`));
+            const serverPath = `${serversPath}[${index}]`;
+            const refusal = authorizationServerRefusal(server, serverPath);
+            if (refusal !== undefined) {
+                diagnostics.push(diagnostic("CONFIG_INVALID_VALUE", serverPath, refusal));
             }
         });
     }
@@ -718,14 +897,49 @@ function validateMcpAuthorization(value, diagnostics) {
         diagnostics.push(diagnostic("CONFIG_INVALID_TYPE", verifyPath, `${verifyPath} must be a function: token in, the caller or null out`));
     }
 }
-function isHttpsUrl(value) {
+const LOOPBACK_HOSTNAMES = new Set(["127.0.0.1", "[::1]"]);
+const LOOPBACK_NAME = "localhost";
+function authorizationServerRefusal(value, path) {
+    const notHttps = `${path} must be an absolute https URL`;
     if (typeof value !== "string") {
-        return false;
+        return notHttps;
     }
+    let url;
     try {
-        return new URL(value).protocol === "https:";
+        url = new URL(value);
     }
     catch {
-        return false;
+        return notHttps;
+    }
+    const http = url.protocol === "http:";
+    if (!http && url.protocol !== "https:") {
+        return notHttps;
+    }
+    if (http &&
+        ((!LOOPBACK_HOSTNAMES.has(url.hostname) &&
+            url.hostname !== LOOPBACK_NAME) ||
+            url.username !== "" ||
+            url.password !== "")) {
+        return notHttps;
+    }
+    if (url.pathname.includes("//")) {
+        return `${path} has an empty path segment ("//"); a client can read what follows it as another host`;
+    }
+    if (url.port === "0") {
+        return `${path} names port 0, which no server listens on`;
+    }
+    if (url.href.includes("?") || url.href.includes("#")) {
+        return `${path} has a query or fragment; an authorization server's URL (its issuer) takes neither`;
+    }
+    if (!http) {
+        return undefined;
+    }
+    if (url.hostname === LOOPBACK_NAME) {
+        url.hostname = "127.0.0.1";
     }
+    const canonical = url.href;
+    const short = canonical === `${url.origin}/` ? url.origin : canonical;
+    return value === canonical || value === short
+        ? undefined
+        : `${path} is an http loopback URL; write it as ${short}, the spelling every client reads as this machine`;
 }

package/dist/config/define-resource.d.ts

@@ -16,10 +16,6 @@ type OverlayLayer = "application" | "client" | "agent";
 type ResourceOverlays = {
     readonly [L in OverlayLayer]?: unknown;
 };
-/** The overlay blocks `Overlays`, each checked against the root `Block`. */
-type CheckedOverlays<M extends AvAdapterModel, R extends AvConfigResourceKey<M>, Block, Overlays> = {
-    readonly [L in keyof Overlays]: L extends OverlayLayer ? NoInfer<AvConfigResource<M, ResourceBlockConfig<R, Block>, R, "overlay"> & ExactOverlayResource<M, ResourceBlockConfig<R, Block>, R, Overlays[L]>> : never;
-};
 /**
  * What {@link defineResource} returns: `root`, and `application`, `client` and
  * `agent` exactly when they were given, each `{ [R]: block }` to spread into that
@@ -53,5 +49,5 @@ export type AvDefinedResource<R extends string, Block, Overlays> = {
  * client: { resources: { ...post.client } },
  * ```
  */
-export declare function defineResource<M extends AvAdapterModel>(): <const R extends AvConfigResourceKey<M>, const Block = AvConfigResource<M, AvConfigAny, R, "root">, const Overlays extends ResourceOverlays = Record<never, never>>(resource: R, block: Block & NoInfer<AvConfigResource<M, ResourceBlockConfig<R, Block>, R, "root"> & ExactRootResource<M, R, Block>>, overlays?: Overlays & CheckedOverlays<M, R, Block, Overlays>) => AvDefinedResource<R, ErasedResourceBlock<Block>, ErasedOverlayBlocks<Overlays>>;
+export declare function defineResource<M extends AvAdapterModel>(): <const R extends AvConfigResourceKey<M>, const Block = AvConfigResource<M, AvConfigAny, R, "root">, const Overlays extends ResourceOverlays = Record<never, never>>(resource: R, block: Block & NoInfer<AvConfigResource<M, ResourceBlockConfig<R, Block>, R, "root"> & ExactRootResource<M, R, Block>>, overlays?: Overlays & { readonly [L in keyof Overlays]: L extends OverlayLayer ? NoInfer<AvConfigResource<M, ResourceBlockConfig<R, Block>, R, "overlay", L> & ExactOverlayResource<M, ResourceBlockConfig<R, Block>, R, Overlays[L]>> : never; }) => AvDefinedResource<R, ErasedResourceBlock<Block>, ErasedOverlayBlocks<Overlays>>;
 export {};

package/dist/config/entrypoint.normalizer.d.ts

@@ -4,7 +4,7 @@
  * Root is the empty string, not `"/"`, so a route joins onto it by concatenation with
  * no special case.
  */
-export type EntrypointPath = "" | `/${string}`;
+type EntrypointPath = "" | `/${string}`;
 /**
  * Why a mount path is refused. Only the slash spelling is ever coerced
  * (`api`, `/api/` and `//api//` are one intent, `/api`); everything else that is
@@ -17,7 +17,7 @@ export type EntrypointRefusalReason = "whitespace" | "scheme" | "query" | "fragm
  * and the rule, and never echoes the value: an entrypoint may carry
  * credentials (the client's rule, shared by the server).
  */
-export type EntrypointNormalization = {
+type EntrypointNormalization = {
     readonly ok: true;
     readonly path: EntrypointPath;
 } | {
@@ -30,3 +30,4 @@ export type EntrypointNormalization = {
  * or a refusal.
  */
 export declare function normalizeEntrypoint(value: string): EntrypointNormalization;
+export {};

package/dist/config/exact-framework-config.d.ts

@@ -103,9 +103,11 @@ type TokenOf<Member> = Member extends {
 } ? {
     [K in keyof Member]: K extends "scopes" ? never : Member[K] extends readonly (infer Token)[] ? Token : never;
 }[keyof Member] : Member extends readonly (infer Token)[] ? Token : never;
+/** The capability members an exemption never names. */
+type AdapterStatedMember = "nestedWriteFilter" | "filterModes" | "pathFilterModes";
 /** A field's exemption against its capabilities: their names, and each one's tokens. */
-type CapabilityExemptionSchema<Caps> = ListOf<Exclude<keyof Caps, "nestedWriteFilter">> & {
-    readonly [K in Exclude<keyof Caps, "nestedWriteFilter">]-?: ListOf<TokenOf<NonNullable<Caps[K]>>>;
+type CapabilityExemptionSchema<Caps> = ListOf<Exclude<keyof Caps, AdapterStatedMember>> & {
+    readonly [K in Exclude<keyof Caps, AdapterStatedMember>]-?: ListOf<TokenOf<NonNullable<Caps[K]>>>;
 };
 type FieldExemptionSchema<M extends AvAdapterModel, R extends AvConfigResourceKey<M>, F> = F extends AvAdapterFieldKey<M, R> ? M["resources"][R]["fields"][F] extends {
     readonly kind: "relation";
@@ -131,33 +133,58 @@ type ExemptionsSchema<M extends AvAdapterModel, Cfg> = {
         };
     };
 };
-/** A Pick overlay's exemptions, against the root's view. */
-type PickExemptionsSchema<Resources> = {
+declare const refusal: unique symbol;
+/** What a level refuses an unknown key for: `layer` cannot expose it, `parent` hid it, under `at`. */
+type Refusal<Layer extends string, Parent extends string, At extends string> = {
+    readonly [refusal]: {
+        readonly layer: Layer;
+        readonly parent: Parent;
+        readonly at: At;
+    };
+};
+/** The sentence a refused key `K` holding `Value` is typed as; `never` for an entry written `false`. */
+type RefusalOf<Info, K, Value> = [Value] extends [false] ? never : Info extends {
+    readonly layer: infer Layer extends string;
+    readonly parent: infer Parent extends string;
+    readonly at: infer At extends string;
+} ? Value extends readonly unknown[] ? {
+    readonly [S in `Error: ${Layer} cannot expose '${At}${K & string}': hidden by ${Parent}`]: true;
+} : readonly [
+    `Error: ${Layer} cannot expose '${At}${K & string}': hidden by ${Parent}`
+] : never;
+/** A Pick layer's operations exemption, a family or variant its parent hid refused by name. */
+type PickOperationsSchema<Ops, Layer extends string, Parent extends string, R extends string> = ListOf<keyof Ops> & {
+    readonly [F in keyof Ops]-?: ListOf<keyof NonNullable<Ops[F]>> & {
+        readonly [V in keyof NonNullable<Ops[F]>]: Leaf;
+    } & Refusal<Layer, Parent, `${R}.${F & string}.`>;
+} & Refusal<Layer, Parent, `${R}.`>;
+/** The fields of one Resource of a view. */
+type ViewFields<Resource> = Resource extends {
+    readonly fields: infer Fields;
+} ? Fields : never;
+/** A Pick layer's exemptions, against its parent's view. */
+type PickExemptionsSchema<Resources, Layer extends string, Parent extends string> = {
     readonly resources: {
         readonly [R in keyof Resources]: {
-            readonly operations: OperationsExemptionSchema<Resources[R] extends {
+            readonly operations: PickOperationsSchema<Resources[R] extends {
                 readonly operations: infer Ops;
-            } ? Ops : never>;
+            } ? Ops : never, Layer, Parent, R & string>;
             readonly fields: {
-                readonly [F in keyof (Resources[R] extends {
-                    readonly fields: infer Fields;
-                } ? Fields : never)]: CapabilityExemptionSchema<(Resources[R] extends {
-                    readonly fields: infer Fields;
-                } ? Fields : never)[F] extends {
+                readonly [F in keyof ViewFields<Resources[R]>]: CapabilityExemptionSchema<ViewFields<Resources[R]>[F] extends {
                     readonly capabilities: infer Caps;
-                } ? Caps : never>;
-            };
+                } ? Caps : never> & Refusal<Layer, Parent, `${R & string}.${F & string}.`>;
+            } & Refusal<Layer, Parent, `${R & string}.`>;
         };
-    };
+    } & Refusal<Layer, Parent, "">;
 };
 /** A layer's own configuration: `application`, `client` or `agent`. */
 type OverlayOf<Cfg, Layer extends "application" | "client" | "agent"> = (Cfg & {
     readonly [L in Layer]?: unknown;
 })[Layer];
 /** An overlay's exemptions schema, by the overlay's own `exposed`. */
-type OverlayExemptionsSchema<M extends AvAdapterModel, Cfg, Overlay> = Overlay extends {
+type OverlayExemptionsSchema<M extends AvAdapterModel, Cfg, Overlay, Layer extends "application" | "client"> = Overlay extends {
     readonly exposed: false;
-} ? PickExemptionsSchema<RootViewResources<M, Cfg>> : ExemptionsSchema<M, Cfg>;
+} ? PickExemptionsSchema<RootViewResources<M, Cfg>, Layer, "root"> : ExemptionsSchema<M, Cfg>;
 type LayerKeysSchema = {
     readonly exposed: Leaf;
     readonly transactionsStyle: Leaf;
@@ -167,7 +194,9 @@ type LayerKeysSchema = {
 type RootResourcesSchema<M extends AvAdapterModel> = {
     readonly [R in AvConfigResourceKey<M>]: ResourceSchema<M, R, FieldsSchema<M, R, "root", AvAdapterFieldKey<M, R>> & {
         readonly [otherKeys]: RootScalarFieldSchema;
-    }>;
+    }> & {
+        readonly managedElsewhere: Leaf;
+    };
 };
 /**
  * One root `resources.<R>` block, checked key by key as
@@ -183,7 +212,7 @@ type OverlaySchema<M extends AvAdapterModel, Cfg, Layer extends "application" |
     readonly resources: {
         readonly [R in AvConfigResourceKey<M>]: ResourceSchema<M, R, FieldsSchema<M, R, "overlay", AvEffectiveFieldKey<M, Cfg, R>>>;
     };
-    readonly exemptions: OverlayExemptionsSchema<M, Cfg, OverlayOf<Cfg, Layer>>;
+    readonly exemptions: OverlayExemptionsSchema<M, Cfg, OverlayOf<Cfg, Layer>, Layer>;
 };
 type McpSchema = {
     readonly path: Leaf;
@@ -197,7 +226,7 @@ type AgentParentOf<Cfg> = OverlayOf<Cfg, "agent"> extends {
     readonly extends: infer Parent;
 } ? Parent : "client";
 /** A Pick agent's exemptions, against the view of the layer it extends. */
-type AgentPickExemptionsSchema<M extends AvAdapterModel, Cfg, Parent> = Parent extends "application" | "client" ? [Parent] extends ["application"] | ["client"] ? PickExemptionsSchema<OverlayViewResources<M, Cfg, Parent>> : PickExemptionsSchema<RootViewResources<M, Cfg>> : PickExemptionsSchema<RootViewResources<M, Cfg>>;
+type AgentPickExemptionsSchema<M extends AvAdapterModel, Cfg, Parent> = Parent extends "application" | "client" ? [Parent] extends ["application"] | ["client"] ? PickExemptionsSchema<OverlayViewResources<M, Cfg, Parent>, "agent", Parent> : PickExemptionsSchema<RootViewResources<M, Cfg>, "agent", "root"> : PickExemptionsSchema<RootViewResources<M, Cfg>, "agent", "root">;
 type AgentSchema<M extends AvAdapterModel, Cfg> = LayerKeysSchema & {
     readonly extends: Leaf;
     readonly resources: {
@@ -211,6 +240,12 @@ type RootSchema<M extends AvAdapterModel, Cfg> = LayerKeysSchema & {
     readonly api: Leaf;
     readonly mcp: McpSchema;
     readonly adapter: Leaf;
+    readonly prebuilt: Leaf;
+    readonly policy: {
+        readonly engine: Leaf;
+        readonly principal: Leaf;
+    };
+    readonly access: Leaf;
     readonly diagnostics: Leaf;
     readonly misuse: Leaf;
     readonly resources: RootResourcesSchema<M>;
@@ -219,9 +254,12 @@ type RootSchema<M extends AvAdapterModel, Cfg> = LayerKeysSchema & {
     readonly client: OverlaySchema<M, Cfg, "client">;
     readonly agent: AgentSchema<M, Cfg>;
 };
-/** `V` with every key schema `S` lacks mapped to `never`; every leaf `unknown`. */
+/**
+ * `V` with every key schema `S` lacks mapped to `never`, or to the sentence a
+ * refusing level states; every leaf `unknown`.
+ */
 type Exact<S, V> = [S] extends [Leaf] ? unknown : V extends readonly unknown[] ? S extends ListOf<infer Names> ? readonly Names[] : unknown : V extends (...args: any) => any ? unknown : V extends object ? string extends keyof V ? unknown : {
-    readonly [K in keyof V]: K extends keyof S ? Exact<S[K], V[K]> : typeof otherKeys extends keyof S ? Exact<S[typeof otherKeys], V[K]> : never;
+    readonly [K in keyof V]: K extends keyof S ? Exact<S[K], V[K]> : typeof otherKeys extends keyof S ? Exact<S[typeof otherKeys], V[K]> : typeof refusal extends keyof S ? RefusalOf<S[typeof refusal], K, V[K]> : never;
 } : unknown;
 /**
  * The authored configuration `Cfg`, checked key by key: a key no level of the
@@ -229,7 +267,14 @@ type Exact<S, V> = [S] extends [Leaf] ? unknown : V extends readonly unknown[] ?
  * rc.0 key, a `definition` in an overlay, a stage a relation field does not take,
  * or a name the model and the root do not have.
  */
-export type AvConfigExact<M extends AvAdapterModel, Cfg> = Exact<RootSchema<M, Cfg>, Cfg> & ExposedWithExemptions<Cfg, "application"> & ExposedWithExemptions<Cfg, "client"> & ExposedWithExemptions<Cfg, "agent"> & ForceNeedsTransactions<M, Cfg>;
+export type AvConfigExact<M extends AvAdapterModel, Cfg> = Exact<RootSchema<M, Cfg>, Cfg> & ExposedWithExemptions<Cfg, "application"> & ExposedWithExemptions<Cfg, "client"> & ExposedWithExemptions<Cfg, "agent"> & ForceNeedsTransactions<M, Cfg> & (Cfg extends {
+    readonly access: object;
+    readonly policy: object;
+} ? {
+    readonly policy: readonly [
+        "Error: `access` brings the policy engine; remove `policy`"
+    ];
+} : unknown);
 /** A layer's own literal `transactionsStyle`, `undefined` when it states none. */
 type StyleOf<Layer> = Layer extends {
     readonly transactionsStyle: infer Style;

package/dist/config/field-compute.resolver.d.ts

@@ -17,3 +17,5 @@ export declare function computeOfLayer(resources: unknown): ResolvedComputeConfi
  * chained phase by phase. Nothing is disabled from below.
  */
 export declare function chainCompute(root: ResolvedComputeConfig, overlay: ResolvedComputeConfig): ResolvedComputeConfig;
+/** The fields of `resource` with a `compute.create` stage in `compute`. */
+export declare function createComputedFields(compute: ResolvedComputeConfig, resource: string): ReadonlySet<string>;

package/dist/config/field-compute.resolver.js

@@ -113,3 +113,11 @@ export function chainCompute(root, overlay) {
     }
     return result;
 }
+export function createComputedFields(compute, resource) {
+    const fields = Object.hasOwn(compute, resource)
+        ? compute[resource]
+        : undefined;
+    return new Set(Object.entries(fields ?? {})
+        .filter(([, phases]) => phases.create !== undefined)
+        .map(([field]) => field));
+}

package/dist/config/framework-config.d.ts

@@ -2,19 +2,28 @@ import type { AvAdapter } from "../adapters/adapter.interface.js";
 import type { AvAdapterModel } from "../adapters/adapter-model.js";
 import type { AvContractLimits } from "../contracts/contract-limits.js";
 import type { AvTransactionCapability } from "../contracts/transaction-capability.js";
+import type { AvAccessProvider } from "../policy/access-provider.interface.js";
+import type { AvPolicyEngine } from "../policy/policy-engine.js";
+import type { AvPrebuiltContracts } from "../prebuilt/prebuilt-contracts.js";
 import type { AvDiagnosticsSink } from "../runtime/diagnostics-reporter.js";
 import type { AvMisuseSink } from "../runtime/misuse-reporter.js";
+import type { AvState } from "../runtime/request-state.js";
 import type { AvConfigAny } from "./any-framework-config.js";
+import type { AvConfigLayerName, AvRequestOrigin } from "./config-layer.js";
 import type { AvConfigExemptions } from "./framework-exemptions-config.js";
-import type { AvConfigLayerKind, AvConfigResources } from "./framework-resources-config.js";
+import type { AvConfigLayerKind, AvConfigResources, LayerOfKind } from "./framework-resources-config.js";
 import type { AvPipeline } from "./pipeline-config.js";
 /**
  * Request limits to override; each one left out takes its default from
  * {@link DEFAULT_CONTRACT_LIMITS}.
  */
 export type AvConfigLimits = Partial<AvContractLimits>;
-/** rc.0's layer keys, each refused with its rc.1 location. */
-type MovedLayerKeys = {
+/**
+ * The six keys every layer holds: the root, `application`, `client` and
+ * `agent`. Stages are added to the root's; `transactionsStyle` and `limits`
+ * replace it where an overlay states them; exposure only narrows.
+ */
+export type AvConfigLayer<M extends AvAdapterModel = AvAdapterModel, Cfg = AvConfigAny, Kind extends AvConfigLayerKind = "root", Layer extends AvConfigLayerName = LayerOfKind<Kind>> = {
     /** Moved: `exposed` + `exemptions`. */
     readonly restrictions?: never;
     /** Moved: `resources.<R>.fields.<f>.pipelines.compute`. */
@@ -23,13 +32,6 @@ type MovedLayerKeys = {
     readonly fields?: never;
     /** Moved: `transactionsStyle`. */
     readonly transactions?: never;
-};
-/**
- * The six keys every layer holds: the root, `application`, `client` and
- * `agent`. Stages are added to the root's; `transactionsStyle` and `limits`
- * replace it where an overlay states them; exposure only narrows.
- */
-export type AvConfigLayer<M extends AvAdapterModel = AvAdapterModel, Cfg = AvConfigAny, Kind extends AvConfigLayerKind = "root"> = MovedLayerKeys & {
     /**
      * Whether the layer's `exemptions` hide (`true`, the root's default) or are
      * the only entries exposed (`false`). Each layer narrows its parent: the root
@@ -43,7 +45,7 @@ export type AvConfigLayer<M extends AvAdapterModel = AvAdapterModel, Cfg = AvCon
     /** Guards, pipes, hooks, interceptors and filters run around every operation of the layer. */
     readonly pipelines?: AvPipeline<NoInfer<M>>;
     /** The per-Resource tree: stages, operations, transactions and fields. */
-    readonly resources?: AvConfigResources<M, Cfg, Kind>;
+    readonly resources?: AvConfigResources<M, Cfg, Kind, Layer>;
     /**
      * The entries that are the opposite of `exposed`. An overlay that sets them
      * states its own `exposed`.
@@ -70,11 +72,45 @@ export type AvConfig<M extends AvAdapterModel = AvAdapterModel, Cfg = AvConfigAn
      */
     readonly mcp?: AvConfigMcp;
     readonly adapter: AvAdapter<M>;
+    /**
+     * Contracts compiled ahead of time (the generated `aventaraContracts`), for a
+     * fast cold start on serverless and edge platforms. Used only when they were
+     * compiled from this configuration and the adapter's model by this core;
+     * otherwise the Contracts are compiled at startup, as without it, and a
+     * `AVENTARA_PREBUILT_STALE` warning says why.
+     */
+    readonly prebuilt?: AvPrebuiltContracts;
+    /**
+     * The policy engine every client and agent request is checked against, and
+     * how a request's principal is derived from its `ctx.$state`. Application
+     * calls bypass it unless they name a principal (`{ as }`); calls a stage
+     * makes through `ctx` always do.
+     */
+    readonly policy?: {
+        readonly engine: AvPolicyEngine;
+        /**
+         * The request's principal, from its `ctx.$state` and its layer; `null` for
+         * an anonymous caller. It may answer with a promise (rc.5), which is
+         * awaited; a throw or a rejection answers `A3000`.
+         */
+        readonly principal: (facts: {
+            readonly $state: AvState;
+            readonly $origin: AvRequestOrigin;
+        }) => unknown;
+    };
+    /**
+     * The access provider (Aventara Access, or one written by hand): its
+     * `policy` engine checks every client and agent request, with
+     * `ctx.$state.me` as the principal, and the host seeds each request's
+     * `ctx.$state` with its `state`. Not together with `policy`, nor with a
+     * host's own `state` option.
+     */
+    readonly access?: AvAccessProvider;
     readonly diagnostics?: AvDiagnosticsSink;
     /** Told about every caller value refused as unreadable or not plain data. */
     readonly misuse?: AvMisuseSink;
-    readonly application?: AvConfigLayer<M, Cfg, "overlay">;
-    readonly client?: AvConfigLayer<M, Cfg, "overlay">;
+    readonly application?: AvConfigLayer<M, Cfg, "overlay", "application">;
+    readonly client?: AvConfigLayer<M, Cfg, "overlay", "client">;
     /**
      * The layer an AI agent's calls run under. It narrows the view of the layer it
      * `extends` (the client's when left out), and its stages run after that
@@ -95,7 +131,9 @@ export type AvConfigMcp = string | {
     readonly authorization?: {
         /**
          * The authorization servers (https URLs) a caller obtains its token
-         * from, advertised in the endpoint's protected-resource metadata.
+         * from, advertised in the endpoint's protected-resource metadata. A
+         * server on this machine may be http: `http://127.0.0.1` or
+         * `http://[::1]`, with any port and path (not `localhost`).
          */
         readonly servers: readonly string[];
         /**
@@ -109,7 +147,7 @@ export type AvConfigMcp = string | {
  * The `agent` layer: the six layer keys, and `extends`, the layer whose final
  * view it narrows and whose stages run before its own.
  */
-export type AvConfigAgentLayer<M extends AvAdapterModel = AvAdapterModel, Cfg = AvConfigAny> = AvConfigLayer<M, Cfg, "overlay"> & {
+export type AvConfigAgentLayer<M extends AvAdapterModel = AvAdapterModel, Cfg = AvConfigAny> = AvConfigLayer<M, Cfg, "overlay", "agent"> & {
     /**
      * The layer the agent starts from: `"client"` (the default), `"application"`
      * or `"root"`. The agent never widens it.