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

package/dist/framework/framework.d.ts

@@ -1,28 +1,41 @@
-import type { AdapterModel } from "../adapters/adapter-model.js";
-import type { FrameworkContracts } from "../compiler/contract.compiler.js";
-import type { AnyFrameworkConfig } from "../config/any-framework-config.js";
+import type { AvAdapterModel } from "../adapters/adapter-model.js";
+import type { AvContracts } from "../compiler/contract.compiler.js";
+import type { AvConfigAny } from "../config/any-framework-config.js";
+import type { AvMcpEndpoint } from "../config/config.resolver.js";
 import type { FrameworkOperationRequest } from "../runtime/operation-request.js";
-import type { OperationResponse } from "../runtime/operation-response.js";
-import type { TransactionRunner } from "../transactions/deferred-operation.js";
+import type { AvOperationResponse } from "../runtime/operation-response.js";
+import type { AvTransactionRunner } from "../transactions/deferred-operation.js";
 import type { FrameworkTransactionRequest } from "../transactions/transaction-request.js";
-import type { TransactionResponse } from "../transactions/transaction-response.js";
+import type { AvTransactionResponse } from "../transactions/transaction-response.js";
 import type { ApplicationOperations, ApplicationTransactionBuilders, ClientOperations, ClientTransactionBuilders } from "./operation-facade.js";
 /**
  * One Aventara instance, as returned by {@link createFramework}: its compiled
  * Contracts, typed in-process operations, transaction builders and the
  * untyped `execute` entry a transport calls.
  */
