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

package/dist/adapters/adapter-operation.d.ts

@@ -2,9 +2,24 @@ import type { AvOperationIdentity } from "../operations/operation-identity.js";
 import type { SemanticOperationArguments } from "../operations/operation-validator.js";
 import type { AvAdapterModel } from "./adapter-model.js";
 /**
- * Provider execution request after framework semantic validation.
- * Operation identity and arguments remain provider-neutral; adapters receive
- * only validated semantic argument objects, never raw transport input.
+ * Provider execution request after framework semantic validation. Operation
+ * identity and arguments remain provider-neutral; adapters receive only validated
+ * semantic argument objects, never raw transport input.
+ *
+ * Three shapes exist here only, each an `AND`: a list of conditions in the general
+ * `where` grammar the addressed row must also meet.
+ *
+ * - The flat unique selector of an `update.unique` or a `delete.unique` may carry
+ *   it. A row the selector names that misses them is a miss (the same `null` as a
+ *   row that is not there).
+ * - A `cursor` may carry it, at the root of a `find.many` and in a to-many
+ *   relation's arguments. A row the cursor names that misses them is a cursor that
+ *   names no row: the same answer as a cursor on a row that is not there.
+ * - A row the selector names that misses them, or no row, is refused: the adapter
+ *   fails the operation with `A4002`.
+ *
+ * An adapter must honour it or refuse the operation, never drop it: dropping it
+ * would write a row the conditions exclude, or position a page at one.
  */
 export type AvAdapterOperation<M extends AvAdapterModel = AvAdapterModel> = AvOperationIdentity & {
     readonly resource: Extract<keyof M["resources"], string>;

package/dist/adapters/adapter-resource.d.ts

@@ -26,4 +26,9 @@ export type AvAdapterResource<M extends AvAdapterModel, TFields extends AvAdapte
      * cannot say; nothing is then checked or typed before the store.
      */
     readonly createRequirements?: AvCreateRequirements;
+    /**
+     * The database schema the store keeps this Resource in (a PostgreSQL schema,
+     * say), when the store has schemas and the model names one. Absent otherwise.
+     */
+    readonly schema?: string;
 };

package/dist/adapters/adapter.interface.d.ts

@@ -1,3 +1,4 @@
+import type { AvConfigComputedFields } from "../config/computed-fields.js";
 import type { ReferentialActionTable } from "../runtime/referential-action.js";
 import type { AvAdapterModel } from "./adapter-model.js";
 import type { AvAdapterOperationExecutor } from "./adapter-operation-executor.interface.js";
@@ -30,6 +31,15 @@ export interface AvAdapter<M extends AvAdapterModel = AvAdapterModel> extends Av
      * or `$set` runs the target's `update` guards.
      */
     readonly referentialActions?: ReferentialActionTable;
+    /**
+     * Optional: which fields the configuration's write compute fills, as the
+     * Adapter's generate step read them when it wrote the model's type (the same
+     * statement as the type's `"~computedFields"`). When the Framework is
+     * constructed it is compared with the configuration, and a difference is a
+     * warning that the generated types are stale (`aventara:prepare` regenerates
+     * them); it changes no behaviour. Never part of a Contract or its hash.
+     */
+    readonly computedFields?: AvConfigComputedFields;
     /**
      * Optional: `true` when the Adapter runs developer SQL statements: standalone
      * through its own {@link executeSql}, and, when it has `transaction`, inside a

package/dist/avz/avz.d.ts

@@ -49,7 +49,7 @@ export interface AvZOptional<Inner extends AvZShape = AvZShape> extends AvZShape
 /** A shape that also admits `null`. */
 export type AvZNullable<Inner extends AvZShape = AvZShape> = AvZShape<JsonShapeValue<Inner> | null, "nullable"> & (Inner extends AvZOptionalKey ? AvZOptionalKey : unknown);
 /** A value a literal shape may hold. */
-export type AvZLiteralValue = JsonSchemaPrimitive;
+type AvZLiteralValue = JsonSchemaPrimitive;
 /** What keys a record shape: any string, an enum's values or one literal. */
 type AvZRecordKey = AvZShape<string, "string"> | AvZShape<string, "enum"> | AvZShape<string, "literal">;
 /** An option of a discriminated union: an object whose discriminator is a literal or an enum. */

