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

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 { FrameworkOperationRequest } from "../runtime/operation-request.js";
-import type { OperationResponse } from "../runtime/operation-response.js";
-import type { TransactionRunner } from "../transactions/deferred-operation.js";
-import type { FrameworkTransactionRequest } from "../transactions/transaction-request.js";
-import type { TransactionResponse } from "../transactions/transaction-response.js";
-import type { ApplicationOperations, ApplicationTransactionBuilders, ClientOperations, ClientTransactionBuilders } from "./operation-facade.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 { AvOperationRequest } from "../runtime/operation-request.js";
+import type { AvOperationResponse } from "../runtime/operation-response.js";
+import type { AvTransactionRunner } from "../transactions/deferred-operation.js";
+import type { AvTransactionRequest } from "../transactions/transaction-request.js";
+import type { AvTransactionResponse } from "../transactions/transaction-response.js";
+import type { ApplicationOperations, ApplicationTransactionBuilders, ClientOperations, ClientTransactionBuilders, ServerClientOperations, ServerClientTransactionBuilders } 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,54 @@ 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>;
+    /**
+     * The client layer for server code, taking application values:
+     * `framework.serverClient.<resource>.<family>.<variant>(args, options?)`.
+     *
+     * Typed and run exactly as {@link client} (the Client Contract's view, the
+     * client pipelines, validation, exposure and policy), but its arguments are
+     * the application forms: a `datetime` is a `Date`, a `bigint` a `bigint`, a
+     * `decimal` an `AvDecimal`, `bytes` a `Uint8Array`. Each call copies its
+     * arguments, encodes them into the wire forms `client` reads, and hands the
+     * same client-origin request to {@link execute}. Results are the same as
+     * `client`'s; the optional second argument is {@link AvExecutionOptions}.
+     */
+    readonly serverClient: ServerClientOperations<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>;
+    /**
+     * The {@link clientTx} builders taking application values, as
+     * {@link serverClient} takes them: each handle's arguments are copied and
+     * encoded into the wire forms when it is built. Its handles are client-origin,
+     * so one {@link transaction} may hold them beside `clientTx` handles, never
+     * beside `appTx` ones.
+     */
+    readonly serverClientTx: ServerClientTransactionBuilders<M, Cfg>;
+    execute(request: AvOperationRequest): Promise<AvOperationResponse>;
     /**
      * Validates a whole transaction plan, then runs its operations one after
      * another inside one Adapter transaction. Answers `A1009` with each
@@ -62,15 +104,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: AvTransactionRequest): 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,42 @@
-import { compileContracts } from "../compiler/contract.compiler.js";
-import { resolveFrameworkConfig } from "../config/config.resolver.js";
+import { compileContracts, } from "../compiler/contract.compiler.js";
+import { validateManagedDeletes } from "../compiler/managed-elsewhere.validator.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 { recordAccessProvider } from "../policy/access-provider.registry.js";
+import { recordAccessQuestions } from "../policy/access-question.registry.js";
+import { createAccessQuestionAnswerer } from "../policy/access-question.runtime.js";
+import { heldTargetsOf } from "../policy/policy-reference-write.runtime.js";
+import { callerOf } from "../policy/policy-request.js";
+import { policyStartupDiagnostics } from "../policy/policy-startup.validator.js";
+import { loadPrebuiltContracts, warnStalePrebuilt, } from "../prebuilt/prebuilt-contracts.loader.js";
+import { copyAtDoor, 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 { encodeOperationArgumentsForWire } from "../transactions/operation-arguments-encoder.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 { createServerClientAccess } from "./access-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,62 +45,146 @@ export async function createFramework(config) {
         ]);
     }
     const resolvedConfig = resolveFrameworkConfig(config);
-    const compilation = await compileContracts(model, resolvedConfig);
+    warnOnStaleComputedFields(config.adapter.computedFields, computedFieldsOf({
+        trees: resolvedConfig.trees,
+        agentExtends: resolvedConfig.agent.parent,
+    }));
+    const compilation = (config.prebuilt === undefined
+        ? undefined
+        : await prebuiltCompilation(config.prebuilt, model, config, resolvedConfig)) ?? (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 managedDeletes = validateManagedDeletes(compilation.contracts, config.adapter.referentialActions);
+    if (managedDeletes.length > 0) {
+        throw new AvConstructionError("configuration", managedDeletes);
+    }
+    if (resolvedConfig.policy !== undefined) {
+        const policy = policyStartupDiagnostics(compilation.contracts.core, resolvedConfig.policy, model);
+        if (policy.length > 0) {
+            throw new AvConstructionError("configuration", policy);
+        }
+    }
+    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 executeOperation = (request, caller) => executeTotally(execute, request, resolvedConfig.diagnostics, "caller", caller);
+    const executeApplicationValues = (request, caller) => executeTotally(encodingApplicationValues(execute, compilation.contracts.client), request, resolvedConfig.diagnostics, "caller", caller);
     const protocol = {
         version: AVENTARA_PROTOCOL_VERSION,
         hash: compilation.contracts.client.protocol.hash,
     };
     const assembler = createTransactionPlanAssembler(compilation.contracts, protocol, misuse);
+    const clientRequest = (resource, identity, args, requestId, state) => ({
+        ...identity,
+        origin: "client",
+        protocol,
+        requestId,
+        ...(state === undefined ? {} : { state }),
+        resource,
+        arguments: args,
+    });
+    const accessAnswerer = compilation.contracts.client.access === undefined
+        ? undefined
+        : createAccessQuestionAnswerer({
+            contracts: compilation.contracts,
+            policy: resolvedConfig.policy,
+            adapter: config.adapter,
+            diagnostics: resolvedConfig.diagnostics,
+            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) => ({
-            ...identity,
-            origin: "client",
-            protocol,
-            requestId,
-            resource,
-            arguments: args,
-        }), executeOperation),
-        appTx: createOperationTree(model, (resource, identity) => (args) => assembler.defer("application", resource, identity, args === undefined ? {} : args)),
+        client: createOperationFacade(model, clientRequest, executeOperation),
+        serverClient: withServerClientAccess(createOperationFacade(model, clientRequest, executeApplicationValues), accessAnswerer === undefined
+            ? undefined
+            : createServerClientAccess({
+                contract: compilation.contracts.client,
+                answer: accessAnswerer,
+                client: config.access?.client,
+                state: (input) => config.access.state(input),
+            })),
+        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)),
+        serverClientTx: createOperationTree(model, (resource, identity) => (args) => assembler.defer("client", resource, identity, args === undefined ? {} : args, "application")),
         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, callerOf(options)))),
     };
     recordDiagnosticsSink(framework, resolvedConfig.diagnostics);
+    recordAccessProvider(framework, config.access);
+    if (accessAnswerer !== undefined) {
+        recordAccessQuestions(framework, accessAnswerer);
+    }
     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 }),
     });
+    if (resolvedConfig.policy !== undefined) {
+        await resolvedConfig.policy.engine.hosted?.({
+            held: heldTargetsOf(compilation.contracts.core, resolvedConfig.policy.unheld),
+        });
+    }
     return framework;
 }
-async function executeTotally(execute, request, diagnostics, source) {
+async function prebuiltCompilation(prebuilt, model, config, resolved) {
+    let loaded;
+    try {
+        loaded = await loadPrebuiltContracts(prebuilt, model, config, resolved);
+    }
+    catch (error) {
+        loaded = {
+            ok: false,
+            reason: `it could not be read (${error instanceof Error ? error.message : String(error)})`,
+        };
+    }
+    if (!loaded.ok) {
+        warnStalePrebuilt(loaded.reason);
+        return undefined;
+    }
+    return { ok: true, contracts: loaded.contracts };
+}
+function encodingApplicationValues(execute, contract) {
+    return (request, report, _source, caller) => {
+        const copy = copyAtDoor(request.arguments);
+        if (!copy.ok) {
+            return execute(request, report, { refused: copy.error }, caller);
+        }
+        return execute({
+            ...request,
+            arguments: encodeOperationArgumentsForWire(contract, request, copy.value),
+        }, report, "owned", caller);
+    };
+}
+async function executeTotally(execute, request, diagnostics, source, caller) {
     const report = createDiagnosticsReporter(diagnostics, request);
     try {
-        return await execute(request, report, source);
+        return await execute(request, report, source, caller);
     }
     catch (error) {
         report(error, "A3000");
@@ -127,18 +225,18 @@ function executeTransactionRequestTotally(execute, request, diagnostics, misuse)
     }
     return executeTransactionTotally(execute, envelope.value, diagnostics, undefined, { source: "caller" });
 }
-async function executeTransactionTotally(execute, request, diagnostics, origins, planArguments) {
+async function executeTransactionTotally(execute, request, diagnostics, origins, planArguments, caller) {
     const channel = createTransactionDiagnosticsChannel(diagnostics, request);
     const report = channel.transaction();
     try {
-        return await execute(request, channel, origins, planArguments);
+        return await execute(request, channel, origins, planArguments, caller);
     }
     catch (error) {
         report(error, "A3000");
         return internalFailure();
     }
 }
-async function runTransactionTotally(execute, assembler, operations, requestId, diagnostics) {
+async function runTransactionTotally(execute, assembler, operations, requestId, state, diagnostics, caller) {
     let assembled;
     try {
         assembled = await assembler.assemble(operations);
@@ -154,5 +252,19 @@ 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,
+    }, caller);
+}
+function withServerClientAccess(facade, access) {
+    return access === undefined
+        ? facade
+        : Object.freeze({ ...facade, $access: access });
 }