-export type Framework<M extends AdapterModel = AdapterModel, Cfg = AnyFrameworkConfig> = {
-    readonly entrypoint: string;
-    readonly contracts: FrameworkContracts;
+export type AvFramework<M extends AvAdapterModel = AvAdapterModel, Cfg = AvConfigAny> = {
+    /**
+     * The protocol's mount path (`api`) in its canonical form: `""` at the
+     * root, otherwise `/seg(/seg)*`.
+     */
+    readonly api: string;
+    /**
+     * The MCP endpoint `mcp` turns on — its canonical mount path and its
+     * authorization — for the host that serves it; `undefined` when MCP is off.
+     */
+    readonly mcp: AvMcpEndpoint | undefined;
+    readonly contracts: AvContracts;
     /**
      * Typed in-process operations under the Application Contract:
      * `framework.application.<resource>.<family>.<variant>(args, options?)`.
      *
      * Typed from the Application Contract as configured: what the application's
-     * restrictions hide, deny or turn off is absent from the types, and a call is
-     * validated like any other request. The optional second argument is
-     * {@link ExecutionOptions}.
+     * exposure hides, denies or turns off is absent from the types, and a call is
+     * validated like any other request. A call resolves the operation's data (a
+     * first-style miss is `null`) and throws every failure as the `AvError`
+     * subclass of its code's class (`AvValidationError`, `AvNotFoundError`, …).
+     * The optional second argument is
+     * {@link AvExecutionOptions}.
      */
     readonly application: ApplicationOperations<M, Cfg>;
     /**
@@ -33,25 +46,33 @@ export type Framework<M extends AdapterModel = AdapterModel, Cfg = AnyFrameworkC
      * as from a generated client, and arguments are read in the wire
      * forms a decoded request body carries, so a transport can pass `req.body` as
      * it is. Each call runs the client pipelines and the same validation as a
-     * remote request.
+     * remote request, and settles like an application call: the data, or the
+     * failure thrown.
      */
     readonly client: ClientOperations<M, Cfg>;
     /**
      * Transaction builders under application rules:
      * `framework.appTx.<resource>.<family>.<variant>(args)` defers one operation
-     * into a handle typed `Operation<OperationResultFor<…>>` from the Application
+     * into a handle typed `AvOperation<AvOperationResultFor<…>>` from the Application
      * Contract's view, and runs nothing. A handle exposes `$ref(field)` exactly
      * where its result is one row; the reference is bound to the handle, and its
      * index is bound when {@link transaction} runs the list it is in.
+     *
+     * `framework.appTx.$sql` defers a developer SQL step, written only as a tagged
+     * template whose every interpolated value is bound as a parameter (a `$ref`
+     * among them, resolved when the earlier steps have run). It runs in plan order
+     * in the same database transaction, with no pipelines around it; its entry in
+     * the committed data is its rows, typed by `appTx.$sql<Row>`. It exists only
+     * here: `clientTx`, the Client Contract and `/_transactions` have no SQL step.
      */
     readonly appTx: ApplicationTransactionBuilders<M, Cfg>;
     /**
      * The same builders under ClientContract rules, taking wire-form arguments.
-     * Client and application handles may share one {@link transaction}; each step
-     * runs under its own handle's rules.
+     * A {@link transaction} has one origin: client and application handles never
+     * share one (`A2004`/`V1020` at the first step of the other origin).
      */
     readonly clientTx: ClientTransactionBuilders<M, Cfg>;
-    execute(request: FrameworkOperationRequest): Promise<OperationResponse>;
+    execute(request: FrameworkOperationRequest): Promise<AvOperationResponse>;
     /**
      * Validates a whole transaction plan, then runs its operations one after
      * another inside one Adapter transaction. Answers `A1009` with each
@@ -62,15 +83,18 @@ export type Framework<M extends AdapterModel = AdapterModel, Cfg = AnyFrameworkC
      * Guards, pipes, hooks and interceptors run while the transaction is open, so
      * they should not perform network I/O or other slow work.
      */
-    executeTransaction(request: FrameworkTransactionRequest): Promise<TransactionResponse>;
+    executeTransaction(request: FrameworkTransactionRequest): Promise<AvTransactionResponse>;
     /**
      * Runs handles from `appTx`/`clientTx` as one transaction:
-     * `framework.transaction([h1, h2, …], options?)`. Resolves the committed
-     * response, typed per position, or the failure response. Never rejects.
+     * `framework.transaction([h1, h2, …], options?)`. Resolves each handle's
+     * result in plan order, typed per position, once the transaction committed,
+     * or throws the failure as the `AvError` subclass of its code's class, with
+     * `cause.operation` naming the failing step.
      *
      * Refused before anything runs: an entry that is not one of this Framework's
-     * handles, or the same handle twice (`A2004`/`V1001`); a `$ref` to a handle
-     * not in the list (`A2007`/`V1010`).
+     * handles, or the same handle twice (`A2004`/`V1001`); `appTx` and `clientTx`
+     * handles in one list (`A2004`/`V1020`); a `$ref` to a handle not in the list
+     * (`A2007`/`V1010`).
      */
-    readonly transaction: TransactionRunner;
+    readonly transaction: AvTransactionRunner;
 };

package/dist/framework/framework.factory.d.ts

@@ -1,11 +1,13 @@
-import type { AdapterModel } from "../adapters/adapter-model.js";
-import type { AnyFrameworkConfig } from "../config/any-framework-config.js";
-import type { FrameworkConfig } from "../config/framework-config.js";
-import type { Framework } from "./framework.js";
+import type { AvAdapterModel } from "../adapters/adapter-model.js";
+import type { AvConfigAny } from "../config/any-framework-config.js";
+import type { AvConfigExact } from "../config/exact-framework-config.js";
+import type { AvConfig } from "../config/framework-config.js";
+import type { ErasedConfig } from "../config/stage-type.eraser.js";
+import type { AvFramework } from "./framework.js";
 /**
  * Creates a Framework: validates the configuration, reads the adapter's
  * model and compiles the Contracts.
  *
- * @throws {@link FrameworkConstructionError} when any of those steps fails.
+ * @throws {@link AvConstructionError} when any of those steps fails.
  */
-export declare function createFramework<M extends AdapterModel, const Cfg = AnyFrameworkConfig>(config: Cfg & FrameworkConfig<M, Cfg>): Promise<Framework<M, Cfg>>;
+export declare function createFramework<M extends AvAdapterModel, const Cfg = AvConfigAny>(config: Cfg & AvConfigExact<M, Cfg> & AvConfig<M, Cfg>): Promise<AvFramework<M, ErasedConfig<Cfg>>>;

package/dist/framework/framework.factory.js

@@ -1,28 +1,32 @@
 import { compileContracts } from "../compiler/contract.compiler.js";
+import { computedFieldsOf, warnOnStaleComputedFields, } from "../config/computed-fields.js";
 import { resolveFrameworkConfig } from "../config/config.resolver.js";
 import { validateFrameworkConfig } from "../config/config.validator.js";
+import { validateForcedOperations } from "../config/forced-operation.validator.js";
 import { AVENTARA_PROTOCOL_VERSION } from "../contracts/contract-protocol.js";
 import { copyEnvelopeAtDoor, refuseCallerData, } from "../runtime/caller-data.door.js";
 import { createDiagnosticsReporter, createTransactionDiagnosticsChannel, recordDiagnosticsSink, } from "../runtime/diagnostics-reporter.js";
 import { createMisuseReporter, } from "../runtime/misuse-reporter.js";
 import { internalFailure, operationFailure, } from "../runtime/operation-response.js";
-import { createOperationRuntime } from "../runtime/operation-runtime.js";
+import { createOperationRuntime, createPipelineDependencies, } from "../runtime/operation-runtime.js";
 import { recordOwnedExecution } from "../runtime/owned-execution.registry.js";
 import { validateOperationEnvelope, validateTransactionEnvelope, } from "../runtime/request-envelope.validator.js";
 import { requestIdOf } from "../runtime/request-id.js";
+import { stateOptionOf } from "../runtime/request-state.resolver.js";
 import { createTransactionPlanAssembler } from "../transactions/transaction-plan-assembler.js";
 import { createTransactionRuntime } from "../transactions/transaction-runtime.js";
-import { FrameworkConstructionError } from "./framework-construction.error.js";
-import { createOperationFacade, createOperationTree, } from "./operation-facade.js";
+import { AvConstructionError } from "./framework-construction.error.js";
+import { createOperationFacade, createOperationTree, settleOperation, } from "./operation-facade.js";
+const APPLICATION_SQL_BUILDER = "$sql";
 export async function createFramework(config) {
     const configDiagnostics = validateFrameworkConfig(config);
     if (configDiagnostics.length > 0) {
-        throw new FrameworkConstructionError("configuration", configDiagnostics);
+        throw new AvConstructionError("configuration", configDiagnostics);
     }
     const model = config.adapter.model;
     if (model.transactions === "interactive" &&
         typeof config.adapter.transaction !== "function") {
-        throw new FrameworkConstructionError("discovery", [
+        throw new AvConstructionError("discovery", [
             {
                 code: "DISCOVERY_TRANSACTION_CAPABILITY_MISMATCH",
                 path: "adapter.transactions",
@@ -31,20 +35,26 @@ export async function createFramework(config) {
         ]);
     }
     const resolvedConfig = resolveFrameworkConfig(config);
+    warnOnStaleComputedFields(config.adapter.computedFields, computedFieldsOf({
+        trees: resolvedConfig.trees,
+        agentExtends: resolvedConfig.agent.parent,
+    }));
     const compilation = await compileContracts(model, resolvedConfig);
     if (!compilation.ok) {
-        throw new FrameworkConstructionError("contract-compilation", compilation.diagnostics);
+        throw new AvConstructionError("contract-compilation", compilation.diagnostics);
     }
-    const execute = createOperationRuntime({
-        adapter: config.adapter,
-        contracts: compilation.contracts,
-        config: resolvedConfig,
-    });
-    const executeTransaction = createTransactionRuntime({
+    const forcing = validateForcedOperations(config, compilation.contracts);
+    if (forcing.length > 0) {
+        throw new AvConstructionError("configuration", forcing);
+    }
+    const runtimeDependencies = {
         adapter: config.adapter,
         contracts: compilation.contracts,
         config: resolvedConfig,
-    });
+    };
+    const pipelineDependencies = createPipelineDependencies(runtimeDependencies, model);
+    const execute = createOperationRuntime(runtimeDependencies, pipelineDependencies);
+    const executeTransaction = createTransactionRuntime(runtimeDependencies, pipelineDependencies);
     const misuse = createMisuseReporter(resolvedConfig.misuse);
     const executeOperation = (request) => executeTotally(execute, request, resolvedConfig.diagnostics, "caller");
     const protocol = {
@@ -53,33 +63,41 @@ export async function createFramework(config) {
     };
     const assembler = createTransactionPlanAssembler(compilation.contracts, protocol, misuse);
     const framework = {
-        entrypoint: resolvedConfig.entrypoint,
+        api: resolvedConfig.api,
+        mcp: resolvedConfig.mcp,
         contracts: compilation.contracts,
-        application: createOperationFacade(model, (resource, identity, args, requestId) => ({
+        application: createOperationFacade(model, (resource, identity, args, requestId, state) => ({
             ...identity,
             origin: "application",
             requestId,
+            ...(state === undefined ? {} : { state }),
             resource,
             arguments: args,
         }), executeOperation),
-        client: createOperationFacade(model, (resource, identity, args, requestId) => ({
+        client: createOperationFacade(model, (resource, identity, args, requestId, state) => ({
             ...identity,
             origin: "client",
             protocol,
             requestId,
+            ...(state === undefined ? {} : { state }),
             resource,
             arguments: args,
         }), executeOperation),
-        appTx: createOperationTree(model, (resource, identity) => (args) => assembler.defer("application", resource, identity, args === undefined ? {} : args)),
+        appTx: Object.freeze({
+            ...createOperationTree(model, (resource, identity) => (args) => assembler.defer("application", resource, identity, args === undefined ? {} : args)),
+            [APPLICATION_SQL_BUILDER]: (strings, ...values) => assembler.deferSql(strings, values),
+        }),
         clientTx: createOperationTree(model, (resource, identity) => (args) => assembler.defer("client", resource, identity, args === undefined ? {} : args)),
         execute: (request) => executeRequestTotally(execute, request, resolvedConfig.diagnostics, misuse),
         executeTransaction: (request) => executeTransactionRequestTotally(executeTransaction, request, resolvedConfig.diagnostics, misuse),
-        transaction: ((operations, options) => runTransactionTotally(executeTransaction, assembler, operations, requestIdOf(options), resolvedConfig.diagnostics)),
+        transaction: (async (operations, options) => settleOperation(await runTransactionTotally(executeTransaction, assembler, operations, requestIdOf(options), stateOptionOf(options), resolvedConfig.diagnostics))),
     };
     recordDiagnosticsSink(framework, resolvedConfig.diagnostics);
     recordOwnedExecution(framework, {
-        execute: (request) => executeTotally(execute, request, resolvedConfig.diagnostics, "owned"),
-        executeTransaction: (request) => executeTransactionTotally(executeTransaction, request, resolvedConfig.diagnostics, undefined, { source: "owned" }),
+        execute: (request, refused) => executeTotally(execute, request, resolvedConfig.diagnostics, refused === undefined ? "owned" : { refused }),
+        executeTransaction: (request, refused) => executeTransactionTotally(executeTransaction, request, resolvedConfig.diagnostics, undefined, refused === undefined
+            ? { source: "owned" }
+            : { source: "owned", refused }),
     });
     return framework;
 }
@@ -138,7 +156,7 @@ async function executeTransactionTotally(execute, request, diagnostics, origins,
         return internalFailure();
     }
 }
-async function runTransactionTotally(execute, assembler, operations, requestId, diagnostics) {
+async function runTransactionTotally(execute, assembler, operations, requestId, state, diagnostics) {
     let assembled;
     try {
         assembled = await assembler.assemble(operations);
@@ -154,5 +172,14 @@ async function runTransactionTotally(execute, assembler, operations, requestId,
     if (!assembled.ok) {
         return assembled.response;
     }
-    return executeTransactionTotally(execute, { origin: "application", requestId, plan: assembled.plan }, diagnostics, assembled.origins, { source: "owned", refused: assembled.refused });
+    return executeTransactionTotally(execute, {
+        origin: "application",
+        requestId,
+        ...(state === undefined ? {} : { state }),
+        plan: assembled.plan,
+    }, diagnostics, assembled.origins, {
+        source: "owned",
+        refused: assembled.refused,
+        statements: assembled.statements,
+    });
 }

package/dist/framework/operation-facade.d.ts

@@ -1,72 +1,137 @@
-import type { AdapterModel } from "../adapters/adapter-model.js";
-import type { Contract } from "../contracts/contract.js";
-import type { ApplicationScalarForms, WireScalarForms } from "../contracts/scalar-value-type.js";
-import type { ResourceKey } from "../operations/operation-arguments.js";
-import type { DeferredOperationCall, OperationCall, OperationGrammar } from "../operations/operation-call.js";
-import type { OperationIdentity } from "../operations/operation-identity.js";
-import type { ExecutionOptions } from "../runtime/execution-options.js";
+import type { AvAdapterModel } from "../adapters/adapter-model.js";
+import type { AvContract } from "../contracts/contract.js";
+import type { AvApplicationScalarForms, AvWireScalarForms } from "../contracts/scalar-value-type.js";
+import type { AvResourceKey } from "../operations/operation-arguments.js";
+import type { AvDeferredOperationCall, AvOperationCall, AvOperationGrammar } from "../operations/operation-call.js";
+import type { AvOperationIdentity } from "../operations/operation-identity.js";
+import type { AvExecutionOptions } from "../runtime/execution-options.js";
 import type { FrameworkOperationRequest } from "../runtime/operation-request.js";
-import type { OperationResponse } from "../runtime/operation-response.js";
-import type { ApplicationContractView, ClientContractView } from "./contract-view.js";
+import type { AvOperationResponse } from "../runtime/operation-response.js";
+import type { AvState } from "../runtime/request-state.js";
+import type { SqlStatementBuilder } from "../transactions/sql-statement.js";
+import type { AvTransactionResponse } from "../transactions/transaction-response.js";
+import type { AvContractApplicationView, ClientContractView } from "./contract-view.js";
 /**
- * A model whose Resource names are not literal — the abstract `AdapterModel` behind
- * the default `Framework` — has no Contract to type a call against, so a surface over
+ * A model whose Resource names are not literal — the abstract `AvAdapterModel` behind
+ * the default `AvFramework` — has no Contract to type a call against, so a surface over
  * it is typed as the opaque object it is, and such a caller uses `execute`.
  */
 type OpaqueSurface = {
     readonly [resource: string]: unknown;
 };
+/** The four typed surfaces of an `AvFramework`, named by the member that holds each. */
+type FacadeSurface = "application" | "client" | "appTx" | "clientTx";
 /**
- * `framework.application`: one call per operation the Application Contract's
- * view advertises, its arguments in the application forms.
+ * One variant on a surface: a direct call (application or wire forms), or a
+ * deferred one for a transaction (`appTx`, `clientTx`).
  */
-export type ApplicationOperations<M extends AdapterModel, Cfg> = ApplicationFacade<ApplicationContractView<M, Cfg>>;
-type ApplicationFacade<C> = C extends Contract ? string extends ResourceKey<C> ? OpaqueSurface : {
-    readonly [R in ResourceKey<C>]: {
-        readonly [F in keyof OperationGrammar<C>[R]]: {
-            readonly [V in keyof OperationGrammar<C>[R][F]]: OperationCall<C, R, OperationGrammar<C>[R][F][V] & OperationIdentity, ApplicationScalarForms, ApplicationScalarForms, "response", ExecutionOptions>;
-        };
-    };
-} : never;
+type SurfaceCall<C extends AvContract, R extends AvResourceKey<C>, I extends AvOperationIdentity, S extends FacadeSurface> = S extends "application" ? AvOperationCall<C, R, I, AvApplicationScalarForms, AvApplicationScalarForms, AvExecutionOptions> : S extends "client" ? AvOperationCall<C, R, I, AvWireScalarForms, AvApplicationScalarForms, AvExecutionOptions> : S extends "appTx" ? AvDeferredOperationCall<C, R, I, AvApplicationScalarForms, AvApplicationScalarForms, "application"> : AvDeferredOperationCall<C, R, I, AvWireScalarForms, AvApplicationScalarForms, "client">;
+/** The families view `C` advertises on Resource `R`. */
+type FamilyKey<C extends AvContract, R extends AvResourceKey<C>> = keyof AvOperationGrammar<C>[R];
+/** One family node of surface `S`; the public names below are its four instances. */
+type FamilyNode<C extends AvContract, S extends FacadeSurface, R extends AvResourceKey<C>, F extends FamilyKey<C, R>> = {
+    readonly [V in keyof AvOperationGrammar<C>[R][F]]: SurfaceCall<C, R, AvOperationGrammar<C>[R][F][V] & AvOperationIdentity, S>;
+};
+/** `framework.application.<Resource>.<family>`: one direct call per variant, application forms. */
+export type AvApplicationFamilyFacade<in out C extends AvContract, in out R extends AvResourceKey<C>, in out F extends FamilyKey<C, R>> = FamilyNode<C, "application", R, F>;
+/** `framework.client.<Resource>.<family>`: one direct call per variant, wire forms. */
+export type AvClientFamilyFacade<in out C extends AvContract, in out R extends AvResourceKey<C>, in out F extends FamilyKey<C, R>> = FamilyNode<C, "client", R, F>;
+/** `framework.appTx.<Resource>.<family>`: one deferred operation per variant. */
+export type AvAppTxFamilyFacade<in out C extends AvContract, in out R extends AvResourceKey<C>, in out F extends FamilyKey<C, R>> = FamilyNode<C, "appTx", R, F>;
+/** `framework.clientTx.<Resource>.<family>`: one deferred operation per variant. */
+export type AvClientTxFamilyFacade<in out C extends AvContract, in out R extends AvResourceKey<C>, in out F extends FamilyKey<C, R>> = FamilyNode<C, "clientTx", R, F>;
+/** `framework.application.<Resource>`: one {@link AvApplicationFamilyFacade} per family. */
+export type AvApplicationResourceFacade<in out C extends AvContract, in out R extends AvResourceKey<C>> = {
+    readonly [F in FamilyKey<C, R>]: AvApplicationFamilyFacade<C, R, F>;
+};
+/** `framework.client.<Resource>`: one {@link AvClientFamilyFacade} per family. */
+export type AvClientResourceFacade<in out C extends AvContract, in out R extends AvResourceKey<C>> = {
+    readonly [F in FamilyKey<C, R>]: AvClientFamilyFacade<C, R, F>;
+};
+/** `framework.appTx.<Resource>`: one {@link AvAppTxFamilyFacade} per family. */
+export type AvAppTxResourceFacade<in out C extends AvContract, in out R extends AvResourceKey<C>> = {
+    readonly [F in FamilyKey<C, R>]: AvAppTxFamilyFacade<C, R, F>;
+};
+/** `framework.clientTx.<Resource>`: one {@link AvClientTxFamilyFacade} per family. */
+export type AvClientTxResourceFacade<in out C extends AvContract, in out R extends AvResourceKey<C>> = {
+    readonly [F in FamilyKey<C, R>]: AvClientTxFamilyFacade<C, R, F>;
+};
 /**
- * `framework.client`: the same over the Client Contract's view, its arguments in
- * the wire forms.
+ * `framework.application`: one {@link AvApplicationResourceFacade} per Resource
+ * of `C`, the Application Contract's view.
  */
-export type ClientOperations<M extends AdapterModel, Cfg> = ClientFacade<ClientContractView<M, Cfg>>;
-type ClientFacade<C> = C extends Contract ? string extends ResourceKey<C> ? OpaqueSurface : {
-    readonly [R in ResourceKey<C>]: {
-        readonly [F in keyof OperationGrammar<C>[R]]: {
-            readonly [V in keyof OperationGrammar<C>[R][F]]: OperationCall<C, R, OperationGrammar<C>[R][F][V] & OperationIdentity, WireScalarForms, ApplicationScalarForms, "response", ExecutionOptions>;
-        };
-    };
-} : never;
+export type AvApplicationFacade<C extends AvContract> = {
+    readonly [R in AvResourceKey<C>]: AvApplicationResourceFacade<C, R>;
+};
 /**
- * `framework.appTx`: one deferred operation per operation the Application
- * Contract's view advertises — application rules, application forms.
+ * `framework.client`: one {@link AvClientResourceFacade} per Resource of `C`,
+ * the Client Contract's view.
  */
-export type ApplicationTransactionBuilders<M extends AdapterModel, Cfg> = ApplicationDeferredSurface<ApplicationContractView<M, Cfg>>;
-type ApplicationDeferredSurface<C> = C extends Contract ? string extends ResourceKey<C> ? OpaqueSurface : {
-    readonly [R in ResourceKey<C>]: {
-        readonly [F in keyof OperationGrammar<C>[R]]: {
-            readonly [V in keyof OperationGrammar<C>[R][F]]: DeferredOperationCall<C, R, OperationGrammar<C>[R][F][V] & OperationIdentity, ApplicationScalarForms, ApplicationScalarForms>;
+export type AvClientFacade<C extends AvContract> = {
+    readonly [R in AvResourceKey<C>]: AvClientResourceFacade<C, R>;
+};
+/** `framework.appTx.$sql`: the developer SQL step only an application transaction has. */
+type ApplicationSqlStep = {
+    /**
+     * A developer SQL step, written only as a tagged template:
+     * ``framework.appTx.$sql<Row>`select … ${value}` ``. Every interpolated value
+     * is bound as a parameter. See {@link SqlStatementBuilder}.
+     */
+    readonly $sql: SqlStatementBuilder;
+};
+/**
+ * `framework.appTx`: one {@link AvAppTxResourceFacade} per Resource of `C`, the
+ * Application Contract's view, and `$sql`.
+ */
+export type AvAppTxFacade<C extends AvContract> = {
+    readonly [R in AvResourceKey<C>]: AvAppTxResourceFacade<C, R>;
+} & ApplicationSqlStep;
+/**
+ * `framework.clientTx`: one {@link AvClientTxResourceFacade} per Resource of
+ * `C`, the Client Contract's view.
+ */
+export type AvClientTxFacade<C extends AvContract> = {
+    readonly [R in AvResourceKey<C>]: AvClientTxResourceFacade<C, R>;
+};
+type ApplicationSurface<C> = C extends AvContract ? string extends AvResourceKey<C> ? OpaqueSurface : AvApplicationFacade<C> : never;
+type ClientSurface<C> = C extends AvContract ? string extends AvResourceKey<C> ? OpaqueSurface : AvClientFacade<C> : never;
+type ApplicationDeferredSurface<C> = C extends AvContract ? string extends AvResourceKey<C> ? OpaqueSurface & ApplicationSqlStep : AvAppTxFacade<C> : never;
+type ClientDeferredSurface<C> = C extends AvContract ? string extends AvResourceKey<C> ? OpaqueSurface : AvClientTxFacade<C> : never;
+/** `framework.application`'s type: {@link AvApplicationFacade}, or opaque. */
+export type ApplicationOperations<M extends AvAdapterModel, Cfg> = ApplicationSurface<AvContractApplicationView<M, Cfg>>;
+/** `framework.client`'s type: {@link AvClientFacade}, or opaque. */
+export type ClientOperations<M extends AvAdapterModel, Cfg> = ClientSurface<ClientContractView<M, Cfg>>;
+/** `framework.appTx`'s type: {@link AvAppTxFacade}, or opaque with `$sql`. */
+export type ApplicationTransactionBuilders<M extends AvAdapterModel, Cfg> = ApplicationDeferredSurface<AvContractApplicationView<M, Cfg>>;
+/** `framework.clientTx`'s type: {@link AvClientTxFacade}, or opaque. */
+export type ClientTransactionBuilders<M extends AvAdapterModel, Cfg> = ClientDeferredSurface<ClientContractView<M, Cfg>>;
+/**
+ * The Resources of a pipeline ctx: `ctx.<Resource>.<family>.<variant>(args)`,
+ * application-origin, resolving the operation's data.
+ */
+export type AvContextOperations<M extends AvAdapterModel> = ContextFacade<AvContractApplicationView<M>>;
+type ContextFacade<C> = C extends AvContract ? string extends AvResourceKey<C> ? unknown : {
+    readonly [R in AvResourceKey<C>]: {
+        readonly [F in keyof AvOperationGrammar<C>[R]]: {
+            readonly [V in keyof AvOperationGrammar<C>[R][F]]: AvOperationCall<C, R, AvOperationGrammar<C>[R][F][V] & AvOperationIdentity, AvApplicationScalarForms, AvApplicationScalarForms, never>;
         };
     };
 } : never;
 /**
- * `framework.clientTx`: the same over the Client Contract's view — ClientContract
- * rules, wire forms.
+ * The Resources of compute's read-only ctx: `ctx.<Resource>.find.<variant>(args)`
+ * only (`find.count` included).
  */
-export type ClientTransactionBuilders<M extends AdapterModel, Cfg> = ClientDeferredSurface<ClientContractView<M, Cfg>>;
-type ClientDeferredSurface<C> = C extends Contract ? string extends ResourceKey<C> ? OpaqueSurface : {
-    readonly [R in ResourceKey<C>]: {
-        readonly [F in keyof OperationGrammar<C>[R]]: {
-            readonly [V in keyof OperationGrammar<C>[R][F]]: DeferredOperationCall<C, R, OperationGrammar<C>[R][F][V] & OperationIdentity, WireScalarForms, ApplicationScalarForms>;
+export type AvComputeReads<M extends AvAdapterModel> = ComputeReadFacade<AvContractApplicationView<M>>;
+type ComputeReadFacade<C> = C extends AvContract ? string extends AvResourceKey<C> ? unknown : {
+    readonly [R in AvResourceKey<C>]: {
+        readonly [F in Extract<keyof AvOperationGrammar<C>[R], "find">]: {
+            readonly [V in keyof AvOperationGrammar<C>[R][F]]: AvOperationCall<C, R, AvOperationGrammar<C>[R][F][V] & AvOperationIdentity, AvApplicationScalarForms, AvApplicationScalarForms, never>;
         };
     };
 } : never;
-/** Builds the request one façade call hands to `execute`, under its request id. */
-export type FacadeRequest = (resource: string, identity: OperationIdentity, args: unknown, requestId: string) => FrameworkOperationRequest;
-type FacadeExecutor = (request: FrameworkOperationRequest) => Promise<OperationResponse>;
+/** Builds the request one façade call hands to `execute`, under its request id and state. */
+export type FacadeRequest = (resource: string, identity: AvOperationIdentity, args: unknown, requestId: string, state: AvState | undefined) => FrameworkOperationRequest;
+type FacadeExecutor = (request: FrameworkOperationRequest) => Promise<AvOperationResponse>;
 /**
  * Builds a façade over `model`, the same object its types are read from, so a
  * call that type-checks always reaches `execute`: a Resource, variant or field
@@ -74,20 +139,26 @@ type FacadeExecutor = (request: FrameworkOperationRequest) => Promise<OperationR
  * validation layer answers it.
  *
  * Each call's request is `request`'s — its origin — under the caller's
- * `ExecutionOptions.requestId`, or a freshly minted id when there is none; an
+ * `AvExecutionOptions.requestId`, or a freshly minted id when there is none, and
+ * with the caller's `AvExecutionOptions.state` when it gives one; an
  * omitted argument is the empty argument object, which the type admits only
  * when every member is optional.
  */
-export declare function createOperationFacade<Facade>(model: AdapterModel, request: FacadeRequest, execute: FacadeExecutor): Facade;
+export declare function createOperationFacade<Facade>(model: AvAdapterModel, request: FacadeRequest, execute: FacadeExecutor): Facade;
+/**
+ * An in-process call's settlement (a façade call or `framework.transaction`):
+ * the response's data, or its failure thrown.
+ */
+export declare function settleOperation(response: AvOperationResponse | AvTransactionResponse): unknown;
 /**
  * One leaf of an operation tree: the callable for one advertised variant. The
  * second parameter is a façade call's options; a builder leaf ignores it.
  */
-export type OperationLeaf = (resource: string, identity: OperationIdentity) => (args?: unknown, options?: unknown) => unknown;
+export type OperationLeaf = (resource: string, identity: AvOperationIdentity) => (args?: unknown, options?: unknown) => unknown;
 /**
  * The runtime shape every façade and builder shares: one frozen property per
  * Resource of `model`, one per family under it, one leaf per variant the model
  * advertises in the standard grammar.
  */
-export declare function createOperationTree<Tree>(model: AdapterModel, leaf: OperationLeaf): Tree;
+export declare function createOperationTree<Tree>(model: AvAdapterModel, leaf: OperationLeaf): Tree;
 export {};

package/dist/framework/operation-facade.js

@@ -1,8 +1,16 @@
 import { isOperationVariantAvailable } from "../contracts/resource-operations.js";
 import { parseOperationIdentity } from "../operations/operation-identity.js";
+import { thrownFailure } from "../runtime/framework-error.factory.js";
 import { requestIdOf } from "../runtime/request-id.js";
+import { stateOptionOf } from "../runtime/request-state.resolver.js";
 export function createOperationFacade(model, request, execute) {
-    return createOperationTree(model, (resource, identity) => (args, options) => execute(request(resource, identity, args === undefined ? {} : args, requestIdOf(options))));
+    return createOperationTree(model, (resource, identity) => async (args, options) => settleOperation(await execute(request(resource, identity, args === undefined ? {} : args, requestIdOf(options), stateOptionOf(options)))));
+}
+export function settleOperation(response) {
+    if (response.cause !== null) {
+        throw thrownFailure(response);
+    }
+    return response.data;
 }
 export function createOperationTree(model, leaf) {
     const resources = Object.entries(model.resources).map(([resource, { operations }]) => {