package/dist/avz/json-shape.registry.d.ts

@@ -3,7 +3,7 @@ import type { AvScalarField } from "../contracts/field.js";
 import type { JsonSchema } from "../contracts/json-shape.js";
 import type { AvValidationIssue } from "../operations/validation-code.js";
 /** What core may do with a Json Shape: read its Contract form, check a value. */
-export type JsonShapeRuntime = {
+type JsonShapeRuntime = {
     /** The shape's Contract form. */
     readonly schema: JsonSchema;
     /**
@@ -20,3 +20,4 @@ export declare function jsonShapeOf(value: unknown): JsonShapeRuntime | undefine
 export declare function bindShapedField(field: AvScalarField<AvContract>, shape: JsonShapeRuntime): void;
 /** The shape a compiled Contract field enforces, or `undefined`. */
 export declare function shapeOfField(field: AvScalarField<AvContract>): JsonShapeRuntime | undefined;
+export {};

package/dist/compiler/contract-compiler-diagnostic.guidance.d.ts

@@ -0,0 +1,6 @@
+import type { ErrorCodeDescription } from "../runtime/error-guidance.js";
+import type { AvContractCompilerDiagnosticCode } from "./contract-compiler-diagnostic.js";
+/** Meaning, cause and fix of every contract-compilation diagnostic code. */
+export declare const CONTRACT_COMPILER_DIAGNOSTIC_GUIDANCE: {
+    readonly [C in AvContractCompilerDiagnosticCode]: ErrorCodeDescription;
+};

package/dist/compiler/contract-compiler-diagnostic.guidance.js

@@ -0,0 +1,97 @@
+export const CONTRACT_COMPILER_DIAGNOSTIC_GUIDANCE = {
+    COMPILER_UNKNOWN_RESOURCE: {
+        message: "Unknown Resource.",
+        cause: "A Resource name the adapter's model does not have, in resources or in exemptions; or a client or agent entry for a Resource managed elsewhere, which those layers never have.",
+        fix: "Use the model's exact name. After a schema change run `npm run aventara:prepare`. Configure a Resource managed elsewhere at the root or in application only.",
+    },
+    COMPILER_UNKNOWN_FIELD: {
+        message: "Unknown field.",
+        cause: "A field that is neither in the schema nor defined at the root.",
+        fix: "Fix the name, run aventara:prepare after a schema change, or add the field with a root definition.",
+    },
+    COMPILER_RELATION_FIELD_CONFIG_UNSUPPORTED: {
+        message: "A relation field takes write guards only.",
+        cause: "Field pipes or compute on a relation field.",
+        fix: "Put the stage on the relation's reference field, or use an operation pipe.",
+    },
+    COMPILER_INCOMPLETE_FIELD: {
+        message: "An added field is incomplete.",
+        cause: "A definition that adds a field leaves out type, nullable or list.",
+        fix: 'Spell out type, nullable and list, with lifecycle: ["VIRTUAL"] for a field that has no column.',
+    },
+    COMPILER_STRUCTURAL_FIELD_OVERRIDE: {
+        message: "A discovered field's structure was redefined.",
+        cause: "A definition on a field the adapter discovered changes its type, format or capabilities.",
+        fix: "Restate only its type, nullable and list. Change capabilities through exemptions and the column through the schema.",
+    },
+    COMPILER_MISSING_SCALAR: {
+        message: "Unknown scalar type.",
+        cause: "A definition names a scalar type that does not exist.",
+        fix: "Use a built-in scalar: string, boolean, int, float, bigint, decimal, datetime, bytes or json.",
+    },
+    COMPILER_MISSING_ENUM: {
+        message: "Unknown enum.",
+        cause: "A definition names an enum the model does not have.",
+        fix: "Use an enum of the schema, and run aventara:prepare after adding one.",
+    },
+    COMPILER_DANGLING_RELATION: {
+        message: "A visible relation points at a hidden Resource.",
+        cause: "A layer hides a Resource but still exposes a relation field that targets it.",
+        fix: "Hide the relation field too (`exemptions.resources.<R>.fields.<relation>: true`), or expose the target.",
+    },
+    COMPILER_UNAVAILABLE_OPERATION: {
+        message: "Operation not available.",
+        cause: "An operation the adapter does not offer (such as delete.many), or an overlay granting one that its parent hid.",
+        fix: "Remove it. To reach an operation from one overlay only, expose it at the root and hide it in the other overlay.",
+    },
+    COMPILER_UNAVAILABLE_CAPABILITY: {
+        message: "Capability not available.",
+        cause: "A capability or token the field does not offer, or an overlay (or the agent layer) granting one its parent hid. Overlays only narrow.",
+        fix: "Remove it, or expose it in the parent layer and hide it in the layer it must not reach.",
+    },
+    COMPILER_INVALID_LIFECYCLE: {
+        message: "Invalid field lifecycle.",
+        cause: "An added field declares a lifecycle other than VIRTUAL, a VIRTUAL field claims a database-generated lifecycle or a provider-side capability, or a definition redefines a discovered field's lifecycle.",
+        fix: 'Give an added field lifecycle: ["VIRTUAL"] and only the capabilities it can serve; computed lifecycles come from compute stages.',
+    },
+    COMPILER_MISSING_READ_COMPUTE: {
+        message: "A selectable virtual field has no compute.read.",
+        cause: "A VIRTUAL field that can be selected has no pipelines.compute.read stage.",
+        fix: "Add a compute.read stage, or make the field write-only with capabilities.select: false.",
+    },
+    COMPILER_INVALID_COMPUTE_DEPENDENCY: {
+        message: "Invalid compute.read dependency.",
+        cause: "A dependsOn entry that is not a stored scalar field of the same Resource.",
+        fix: "List only stored scalar fields of the Resource in dependsOn.",
+    },
+    COMPILER_RESERVED_RESOURCE_NAME: {
+        message: "Reserved Resource name.",
+        cause: "A model name starts with $, which is reserved for the framework's own names (ctx.$sql, $ref), or, on a host that adds members beside the Resources, is one of those members' names (on Next.js: tx and transaction on avClient, appTx and transaction on avApp).",
+        fix: "Rename the model; the table it maps to can keep its name. A host member's name is also left free when the layer it belongs to hides the Resource.",
+    },
+    COMPILER_MISSING_IDENTIFIER: {
+        message: "A unique operation has no identifier.",
+        cause: "A layer exposes a unique variant (find.unique, update.unique, delete.unique, upsert.unique) and no complete identifier of the Resource: a Pick that did not pick one, or an Omit that hid every one.",
+        fix: "Expose an identifier field (id, or every field of one unique), or exempt the unique variants.",
+    },
+    COMPILER_HIDDEN_REQUIRED_FIELD: {
+        message: "A layer that creates a Resource hides a required field.",
+        cause: "A layer still creates the Resource (a create or upsert variant, or a nested create) while a required field, or a required relation's reference field, is hidden or has its create capability exempted, and no compute.create fills it.",
+        fix: "Expose the field, give it a compute.create stage, or exempt the layer's create operations.",
+    },
+    COMPILER_INVALID_VALIDATOR: {
+        message: "A field validator cannot apply.",
+        cause: "A validator that is not built with AvZ, does not fit the field's type (AvZ.maxLength on an int, AvZ.maxItems on a field that is not a list), or sits on a relation or Json field.",
+        fix: "Use an AvZ check that fits the field's type; a Json field's checks go in its json shape.",
+    },
+    COMPILER_INVALID_JSON_SHAPE: {
+        message: "A Json shape cannot apply.",
+        cause: "A json shape on a field that is not a discovered Json field, a shape not built with AvZ, or one that admits null or absence at its top level.",
+        fix: "Put the shape on a Json field, build it with AvZ, and keep its top level non-null (the column's nullability decides null).",
+    },
+    COMPILER_INVALID_CLIENT_CONTRACT: {
+        message: "The compiled client contract is invalid.",
+        cause: "The finished client contract failed its own structural check: a framework defect.",
+        fix: "Report it with the diagnostic's path and message.",
+    },
+};

package/dist/compiler/contract.compiler.d.ts

@@ -30,3 +30,9 @@ export type ContractCompilationResult = {
  * Agent Contract from the view of the layer it extends.
  */
 export declare function compileContracts<M extends AvAdapterModel>(model: M, config: ResolvedFrameworkConfig<M>): Promise<ContractCompilationResult>;
+/**
+ * Binds Contracts loaded from a prebuilt file to the runtime pieces
+ * {@link compileContracts} binds to the ones it compiles, from the live
+ * `config` and `model` they were compiled from.
+ */
+export declare function bindPrebuiltContracts<M extends AvAdapterModel>(model: M, config: ResolvedFrameworkConfig<M>, contracts: AvContracts): void;

package/dist/compiler/contract.compiler.js

@@ -1,5 +1,5 @@
 import { bindShapedField, jsonShapeOf } from "../avz/json-shape.registry.js";
-import { PROJECTION_SCOPES, WRITE_SCOPES } from "../contracts/capability.js";
+import { FILTER_MODES, PROJECTION_SCOPES, WRITE_SCOPES, } from "../contracts/capability.js";
 import { validateClientContractStructure } from "../contracts/client-contract-structure.validator.js";
 import { canonicalizeContract, canonicalizeContractMembers, canonicalizeJson, joinCanonicalContractMembers, recordCanonicalContractText, } from "../contracts/contract-canonicalizer.js";
 import { hashCanonicalContractText, } from "../contracts/contract-hash.js";
@@ -9,6 +9,7 @@ import { advertisedDirectives, advertisedReducers, holdsInAnyScope, } from "../c
 import { isOperationVariantAvailable, } from "../contracts/resource-operations.js";
 import { checkCreateRequirements, checkHiddenRequirements, projectCreateRequirements, } from "./create-requirements.projector.js";
 import { applyValidators, bindFieldValidators, checkLayerValidators, compileValidatorTable, } from "./field-validator.compiler.js";
+import { explainManagedRefusals, hideManagedElsewhere, managedElsewhereOf, managedWriteReason, markCoreResources, pruneManagedEnums, withholdManagedWrites, } from "./managed-elsewhere.projector.js";
 const UNIQUE_VARIANTS = [
     ["find", "unique"],
     ["update", "unique"],
@@ -41,6 +42,12 @@ function normalizeAdapterScalarCapabilities(capabilities) {
         ...(capabilities.filter !== undefined
             ? { filter: [...capabilities.filter] }
             : {}),
+        ...(capabilities.filterModes !== undefined
+            ? { filterModes: [...capabilities.filterModes] }
+            : {}),
+        ...(capabilities.pathFilterModes !== undefined
+            ? { pathFilterModes: [...capabilities.pathFilterModes] }
+            : {}),
         ...(capabilities.order !== undefined ? { order: capabilities.order } : {}),
         ...(capabilities.orderNulls !== undefined
             ? { orderNulls: capabilities.orderNulls }
@@ -71,8 +78,65 @@ function cloneAdapterField(field) {
         cardinality: field.cardinality,
         nullable: field.nullable,
         capabilities: cloneValue(field.capabilities),
+        ...(typeof field.inverse === "string" ? { inverse: field.inverse } : {}),
+        ...(Array.isArray(field.referenceFields) && field.referenceFields.length > 0
+            ? { referenceFields: [...field.referenceFields] }
+            : {}),
+        ...(Array.isArray(field.referenceFields) &&
+            Array.isArray(field.references) &&
+            field.references.length > 0 &&
+            field.references.length === field.referenceFields.length
+            ? { references: [...field.references] }
+            : {}),
     };
 }
+function pruneHiddenPairings(projection, references) {
+    const resources = projection.resources;
+    for (const [name, resource] of Object.entries(resources)) {
+        for (const field of Object.values(resource.fields)) {
+            if (field.kind !== "relation") {
+                continue;
+            }
+            if (Array.isArray(field.references) &&
+                (references === "none" ||
+                    !wholePairing(resource.fields, Object.hasOwn(resources, String(field.target))
+                        ? resources[String(field.target)]?.fields
+                        : undefined, field.referenceFields, field.references))) {
+                delete field.references;
+            }
+            if (Array.isArray(field.referenceFields)) {
+                const shown = field.referenceFields.filter((reference) => typeof reference === "string" &&
+                    Object.hasOwn(resource.fields, reference) &&
+                    resource.fields[reference]?.kind === "scalar");
+                if (shown.length > 0) {
+                    field.referenceFields = shown;
+                }
+                else {
+                    delete field.referenceFields;
+                }
+            }
+            if (typeof field.inverse !== "string") {
+                continue;
+            }
+            const other = Object.hasOwn(resources, String(field.target))
+                ? resources[String(field.target)]?.fields[field.inverse]
+                : undefined;
+            if (other?.kind !== "relation" || other.target !== name) {
+                delete field.inverse;
+            }
+        }
+    }
+}
+function wholePairing(fields, targetFields, referenceFields, references) {
+    const shownIn = (within, name) => typeof name === "string" &&
+        within !== undefined &&
+        Object.hasOwn(within, name) &&
+        within[name]?.kind === "scalar";
+    return (Array.isArray(referenceFields) &&
+        referenceFields.length === references.length &&
+        referenceFields.every((name) => shownIn(fields, name)) &&
+        references.every((name) => shownIn(targetFields, name)));
+}
 function cloneOperations(operations) {
     return cloneValue(operations);
 }
@@ -86,8 +150,40 @@ function cloneAdapterResource(resource) {
         operations: cloneOperations(resource.operations),
     };
 }
+function canonicalModes(modes) {
+    const stated = Array.isArray(modes) ? modes : [];
+    const known = FILTER_MODES.filter((mode) => mode === "default" || stated.includes(mode));
+    const unknown = stated.filter((mode) => !FILTER_MODES.includes(mode));
+    return [...known, ...unknown];
+}
+function qualifyFilterModes(projection) {
+    for (const resource of Object.values(projection.resources)) {
+        for (const field of Object.values(resource.fields)) {
+            if (field.kind !== "scalar") {
+                continue;
+            }
+            const capabilities = field.capabilities;
+            const filter = Array.isArray(capabilities.filter)
+                ? capabilities.filter
+                : [];
+            if (!filter.includes("mode")) {
+                delete capabilities.filterModes;
+                delete capabilities.pathFilterModes;
+                continue;
+            }
+            const stated = capabilities.filterModes;
+            capabilities.filterModes = canonicalModes(stated);
+            if (filter.includes("path")) {
+                capabilities.pathFilterModes = canonicalModes(capabilities.pathFilterModes ?? stated);
+            }
+            else {
+                delete capabilities.pathFilterModes;
+            }
+        }
+    }
+}
 function createBaseline(model) {
-    return {
+    const baseline = {
         scalars: Object.fromEntries(Object.entries(model.scalars).map(([key, value]) => [
             key,
             cloneValue(value),
@@ -106,6 +202,8 @@ function createBaseline(model) {
             ? {}
             : { referenceWrites: model.referenceWrites }),
     };
+    qualifyFilterModes(baseline);
+    return baseline;
 }
 function definitionPath(resource, field) {
     return `root.resources.${resource}.fields.${field}.definition`;
@@ -285,7 +383,7 @@ function checkFieldCompute(model, resourceName, fieldName, field, compute, path,
         }
     }
 }
-function checkResourceTree(model, baseline, scope, tree, definitions, diagnostics) {
+function checkResourceTree(model, baseline, scope, tree, definitions, managed, diagnostics) {
     if (!isRecord(tree)) {
         return;
     }
@@ -296,12 +394,22 @@ function checkResourceTree(model, baseline, scope, tree, definitions, diagnostic
             diagnostics.push(diagnostic("COMPILER_UNKNOWN_RESOURCE", resourcePath, `resource "${resourceName}" is not present in the canonical adapter model`));
             continue;
         }
+        if ((scope === "client" || scope === "agent") &&
+            managed.has(resourceName)) {
+            diagnostics.push(diagnostic("COMPILER_UNKNOWN_RESOURCE", resourcePath, `resource "${resourceName}" is managed elsewhere (resources.${resourceName}.managedElsewhere), so the ${scope} layer never has it: nothing configured for it here runs`));
+            continue;
+        }
         if (!isRecord(entry)) {
             continue;
         }
         if (isRecord(entry.operations)) {
             for (const [family, level] of Object.entries(entry.operations)) {
                 const familyPath = `${resourcePath}.operations.${family}`;
+                const managedReason = managedWriteReason(managed, resourceName, family);
+                if (managedReason !== undefined) {
+                    diagnostics.push(diagnostic("COMPILER_UNAVAILABLE_OPERATION", familyPath, managedReason));
+                    continue;
+                }
                 const variants = resource.operations[family];
                 if (!isRecord(variants)) {
                     diagnostics.push(diagnostic("COMPILER_UNAVAILABLE_OPERATION", familyPath, `operation family "${family}" is not available for resource "${resourceName}"`));
@@ -349,9 +457,14 @@ function checkReservedResourceNames(model, diagnostics) {
         }
     }
 }
+function isAdapterStated(axis) {
+    return axis?.kind === "limit" || axis?.kind === "adapterTokens";
+}
 const SCALAR_CAPABILITY_AXES = {
     select: { kind: "flag" },
     filter: { kind: "tokens" },
+    filterModes: { kind: "adapterTokens", values: FILTER_MODES },
+    pathFilterModes: { kind: "adapterTokens", values: FILTER_MODES },
     order: { kind: "flag" },
     orderNulls: { kind: "flag" },
     create: { kind: "tokens" },
@@ -445,11 +558,11 @@ function fieldName(resource, field) {
 }
 function exemptableAxis(walk, universeField, capability, label, path) {
     const axis = capabilityAxisFor(universeField.kind, capability);
-    if (axis === undefined || axis.kind === "limit") {
+    if (axis === undefined || isAdapterStated(axis)) {
         const names = Object.entries(universeField.kind === "scalar"
             ? SCALAR_CAPABILITY_AXES
             : RELATION_CAPABILITY_AXES)
-            .filter(([, entry]) => entry.kind !== "limit")
+            .filter(([, entry]) => !isAdapterStated(entry))
             .map(([name]) => name);
         unavailableCapability(path, `"${capability}" is not a capability a ${universeField.kind} field's exemption can name; it takes ${names.join(", ")}`, walk.diagnostics);
         return undefined;
@@ -533,7 +646,7 @@ function exemptField(walk, universeField, parentField, entry, label, path) {
     const result = walk.style === "omit" ? cloneValue(parentCapabilities) : {};
     if (walk.style === "pick") {
         for (const [key, value] of Object.entries(parentCapabilities)) {
-            if (capabilityAxisFor(universeField.kind, key)?.kind === "limit") {
+            if (isAdapterStated(capabilityAxisFor(universeField.kind, key))) {
                 result[key] = cloneValue(value);
             }
         }
@@ -552,7 +665,7 @@ function exemptField(walk, universeField, parentField, entry, label, path) {
         return undefined;
     }
     if (walk.style === "pick" &&
-        !Object.keys(result).some((key) => capabilityAxisFor(universeField.kind, key)?.kind !== "limit")) {
+        !Object.keys(result).some((key) => !isAdapterStated(capabilityAxisFor(universeField.kind, key)))) {
         return undefined;
     }
     return { ...cloneValue(parentField), capabilities: result };
@@ -839,6 +952,11 @@ function representationFault(axis, value) {
             return typeof value === "string" && axis.values.includes(value)
                 ? undefined
                 : `one of ${axis.values.join(", ")} is expected`;
+        case "adapterTokens":
+            return isTokenList(value) &&
+                value.every((token) => axis.values.includes(token))
+                ? undefined
+                : `a list of ${axis.values.join(", ")} is expected`;
         case "flag":
             return typeof value === "boolean" ? undefined : "a boolean is expected";
         case "tokens":
@@ -912,35 +1030,71 @@ function exposureStyle(layer) {
 }
 function projectCore(model, config, diagnostics) {
     const scope = config.root;
+    const managed = managedElsewhereOf(config.trees.root);
     const providerBaseline = createBaseline(model);
     const baseline = cloneValue(providerBaseline);
     baseline.limits = resolveLimits(scope);
     baseline.transactions = resolveTransactions(model, "root", scope, diagnostics);
-    checkResourceTree(model, baseline, "root", config.trees.root, config.definitions, diagnostics);
+    checkResourceTree(model, baseline, "root", config.trees.root, config.definitions, managed, diagnostics);
     applyFieldDefinitions(model, baseline, config.definitions, diagnostics);
+    const unwithheld = managed.size === 0 ? baseline : cloneValue(baseline);
+    withholdManagedWrites(baseline, managed);
+    markGovernedFields(baseline, config.policy?.governed);
     applyCompute(baseline, scope.compute);
     checkLayerValidators(baseline.resources, "root", config.trees.root, diagnostics);
     const validators = compileValidatorTable(baseline.resources, scope.pipelines);
     const projection = projectExposure({ layer: "root", style: exposureStyle(scope), diagnostics }, baseline, baseline, scope.exemptions);
+    qualifyFilterModes(projection);
+    pruneHiddenPairings(projection, "shown");
     projectCreateRequirements(model, projection.resources);
-    checkHiddenRequirements(model, "root", baseline.resources, baseline.resources, projection.resources, diagnostics);
+    const rootChecked = diagnostics.length;
+    checkHiddenRequirements(model, "root", baseline.resources, unwithheld.resources, projection.resources, diagnostics);
+    explainManagedRefusals(diagnostics, rootChecked, "root", baseline, managed);
     applyValidators(projection.resources, validators);
     validateProjection(projection, "root", diagnostics);
     return { baseline, projection, validators };
 }
+function markGovernedFields(baseline, governed) {
+    if (governed === undefined) {
+        return;
+    }
+    for (const [resourceName, names] of Object.entries(governed)) {
+        const resource = Object.hasOwn(baseline.resources, resourceName)
+            ? baseline.resources[resourceName]
+            : undefined;
+        if (resource === undefined) {
+            continue;
+        }
+        for (const name of names) {
+            const field = Object.hasOwn(resource.fields, name)
+                ? resource.fields[name]
+                : undefined;
+            if (field !== undefined) {
+                field.governed = true;
+            }
+        }
+    }
+}
 function projectDerivedScope(model, scopeName, core, parentView, config, diagnostics) {
     const scope = config[scopeName];
+    const managed = managedElsewhereOf(config.trees.root);
     const baseline = cloneValue(core.baseline);
     baseline.limits = resolveLimits(scope);
     baseline.transactions = resolveTransactions(model, scopeName, scope, scopeName === "agent" &&
         scope.transactionsStyle === config[config.agent.parent].transactionsStyle
         ? []
         : diagnostics);
-    checkResourceTree(model, baseline, scopeName, config.trees[scopeName], config.definitions, diagnostics);
+    checkResourceTree(model, baseline, scopeName, config.trees[scopeName], config.definitions, managed, diagnostics);
     applyCompute(baseline, scope.compute);
     checkLayerValidators(baseline.resources, scopeName, config.trees[scopeName], diagnostics);
     const validators = compileValidatorTable(baseline.resources, scope.pipelines);
     const parent = cloneValue(parentView);
+    const unhidden = (scopeName === "client" || scopeName === "agent") && managed.size > 0
+        ? cloneValue(parent)
+        : parent;
+    if (unhidden !== parent) {
+        hideManagedElsewhere(parent, managed);
+    }
     parent.limits = resolveLimits(scope);
     parent.transactions = baseline.transactions;
     applyCompute(parent, scope.compute);
@@ -950,8 +1104,15 @@ function projectDerivedScope(model, scopeName, core, parentView, config, diagnos
         diagnostics,
         ...(scopeName === "agent" ? { parent: config.agent.parent } : {}),
     }, baseline, parent, scope.exemptions);
+    qualifyFilterModes(projection);
+    pruneHiddenPairings(projection, "none");
+    if (unhidden !== parent) {
+        pruneManagedEnums(projection, unhidden, managed);
+    }
     projectCreateRequirements(model, projection.resources);
-    checkHiddenRequirements(model, scopeName, baseline.resources, parent.resources, projection.resources, diagnostics);
+    const layerChecked = diagnostics.length;
+    checkHiddenRequirements(model, scopeName, baseline.resources, unhidden.resources, projection.resources, diagnostics);
+    explainManagedRefusals(diagnostics, layerChecked, scopeName, baseline, managed);
     applyValidators(projection.resources, validators);
     validateProjection(projection, scopeName, diagnostics);
     return { projection, validators };
@@ -984,12 +1145,15 @@ export async function compileContracts(model, config) {
         : agentParent === "application"
             ? applicationProjection.projection
             : clientProjection.projection, compilerConfig, diagnostics);
+    markCoreResources(coreCompilation.projection, model, managedElsewhereOf(compilerConfig.trees.root));
     if (diagnostics.length > 0) {
         return { ok: false, diagnostics };
     }
     const core = semanticObject(coreCompilation.projection);
     const application = semanticObject(applicationProjection.projection);
-    const client = await identifiedContract(clientProjection.projection);
+    const client = await identifiedContract(compilerConfig.access === undefined
+        ? clientProjection.projection
+        : { ...clientProjection.projection, access: compilerConfig.access });
     const agent = await identifiedContract(agentProjection.projection);
     for (const [layer, contract] of [
         ["client", client],
@@ -1007,18 +1171,57 @@ export async function compileContracts(model, config) {
             };
         }
     }
-    bindShapedFields(core, compilerConfig.definitions);
-    bindShapedFields(application, compilerConfig.definitions);
-    bindShapedFields(client, compilerConfig.definitions);
-    bindShapedFields(agent, compilerConfig.definitions);
-    bindFieldValidators(core, coreCompilation.validators);
-    bindFieldValidators(application, applicationProjection.validators);
-    bindFieldValidators(client, clientProjection.validators);
-    bindFieldValidators(agent, agentProjection.validators);
-    return {
-        ok: true,
-        contracts: { core, application, client, agent },
-    };
+    const contracts = { core, application, client, agent };
+    bindRuntimePieces(contracts, compilerConfig.definitions, {
+        core: coreCompilation.validators,
+        application: applicationProjection.validators,
+        client: clientProjection.validators,
+        agent: agentProjection.validators,
+    });
+    return { ok: true, contracts };
+}
+function bindRuntimePieces(contracts, definitions, validators) {
+    for (const origin of ["core", "application", "client", "agent"]) {
+        bindShapedFields(contracts[origin], definitions);
+        bindFieldValidators(contracts[origin], validators[origin]);
+    }
+}
+export function bindPrebuiltContracts(model, config, contracts) {
+    const compilerConfig = config;
+    const fields = validatedFieldsView(model, compilerConfig.definitions);
+    bindRuntimePieces(contracts, compilerConfig.definitions, {
+        core: compileValidatorTable(fields, compilerConfig.root.pipelines),
+        application: compileValidatorTable(fields, compilerConfig.application.pipelines),
+        client: compileValidatorTable(fields, compilerConfig.client.pipelines),
+        agent: compileValidatorTable(fields, compilerConfig.agent.pipelines),
+    });
+}
+function validatedFieldsView(model, definitions) {
+    const resources = { ...model.resources };
+    for (const [resourceName, resourceDefinitions] of Object.entries(definitions)) {
+        const resource = Object.hasOwn(model.resources, resourceName)
+            ? model.resources[resourceName]
+            : undefined;
+        if (resource === undefined) {
+            continue;
+        }
+        let added;
+        for (const [fieldName, definition] of Object.entries(resourceDefinitions)) {
+            if (Object.hasOwn(resource.fields, fieldName)) {
+                continue;
+            }
+            added ??= {};
+            added[fieldName] = {
+                kind: "scalar",
+                type: definition.type,
+                list: definition.list,
+            };
+        }
+        if (added !== undefined) {
+            resources[resourceName] = { fields: { ...resource.fields, ...added } };
+        }
+    }
+    return resources;
 }
 async function identifiedContract(projection) {
     const members = canonicalizeContractMembers({