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

package/dist/runtime/computed-read-runtime.js

@@ -1,3 +1,4 @@
+import { adapterPrimaryIdentifier } from "../adapters/adapter-identifier.js";
 import { lookupField, lookupResource } from "../contracts/contract-lookup.js";
 import { AvComputedValueError } from "./computed-value.error.js";
 import { frozenCopy } from "./readonly-value.js";
@@ -37,12 +38,6 @@ function appendUniqueProjection(values, value) {
         values.push(value);
     }
 }
-function adapterIdentifier(model, resource) {
-    const resources = model.resources;
-    return ((Object.hasOwn(resources, resource)
-        ? resources[resource]?.identifiers?.[0]
-        : undefined) ?? []);
-}
 function supportsProjection(request) {
     if (request.family === "upsert") {
         return true;
@@ -59,7 +54,7 @@ function addScalarProjection(core, model, active, compute, resourceName, fieldNa
     if (stage !== undefined) {
         appendUnique(computed, fieldName);
         if (stage.dependsOn.length === 0) {
-            for (const member of adapterIdentifier(model, resourceName)) {
+            for (const member of adapterPrimaryIdentifier(model, resourceName)) {
                 appendUniqueProjection(adapterSelect, member);
             }
         }
@@ -89,18 +84,27 @@ function projectionEntry(entry) {
 function withoutProjectionChoice(value) {
     return Object.fromEntries(Object.entries(value).filter(([key]) => key !== "select" && key !== "include"));
 }
-function defaultProjectionLevel(core, model, active, compute, resourceName) {
+export function defaultProjectionFields(active, resourceName) {
     const activeResource = lookupResource(active, resourceName);
+    if (activeResource === undefined) {
+        return [];
+    }
+    const fields = [];
+    for (const [fieldName, field] of Object.entries(activeResource.fields)) {
+        if (field.kind === "scalar" &&
+            field.capabilities.select === true &&
+            field.governed !== true) {
+            fields.push(fieldName);
+        }
+    }
+    return fields;
+}
+function defaultProjectionLevel(core, model, active, compute, resourceName) {
     const adapterSelect = [];
     const requested = [];
     const computed = [];
-    if (activeResource !== undefined) {
-        for (const [fieldName, field] of Object.entries(activeResource.fields)) {
-            if (field.kind !== "scalar" || field.capabilities.select !== true) {
-                continue;
-            }
-            addScalarProjection(core, model, active, compute, resourceName, fieldName, adapterSelect, requested, computed);
-        }
+    for (const fieldName of defaultProjectionFields(active, resourceName)) {
+        addScalarProjection(core, model, active, compute, resourceName, fieldName, adapterSelect, requested, computed);
     }
     return {
         select: adapterSelect,
@@ -168,6 +172,12 @@ function planSelectLevel(core, model, active, compute, resourceName, select, col
     }
     for (const entry of select) {
         if (typeof entry === "string") {
+            if (entry === "$defaults") {
+                for (const fieldName of defaultProjectionFields(active, resourceName)) {
+                    addScalarProjection(core, model, active, compute, resourceName, fieldName, adapterSelect, requested, computed);
+                }
+                continue;
+            }
             if (entry === "$count") {
                 adapterSelect.push(entry);
                 if (collectReducers) {
@@ -292,7 +302,175 @@ export function planReadOperation(core, model, active, compute, request, args) {
         materialize: defaults.plan.computed.length > 0,
     };
 }
-async function materializeRelation(active, compute, request, relation, value, contextFactory) {
+function resolveReadLevel(active, compute, plan, tail) {
+    const resource = lookupResource(active, plan.resource);
+    if (resource === undefined) {
+        return undefined;
+    }
+    const stages = [];
+    for (const fieldName of plan.computed) {
+        const field = lookupField(resource, fieldName);
+        const stage = readCompute(compute?.[plan.resource]?.[fieldName]?.read);
+        if (field?.kind !== "scalar" || stage === undefined) {
+            continue;
+        }
+        stages.push({
+            field: fieldName,
+            definition: field,
+            compute: stage.compute,
+        });
+    }
+    const relations = [];
+    let restFree = true;
+    for (const relation of [...plan.relations].reverse()) {
+        const level = resolveReadLevel(active, compute, relation.projection, tail && restFree);
+        relations.unshift({ relation, level });
+        restFree &&= level?.computeFree ?? true;
+    }
+    return {
+        plan,
+        stages,
+        relations,
+        computeFree: stages.length === 0 && restFree,
+        atOnce: tail && stages.length <= 1 && restFree,
+        plainKeys: plan.requested.every((field) => !(field in Object.prototype)),
+    };
+}
+function isNestedContainer(value) {
+    return (value !== null &&
+        typeof value === "object" &&
+        !(value instanceof Date) &&
+        !(value instanceof Uint8Array));
+}
+function isThenable(value) {
+    return (value !== null &&
+        (typeof value === "object" || typeof value === "function") &&
+        typeof value.then === "function");
+}
+function setOwn(target, key, value) {
+    if (key in target) {
+        Object.defineProperty(target, key, {
+            value,
+            writable: true,
+            enumerable: true,
+            configurable: true,
+        });
+        return;
+    }
+    target[key] = value;
+}
+function answerOf(level, record) {
+    const answer = {};
+    for (const fieldName of level.plan.requested) {
+        if (!Object.hasOwn(record, fieldName)) {
+            continue;
+        }
+        if (level.plainKeys) {
+            answer[fieldName] = record[fieldName];
+        }
+        else {
+            setOwn(answer, fieldName, record[fieldName]);
+        }
+    }
+    return answer;
+}
+function heldReadValue(active, level, stage, value) {
+    const validation = normalizeScalarFieldValue(active, stage.definition, value, "runtime", [
+        "resources",
+        level.plan.resource,
+        "fields",
+        stage.field,
+        "pipelines",
+        "compute",
+        "read",
+    ]);
+    if (!validation.ok) {
+        throw new AvComputedValueError(level.plan.resource, stage.field, "read", validation.issues);
+    }
+    return validation.value;
+}
+function projectedAtOnce(level, value) {
+    if (!isRecord(value) || level === undefined) {
+        return value;
+    }
+    const record = { ...value };
+    relationsAtOnce(level, record);
+    return answerOf(level, record);
+}
+function relationsAtOnce(level, record) {
+    for (const { relation, level: nested } of level.relations) {
+        if (!Object.hasOwn(record, relation.field)) {
+            continue;
+        }
+        const value = record[relation.field];
+        if (value === null || value === undefined) {
+            continue;
+        }
+        if (relation.cardinality === "many") {
+            if (Array.isArray(value)) {
+                record[relation.field] = Array.from(value, (entry) => projectedAtOnce(nested, entry));
+            }
+            continue;
+        }
+        record[relation.field] = projectedAtOnce(nested, value);
+    }
+}
+function computedAtOnce(active, level, stage, value, contextFactory) {
+    const record = { ...value };
+    const view = frozenCopy(record);
+    let computedValue;
+    try {
+        computedValue = stage.compute({
+            field: stage.field,
+            value: view[stage.field],
+            record: view,
+            ctx: contextFactory(),
+        });
+    }
+    catch (error) {
+        return Promise.reject(error);
+    }
+    const finish = (returned) => {
+        if (returned !== undefined) {
+            record[stage.field] = heldReadValue(active, level, stage, returned);
+        }
+        relationsAtOnce(level, record);
+        return answerOf(level, record);
+    };
+    const later = (error) => Promise.resolve().then(() => {
+        throw error;
+    });
+    let waits;
+    try {
+        waits = isThenable(computedValue);
+    }
+    catch (error) {
+        return later(error);
+    }
+    if (waits) {
+        const pending = computedValue;
+        return (async () => finish(await pending))();
+    }
+    try {
+        return finish(computedValue);
+    }
+    catch (error) {
+        return later(error);
+    }
+}
+function materializeRecord(active, level, value, contextFactory) {
+    if (level?.atOnce !== true) {
+        return materializeInTurn(active, level, value, contextFactory);
+    }
+    if (!isRecord(value)) {
+        return value;
+    }
+    const [stage] = level.stages;
+    return stage === undefined
+        ? projectedAtOnce(level, value)
+        : computedAtOnce(active, level, stage, value, contextFactory);
+}
+async function materializeRelation(active, level, relation, value, contextFactory) {
     if (value === null || value === undefined) {
         return value;
     }
@@ -300,66 +478,62 @@ async function materializeRelation(active, compute, request, relation, value, co
         if (!Array.isArray(value)) {
             return value;
         }
-        return Promise.all(value.map((entry) => materializeRecord(active, compute, request, relation.projection, entry, contextFactory)));
+        return Promise.all(value.map((entry) => materializeRecord(active, level, entry, contextFactory)));
     }
-    return materializeRecord(active, compute, request, relation.projection, value, contextFactory);
+    return materializeRecord(active, level, value, contextFactory);
 }
-async function materializeRecord(active, compute, request, plan, value, contextFactory) {
-    if (!isRecord(value)) {
-        return value;
-    }
-    const resource = lookupResource(active, plan.resource);
-    if (resource === undefined) {
+async function materializeInTurn(active, level, value, contextFactory) {
+    if (!isRecord(value) || level === undefined) {
         return value;
     }
+    const { stages } = level;
     const record = { ...value };
-    for (const fieldName of plan.computed) {
-        const field = lookupField(resource, fieldName);
-        const stage = readCompute(compute?.[plan.resource]?.[fieldName]?.read);
-        if (field?.kind !== "scalar" || stage === undefined) {
-            continue;
+    let told;
+    if (stages.length > 1) {
+        told = { ...record };
+        for (const key of Object.keys(told)) {
+            const nested = told[key];
+            if (isNestedContainer(nested)) {
+                told[key] = frozenCopy(nested, true);
+            }
         }
-        const view = frozenCopy(record);
+    }
+    for (const stage of stages) {
+        const view = frozenCopy(told ?? record);
         const computedValue = await stage.compute({
-            field: fieldName,
-            value: view[fieldName],
+            field: stage.field,
+            value: view[stage.field],
             record: view,
             ctx: contextFactory(),
         });
         if (computedValue === undefined) {
             continue;
         }
-        const validation = normalizeScalarFieldValue(active, field, computedValue, "runtime", [
-            "resources",
-            plan.resource,
-            "fields",
-            fieldName,
-            "pipelines",
-            "compute",
-            "read",
-        ]);
-        if (!validation.ok) {
-            throw new AvComputedValueError(plan.resource, fieldName, "read", validation.issues);
+        const held = heldReadValue(active, level, stage, computedValue);
+        record[stage.field] = held;
+        if (told !== undefined) {
+            told[stage.field] = held;
         }
-        record[fieldName] = validation.value;
     }
-    for (const relation of plan.relations) {
+    for (const { relation, level: nested } of level.relations) {
         if (!Object.hasOwn(record, relation.field)) {
             continue;
         }
-        record[relation.field] = await materializeRelation(active, compute, request, relation, record[relation.field], contextFactory);
+        record[relation.field] = await materializeRelation(active, nested, relation, record[relation.field], contextFactory);
     }
-    return Object.fromEntries(plan.requested
-        .filter((fieldName) => Object.hasOwn(record, fieldName))
-        .map((fieldName) => [fieldName, record[fieldName]]));
+    return answerOf(level, record);
 }
-export async function materializeReadOperation(active, compute, request, plan, value, contextFactory) {
+export async function materializeReadOperation(active, compute, _request, plan, value, contextFactory) {
     const projection = plan.projection;
     if (!plan.materialize || projection === undefined) {
         return value;
     }
+    const level = resolveReadLevel(active, compute, projection, true);
     if (Array.isArray(value)) {
-        return Promise.all(value.map((entry) => materializeRecord(active, compute, request, projection, entry, contextFactory)));
+        const rows = value.map((entry) => materializeRecord(active, level, entry, contextFactory));
+        return rows.some((row) => row instanceof Promise)
+            ? Promise.all(rows)
+            : Array.from(rows);
     }
-    return materializeRecord(active, compute, request, projection, value, contextFactory);
+    return materializeRecord(active, level, value, contextFactory);
 }

package/dist/runtime/context-executor.runtime.d.ts

@@ -7,7 +7,7 @@ import type { AvOperationFamily } from "../operations/operation-identity.js";
 import { type AvDiagnosticsSink } from "./diagnostics-reporter.js";
 import type { AvComputeContext } from "./field-compute.js";
 import type { MisuseReporter } from "./misuse-reporter.js";
-import type { ApplicationOperationRequest } from "./operation-request.js";
+import type { AvApplicationOperationRequest } from "./operation-request.js";
 import type { AvOperationResponse } from "./operation-response.js";
 import type { AvContext, AvTransactionContext, AvTransportContext } from "./pipeline.js";
 import type { AvState } from "./request-state.js";
@@ -35,7 +35,7 @@ export type ContextFacts = {
     readonly $args: unknown;
 };
 /** Runs one raw application-origin call in `transaction`, or standalone. Total. */
-export type RawOperationRunner<M extends AvAdapterModel> = (request: ApplicationOperationRequest, transaction: AvAdapterTransactionExecutor<M> | undefined) => Promise<AvOperationResponse>;
+export type RawOperationRunner<M extends AvAdapterModel> = (request: AvApplicationOperationRequest, transaction: AvAdapterTransactionExecutor<M> | undefined) => Promise<AvOperationResponse>;
 export type ContextExecutorDependencies<M extends AvAdapterModel> = {
     /** The model, as construction read it once: the ctx's Resources. */
     readonly model: M;

package/dist/runtime/context-executor.runtime.js

@@ -195,9 +195,10 @@ export function createContextExecutor(dependencies) {
     const contextOf = (prototype, scope, facts, readOnly = false) => {
         const context = Object.create(prototype);
         Object.defineProperty(context, STATE, {
-            value: { scope, facts, resources: new Map() },
+            value: { scope, facts, resources: undefined },
         });
-        for (const [key, value] of Object.entries(facts)) {
+        for (const key of Object.keys(facts)) {
+            const value = facts[key];
             if (value !== undefined) {
                 Object.defineProperty(context, key, { value, enumerable: true });
             }
@@ -232,6 +233,7 @@ export function createContextExecutor(dependencies) {
             Object.defineProperty(prototype, resource, {
                 get() {
                     const state = stateOf(this);
+                    state.resources ??= new Map();
                     let tree = state.resources.get(resource);
                     if (tree === undefined) {
                         tree = resourceTree(state.scope, resource, readOnly);

package/dist/runtime/create-requirement.js

@@ -13,7 +13,7 @@ function edgesOf(table, resource) {
     return Array.isArray(listed) ? listed : [];
 }
 function referencesOf(edge) {
-    return Array.isArray(edge.references) ? edge.references : [];
+    return Array.isArray(edge.referenceFields) ? edge.referenceFields : [];
 }
 function creatableScalar(contract, resource, field) {
     const found = lookupField(lookupResource(contract, resource), field);

package/dist/runtime/diagnostics-reporter.d.ts

@@ -1,7 +1,7 @@
 import type { AvRequestOrigin } from "../config/config-layer.js";
 import type { AvOperationFamily } from "../operations/operation-identity.js";
-import type { FrameworkTransactionRequest } from "../transactions/transaction-request.js";
-import type { FrameworkOperationRequest } from "./operation-request.js";
+import type { AvTransactionRequest } from "../transactions/transaction-request.js";
+import type { AvOperationRequest } from "./operation-request.js";
 import { type AvOperationErrorCode, type AvOperationFailureResponse } from "./operation-response.js";
 /**
  * One unplanned failure of an operation: the raw error, the code the caller
@@ -100,14 +100,14 @@ export declare function diagnosticsSinkOf(framework: object): AvDiagnosticsSink
  * Binds the configured sink to one operation request. The sink is not awaited,
  * and nothing it throws or rejects with reaches the response.
  */
-export declare function createDiagnosticsReporter(sink: AvDiagnosticsSink | undefined, request: FrameworkOperationRequest, operation?: number): DiagnosticsReporter;
+export declare function createDiagnosticsReporter(sink: AvDiagnosticsSink | undefined, request: AvOperationRequest, operation?: number): DiagnosticsReporter;
 /** The diagnostics channel of one transaction request. */
 export type TransactionDiagnosticsChannel = {
     /** A plan-level report; `operation` attributes it to a recorded failing index. */
     readonly transaction: (operation?: number) => DiagnosticsReporter;
     /** A report carrying one plan operation's own identity and index. */
-    readonly operation: (request: FrameworkOperationRequest, operation: number) => DiagnosticsReporter;
+    readonly operation: (request: AvOperationRequest, operation: number) => DiagnosticsReporter;
 };
 /** Binds the configured sink to one transaction request and its plan operations. */
-export declare function createTransactionDiagnosticsChannel(sink: AvDiagnosticsSink | undefined, request: FrameworkTransactionRequest): TransactionDiagnosticsChannel;
+export declare function createTransactionDiagnosticsChannel(sink: AvDiagnosticsSink | undefined, request: AvTransactionRequest): TransactionDiagnosticsChannel;
 export {};

package/dist/runtime/execution-options.d.ts

@@ -18,4 +18,12 @@ export type AvExecutionOptions = {
      * object), the Framework starts the request with `{}`.
      */
     readonly state?: AvState & object;
+    /**
+     * The principal the call or run is checked as by the configuration's
+     * `policy`. An application call names one to opt in: left out, it is server
+     * code and the policy does not check it. A `framework.client.*` call is
+     * checked either way, and `as` replaces the principal `policy.principal`
+     * would derive from its state. `null` is the anonymous principal.
+     */
+    readonly as?: unknown;
 };

package/dist/runtime/framework-warning.emitter.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Emits a framework warning: through `process.emitWarning` (type
+ * `AventaraWarning`, `code` as given) where the runtime has it, else through
+ * `console.warn`. A warning changes no behaviour.
+ */
+export declare function emitFrameworkWarning(message: string, code: string): void;

package/dist/runtime/framework-warning.emitter.js

@@ -0,0 +1,8 @@
+export function emitFrameworkWarning(message, code) {
+    const emitWarning = globalThis.process?.emitWarning;
+    if (typeof emitWarning === "function") {
+        emitWarning(message, { type: "AventaraWarning", code });
+        return;
+    }
+    globalThis.console?.warn(`AventaraWarning: ${message}`);
+}

package/dist/runtime/level-lifecycle.runtime.js

@@ -20,8 +20,9 @@ export async function runLevelLifecycle(levels, context, inner, settle, reuse, r
         }
         const result = await settle(await inner());
         const after = [...levels].reverse().flatMap((level) => level.hooks.after);
-        for (const hook of after) {
-            await hook(frozenCopy(result), context());
+        const settled = after.length > 0 ? frozenCopy(result, true) : undefined;
+        for (const [index, hook] of after.entries()) {
+            await hook(index === after.length - 1 ? settled : frozenCopy(settled), context());
         }
         return result;
     };

package/dist/runtime/operation-code.guidance.js

@@ -66,7 +66,7 @@ export const OPERATION_CODE_GUIDANCE = {
     },
     A2003: {
         message: "Not found.",
-        cause: "A unique operation (find.unique, update.unique, delete.unique) matched no row, or a $connect names a record that does not exist. The operation fails, so no after hook runs.",
+        cause: "A unique operation (find.unique, update.unique, delete.unique) matched no row, or a $connect names a record that does not exist. The operation fails, so no after hook runs. Under a policy, a row outside the caller's read scope is a miss too, and so is a single-row update or delete of a row the caller cannot read, so the answer does not reveal that the row exists. A row the caller can read but not change answers A4002.",
         fix: "Catch AvNotFoundError, or use a first-style operation, which answers A1001 with null. Check the $connect identifier.",
     },
     A2004: {
@@ -161,7 +161,7 @@ export const OPERATION_CODE_GUIDANCE = {
     },
     A4002: {
         message: "Policy denied.",
-        cause: 'A guard or hook threw new AvError("A4002", ...) with a policy reason of your own.',
-        fix: "Read cause.message for the policy's reason.",
+        cause: "The configuration's policy refused the request: its engine does not allow the operation, a field the request names, writes or returns, a row it reaches, a row it creates, or the row a change leaves (moved out of what the caller reads, or failing its grant's after condition, which rolls the write back); on a database without interactive transactions, a write the policy can only check after it runs; or a stage threw new AvError(\"A4002\", ...).",
+        fix: "Read cause.message, which names what the policy refused. Call as a principal the policy allows, leave the refused field or relation out (a governed one is named only where every row grants it), or change only rows the caller may change and still read afterwards.",
     },
 };

package/dist/runtime/operation-request.d.ts

@@ -1,11 +1,12 @@
 import type { AvOperationIdentity } from "../operations/operation-identity.js";
+import type { PolicySession } from "../policy/policy-session.js";
 import type { AvTransportContext } from "./pipeline.js";
 import type { AvState } from "./request-state.js";
 /**
  * The protocol version and Contract hash a remote caller says it was built for:
  * the Client Contract's for a client, the Agent Contract's for an agent.
  */
-export type ClientProtocolIdentity = {
+export type AvRequestProtocol = {
     readonly version: number;
     readonly hash: string;
 };
@@ -20,7 +21,7 @@ type RuntimeOperationBase = AvOperationIdentity & {
     readonly state?: AvState;
 };
 /** An in-process request, run under the Application Contract. */
-export type ApplicationOperationRequest = RuntimeOperationBase & {
+export type AvApplicationOperationRequest = RuntimeOperationBase & {
     readonly origin: "application";
     readonly protocol?: never;
     readonly transport?: never;
@@ -29,24 +30,24 @@ export type ApplicationOperationRequest = RuntimeOperationBase & {
  * A remote request, run under the Client Contract; `protocol` is the identity
  * the client sent.
  */
-export type ClientOperationRequest = RuntimeOperationBase & {
+export type AvClientOperationRequest = RuntimeOperationBase & {
     readonly origin: "client";
-    readonly protocol: ClientProtocolIdentity;
+    readonly protocol: AvRequestProtocol;
     readonly transport?: AvTransportContext;
 };
 /**
  * An AI agent's request, run under the Agent Contract; `protocol` is the
  * identity of the Agent Contract the caller (an MCP server) was built from.
  */
-export type AgentOperationRequest = RuntimeOperationBase & {
+export type AvAgentOperationRequest = RuntimeOperationBase & {
     readonly origin: "agent";
-    readonly protocol: ClientProtocolIdentity;
+    readonly protocol: AvRequestProtocol;
     readonly transport?: AvTransportContext;
 };
 /** A request from outside the server: a client's or an agent's. */
-export type RemoteOperationRequest = ClientOperationRequest | AgentOperationRequest;
+export type RemoteOperationRequest = AvClientOperationRequest | AvAgentOperationRequest;
 /** One operation request, as `framework.execute` takes it. */
-export type FrameworkOperationRequest = ApplicationOperationRequest | ClientOperationRequest | AgentOperationRequest;
+export type AvOperationRequest = AvApplicationOperationRequest | AvClientOperationRequest | AvAgentOperationRequest;
 type WithoutArguments<Request> = Request extends unknown ? Omit<Request, "arguments"> : never;
 /**
  * A request as every stage after the Framework Validation Layer sees it:
@@ -56,12 +57,18 @@ type WithoutArguments<Request> = Request extends unknown ? Omit<Request, "argume
  * unreachable by type. Distributive, so the origin and family/variant
  * correlations survive the omission.
  */
-export type OperationExecutionRequest = WithoutArguments<FrameworkOperationRequest>;
+export type OperationExecutionRequest = WithoutArguments<AvOperationRequest>;
 /**
  * A request whose stages run: its `state` settled once, the seed or the `{}`
  * the runtime made for it, so every stage is told the same object.
  */
 export type StatefulOperationRequest = OperationExecutionRequest & {
     readonly state: AvState;
+    /**
+     * The request's policy session, when the policy checks it: a client's or an
+     * agent's request, or an application call made `as` a principal. Absent, nothing
+     * is checked: an application call, or a call a stage made through `ctx`.
+     */
+    readonly policy?: PolicySession;
 };
 export {};

package/dist/runtime/operation-runtime.d.ts

@@ -7,14 +7,15 @@ import type { ResolvedFrameworkConfig } from "../config/config.resolver.js";
 import type { AvRequestOrigin, RemoteRequestOrigin } from "../config/config-layer.js";
 import type { AvContract } from "../contracts/contract.js";
 import type { OperationValidationOptions, SemanticOperationArguments } from "../operations/operation-validator.js";
-import type { FrameworkTransactionRequest } from "../transactions/transaction-request.js";
+import { type PolicyCaller } from "../policy/policy-request.js";
+import type { AvTransactionRequest } from "../transactions/transaction-request.js";
 import { type ArgumentsSource } from "./caller-data.door.js";
 import { type ContextExecutor, type ExecutorScope } from "./context-executor.runtime.js";
 import { type RecordWriteFacts } from "./create-requirement.js";
 import { type DiagnosticsReporter } from "./diagnostics-reporter.js";
 import { type OuterFailureLayer } from "./error-boundary.js";
 import { type FieldStagePlan } from "./field-stage.plan.js";
-import type { ClientProtocolIdentity, FrameworkOperationRequest, StatefulOperationRequest } from "./operation-request.js";
+import type { AvOperationRequest, AvRequestProtocol, StatefulOperationRequest } from "./operation-request.js";
 import type { AvOperationFailureResponse, AvOperationResponse } from "./operation-response.js";
 import type { AvState } from "./request-state.js";
 import { type NormalizationWrite } from "./scalar-runtime.js";
@@ -65,6 +66,11 @@ export declare function withRequestState<Request extends {
 }>(request: Request): Request & {
     readonly state: AvState;
 };
+/**
+ * `request` with its policy session when the policy checks it, or the failure
+ * deriving its principal answered.
+ */
+export declare function withRequestPolicy<M extends AvAdapterModel>(dependencies: Pick<OperationRuntimeDependencies<M>, "adapter" | "config" | "contracts">, request: StatefulOperationRequest, caller: PolicyCaller | undefined, report: DiagnosticsReporter): StatefulOperationRequest | AvOperationFailureResponse | Promise<StatefulOperationRequest | AvOperationFailureResponse>;
 /**
  * Builds what every operation's pipeline shares, the ctx executor included: its
  * raw calls run the application's operation path with every developer stage
@@ -79,13 +85,15 @@ export declare function createPipelineDependencies<M extends AvAdapterModel>(dep
  * request's arguments are the caller's own objects, copied at the door, or data
  * no caller holds (see {@link ArgumentsSource}).
  */
-export type FrameworkOperationExecutor = (request: FrameworkOperationRequest, report: DiagnosticsReporter, source: ArgumentsSource) => Promise<AvOperationResponse>;
+export type FrameworkOperationExecutor = (request: AvOperationRequest, report: DiagnosticsReporter, source: ArgumentsSource, 
+/** The principal an application call runs as (`{ as }`), when it names one. */
+caller?: PolicyCaller) => Promise<AvOperationResponse>;
 /** Selects the Contract of the request's origin. */
-export declare function activeContract(contracts: AvContracts, request: FrameworkOperationRequest | FrameworkTransactionRequest): AvContract;
+export declare function activeContract(contracts: AvContracts, request: AvOperationRequest | AvTransactionRequest): AvContract;
 /** Creates the transport-independent operation executor owned by core. */
 export declare function createOperationRuntime<M extends AvAdapterModel>(dependencies: OperationRuntimeDependencies<M>, pipelineDependencies: OperationPipelineDependencies<M>): FrameworkOperationExecutor;
 /** Validates the request-level protocol identity. */
-export declare function validateProtocolIdentity(contracts: AvContracts, request: FrameworkOperationRequest | FrameworkTransactionRequest): AvOperationFailureResponse | undefined;
+export declare function validateProtocolIdentity(contracts: AvContracts, request: AvOperationRequest | AvTransactionRequest): AvOperationFailureResponse | undefined;
 /**
  * The stale-client check on one remote protocol identity: the protocol version first
  * (`A2006`), then the hash of the origin's Contract (`A2005`): the ClientContract's
@@ -94,7 +102,7 @@ export declare function validateProtocolIdentity(contracts: AvContracts, request
  * (`@aventara/core/protocol`) call it too, so a stale client hears the same envelope
  * whichever layer answers.
  */
-export declare function protocolIdentityFailure(contracts: AvContracts, protocol: ClientProtocolIdentity, origin: RemoteRequestOrigin): AvOperationFailureResponse | undefined;
+export declare function protocolIdentityFailure(contracts: AvContracts, protocol: AvRequestProtocol, origin: RemoteRequestOrigin): AvOperationFailureResponse | undefined;
 export type ValidatedOperationArguments = {
     readonly ok: true;
     readonly arguments: SemanticOperationArguments;
@@ -103,7 +111,7 @@ export type ValidatedOperationArguments = {
     readonly response: AvOperationFailureResponse;
 };
 /** Validates one operation's arguments through the Framework Validation Layer. */
-export declare function validateOperationRequest(contract: AvContract, request: FrameworkOperationRequest, options?: OperationValidationOptions, write?: NormalizationWrite): ValidatedOperationArguments;
+export declare function validateOperationRequest(contract: AvContract, request: AvOperationRequest, options?: OperationValidationOptions, write?: NormalizationWrite): ValidatedOperationArguments;
 /** The subject a refused output of an operation's pipes is reported under at a plan step. */
 export declare const STEP_PIPES = "Pipes";
 /**