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

package/dist/prebuilt/prebuilt-inputs.fingerprint.js

@@ -0,0 +1,192 @@
+import { avzCheckOf } from "../avz/avz-check.registry.js";
+import { jsonShapeOf } from "../avz/json-shape.registry.js";
+import { hashCanonicalContractText } from "../contracts/contract-hash.js";
+import { AVENTARA_PROTOCOL_VERSION } from "../contracts/contract-protocol.js";
+import { CORE_VERSION } from "./core-version.generated.js";
+import { PREBUILT_FORMAT } from "./prebuilt-contracts.js";
+const LAYERS = ["root", "application", "client", "agent"];
+const NOT_INPUTS = new Set(["adapter", "prebuilt"]);
+const PER_RESOURCE = "#resources";
+function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function sortedRecord(record) {
+    const keys = Object.keys(record);
+    const prototype = Object.getPrototypeOf(record);
+    const plain = prototype === Object.prototype || prototype === null;
+    let written = plain;
+    for (let index = 0; written && index < keys.length; index += 1) {
+        const key = keys[index];
+        written =
+            !key.startsWith("#") &&
+                (index === 0 || keys[index - 1] < key);
+    }
+    if (written) {
+        return record;
+    }
+    const sorted = {};
+    if (!plain) {
+        const name = record.constructor?.name;
+        sorted["#class"] = typeof name === "string" ? name : "";
+    }
+    for (const key of keys.sort()) {
+        sorted[key.startsWith("#") ? `#${key}` : key] = record[key];
+    }
+    return sorted;
+}
+function inputMember(key, value) {
+    const raw = this[key];
+    switch (typeof raw) {
+        case "string":
+            return raw.startsWith("#") ? `#${raw}` : raw;
+        case "number":
+            return Number.isFinite(raw) ? raw : `#number(${raw})`;
+        case "bigint":
+            return `#bigint(${raw})`;
+        case "function":
+            return "#function";
+        case "symbol":
+            return `#symbol(${String(raw.description)})`;
+        case "undefined":
+            return "#undefined";
+        case "boolean":
+            return raw;
+    }
+    if (raw === null) {
+        return value;
+    }
+    const check = avzCheckOf(raw);
+    if (check !== undefined) {
+        return `#avz(${inputText(check)})`;
+    }
+    const shape = jsonShapeOf(raw);
+    if (shape !== undefined) {
+        return `#shape(${inputText(shape.schema)})`;
+    }
+    if (raw instanceof Date) {
+        return `#date(${Number.isNaN(raw.getTime()) ? "invalid" : raw.toISOString()})`;
+    }
+    if (raw instanceof RegExp) {
+        return `#regexp(${JSON.stringify(raw.source)},${raw.flags})`;
+    }
+    if (raw instanceof Map || raw instanceof Set) {
+        return `#${raw instanceof Map ? "map" : "set"}(${inputText([...raw])})`;
+    }
+    if (value !== raw) {
+        return `#json(${inputText(value)})`;
+    }
+    return Array.isArray(raw) ? raw : sortedRecord(raw);
+}
+function inputText(value) {
+    return JSON.stringify(value, inputMember);
+}
+function modelText(value) {
+    try {
+        return JSON.stringify(value) ?? "#undefined";
+    }
+    catch {
+        return inputText(value);
+    }
+}
+function recordAt(value, key) {
+    if (!isRecord(value) || !Object.hasOwn(value, key)) {
+        return undefined;
+    }
+    const member = value[key];
+    return isRecord(member) ? member : undefined;
+}
+function layerOf(config, layer) {
+    return layer === "root"
+        ? config
+        : Object.hasOwn(config, layer)
+            ? config[layer]
+            : undefined;
+}
+function sharedLayer(layer) {
+    if (!isRecord(layer)) {
+        return layer;
+    }
+    const shared = { ...layer };
+    if (isRecord(layer.resources)) {
+        shared.resources = PER_RESOURCE;
+    }
+    const exemptions = layer.exemptions;
+    if (isRecord(exemptions) && isRecord(exemptions.resources)) {
+        shared.exemptions = { ...exemptions, resources: PER_RESOURCE };
+    }
+    return shared;
+}
+function policyInput(policy) {
+    if (!isRecord(policy) || !Object.hasOwn(policy, "engine")) {
+        return policy;
+    }
+    const engine = policy.engine;
+    const governed = engine !== null && typeof engine === "object"
+        ? engine.governed
+        : undefined;
+    return { ...policy, engine: { governed: governed ?? null } };
+}
+function authoredInputs(config) {
+    const authored = config;
+    const root = {};
+    for (const key of Object.keys(authored)) {
+        if (!NOT_INPUTS.has(key)) {
+            root[key] = key === "policy" ? policyInput(authored[key]) : authored[key];
+        }
+    }
+    return root;
+}
+const HEADER = `aventara-prebuilt format ${PREBUILT_FORMAT} core ${CORE_VERSION} protocol ${AVENTARA_PROTOCOL_VERSION}`;
+export function prebuiltInputsFingerprint(model, config) {
+    return hashCanonicalContractText(`${HEADER}\n${inputText(authoredInputs(config))}\n${modelText(model)}`);
+}
+export async function prebuiltPartFingerprints(model, config) {
+    const root = authoredInputs(config);
+    const names = new Set(Object.keys(model.resources));
+    for (const layer of LAYERS) {
+        const value = layerOf(root, layer);
+        for (const name of Object.keys(recordAt(value, "resources") ?? {})) {
+            names.add(name);
+        }
+        const exemptions = recordAt(value, "exemptions");
+        for (const name of Object.keys(recordAt(exemptions, "resources") ?? {})) {
+            names.add(name);
+        }
+    }
+    const sharedRoot = sharedLayer(root);
+    for (const layer of LAYERS) {
+        if (layer !== "root" && Object.hasOwn(root, layer)) {
+            sharedRoot[layer] = sharedLayer(root[layer]);
+        }
+    }
+    const { resources: _resources, ...sharedModel } = model;
+    const shared = hashCanonicalContractText(`${HEADER}\n${inputText(sharedRoot)}\n${modelText(sharedModel)}`);
+    const sorted = [...names].sort();
+    const parts = sorted.map((name) => {
+        const entries = {};
+        for (const layer of LAYERS) {
+            const value = layerOf(root, layer);
+            const resources = recordAt(value, "resources");
+            const exemptions = recordAt(recordAt(value, "exemptions"), "resources");
+            const entry = {};
+            if (resources !== undefined && Object.hasOwn(resources, name)) {
+                entry.resources = resources[name];
+            }
+            if (exemptions !== undefined && Object.hasOwn(exemptions, name)) {
+                entry.exemptions = exemptions[name];
+            }
+            if (Object.keys(entry).length > 0) {
+                entries[layer] = entry;
+            }
+        }
+        const modelPart = Object.hasOwn(model.resources, name)
+            ? modelText(model.resources[name])
+            : "#absent";
+        return hashCanonicalContractText(`${inputText(entries)}\n${modelPart}`);
+    });
+    const hashes = await Promise.all(parts);
+    return {
+        shared: await shared,
+        resources: Object.fromEntries(sorted.map((name, index) => [name, hashes[index]])),
+    };
+}

