@aventara/core 1.0.0-rc.3 → 1.0.0-rc.8

package/dist/compiler/contract.compiler.js

@@ -81,15 +81,28 @@ function cloneAdapterField(field) {
         ...(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) {
+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) &&
@@ -113,6 +126,16 @@ function pruneHiddenPairings(projection) {
         }
     }
 }
+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);
 }
@@ -1002,18 +1025,40 @@ function projectCore(model, config, diagnostics) {
     baseline.transactions = resolveTransactions(model, "root", scope, diagnostics);
     checkResourceTree(model, baseline, "root", config.trees.root, config.definitions, diagnostics);
     applyFieldDefinitions(model, baseline, config.definitions, diagnostics);
+    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);
+    pruneHiddenPairings(projection, "shown");
     projectCreateRequirements(model, projection.resources);
     checkHiddenRequirements(model, "root", baseline.resources, baseline.resources, projection.resources, diagnostics);
     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 baseline = cloneValue(core.baseline);
@@ -1037,7 +1082,7 @@ function projectDerivedScope(model, scopeName, core, parentView, config, diagnos
         ...(scopeName === "agent" ? { parent: config.agent.parent } : {}),
     }, baseline, parent, scope.exemptions);
     qualifyFilterModes(projection);
-    pruneHiddenPairings(projection);
+    pruneHiddenPairings(projection, "none");
     projectCreateRequirements(model, projection.resources);
     checkHiddenRequirements(model, scopeName, baseline.resources, parent.resources, projection.resources, diagnostics);
     applyValidators(projection.resources, validators);
