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

package/dist/config/config.validator.js

@@ -1,34 +1,76 @@
 import { TRANSACTION_CAPABILITIES } from "../contracts/transaction-capability.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",
     "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",
+]);
+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 +90,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 +121,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 +131,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 +139,432 @@ 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`));
+            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"`));
         }
     }
-    validateNamedObject(value, "fields", `${path}.fields`, diagnostics);
-    validateNamedObject(value, "behaviors", `${path}.behaviors`, diagnostics);
-    validateNamedObject(value, "restrictions", `${path}.restrictions`, diagnostics);
+    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"`));
+    }
     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,22 +592,25 @@ 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}`));
-        }
-    }
-    if (!Object.hasOwn(value, "entrypoint")) {
-        diagnostics.push(diagnostic("CONFIG_REQUIRED", "entrypoint", "entrypoint is required"));
+    validateLayer(value, "", "root", diagnostics);
+    let api;
+    if (!Object.hasOwn(value, "api")) {
+        diagnostics.push(diagnostic("CONFIG_REQUIRED", "api", "api 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"));
@@ -189,19 +618,6 @@ export function validateFrameworkConfig(value) {
     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, "pipelines")) {
-        validatePipelines(value.pipelines, "pipelines", 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, "diagnostics") &&
         value.diagnostics !== undefined &&
         typeof value.diagnostics !== "function") {
@@ -212,11 +628,104 @@ 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;
 }
+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) => {
+            if (!isHttpsUrl(server)) {
+                const serverPath = `${serversPath}[${index}]`;
+                diagnostics.push(diagnostic("CONFIG_INVALID_VALUE", serverPath, `${serverPath} must be an absolute https URL`));
+            }
+        });
+    }
+    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`));
+    }
+}
+function isHttpsUrl(value) {
+    if (typeof value !== "string") {
+        return false;
+    }
+    try {
+        return new URL(value).protocol === "https:";
+    }
+    catch {
+        return false;
+    }
+}