package/dist/runtime/computed-read-runtime.d.ts

@@ -21,6 +21,11 @@ export type PlannedReadOperation = {
     readonly projection: ReadProjectionPlan | undefined;
     readonly materialize: boolean;
 };
+/**
+ * The fields a level returns when it states no projection: every scalar of the
+ * active Contract whose `select` is `true` and that is not governed.
+ */
+export declare function defaultProjectionFields(active: AvContract, resourceName: string): readonly string[];
 /**
  * Clone the caller projection into the internal Adapter projection: the read
  * set the Adapter is asked for, always explicit for a projecting variant, plus
@@ -33,5 +38,5 @@ export declare function planReadOperation(core: AvContractCore, model: AvAdapter
  * Materialize computed scalar reads and remove internal dependency fields,
  * against `active` — the Contract `planReadOperation` was given as `active`.
  */
-export declare function materializeReadOperation(active: AvContract, compute: ResolvedComputeConfig | undefined, request: OperationExecutionRequest, plan: PlannedReadOperation, value: unknown, contextFactory: ContextFactory): Promise<unknown>;
+export declare function materializeReadOperation(active: AvContract, compute: ResolvedComputeConfig | undefined, _request: OperationExecutionRequest, plan: PlannedReadOperation, value: unknown, contextFactory: ContextFactory): Promise<unknown>;
 export {};

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

@@ -89,18 +89,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 +177,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 +307,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 +483,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.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/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,4 +1,5 @@
 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";
 /**
@@ -63,5 +64,11 @@ export type OperationExecutionRequest = WithoutArguments<FrameworkOperationReque
  */
 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,6 +7,7 @@ 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 PolicyCaller } from "../policy/policy-request.js";
 import type { FrameworkTransactionRequest } from "../transactions/transaction-request.js";
 import { type ArgumentsSource } from "./caller-data.door.js";
 import { type ContextExecutor, type ExecutorScope } from "./context-executor.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;
 /**
  * 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,7 +85,9 @@ 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: FrameworkOperationRequest, 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;
 /** Creates the transport-independent operation executor owned by core. */