@@ -1095,18 +1140,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({

package/dist/config/computed-fields.js

@@ -1,3 +1,4 @@
+import { emitFrameworkWarning } from "../runtime/framework-warning.emitter.js";
 import { computeOfLayer } from "./field-compute.resolver.js";
 function layerComputedFields(resources) {
     const result = {};
@@ -68,13 +69,5 @@ export function warnOnStaleComputedFields(generated, configured) {
     const message = `generated types are stale: run aventara:prepare. The computed fields the pre-compute stages are typed with differ from the configuration's:\n${drift
         .map((line) => `  - ${line}`)
         .join("\n")}`;
-    const emitWarning = globalThis.process?.emitWarning;
-    if (typeof emitWarning === "function") {
-        emitWarning(message, {
-            type: "AventaraWarning",
-            code: STALE_GENERATED_TYPES_WARNING,
-        });
-        return;
-    }
-    globalThis.console?.warn(`AventaraWarning: ${message}`);
+    emitFrameworkWarning(message, STALE_GENERATED_TYPES_WARNING);
 }

package/dist/config/config-diagnostic.guidance.js

@@ -1,12 +1,12 @@
 export const CONFIG_DIAGNOSTIC_GUIDANCE = {
     CONFIG_REQUIRED: {
         message: "A required configuration key is missing.",
-        cause: "A key that must be present is absent: api, adapter, or an overlay's exposed when the overlay sets exemptions.",
+        cause: "A key that must be present is absent: api, adapter, or an overlay's exposed when the overlay sets exemptions, or policy.engine or policy.principal when policy is set.",
         fix: "Add the key at the diagnostic's path.",
     },
     CONFIG_UNKNOWN_PROPERTY: {
         message: "Unknown configuration key.",
-        cause: "A key the configuration does not define at that place: a typo, or a key written at the wrong level of the tree.",
+        cause: "A key the configuration does not define at that place: a typo, or a key written at the wrong level of the tree. `policy` and `prebuilt` are root-only keys; in an overlay they read as unknown.",
         fix: 'Remove it, or move it where it belongs (the configuration reference\'s "Where a key can go").',
     },
     CONFIG_INVALID_TYPE: {
@@ -16,7 +16,7 @@ export const CONFIG_DIAGNOSTIC_GUIDANCE = {
     },
     CONFIG_INVALID_VALUE: {
         message: "A configuration value is not allowed.",
-        cause: 'A malformed api or mcp path, a negative limit, an unknown transactionsStyle, a format that is not a named zod format, or forceTransaction under an effective transactionsStyle "none".',
+        cause: 'A malformed api or mcp path, a negative limit, an unknown transactionsStyle, a format that is not a named zod format, forceTransaction under an effective transactionsStyle "none", an after check on any action but update, or a policy engine\'s governed, paths or afterChecks naming a Resource, field or path the Core Contract does not have (the message names the Resource or the rule).',
         fix: "Use a value the message allows.",
     },
     CONFIG_MOVED_PROPERTY: {

package/dist/config/config.resolver.d.ts

@@ -1,6 +1,7 @@
 import type { AvAdapter } from "../adapters/adapter.interface.js";
 import type { AvAdapterModel } from "../adapters/adapter-model.js";
 import type { AvTransactionCapability } from "../contracts/transaction-capability.js";
+import type { AvPolicyEngine } from "../policy/policy-engine.js";
 import type { AvDiagnosticsSink } from "../runtime/diagnostics-reporter.js";
 import type { AvMisuseSink } from "../runtime/misuse-reporter.js";
 import type { AvConfigAgentParent } from "./config-layer.js";
@@ -8,6 +9,17 @@ import { type ResolvedComputeConfig } from "./field-compute.resolver.js";
 import type { AvConfig, AvConfigLimits } from "./framework-config.js";
 import type { AvConfigFieldDefinition } from "./framework-field-definition.js";
 import { type ResolvedPipelineTree } from "./pipeline-tree.resolver.js";
+/** The root's `policy`, its engine's passive lists read once. */
+export type ResolvedPolicyConfig = {
+    readonly engine: AvPolicyEngine;
+    readonly principal: NonNullable<AvConfig["policy"]>["principal"];
+    /** The governed fields and relations, by Resource. */
+    readonly governed: Readonly<Record<string, readonly string[]>>;
+    /** The rule paths, by rule name, each a list of segments. */
+    readonly paths: Readonly<Record<string, readonly (readonly string[])[]>>;
+    /** The writes whose grants carry an `after` condition, by Resource. */
+    readonly afterChecks: Readonly<Record<string, readonly string[]>>;
+};
 /** The root's field definitions, by Resource and field name. */
 export type ResolvedFieldDefinitions = Readonly<Record<string, Readonly<Record<string, AvConfigFieldDefinition>>>>;
 /** One resolved layer of the configuration: root, application, client or agent. */
@@ -63,6 +75,8 @@ export type ResolvedFrameworkConfig<M extends AvAdapterModel = AvAdapterModel> =
     readonly diagnostics: AvDiagnosticsSink | undefined;
     /** The misuse sink, from the root configuration only. */
     readonly misuse: AvMisuseSink | undefined;
+    /** The policy, from the root configuration only; absent, nothing is checked. */
+    readonly policy: ResolvedPolicyConfig | undefined;
     /** Every field definition, from the root only; the same for all three layers. */
     readonly definitions: ResolvedFieldDefinitions;
     /** Each layer's `resources` tree as authored: the compiler checks its names. */

package/dist/config/config.resolver.js

@@ -140,6 +140,36 @@ function resolveMcp(mcp) {
             }),
         });
 }
+function frozenLists(value) {
+    if (!isPlainRecord(value)) {
+        return Object.freeze({});
+    }
+    return Object.freeze(Object.fromEntries(Object.entries(value).map(([key, names]) => [
+        key,
+        Object.freeze([...names]),
+    ])));
+}
+function frozenPathLists(value) {
+    if (!isPlainRecord(value)) {
+        return Object.freeze({});
+    }
+    return Object.freeze(Object.fromEntries(Object.entries(value).map(([key, paths]) => [
+        key,
+        Object.freeze(paths.map((path) => Object.freeze([...path]))),
+    ])));
+}
+function resolvePolicy(policy) {
+    if (policy === undefined) {
+        return undefined;
+    }
+    return Object.freeze({
+        engine: policy.engine,
+        principal: policy.principal,
+        governed: frozenLists(policy.engine.governed),
+        paths: frozenPathLists(policy.engine.paths),
+        afterChecks: frozenLists(policy.engine.afterChecks),
+    });
+}
 export function resolveFrameworkConfig(config) {
     const root = config;
     const application = config.application;
@@ -158,6 +188,7 @@ export function resolveFrameworkConfig(config) {
         adapter: config.adapter,
         diagnostics: config.diagnostics,
         misuse: config.misuse,
+        policy: resolvePolicy(config.policy),
         definitions: definitionsOf(root.resources),
         trees: {
             root: root.resources,

package/dist/config/config.validator.js

@@ -5,6 +5,8 @@ const ROOT_ONLY_PROPERTIES = new Set([
     "api",
     "mcp",
     "adapter",
+    "prebuilt",
+    "policy",
     "diagnostics",
     "misuse",
     "application",
@@ -618,6 +620,14 @@ export function validateFrameworkConfig(value) {
     else {
         validateAdapter(value.adapter, diagnostics);
     }
+    if (Object.hasOwn(value, "prebuilt") &&
+        value.prebuilt !== undefined &&
+        (value.prebuilt === null || typeof value.prebuilt !== "object")) {
+        diagnostics.push(diagnostic("CONFIG_INVALID_TYPE", "prebuilt", "prebuilt must be the generated prebuilt Contracts object when provided"));
+    }
+    if (Object.hasOwn(value, "policy") && value.policy !== undefined) {
+        validatePolicy(value.policy, diagnostics);
+    }
     if (Object.hasOwn(value, "diagnostics") &&
         value.diagnostics !== undefined &&
         typeof value.diagnostics !== "function") {
@@ -639,6 +649,78 @@ export function validateFrameworkConfig(value) {
     }
     return diagnostics;
 }
+const POLICY_PROPERTIES = new Set(["engine", "principal"]);
+function validatePolicy(value, diagnostics) {
+    if (!isPlainRecord(value)) {
+        diagnostics.push(diagnostic("CONFIG_INVALID_TYPE", "policy", "policy must be { engine, principal }"));
+        return;
+    }
+    for (const key of Object.keys(value)) {
+        if (!POLICY_PROPERTIES.has(key)) {
+            diagnostics.push(diagnostic("CONFIG_UNKNOWN_PROPERTY", `policy.${key}`, `unknown policy property: ${key}`));
+        }
+    }
+    if (!Object.hasOwn(value, "principal")) {
+        diagnostics.push(diagnostic("CONFIG_REQUIRED", "policy.principal", "policy.principal is required"));
+    }
+    else if (typeof value.principal !== "function") {
+        diagnostics.push(diagnostic("CONFIG_INVALID_TYPE", "policy.principal", "policy.principal must be a function"));
+    }
+    if (!Object.hasOwn(value, "engine")) {
+        diagnostics.push(diagnostic("CONFIG_REQUIRED", "policy.engine", "policy.engine is required"));
+        return;
+    }
+    const engine = value.engine;
+    if (engine === null || typeof engine !== "object") {
+        diagnostics.push(diagnostic("CONFIG_INVALID_TYPE", "policy.engine", "policy.engine 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", `policy.engine.${question}`, `policy.engine.${question} must be a function`));
+        }
+    }
+    validatePolicyLists(members.governed, "governed", { all: "string lists", one: "a list of strings" }, isStringList, diagnostics);
+    validatePolicyLists(members.paths, "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, "afterChecks", { all: "action lists", one: "a list of actions" }, isStringList, diagnostics);
+    validateAfterCheckActions(members.afterChecks, diagnostics);
+}
+function validateAfterCheckActions(lists, 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", `policy.engine.afterChecks.${resource}`, `policy.engine.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, list, entry, isEntry, diagnostics) {
+    if (lists === undefined) {
+        return;
+    }
+    if (!isPlainRecord(lists)) {
+        diagnostics.push(diagnostic("CONFIG_INVALID_TYPE", `policy.engine.${list}`, `policy.engine.${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", `policy.engine.${list}.${key}`, `policy.engine.${list}.${key} must be ${entry.one}`));
+        }
+    }
+}
 function validateMcp(value, api, diagnostics) {
     if (typeof value === "string") {
         validateMcpPath(value, "mcp", api, diagnostics);

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

@@ -238,6 +238,11 @@ type RootSchema<M extends AvAdapterModel, Cfg> = LayerKeysSchema & {
     readonly api: Leaf;
     readonly mcp: McpSchema;
     readonly adapter: Leaf;
+    readonly prebuilt: Leaf;
+    readonly policy: {
+        readonly engine: Leaf;
+        readonly principal: Leaf;
+    };
     readonly diagnostics: Leaf;
     readonly misuse: Leaf;
     readonly resources: RootResourcesSchema<M>;

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

@@ -2,10 +2,13 @@ import type { AvAdapter } from "../adapters/adapter.interface.js";
 import type { AvAdapterModel } from "../adapters/adapter-model.js";
 import type { AvContractLimits } from "../contracts/contract-limits.js";
 import type { AvTransactionCapability } from "../contracts/transaction-capability.js";
+import type { AvPolicyEngine } from "../policy/policy-engine.js";
+import type { AvPrebuiltContracts } from "../prebuilt/prebuilt-contracts.js";
 import type { AvDiagnosticsSink } from "../runtime/diagnostics-reporter.js";
 import type { AvMisuseSink } from "../runtime/misuse-reporter.js";
+import type { AvState } from "../runtime/request-state.js";
 import type { AvConfigAny } from "./any-framework-config.js";
-import type { AvConfigLayerName } from "./config-layer.js";
+import type { AvConfigLayerName, AvRequestOrigin } from "./config-layer.js";
 import type { AvConfigExemptions } from "./framework-exemptions-config.js";
 import type { AvConfigLayerKind, AvConfigResources, LayerOfKind } from "./framework-resources-config.js";
 import type { AvPipeline } from "./pipeline-config.js";
@@ -71,6 +74,32 @@ export type AvConfig<M extends AvAdapterModel = AvAdapterModel, Cfg = AvConfigAn
      */
     readonly mcp?: AvConfigMcp;
     readonly adapter: AvAdapter<M>;
+    /**
+     * Contracts compiled ahead of time (the generated `aventaraContracts`), for a
+     * fast cold start on serverless and edge platforms. Used only when they were
+     * compiled from this configuration and the adapter's model by this core;
+     * otherwise the Contracts are compiled at startup, as without it, and a
+     * `AVENTARA_PREBUILT_STALE` warning says why.
+     */
+    readonly prebuilt?: AvPrebuiltContracts;
+    /**
+     * The policy engine every client and agent request is checked against, and
+     * how a request's principal is derived from its `ctx.$state`. Application
+     * calls bypass it unless they name a principal (`{ as }`); calls a stage
+     * makes through `ctx` always do.
+     */
+    readonly policy?: {
+        readonly engine: AvPolicyEngine;
+        /**
+         * The request's principal, from its `ctx.$state` and its layer; `null` for
+         * an anonymous caller. It may answer with a promise (rc.5), which is
+         * awaited; a throw or a rejection answers `A3000`.
+         */
+        readonly principal: (facts: {
+            readonly $state: AvState;
+            readonly $origin: AvRequestOrigin;
+        }) => unknown;
+    };
     readonly diagnostics?: AvDiagnosticsSink;
     /** Told about every caller value refused as unreadable or not plain data. */
     readonly misuse?: AvMisuseSink;

package/dist/contracts/client-contract-structure.validator.d.ts

@@ -498,6 +498,10 @@ export declare const CLIENT_CONTRACT_STRUCTURE: {
                                             readonly minimum: 0;
                                             readonly unique: false;
                                         };
+                                        readonly governed: {
+                                            readonly is: "literal";
+                                            readonly values: readonly [true];
+                                        };
                                     };
                                 };
                                 readonly relation: {
@@ -694,6 +698,10 @@ export declare const CLIENT_CONTRACT_STRUCTURE: {
                                             readonly minimum: 1;
                                             readonly unique: false;
                                         };
+                                        readonly governed: {
+                                            readonly is: "literal";
+                                            readonly values: readonly [true];
+                                        };
                                     };
                                 };
                             };

package/dist/contracts/client-contract-structure.validator.js

@@ -237,6 +237,7 @@ const SCALAR_FIELD = object({
     format: STRING,
     json: { is: "jsonSchema" },
     validators: list(FIELD_CHECK),
+    governed: literal([true]),
 });
 const RELATION_FIELD = object({
     kind: literal(["relation"]),
@@ -257,7 +258,11 @@ const RELATION_FIELD = object({
         update: RELATION_MUTATION,
         nestedWriteFilter: literal(["scalar"]),
     }),
-}, { inverse: STRING, referenceFields: nonEmptyList(STRING) });
+}, {
+    inverse: STRING,
+    referenceFields: nonEmptyList(STRING),
+    governed: literal([true]),
+});
 const OPERATION_AVAILABILITY = union(literal([true]), object({ projection: literal(PROJECTION_SCOPES) }, { write: literal(WRITE_SCOPES) }), object({ write: literal(WRITE_SCOPES) }, { projection: literal(PROJECTION_SCOPES) }));
 const RESOURCE = object({
     fields: registry({

package/dist/contracts/contract.d.ts

@@ -1,6 +1,7 @@
 import type { AvContractLimits } from "./contract-limits.js";
 import type { AvContractClientProtocol } from "./contract-protocol.js";
 import type { AvEnumDefinition } from "./enum-definition.js";
+import type { AvCoreField } from "./field.js";
 import type { ReferenceWriteLimit } from "./reference-write-limit.js";
 import type { AvResource } from "./resource.js";
 import type { AvScalarRegistry } from "./scalar.js";
@@ -24,8 +25,21 @@ export interface AvContract {
      */
     readonly referenceWrites?: ReferenceWriteLimit;
 }
-/** The Contract compiled from the root configuration. */
+/**
+ * The Contract compiled from the root configuration. Its relation fields also
+ * state the target's fields their reference names (`references`), which no
+ * other Contract carries.
+ */
 export interface AvContractCore extends AvContract {
+    /** The Resources, by name. */
+    readonly resources: Readonly<Record<string, AvCoreResource>>;
+}
+/**
+ * A Resource as the Core Contract states it: its fields are
+ * {@link AvCoreField}s, so its relation fields carry `references`.
+ */
+export interface AvCoreResource extends AvResource<AvContractCore> {
+    readonly fields: Readonly<Record<string, AvCoreField<AvContractCore>>>;
 }
 /** The Contract in-process calls run under (`framework.application`). */
 export interface AvContractApplication extends AvContract {

package/dist/contracts/field.d.ts

@@ -138,6 +138,12 @@ export type AvScalarField<C extends AvContract> = {
      * `list: true` length check, which applies to the list.
      */
     readonly validators?: readonly AvFieldCheck[];
+    /**
+     * `true` when the policy governs the field: it is left out of every default
+     * projection, and a caller that wants it names it (`select: ["$defaults",
+     * "email"]`).
+     */
+    readonly governed?: true;
 };
 /** A relation field; the `target` Resource describes the related row. */
 export type AvRelationField<C extends AvContract> = {
@@ -162,6 +168,28 @@ export type AvRelationField<C extends AvContract> = {
      * holds no reference, and where the layer shows none of them.
      */
     readonly referenceFields?: readonly [string, ...string[]];
+    /**
+     * `true` when the policy engine's `governed` set names the relation: including
+     * it on rows the caller may not read it on refuses the request.
+     */
+    readonly governed?: true;
 };
 /** One field of a Resource: a scalar or a relation. */
 export type AvField<C extends AvContract> = AvScalarField<C> | AvRelationField<C>;
+/**
+ * A relation field as the Core Contract states it: an {@link AvRelationField}
+ * and, on the end that holds the reference, the target's fields it names.
+ */
+export type AvCoreRelationField<C extends AvContract> = AvRelationField<C> & {
+    /**
+     * The target's scalar fields that `referenceFields` name, pair by pair in the
+     * same order (`Post.author`: `referenceFields: ["authorId"]`,
+     * `references: ["id"]`). Present only beside a `referenceFields` the
+     * Contract states whole, and only when every one of them is a scalar field
+     * the Core Contract shows on the target; absent on the end that holds no
+     * reference, where the other end (`inverse`) states the pairs.
+     */
+    readonly references?: readonly [string, ...string[]];
+};
+/** One field of a Resource as the Core Contract states it. */
+export type AvCoreField<C extends AvContract> = AvScalarField<C> | AvCoreRelationField<C>;

package/dist/contracts/scalar-value-type.d.ts

@@ -78,5 +78,7 @@ type ListValue<List, Atom> = [List] extends [false] ? Atom : [List] extends [tru
  * - `list: true` → `readonly T[]`, whose entries are never `null`;
  * - `nullable: true` → `| null`, on the whole value, list or not.
  */
-export type AvScalarValueType<C extends AvContract, Field extends AvScalarField<C>, Forms extends ScalarForms = AvApplicationScalarForms> = ListValue<Field["list"], FieldAtom<C, Field, Forms>> | (true extends Field["nullable"] ? null : never);
+export type AvScalarValueType<C extends AvContract, Field extends AvScalarField<C>, Forms extends ScalarForms = AvApplicationScalarForms> = [
+    ListValue<Field["list"], FieldAtom<C, Field, Forms>> | (true extends Field["nullable"] ? null : never)
+] extends [infer Value] ? Value : never;
 export {};