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

package/dist/config/config.validator.js

@@ -1,34 +1,82 @@
+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";
-const ROOT_PROPERTIES = new Set([
-    "entrypoint",
+import { AVZ_FORMATS } from "./framework-field-definition.js";
+const ROOT_ONLY_PROPERTIES = new Set([
+    "api",
+    "mcp",
     "adapter",
-    "fields",
-    "behaviors",
-    "restrictions",
-    "limits",
-    "pipelines",
-    "transactions",
+    "prebuilt",
+    "policy",
+    "access",
     "diagnostics",
     "misuse",
     "application",
     "client",
+    "agent",
 ]);
-const SCOPE_PROPERTIES = new Set([
-    "fields",
-    "behaviors",
-    "restrictions",
+const MOVED_ROOT_PROPERTIES = new Map([
+    ["entrypoint", "api"],
+]);
+const AGENT_PARENTS = new Set(["root", "application", "client"]);
+const MCP_PROPERTIES = new Set(["path", "authorization"]);
+const MCP_AUTHORIZATION_PROPERTIES = new Set(["servers", "verify"]);
+const LAYER_PROPERTIES = new Set([
+    "exposed",
+    "transactionsStyle",
     "limits",
     "pipelines",
+    "resources",
+    "exemptions",
+]);
+const MOVED_LAYER_PROPERTIES = new Map([
+    ["restrictions", ["exposed", "exemptions"]],
+    ["behaviors", ["resources.<Resource>.fields.<field>.pipelines.compute"]],
+    ["fields", ["resources.<Resource>.fields.<field>.definition"]],
+    ["transactions", ["transactionsStyle"]],
+]);
+const RESOURCE_PROPERTIES = new Set([
+    "pipelines",
+    "operations",
     "transactions",
+    "fields",
+    "managedElsewhere",
 ]);
+const FIELD_PROPERTIES = new Set(["definition", "pipelines"]);
+const DEFINITION_PROPERTIES = new Set([
+    "type",
+    "nullable",
+    "list",
+    "lifecycle",
+    "format",
+    "capabilities",
+    "json",
+]);
+const COMPUTE_PHASES = new Set(["create", "read", "update"]);
+const FIELD_PIPELINE_PROPERTIES = new Set([
+    "validators",
+    "pipes",
+    "compute",
+    "guards",
+]);
+const OPERATION_FAMILIES = new Set([
+    "find",
+    "create",
+    "update",
+    "delete",
+    "upsert",
+]);
+const OPERATION_VARIANTS = new Set(["first", "unique", "many", "count", "one"]);
 const TRANSACTION_CAPABILITY_SET = new Set(TRANSACTION_CAPABILITIES);
+const AVZ_FORMAT_SET = new Set(AVZ_FORMATS);
 const LIMIT_PROPERTIES = new Set([
     "maxRequestBytes",
     "maxNestingDepth",
     "maxListLimit",
     "maxTransactionOperations",
     "maxBooleanNodes",
+    "maxJsonDepth",
 ]);
 const PIPELINE_PROPERTIES = new Set([
     "guards",
@@ -48,20 +96,21 @@ function isPlainRecord(value) {
 function diagnostic(code, path, message) {
     return { code, path, message };
 }
-export function entrypointRefusalDiagnostic(message) {
-    return diagnostic("CONFIG_INVALID_VALUE", "entrypoint", `entrypoint ${message}`);
+function childPath(path, key) {
+    return path === "" ? key : `${path}.${key}`;
 }
-function validateNamedObject(owner, key, path, diagnostics) {
-    if (!Object.hasOwn(owner, key)) {
-        return;
-    }
-    if (!isPlainRecord(owner[key])) {
-        diagnostics.push(diagnostic("CONFIG_INVALID_TYPE", path, `${path} must be an object`));
+export function mountPathRefusalDiagnostic(path, message) {
+    return diagnostic("CONFIG_INVALID_VALUE", path, `${path} ${message}`);
+}
+function requireRecord(value, path, diagnostics) {
+    if (isPlainRecord(value)) {
+        return true;
     }
+    diagnostics.push(diagnostic("CONFIG_INVALID_TYPE", path, `${path} must be an object`));
+    return false;
 }
 function validateLimits(value, path, diagnostics) {
-    if (!isPlainRecord(value)) {
-        diagnostics.push(diagnostic("CONFIG_INVALID_TYPE", path, `${path} must be an object`));
+    if (!requireRecord(value, path, diagnostics)) {
         return;
     }
     for (const [key, limit] of Object.entries(value)) {
@@ -78,7 +127,7 @@ function validateLimits(value, path, diagnostics) {
         }
     }
 }
-function validatePipelineArray(value, key, path, diagnostics) {
+function validateArray(value, key, path, diagnostics) {
     if (!Object.hasOwn(value, key)) {
         return;
     }
@@ -88,8 +137,7 @@ function validatePipelineArray(value, key, path, diagnostics) {
     }
 }
 function validatePipelineHooks(value, path, diagnostics) {
-    if (!isPlainRecord(value)) {
-        diagnostics.push(diagnostic("CONFIG_INVALID_TYPE", path, `${path} must be an object`));
+    if (!requireRecord(value, path, diagnostics)) {
         return;
     }
     for (const key of Object.keys(value)) {
@@ -97,48 +145,441 @@ function validatePipelineHooks(value, path, diagnostics) {
             diagnostics.push(diagnostic("CONFIG_UNKNOWN_PROPERTY", `${path}.${key}`, `unknown pipeline hook property: ${key}`));
         }
     }
-    validatePipelineArray(value, "before", path, diagnostics);
-    validatePipelineArray(value, "after", path, diagnostics);
+    validateArray(value, "before", path, diagnostics);
+    validateArray(value, "after", path, diagnostics);
 }
 function validatePipelines(value, path, diagnostics) {
-    if (!isPlainRecord(value)) {
-        diagnostics.push(diagnostic("CONFIG_INVALID_TYPE", path, `${path} must be an object`));
+    if (!requireRecord(value, path, diagnostics)) {
         return;
     }
     for (const key of Object.keys(value)) {
+        if (PIPELINE_HOOK_PROPERTIES.has(key)) {
+            diagnostics.push(diagnostic("CONFIG_MOVED_PROPERTY", `${path}.${key}`, `${path}.${key} moved in rc.1: hooks are ${path}.hooks.${key}`));
+            continue;
+        }
         if (!PIPELINE_PROPERTIES.has(key)) {
             diagnostics.push(diagnostic("CONFIG_UNKNOWN_PROPERTY", `${path}.${key}`, `unknown pipeline property: ${key}`));
         }
     }
     for (const key of ["guards", "pipes", "interceptors", "filters"]) {
-        validatePipelineArray(value, key, path, diagnostics);
+        validateArray(value, key, path, diagnostics);
     }
     if (Object.hasOwn(value, "hooks")) {
         validatePipelineHooks(value.hooks, `${path}.hooks`, diagnostics);
     }
 }
-function validateScope(value, path, diagnostics) {
+function validateForceTransaction(value, path, diagnostics) {
+    if (!Object.hasOwn(value, "forceTransaction")) {
+        return;
+    }
+    const propertyPath = `${path}.forceTransaction`;
+    if (typeof value.forceTransaction !== "boolean") {
+        diagnostics.push(diagnostic("CONFIG_INVALID_TYPE", propertyPath, `${propertyPath} must be a boolean`));
+    }
+}
+function validateOperationLevel(value, path, isFamily, diagnostics) {
+    if (!requireRecord(value, path, diagnostics)) {
+        return;
+    }
+    for (const [key, child] of Object.entries(value)) {
+        const keyPath = `${path}.${key}`;
+        if (key === "pipelines") {
+            validatePipelines(child, keyPath, diagnostics);
+            continue;
+        }
+        if (key === "forceTransaction") {
+            continue;
+        }
+        if (isFamily && OPERATION_VARIANTS.has(key)) {
+            validateOperationLevel(child, keyPath, false, diagnostics);
+            continue;
+        }
+        diagnostics.push(diagnostic("CONFIG_UNKNOWN_PROPERTY", keyPath, isFamily
+            ? `unknown operation family property: ${key}; a family takes pipelines, forceTransaction and its variants by name`
+            : `unknown operation variant property: ${key}; a variant takes pipelines and forceTransaction`));
+    }
+    validateForceTransaction(value, path, diagnostics);
+}
+function validateOperations(value, path, diagnostics) {
+    if (!requireRecord(value, path, diagnostics)) {
+        return;
+    }
+    for (const [family, level] of Object.entries(value)) {
+        const familyPath = `${path}.${family}`;
+        if (!OPERATION_FAMILIES.has(family)) {
+            diagnostics.push(diagnostic("CONFIG_UNKNOWN_PROPERTY", familyPath, `unknown operation family: ${family}`));
+            continue;
+        }
+        validateOperationLevel(level, familyPath, true, diagnostics);
+    }
+}
+function validateResourceTransactions(value, path, diagnostics) {
+    if (!requireRecord(value, path, diagnostics)) {
+        return;
+    }
+    for (const [key, child] of Object.entries(value)) {
+        const keyPath = `${path}.${key}`;
+        if (key !== "pipelines") {
+            diagnostics.push(diagnostic("CONFIG_UNKNOWN_PROPERTY", keyPath, `unknown Resource transactions property: ${key}`));
+            continue;
+        }
+        validatePipelines(child, keyPath, diagnostics);
+    }
+}
+function validateDefinition(value, path, diagnostics) {
+    if (!requireRecord(value, path, diagnostics)) {
+        return;
+    }
+    for (const key of Object.keys(value)) {
+        if (!DEFINITION_PROPERTIES.has(key)) {
+            diagnostics.push(diagnostic("CONFIG_UNKNOWN_PROPERTY", `${path}.${key}`, `unknown field definition property: ${key}`));
+        }
+    }
+    if (Object.hasOwn(value, "format") && !AVZ_FORMAT_SET.has(value.format)) {
+        diagnostics.push(diagnostic("CONFIG_INVALID_VALUE", `${path}.format`, `${path}.format must be one of zod's named string formats (${AVZ_FORMATS.join(", ")})`));
+    }
+}
+function validateComputeStage(value, path, phase, diagnostics) {
+    if (typeof value === "function") {
+        return;
+    }
+    if (phase === "read" && isPlainRecord(value)) {
+        for (const key of Object.keys(value)) {
+            if (key !== "compute" && key !== "dependsOn") {
+                diagnostics.push(diagnostic("CONFIG_UNKNOWN_PROPERTY", `${path}.${key}`, `unknown computed read property: ${key}`));
+            }
+        }
+        if (typeof value.compute !== "function") {
+            diagnostics.push(diagnostic("CONFIG_INVALID_TYPE", `${path}.compute`, `${path}.compute must be a function`));
+        }
+        validateArray(value, "dependsOn", path, diagnostics);
+        return;
+    }
+    diagnostics.push(diagnostic("CONFIG_INVALID_TYPE", path, value === false
+        ? `${path} must be a function: compute stages chain across layers, and none is disabled from below`
+        : phase === "read"
+            ? `${path} must be a function or { compute, dependsOn }`
+            : `${path} must be a function`));
+}
+function validateCompute(value, path, diagnostics) {
+    if (!requireRecord(value, path, diagnostics)) {
+        return;
+    }
+    for (const [phase, stage] of Object.entries(value)) {
+        const phasePath = `${path}.${phase}`;
+        if (!COMPUTE_PHASES.has(phase)) {
+            diagnostics.push(diagnostic("CONFIG_UNKNOWN_PROPERTY", phasePath, `unknown compute phase: ${phase}; the phases are create, read and update`));
+            continue;
+        }
+        if (stage !== undefined) {
+            validateComputeStage(stage, phasePath, phase, diagnostics);
+        }
+    }
+}
+function validateFieldPipelines(value, path, diagnostics) {
+    if (!requireRecord(value, path, diagnostics)) {
+        return;
+    }
+    for (const [key, child] of Object.entries(value)) {
+        const keyPath = `${path}.${key}`;
+        if (!FIELD_PIPELINE_PROPERTIES.has(key)) {
+            diagnostics.push(diagnostic("CONFIG_UNKNOWN_PROPERTY", keyPath, `unknown field pipeline property: ${key}`));
+            continue;
+        }
+        if (key === "compute") {
+            validateCompute(child, keyPath, diagnostics);
+            continue;
+        }
+        validateArray(value, key, path, diagnostics);
+    }
+}
+function movedFieldKey(key) {
+    if (DEFINITION_PROPERTIES.has(key)) {
+        return `definition.${key}`;
+    }
+    if (COMPUTE_PHASES.has(key)) {
+        return `pipelines.compute.${key}`;
+    }
+    return undefined;
+}
+function validateField(value, path, isRoot, resourcePath, diagnostics) {
+    if (!requireRecord(value, path, diagnostics)) {
+        return;
+    }
+    for (const [key, child] of Object.entries(value)) {
+        const keyPath = `${path}.${key}`;
+        if (key === "definition") {
+            if (!isRoot) {
+                diagnostics.push(diagnostic("CONFIG_FORBIDDEN_IN_OVERLAY", keyPath, `${keyPath}: definition is only allowed at root; a field is defined once and overlays only choose its visibility (define it at ${resourcePath})`));
+                continue;
+            }
+            validateDefinition(child, keyPath, diagnostics);
+            continue;
+        }
+        if (key === "pipelines") {
+            validateFieldPipelines(child, keyPath, diagnostics);
+            continue;
+        }
+        if (key === "hidden") {
+            diagnostics.push(movedHidden(keyPath));
+            continue;
+        }
+        const moved = movedFieldKey(key);
+        if (moved !== undefined) {
+            diagnostics.push(diagnostic("CONFIG_MOVED_PROPERTY", keyPath, `${keyPath} moved in rc.1: it is ${path}.${moved}`));
+            continue;
+        }
+        if (!FIELD_PROPERTIES.has(key)) {
+            diagnostics.push(diagnostic("CONFIG_UNKNOWN_PROPERTY", keyPath, `unknown field property: ${key}; a field takes definition and pipelines`));
+        }
+    }
+}
+function validateResource(value, path, resource, isRoot, diagnostics) {
+    if (!requireRecord(value, path, diagnostics)) {
+        return;
+    }
+    for (const [key, child] of Object.entries(value)) {
+        const keyPath = `${path}.${key}`;
+        if (key === "hidden") {
+            diagnostics.push(movedHidden(keyPath));
+            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 (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") {
+            validatePipelines(child, keyPath, diagnostics);
+            continue;
+        }
+        if (key === "operations") {
+            validateOperations(child, keyPath, diagnostics);
+            continue;
+        }
+        if (key === "transactions") {
+            validateResourceTransactions(child, keyPath, diagnostics);
+            continue;
+        }
+        if (!requireRecord(child, keyPath, diagnostics)) {
+            continue;
+        }
+        for (const [field, entry] of Object.entries(child)) {
+            validateField(entry, `${keyPath}.${field}`, isRoot, `resources.${resource}.fields.${field}.definition`, diagnostics);
+        }
+    }
+}
+function validateResources(value, path, isRoot, diagnostics) {
+    if (!requireRecord(value, path, diagnostics)) {
+        return;
+    }
+    for (const [resource, entry] of Object.entries(value)) {
+        validateResource(entry, `${path}.${resource}`, resource, isRoot, diagnostics);
+    }
+}
+const EXEMPTIONS_PROPERTIES = new Set(["resources"]);
+const RESOURCE_EXEMPTION_PROPERTIES = new Set(["operations", "fields"]);
+const FLAG_CAPABILITIES = new Set(["select", "include", "order", "orderNulls"]);
+function movedHidden(path) {
+    return diagnostic("CONFIG_MOVED_PROPERTY", path, `${path} moved in rc.1: an entry is hidden with \`true\` under exposed: true`);
+}
+function validateNameList(value, path, what, diagnostics) {
+    value.forEach((entry, index) => {
+        if (typeof entry !== "string") {
+            diagnostics.push(diagnostic("CONFIG_INVALID_TYPE", `${path}[${index}]`, `${path}[${index}] must be ${what}`));
+        }
+    });
+}
+function validateExemptionValue(value, path, what, diagnostics) {
+    if (typeof value === "boolean") {
+        return "boolean";
+    }
+    if (Array.isArray(value)) {
+        validateNameList(value, path, what, diagnostics);
+        return "list";
+    }
+    if (isPlainRecord(value)) {
+        if (Object.hasOwn(value, "hidden")) {
+            diagnostics.push(movedHidden(`${path}.hidden`));
+        }
+        return "object";
+    }
+    return undefined;
+}
+function validateOperationsExemption(value, path, diagnostics) {
+    const kind = validateExemptionValue(value, path, "an operation family name", diagnostics);
+    if (kind === undefined) {
+        diagnostics.push(diagnostic("CONFIG_INVALID_TYPE", path, `${path} must be true, false, a list of operation families, or an object of them`));
+        return;
+    }
+    if (kind !== "object") {
+        return;
+    }
+    for (const [family, variants] of Object.entries(value)) {
+        if (family === "hidden") {
+            continue;
+        }
+        const familyPath = `${path}.${family}`;
+        const familyKind = validateExemptionValue(variants, familyPath, "an operation variant name", diagnostics);
+        if (familyKind === undefined) {
+            diagnostics.push(diagnostic("CONFIG_INVALID_TYPE", familyPath, `${familyPath} must be true, false, a list of variants, or an object of them`));
+            continue;
+        }
+        if (familyKind !== "object") {
+            continue;
+        }
+        for (const [variant, flag] of Object.entries(variants)) {
+            if (variant !== "hidden" && typeof flag !== "boolean") {
+                diagnostics.push(diagnostic("CONFIG_INVALID_TYPE", `${familyPath}.${variant}`, `${familyPath}.${variant} must be a boolean`));
+            }
+        }
+    }
+}
+function validateFieldExemption(value, path, diagnostics) {
+    const kind = validateExemptionValue(value, path, "a capability name", diagnostics);
+    if (kind === undefined) {
+        diagnostics.push(diagnostic("CONFIG_INVALID_TYPE", path, `${path} must be true, false, a list of capability names, or an object of them`));
+        return;
+    }
+    if (kind !== "object") {
+        return;
+    }
+    for (const [capability, entry] of Object.entries(value)) {
+        if (capability === "hidden") {
+            continue;
+        }
+        const capabilityPath = `${path}.${capability}`;
+        if (capability === "capabilities") {
+            diagnostics.push(diagnostic("CONFIG_MOVED_PROPERTY", capabilityPath, `${capabilityPath} moved in rc.1: capabilities are named directly on the field's exemption`));
+            continue;
+        }
+        if (typeof entry === "boolean") {
+            continue;
+        }
+        if (Array.isArray(entry) && !FLAG_CAPABILITIES.has(capability)) {
+            validateNameList(entry, capabilityPath, "a token", diagnostics);
+            continue;
+        }
+        diagnostics.push(diagnostic("CONFIG_INVALID_TYPE", capabilityPath, FLAG_CAPABILITIES.has(capability)
+            ? `${capabilityPath} must be a boolean`
+            : `${capabilityPath} must be a boolean or a list of tokens`));
+    }
+}
+function validateResourceExemption(value, path, diagnostics) {
+    if (typeof value === "boolean") {
+        return;
+    }
     if (!isPlainRecord(value)) {
-        diagnostics.push(diagnostic("CONFIG_INVALID_TYPE", path, `${path} must be an object`));
+        diagnostics.push(diagnostic("CONFIG_INVALID_TYPE", path, `${path} must be true, false or { operations, fields }; a Resource takes no list`));
         return;
     }
+    for (const [key, entry] of Object.entries(value)) {
+        const keyPath = `${path}.${key}`;
+        if (key === "hidden") {
+            diagnostics.push(movedHidden(keyPath));
+            continue;
+        }
+        if (!RESOURCE_EXEMPTION_PROPERTIES.has(key)) {
+            diagnostics.push(diagnostic("CONFIG_UNKNOWN_PROPERTY", keyPath, `unknown Resource exemption property: ${key}; a Resource's exemption takes operations and fields`));
+            continue;
+        }
+        if (key === "operations") {
+            validateOperationsExemption(entry, keyPath, diagnostics);
+            continue;
+        }
+        if (!requireRecord(entry, keyPath, diagnostics)) {
+            continue;
+        }
+        for (const [field, fieldEntry] of Object.entries(entry)) {
+            validateFieldExemption(fieldEntry, `${keyPath}.${field}`, diagnostics);
+        }
+    }
+}
+function validateExemptions(value, path, diagnostics) {
+    if (!requireRecord(value, path, diagnostics)) {
+        return;
+    }
+    for (const [key, entry] of Object.entries(value)) {
+        const keyPath = `${path}.${key}`;
+        if (!EXEMPTIONS_PROPERTIES.has(key)) {
+            diagnostics.push(diagnostic("CONFIG_UNKNOWN_PROPERTY", keyPath, `unknown exemptions property: ${key}; exemptions take resources`));
+            continue;
+        }
+        if (!requireRecord(entry, keyPath, diagnostics)) {
+            continue;
+        }
+        for (const [resource, resourceEntry] of Object.entries(entry)) {
+            validateResourceExemption(resourceEntry, `${keyPath}.${resource}`, diagnostics);
+        }
+    }
+}
+function validateLayer(value, path, kind, diagnostics) {
+    const isRoot = kind === "root";
     for (const key of Object.keys(value)) {
-        if (!SCOPE_PROPERTIES.has(key)) {
-            diagnostics.push(diagnostic("CONFIG_UNKNOWN_PROPERTY", `${path}.${key}`, `unknown scoped configuration property: ${key}`));
+        const keyPath = childPath(path, key);
+        const moved = MOVED_LAYER_PROPERTIES.get(key);
+        if (moved !== undefined) {
+            diagnostics.push(diagnostic("CONFIG_MOVED_PROPERTY", keyPath, `${keyPath} moved in rc.1: use ${moved.map((next) => childPath(path, next)).join(" + ")}`));
+            continue;
+        }
+        const movedRootKey = isRoot ? MOVED_ROOT_PROPERTIES.get(key) : undefined;
+        if (movedRootKey !== undefined) {
+            diagnostics.push(diagnostic("CONFIG_MOVED_PROPERTY", keyPath, `${keyPath} moved in rc.1: use ${movedRootKey}`));
+            continue;
+        }
+        if (LAYER_PROPERTIES.has(key) ||
+            (isRoot && ROOT_ONLY_PROPERTIES.has(key)) ||
+            (kind === "agent" && key === "extends")) {
+            continue;
+        }
+        diagnostics.push(diagnostic("CONFIG_UNKNOWN_PROPERTY", keyPath, key === "extends"
+            ? `${keyPath}: extends is only allowed in the agent layer (agent.extends)`
+            : !isRoot && ROOT_ONLY_PROPERTIES.has(key)
+                ? `${keyPath}: ${key} is a root-only configuration property`
+                : isRoot
+                    ? `unknown configuration property: ${key}`
+                    : `unknown scoped configuration property: ${key}`));
+    }
+    if (kind === "agent" && Object.hasOwn(value, "extends")) {
+        if (!AGENT_PARENTS.has(value.extends)) {
+            const extendsPath = childPath(path, "extends");
+            diagnostics.push(diagnostic("CONFIG_INVALID_VALUE", extendsPath, `${extendsPath} must be "client", "application" or "root"`));
+        }
+    }
+    const exposedPath = childPath(path, "exposed");
+    if (Object.hasOwn(value, "exposed")) {
+        if (typeof value.exposed !== "boolean") {
+            diagnostics.push(diagnostic("CONFIG_INVALID_TYPE", exposedPath, `${exposedPath} must be a boolean`));
+        }
+    }
+    if (Object.hasOwn(value, "exemptions")) {
+        const exemptionsPath = childPath(path, "exemptions");
+        if (!isRoot && !Object.hasOwn(value, "exposed")) {
+            diagnostics.push(diagnostic("CONFIG_REQUIRED", exposedPath, `${exposedPath} is required when ${exemptionsPath} is set: true makes the exemptions hide, false makes them the only entries exposed`));
         }
+        validateExemptions(value.exemptions, exemptionsPath, diagnostics);
+    }
+    if (Object.hasOwn(value, "transactionsStyle") &&
+        !TRANSACTION_CAPABILITY_SET.has(value.transactionsStyle)) {
+        const stylePath = childPath(path, "transactionsStyle");
+        diagnostics.push(diagnostic("CONFIG_INVALID_VALUE", stylePath, `${stylePath} must be "none" or "interactive"`));
     }
-    validateNamedObject(value, "fields", `${path}.fields`, diagnostics);
-    validateNamedObject(value, "behaviors", `${path}.behaviors`, diagnostics);
-    validateNamedObject(value, "restrictions", `${path}.restrictions`, diagnostics);
     if (Object.hasOwn(value, "limits")) {
-        validateLimits(value.limits, `${path}.limits`, diagnostics);
+        validateLimits(value.limits, childPath(path, "limits"), diagnostics);
     }
     if (Object.hasOwn(value, "pipelines")) {
-        validatePipelines(value.pipelines, `${path}.pipelines`, diagnostics);
+        validatePipelines(value.pipelines, childPath(path, "pipelines"), diagnostics);
     }
-    if (Object.hasOwn(value, "transactions") &&
-        !TRANSACTION_CAPABILITY_SET.has(value.transactions)) {
-        diagnostics.push(diagnostic("CONFIG_INVALID_VALUE", `${path}.transactions`, `${path}.transactions must be "none" or "interactive"`));
+    if (Object.hasOwn(value, "resources")) {
+        validateResources(value.resources, childPath(path, "resources"), isRoot, diagnostics);
     }
 }
 function validateAdapter(value, diagnostics) {
@@ -166,41 +607,45 @@ export function validateFrameworkConfig(value) {
             diagnostic("CONFIG_INVALID_TYPE", "$", "framework configuration must be an object"),
         ];
     }
-    for (const key of Object.keys(value)) {
-        if (!ROOT_PROPERTIES.has(key)) {
-            diagnostics.push(diagnostic("CONFIG_UNKNOWN_PROPERTY", key, `unknown configuration property: ${key}`));
-        }
+    validateLayer(value, "", "root", diagnostics);
+    let api;
+    if (!Object.hasOwn(value, "api")) {
+        diagnostics.push(diagnostic("CONFIG_REQUIRED", "api", "api is required"));
     }
-    if (!Object.hasOwn(value, "entrypoint")) {
-        diagnostics.push(diagnostic("CONFIG_REQUIRED", "entrypoint", "entrypoint is required"));
-    }
-    else if (typeof value.entrypoint !== "string") {
-        diagnostics.push(diagnostic("CONFIG_INVALID_TYPE", "entrypoint", "entrypoint must be a string"));
+    else if (typeof value.api !== "string") {
+        diagnostics.push(diagnostic("CONFIG_INVALID_TYPE", "api", "api must be a string"));
     }
     else {
-        const normalized = normalizeEntrypoint(value.entrypoint);
-        if (!normalized.ok) {
-            diagnostics.push(entrypointRefusalDiagnostic(normalized.message));
+        const normalized = normalizeEntrypoint(value.api);
+        if (normalized.ok) {
+            api = normalized.path;
+        }
+        else {
+            diagnostics.push(mountPathRefusalDiagnostic("api", normalized.message));
         }
     }
+    if (Object.hasOwn(value, "mcp")) {
+        validateMcp(value.mcp, api, diagnostics);
+    }
     if (!Object.hasOwn(value, "adapter")) {
         diagnostics.push(diagnostic("CONFIG_REQUIRED", "adapter", "adapter is required"));
     }
     else {
         validateAdapter(value.adapter, diagnostics);
     }
-    validateNamedObject(value, "fields", "fields", diagnostics);
-    validateNamedObject(value, "behaviors", "behaviors", diagnostics);
-    validateNamedObject(value, "restrictions", "restrictions", diagnostics);
-    if (Object.hasOwn(value, "limits")) {
-        validateLimits(value.limits, "limits", 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, "pipelines")) {
-        validatePipelines(value.pipelines, "pipelines", diagnostics);
+    if (Object.hasOwn(value, "policy") && value.policy !== undefined) {
+        validatePolicy(value.policy, diagnostics);
     }
-    if (Object.hasOwn(value, "transactions") &&
-        !TRANSACTION_CAPABILITY_SET.has(value.transactions)) {
-        diagnostics.push(diagnostic("CONFIG_INVALID_VALUE", "transactions", 'transactions must be "none" or "interactive"'));
+    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 &&
@@ -212,11 +657,289 @@ export function validateFrameworkConfig(value) {
         typeof value.misuse !== "function") {
         diagnostics.push(diagnostic("CONFIG_INVALID_TYPE", "misuse", "misuse must be a function when provided"));
     }
-    if (Object.hasOwn(value, "application")) {
-        validateScope(value.application, "application", diagnostics);
-    }
-    if (Object.hasOwn(value, "client")) {
-        validateScope(value.client, "client", diagnostics);
+    for (const overlay of ["application", "client", "agent"]) {
+        if (!Object.hasOwn(value, overlay)) {
+            continue;
+        }
+        const layer = value[overlay];
+        if (requireRecord(layer, overlay, diagnostics)) {
+            validateLayer(layer, overlay, overlay === "agent" ? "agent" : "overlay", diagnostics);
+        }
     }
     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);
+        return;
+    }
+    if (!isPlainRecord(value)) {
+        diagnostics.push(diagnostic("CONFIG_INVALID_TYPE", "mcp", "mcp must be a mount path or { path, authorization? }"));
+        return;
+    }
+    for (const key of Object.keys(value)) {
+        if (!MCP_PROPERTIES.has(key)) {
+            diagnostics.push(diagnostic("CONFIG_UNKNOWN_PROPERTY", `mcp.${key}`, `unknown mcp property: ${key}`));
+        }
+    }
+    if (!Object.hasOwn(value, "path")) {
+        diagnostics.push(diagnostic("CONFIG_REQUIRED", "mcp.path", "mcp.path is required"));
+    }
+    else if (typeof value.path !== "string") {
+        diagnostics.push(diagnostic("CONFIG_INVALID_TYPE", "mcp.path", "mcp.path must be a string"));
+    }
+    else {
+        validateMcpPath(value.path, "mcp.path", api, diagnostics);
+    }
+    if (Object.hasOwn(value, "authorization")) {
+        validateMcpAuthorization(value.authorization, diagnostics);
+    }
+}
+function validateMcpPath(value, path, api, diagnostics) {
+    const normalized = normalizeEntrypoint(value);
+    if (!normalized.ok) {
+        diagnostics.push(mountPathRefusalDiagnostic(path, normalized.message));
+        return;
+    }
+    if (api === undefined) {
+        return;
+    }
+    if (normalized.path === api) {
+        diagnostics.push(diagnostic("CONFIG_INVALID_VALUE", path, `${path} is the mount path api already has; mount the MCP endpoint at a path of its own`));
+    }
+    else if (normalized.path.startsWith(`${api}/_`)) {
+        diagnostics.push(diagnostic("CONFIG_INVALID_VALUE", path, `${path} is inside the protocol's namespace (the "_" segments under api); mount the MCP endpoint outside it`));
+    }
+}
+function validateMcpAuthorization(value, diagnostics) {
+    const path = "mcp.authorization";
+    if (!requireRecord(value, path, diagnostics)) {
+        return;
+    }
+    for (const key of Object.keys(value)) {
+        if (!MCP_AUTHORIZATION_PROPERTIES.has(key)) {
+            diagnostics.push(diagnostic("CONFIG_UNKNOWN_PROPERTY", `${path}.${key}`, `unknown mcp.authorization property: ${key}`));
+        }
+    }
+    const serversPath = `${path}.servers`;
+    if (!Object.hasOwn(value, "servers")) {
+        diagnostics.push(diagnostic("CONFIG_REQUIRED", serversPath, `${serversPath} is required`));
+    }
+    else if (!Array.isArray(value.servers)) {
+        diagnostics.push(diagnostic("CONFIG_INVALID_TYPE", serversPath, `${serversPath} must be a list of https URLs`));
+    }
+    else if (value.servers.length === 0) {
+        diagnostics.push(diagnostic("CONFIG_INVALID_VALUE", serversPath, `${serversPath} must name at least one authorization server`));
+    }
+    else {
+        value.servers.forEach((server, index) => {
+            const serverPath = `${serversPath}[${index}]`;
+            const refusal = authorizationServerRefusal(server, serverPath);
+            if (refusal !== undefined) {
+                diagnostics.push(diagnostic("CONFIG_INVALID_VALUE", serverPath, refusal));
+            }
+        });
+    }
+    const verifyPath = `${path}.verify`;
+    if (!Object.hasOwn(value, "verify")) {
+        diagnostics.push(diagnostic("CONFIG_REQUIRED", verifyPath, `${verifyPath} is required`));
+    }
+    else if (typeof value.verify !== "function") {
+        diagnostics.push(diagnostic("CONFIG_INVALID_TYPE", verifyPath, `${verifyPath} must be a function: token in, the caller or null out`));
+    }
+}
+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 notHttps;
+    }
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        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`;
+}