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

package/dist/runtime/request-envelope.validator.js

@@ -1,4 +1,4 @@
-const ORIGINS = ["application", "client"];
+const ORIGINS = ["application", "client", "agent"];
 const OPERATION_IDENTITY_MEMBERS = ["resource", "family", "variant"];
 export function validateOperationEnvelope(request) {
     if (!isRecord(request)) {
@@ -29,7 +29,7 @@ function originAndIdentityIssues(request) {
         issues.push(issue(["origin"], "V1001", "Request origin must be a string."));
     }
     else if (!ORIGINS.includes(origin)) {
-        issues.push(issue(["origin"], "V1002", 'Request origin must be "application" or "client".'));
+        issues.push(issue(["origin"], "V1002", 'Request origin must be "application", "client" or "agent".'));
     }
     const requestId = request.requestId;
     if (requestId === undefined || requestId === "") {
@@ -38,8 +38,13 @@ function originAndIdentityIssues(request) {
     else if (typeof requestId !== "string") {
         issues.push(issue(["requestId"], "V1001", "Request id must be a string."));
     }
-    if (origin === "client") {
-        issues.push(...protocolIssues(request.protocol));
+    const state = request.state;
+    if (state !== undefined &&
+        (typeof state !== "object" || state === null || Array.isArray(state))) {
+        issues.push(issue(["state"], "V1001", "Request state must be an object."));
+    }
+    if (origin === "client" || origin === "agent") {
+        issues.push(...protocolIssues(request.protocol, origin));
         if (request.transport !== undefined) {
             issues.push(...transportIssues(request.transport));
         }
@@ -47,16 +52,16 @@ function originAndIdentityIssues(request) {
     else if (origin === "application") {
         for (const member of ["protocol", "transport"]) {
             if (request[member] !== undefined) {
-                issues.push(issue([member], "V1005", `Property "${member}" belongs to a client request, not an application one.`));
+                issues.push(issue([member], "V1005", `Property "${member}" belongs to a client or agent request, not an application one.`));
             }
         }
     }
     return issues;
 }
-function protocolIssues(protocol) {
+function protocolIssues(protocol, origin) {
     if (protocol === undefined) {
         return [
-            issue(["protocol"], "V1000", 'Required property "protocol" is missing from a client request.'),
+            issue(["protocol"], "V1000", `Required property "protocol" is missing from ${origin === "client" ? "a client" : "an agent"} request.`),
         ];
     }
     if (!isRecord(protocol)) {

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

@@ -1,6 +1,6 @@
 /**
  * The request id of one call or transaction run: the caller's
- * `ExecutionOptions.requestId` when it is a non-empty string, otherwise a new
+ * `AvExecutionOptions.requestId` when it is a non-empty string, otherwise a new
  * one. Any other value is ignored.
  */
 export declare function requestIdOf(options: unknown): string;

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

@@ -0,0 +1,14 @@
+/**
+ * The per-request state every stage reads and writes as `ctx.$state`. Empty
+ * until the application declares its members by module augmentation:
+ *
+ * ```ts
+ * declare module "@aventara/core" {
+ *   interface AvState {
+ *     user?: { id: string; roles: string[] };
+ *   }
+ * }
+ * ```
+ */
+export interface AvState {
+}

package/dist/runtime/request-state.js

@@ -0,0 +1 @@
+export {};

package/dist/runtime/request-state.resolver.d.ts

@@ -0,0 +1,12 @@
+import type { AvState } from "./request-state.js";
+/**
+ * The state of one request: the seed when it is an object, otherwise a fresh
+ * `{}`. A seed that is not an object is ignored, as an unusable request id is.
+ */
+export declare function requestStateOf(seed: unknown): AvState;
+/**
+ * The state an in-process call's `AvExecutionOptions` seeds, or `undefined`.
+ * Read as `unknown`, like the request id: a façade is total for untyped
+ * callers, so a getter that throws or a value that is not an object is ignored.
+ */
+export declare function stateOptionOf(options: unknown): AvState | undefined;

package/dist/runtime/request-state.resolver.js

@@ -0,0 +1,20 @@
+export function requestStateOf(seed) {
+    return typeof seed === "object" && seed !== null && !Array.isArray(seed)
+        ? seed
+        : {};
+}
+export function stateOptionOf(options) {
+    if (typeof options !== "object" || options === null) {
+        return undefined;
+    }
+    let state;
+    try {
+        state = options.state;
+    }
+    catch {
+        return undefined;
+    }
+    return typeof state === "object" && state !== null && !Array.isArray(state)
+        ? state
+        : undefined;
+}

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

@@ -1,41 +1,56 @@
-import type { RequestOrigin } from "../config/config-layer.js";
-import type { ScalarFilterOperator } from "../contracts/capability.js";
-import type { Contract } from "../contracts/contract.js";
-import type { ScalarField } from "../contracts/field.js";
-import type { OperationIdentity } from "../operations/operation-identity.js";
+import type { AvRequestOrigin } from "../config/config-layer.js";
+import type { AvScalarFilterOperator } from "../contracts/capability.js";
+import type { AvContract } from "../contracts/contract.js";
+import type { AvScalarField } from "../contracts/field.js";
+import type { AvOperationIdentity } from "../operations/operation-identity.js";
 import type { OperationValidationOptions, SemanticOperationArguments } from "../operations/operation-validator.js";
-import type { ValidationIssue } from "../operations/validation-code.js";
+import type { AvValidationIssue } from "../operations/validation-code.js";
 import { type TransactionSlotShape } from "../transactions/transaction-reference.js";
 export type ScalarNormalizationResult = {
     readonly ok: true;
     readonly arguments: SemanticOperationArguments;
 } | {
     readonly ok: false;
-    readonly issues: readonly ValidationIssue[];
+    readonly issues: readonly AvValidationIssue[];
 };
 export type ScalarValueNormalizationResult = {
     readonly ok: true;
     readonly value: unknown;
 } | {
     readonly ok: false;
-    readonly issues: readonly ValidationIssue[];
+    readonly issues: readonly AvValidationIssue[];
 };
 type Path = readonly (string | number)[];
 /**
  * The one discriminant between an argument OBJECT and a VALUE wherever a position
  * admits both — a filter position above all: a **plain** record is an operator object,
- * and anything else — a `Date`, a core `Decimal`, a `Uint8Array` — is a value, which
+ * and anything else — a `Date`, a core `AvDecimal`, a `Uint8Array` — is a value, which
  * equality shorthand then holds to the field's scalar. The validator (`operation-
  * validator-core.ts`) reads a filter position through this same answer, and an
  * adapter's filter translation is expected to, so a position cannot be operators to
  * one reader and a value to another.
  */
 export declare function isPlainRecord(value: unknown): value is Readonly<Record<string, unknown>>;
+/**
+ * An operation argument's JSON value is bounded by `maxJsonDepth`, which the
+ * structural walk enforces before this runs; a `$sql` step's parameter is not
+ * bounded by it. The traversal therefore carries its own stack on the heap: a
+ * payload deep enough to exhaust the call stack must still normalize rather
+ * than become an internal failure.
+ *
+ * `seen` holds the ancestors of the value being visited, so a repeated
+ * sibling reference is legal and only a genuine cycle is rejected.
+ *
+ * Every node it emits is typed {@link AvJsonValue}, so the public type and what
+ * this traversal produces are one fact: a branch that emitted anything else
+ * would not compile.
+ */
+export declare function normalizeJsonValue(value: unknown, path: Path, seen: Set<object>): ScalarValueNormalizationResult;
 /**
  * Normalizes one field value to Aventara's provider-neutral runtime form.
  * `runtime` is used for framework-produced values regardless of request origin.
  */
-export declare function normalizeScalarFieldValue(contract: Contract, field: ScalarField<Contract>, value: unknown, origin: RequestOrigin | "runtime", path: Path): ScalarValueNormalizationResult;
+export declare function normalizeScalarFieldValue(contract: AvContract, field: AvScalarField<AvContract>, value: unknown, origin: AvRequestOrigin | "runtime", path: Path): ScalarValueNormalizationResult;
 /**
  * Every way a normalized value written to `field` does not conform to the field's
  * Json Shape, each at its full path; none for an unshaped field or a `null`.
@@ -45,17 +60,17 @@ export declare function normalizeScalarFieldValue(contract: Contract, field: Sca
  * @throws Error when the field carries a shape no checker is bound to — a Contract
  *   the Framework did not compile.
  */
-export declare function jsonShapeIssues(field: ScalarField<Contract>, value: unknown, path: Path, position?: "value" | "entry"): readonly ValidationIssue[];
+export declare function jsonShapeIssues(field: AvScalarField<AvContract>, value: unknown, path: Path, position?: "value" | "entry"): readonly AvValidationIssue[];
 /**
  * Copies one validated runtime value of a scalar field into a value the framework
  * owns, per scalar codec: `datetime` → a new `Date`, `bytes` → a sliced `Uint8Array`,
  * `json` → a structured deep copy, and a list → a new array of copied items. `decimal`
  * keeps its identity, and strings, numbers, booleans, bigints, enum members and `null`
  * are immutable and returned unchanged. {@link SCALAR_ATOM_COPIERS} is exhaustive over
- * {@link BuiltInScalar}, so a new codec cannot reach this function without declaring
+ * {@link AvBuiltInScalar}, so a new codec cannot reach this function without declaring
  * its copy.
  */
-export declare function copyScalarFieldValue(field: ScalarField<Contract>, value: unknown): unknown;
+export declare function copyScalarFieldValue(field: AvScalarField<AvContract>, value: unknown): unknown;
 /**
  * The operators of a step's own filter whose operand is a reference position, and
  * the shape each holds — the one table the normalization below and the reference
@@ -63,7 +78,7 @@ export declare function copyScalarFieldValue(field: ScalarField<Contract>, value
  * nested operator object. Not here, so never a reference: `mode`, `isEmpty`, `path`
  * and a `json` field's `string*`/`array*` operators, which take no field value.
  */
-export declare const REFERENCE_OPERANDS: Readonly<Partial<Record<ScalarFilterOperator, TransactionSlotShape>>>;
+export declare const REFERENCE_OPERANDS: Readonly<Partial<Record<AvScalarFilterOperator, TransactionSlotShape>>>;
 /** The shape of `operator`'s operand when it is a reference position. */
 export declare function referenceOperandShape(operator: string): TransactionSlotShape | undefined;
 /**
@@ -76,8 +91,8 @@ export type NormalizationWrite = "copy" | "in-place";
  * Normalizes every scalar leaf in one structurally valid standard operation.
  * Client wire values are decoded; application values are validated in runtime form.
  */
-export declare function normalizeOperationScalarValues(contract: Contract, request: OperationIdentity & {
+export declare function normalizeOperationScalarValues(contract: AvContract, request: AvOperationIdentity & {
     readonly resource: string;
     readonly arguments: SemanticOperationArguments;
-}, origin: RequestOrigin, options?: OperationValidationOptions, write?: NormalizationWrite): ScalarNormalizationResult;
+}, origin: AvRequestOrigin, options?: OperationValidationOptions, write?: NormalizationWrite): ScalarNormalizationResult;
 export {};

package/dist/runtime/scalar-runtime.js

@@ -1,8 +1,8 @@
+import { shapeOfField } from "../avz/json-shape.registry.js";
 import { lookupField, lookupOwn, lookupResource, } from "../contracts/contract-lookup.js";
 import { decodeBase64, WIRE_SCALAR_PATTERNS, } from "../contracts/wire-scalar-format.js";
-import { shapeOfField } from "../json/json-shape.registry.js";
 import { routeTransactionReferenceCandidate, } from "../transactions/transaction-reference.js";
-import { Decimal } from "./decimal.js";
+import { AvDecimal } from "./decimal.js";
 const INT_MIN = -(2 ** 31);
 const INT_MAX = 2 ** 31 - 1;
 const BIGINT_MIN = -(2n ** 63n);
@@ -39,7 +39,7 @@ function materializeJsonPath(root, link) {
     segments.reverse();
     return [...root, ...segments];
 }
-function normalizeJsonValue(value, path, seen) {
+export function normalizeJsonValue(value, path, seen) {
     const issues = [];
     let root;
     const stack = [
@@ -232,7 +232,7 @@ function normalizeScalarAtom(contract, field, value, origin, path, allowNull) {
         case "decimal":
             if (origin === "application") {
                 normalized =
-                    value instanceof Decimal
+                    value instanceof AvDecimal
                         ? { ok: true, value }
                         : { ok: false, issues: [typeIssue(path, "an Aventara Decimal")] };
             }
@@ -244,7 +244,7 @@ function normalizeScalarAtom(contract, field, value, origin, path, allowNull) {
             }
             else {
                 try {
-                    normalized = { ok: true, value: new Decimal(value) };
+                    normalized = { ok: true, value: new AvDecimal(value) };
                 }
                 catch {
                     normalized = {
@@ -385,7 +385,6 @@ function normalizeWrittenValue(contract, field, value, origin, path, issues) {
         issues.push(...result.issues);
         return undefined;
     }
-    issues.push(...jsonShapeIssues(field, result.value, path));
     return result.value;
 }
 function normalizeWrittenElement(contract, field, value, origin, path, issues) {
@@ -394,7 +393,6 @@ function normalizeWrittenElement(contract, field, value, origin, path, issues) {
         issues.push(...result.issues);
         return undefined;
     }
-    issues.push(...jsonShapeIssues(field, result.value, path, "entry"));
     return result.value;
 }
 const SCALAR_ATOM_COPIERS = {
@@ -679,9 +677,9 @@ function normalizeRelationMutation(contract, edge, value, origin, path, issues,
     const normalized = cloneRecord(value);
     for (const [directive, operand] of Object.entries(value)) {
         const directivePath = [...path, directive];
-        const entries = edge.cardinality === "many" && Array.isArray(operand)
-            ? operand
-            : [operand];
+        const listed = edge.cardinality === "many" && Array.isArray(operand);
+        const entries = listed ? operand : [operand];
+        const entryPath = (index) => listed ? [...directivePath, index] : directivePath;
         if (directive === "$create") {
             normalized[directive] =
                 edge.cardinality === "many" && Array.isArray(operand)
@@ -714,8 +712,8 @@ function normalizeRelationMutation(contract, edge, value, origin, path, issues,
                 }
                 return {
                     ...entry,
-                    where: normalizeUniqueSelector(contract, edge.target, entry.where, origin, [...directivePath, index, "where"], issues, references),
-                    create: normalizeMutationData(contract, edge.target, entry.create, origin, [...directivePath, index, "create"], issues, references),
+                    where: normalizeUniqueSelector(contract, edge.target, entry.where, origin, [...entryPath(index), "where"], issues, references),
+                    create: normalizeMutationData(contract, edge.target, entry.create, origin, [...entryPath(index), "create"], issues, references),
                 };
             });
             normalized[directive] =
@@ -733,10 +731,10 @@ function normalizeRelationMutation(contract, edge, value, origin, path, issues,
                     ...entry,
                     ...(entry.where !== undefined
                         ? {
-                            where: normalizeWhere(contract, edge.target, entry.where, origin, [...directivePath, index, "where"], issues, references),
+                            where: normalizeWhere(contract, edge.target, entry.where, origin, [...entryPath(index), "where"], issues, references),
                         }
                         : {}),
-                    data: normalizeMutationData(contract, edge.target, entry.data, origin, [...directivePath, index, "data"], issues, references),
+                    data: normalizeMutationData(contract, edge.target, entry.data, origin, [...entryPath(index), "data"], issues, references),
                 };
             });
             normalized[directive] =
@@ -752,7 +750,7 @@ function normalizeRelationMutation(contract, edge, value, origin, path, issues,
                 }
                 return {
                     ...entry,
-                    where: normalizeWhere(contract, edge.target, entry.where, origin, [...directivePath, index, "where"], issues, references),
+                    where: normalizeWhere(contract, edge.target, entry.where, origin, [...entryPath(index), "where"], issues, references),
                 };
             });
             normalized[directive] =
@@ -770,11 +768,11 @@ function normalizeRelationMutation(contract, edge, value, origin, path, issues,
                     ...entry,
                     ...(entry.where !== undefined
                         ? {
-                            where: normalizeUniqueSelector(contract, edge.target, entry.where, origin, [...directivePath, index, "where"], issues, references),
+                            where: normalizeUniqueSelector(contract, edge.target, entry.where, origin, [...entryPath(index), "where"], issues, references),
                         }
                         : {}),
-                    create: normalizeMutationData(contract, edge.target, entry.create, origin, [...directivePath, index, "create"], issues, references),
-                    update: normalizeMutationData(contract, edge.target, entry.update, origin, [...directivePath, index, "update"], issues, references),
+                    create: normalizeMutationData(contract, edge.target, entry.create, origin, [...entryPath(index), "create"], issues, references),
+                    update: normalizeMutationData(contract, edge.target, entry.update, origin, [...entryPath(index), "update"], issues, references),
                 };
             });
             normalized[directive] =

package/dist/transactions/deferred-operation.d.ts

@@ -1,12 +1,10 @@
-import type { OperationIdentity } from "../operations/operation-identity.js";
-import type { ExecutionOptions } from "../runtime/execution-options.js";
-import type { OperationFailureResponse } from "../runtime/operation-response.js";
-import type { TransactionReference } from "./transaction-reference.js";
-import type { TransactionCommittedResponse } from "./transaction-response.js";
+import type { AvOperationIdentity } from "../operations/operation-identity.js";
+import type { AvExecutionOptions } from "../runtime/execution-options.js";
+import type { AvTransactionReference } from "./transaction-reference.js";
 /** An operation fingerprint: `fp1:` and a hash of the operation and its arguments. */
 export type OperationFingerprint = `fp1:${string}`;
 /** One serializable transaction-plan operation node. */
-export type DeferredOperation = OperationIdentity & {
+export type DeferredOperation = AvOperationIdentity & {
     readonly resource: string;
     readonly args: unknown;
     readonly fingerprint: OperationFingerprint;
@@ -17,34 +15,51 @@ export type TransactionPlan = {
 };
 declare const OPERATION_RESULT: unique symbol;
 declare const OPERATION_HANDLE: unique symbol;
+/** The origin a handle's builder gives it: `appTx`'s or `clientTx`'s. */
+type HandleOrigin = "application" | "client";
+type AnyOrigin = any;
 /** Standard-library shapes that are objects but never a projected result row. */
 export type BuiltinNonRow = Date | RegExp | ReadonlyMap<unknown, unknown> | ReadonlySet<unknown> | PromiseLike<unknown> | ArrayBufferView;
 /**
  * The single row behind a result type, or `never` when the result is not one
  * referenceable row.
  */
-export type SingleRowResult<T> = NonNullable<T> extends readonly unknown[] ? never : NonNullable<T> extends (...args: never[]) => unknown ? never : NonNullable<T> extends BuiltinNonRow ? never : NonNullable<T> extends object ? Extract<keyof NonNullable<T>, string> extends never ? never : NonNullable<T> : never;
+export type AvSingleRowResult<T> = NonNullable<T> extends readonly unknown[] ? never : NonNullable<T> extends (...args: never[]) => unknown ? never : NonNullable<T> extends BuiltinNonRow ? never : NonNullable<T> extends object ? Extract<keyof NonNullable<T>, string> extends never ? never : NonNullable<T> : never;
 /** The field names a result row can be referenced by. */
-export type ReferenceableField<T> = Extract<keyof SingleRowResult<T>, string>;
+export type AvReferenceableField<T> = Extract<keyof AvSingleRowResult<T>, string>;
 /** Builds a `$ref` to one field of this handle's row, typed as that field. */
-export type ReferenceBuilder<T> = <F extends ReferenceableField<T>>(field: F) => TransactionReference<SingleRowResult<T>[F]>;
+export type AvReferenceBuilder<T> = <F extends AvReferenceableField<T>>(field: F) => AvTransactionReference<AvSingleRowResult<T>[F]>;
 /** Contributes `$ref` only where the result is a referenceable single row. */
-export type OperationReferenceSurface<T> = [SingleRowResult<T>] extends [never] ? {} : {
-    readonly $ref: ReferenceBuilder<T>;
+export type AvOperationReferenceSurface<T> = [AvSingleRowResult<T>] extends [
+    never
+] ? {} : {
+    readonly $ref: AvReferenceBuilder<T>;
 };
-/** An opaque deferred-operation handle. */
-export type Operation<T> = {
-    readonly [OPERATION_HANDLE]: true;
+/**
+ * The opaque part of every deferred-operation handle: the result type `T` its
+ * transaction slot resolves to, and the origin of the builder that made it
+ * (`appTx` is `"application"`, `clientTx` is `"client"`; left out, either).
+ * Type-level only: a handle holds neither at runtime.
+ */
+export interface AvOperationHandle<T, Origin extends HandleOrigin = AnyOrigin> {
+    readonly [OPERATION_HANDLE]: Origin;
     readonly [OPERATION_RESULT]?: T;
-} & OperationReferenceSurface<T>;
+}
+/**
+ * An opaque deferred-operation handle: its result type and origin
+ * ({@link AvOperationHandle}), and `$ref` where the result is one row.
+ */
+export type AvOperation<T, Origin extends HandleOrigin = AnyOrigin> = AvOperationHandle<T, Origin> & AvOperationReferenceSurface<T>;
 /** Ordered results of a tuple of handles, positionally typed. */
-export type TransactionResults<Ops extends readonly Operation<unknown>[]> = {
-    readonly [I in keyof Ops]: Ops[I] extends Operation<infer R> ? R : never;
+export type AvTransactionResults<Ops extends readonly AvOperation<unknown>[]> = {
+    readonly [I in keyof Ops]: Ops[I] extends AvOperation<infer R> ? R : never;
 };
 /**
  * `framework.transaction`'s type. It infers the handle tuple without `as const`
- * and resolves the committed response (`A1009`) with each handle's result in
- * plan order, or the failure response.
+ * and resolves each handle's result in plan order once the transaction
+ * committed, or throws its failure as the `AvError` subclass of the code's class
+ * (`cause.operation` names the failing step). The handles are all `appTx`
+ * handles or all `clientTx` handles: a list that mixes them is a type error.
  */
-export type TransactionRunner = <const Ops extends readonly Operation<unknown>[]>(operations: Ops, options?: ExecutionOptions) => Promise<TransactionCommittedResponse<TransactionResults<Ops>> | OperationFailureResponse>;
+export type AvTransactionRunner = <const Ops extends readonly AvOperation<unknown, "application">[] | readonly AvOperation<unknown, "client">[]>(operations: Ops, options?: AvExecutionOptions) => Promise<AvTransactionResults<Ops>>;
 export {};

package/dist/transactions/operation-arguments-encoder.d.ts

@@ -1,7 +1,7 @@
-import type { Contract } from "../contracts/contract.js";
-import type { OperationIdentity } from "../operations/operation-identity.js";
+import type { AvContract } from "../contracts/contract.js";
+import type { AvOperationIdentity } from "../operations/operation-identity.js";
 import type { SemanticOperationArguments } from "../operations/operation-validator.js";
 /** Encodes validated application arguments into the wire scalar form. */
-export declare function encodeOperationArgumentsForWire(contract: Contract, operation: OperationIdentity & {
+export declare function encodeOperationArgumentsForWire(contract: AvContract, operation: AvOperationIdentity & {
     readonly resource: string;
 }, args: SemanticOperationArguments): unknown;

package/dist/transactions/operation-arguments-encoder.js

@@ -1,6 +1,6 @@
 import { lookupField, lookupResource } from "../contracts/contract-lookup.js";
 import { encodeBase64 } from "../contracts/wire-scalar-format.js";
-import { Decimal } from "../runtime/decimal.js";
+import { AvDecimal } from "../runtime/decimal.js";
 import { isRelationMutationDirective, RELATION_MUTATION_RECORD_SITES, } from "../runtime/mutation-planner.js";
 import { isTransactionReferenceCandidate } from "./transaction-reference.js";
 function isPlainRecord(value) {
@@ -27,7 +27,7 @@ function encodeScalarAtom(field, value) {
         case "bigint":
             return typeof value === "bigint" ? value.toString(10) : value;
         case "decimal":
-            return value instanceof Decimal ? value.toString() : value;
+            return value instanceof AvDecimal ? value.toString() : value;
         case "datetime":
             return value instanceof Date ? value.toISOString() : value;
         case "bytes":

package/dist/transactions/sql-statement.d.ts

@@ -0,0 +1,77 @@
+import type { AvAdapterSqlValue } from "../adapters/adapter-sql-statement.js";
+import type { AvContract } from "../contracts/contract.js";
+import type { AvScalarField } from "../contracts/field.js";
+import type { AvCallerDataError } from "../runtime/caller-data.copier.js";
+import type { AvOperation } from "./deferred-operation.js";
+import type { AvTransactionReference } from "./transaction-reference.js";
+/**
+ * One value an `appTx.$sql` template binds: a primitive, a `Date`, an `AvDecimal`, a
+ * `Uint8Array`, a JSON value (a plain object or array, bound as JSON text — cast it,
+ * `${value}::jsonb`), or a `$ref` to an earlier step's field, resolved when the
+ * earlier steps have run and then bound like any other value.
+ */
+export type SqlStatementValue = AvAdapterSqlValue | AvTransactionReference;
+/**
+ * `framework.appTx.$sql`: a developer SQL step, written only as a tagged template —
+ * ``framework.appTx.$sql`select pgmq.send('jobs', jsonb_build_object('id', ${ref}))` ``.
+ * Every interpolated value is bound as a parameter, never spliced into the text, so
+ * the text is static: a table or column name cannot come from a value.
+ *
+ * The step runs in plan order inside the same database transaction as the other
+ * steps; its entry in the committed `data` is the rows the statement returned,
+ * typed `Row[]` (`unknown[]` unless `Row` is given). A later step cannot `$ref` a
+ * SQL step's rows. No guard, pipe, hook, interceptor or filter runs around it: it
+ * has no Resource or operation for one to wrap.
+ */
+export type SqlStatementBuilder = <Row = unknown>(strings: TemplateStringsArray, ...values: readonly SqlStatementValue[]) => AvOperation<Row[], "application">;
+/** One value of a planned SQL step, as the typed runner bound it. */
+export type PlannedSqlValue = {
+    readonly kind: "value";
+    readonly value: unknown;
+}
+/** A `$ref` placeholder standing as the whole value: the source's position and field. */
+ | {
+    readonly kind: "reference";
+    readonly operation: number;
+    readonly field: string;
+}
+/** A `$ref` placeholder found inside a value, at `path` within it: refused. */
+ | {
+    readonly kind: "misplaced-reference";
+    readonly path: readonly (string | number)[];
+};
+/**
+ * A SQL step as the typed runner hands it to the validator, unvalidated: the
+ * template's static text (`undefined` when the call was no genuine tagged
+ * template), its values with each `$ref` bound to its source's position, or why the
+ * builder could not copy the values.
+ */
+export type PlannedSqlStatement = {
+    readonly strings: readonly string[] | undefined;
+    readonly values: readonly PlannedSqlValue[];
+    readonly refused?: AvCallerDataError;
+};
+/** One validated value of a SQL step: bound as it is, or resolved from a `$ref`. */
+export type ValidatedSqlValue = {
+    readonly kind: "value";
+    readonly value: AvAdapterSqlValue;
+} | {
+    readonly kind: "reference";
+    readonly operation: number;
+    readonly field: string;
+    /** The source field, under its own step's Contract: what the value is read as. */
+    readonly source: AvScalarField<AvContract>;
+};
+/** A SQL step the Framework Validation Layer accepted. */
+export type ValidatedSqlStatement = {
+    readonly kind: "sql";
+    readonly index: number;
+    readonly strings: readonly string[];
+    readonly values: readonly ValidatedSqlValue[];
+};
+/**
+ * The static text of a genuine tagged template, read once and copied, or
+ * `undefined` when `strings` is not one or does not fit `valueCount` values.
+ * Total: a hostile value is `undefined`, never a throw.
+ */
+export declare function readSqlTemplate(strings: unknown, valueCount: number): readonly string[] | undefined;

package/dist/transactions/sql-statement.js

@@ -0,0 +1,47 @@
+function ownData(target, key) {
+    const descriptor = Object.getOwnPropertyDescriptor(target, key);
+    return descriptor !== undefined && "value" in descriptor
+        ? descriptor.value
+        : undefined;
+}
+function frozenStrings(value, length) {
+    if (!Array.isArray(value) || !Object.isFrozen(value)) {
+        return undefined;
+    }
+    const size = ownData(value, "length");
+    if (typeof size !== "number" ||
+        size < 1 ||
+        (length !== undefined && size !== length)) {
+        return undefined;
+    }
+    const strings = [];
+    for (let index = 0; index < size; index += 1) {
+        const entry = ownData(value, String(index));
+        if (typeof entry !== "string") {
+            return undefined;
+        }
+        strings.push(entry);
+    }
+    return strings;
+}
+export function readSqlTemplate(strings, valueCount) {
+    try {
+        if (typeof strings !== "object" || strings === null) {
+            return undefined;
+        }
+        const raw = Object.getOwnPropertyDescriptor(strings, "raw");
+        if (raw === undefined || raw.enumerable || !("value" in raw)) {
+            return undefined;
+        }
+        const cooked = frozenStrings(strings, valueCount + 1);
+        if (cooked === undefined) {
+            return undefined;
+        }
+        return frozenStrings(raw.value, cooked.length) === undefined
+            ? undefined
+            : Object.freeze(cooked);
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/transactions/sql-statement.validator.d.ts

@@ -0,0 +1,44 @@
+import type { AvAdapterSqlValue } from "../adapters/adapter-sql-statement.js";
+import type { AvValidationIssue } from "../operations/validation-code.js";
+import type { MisuseReporter } from "../runtime/misuse-reporter.js";
+import type { AvOperationFailureResponse } from "../runtime/operation-response.js";
+import type { PlannedSqlStatement, ValidatedSqlStatement } from "./sql-statement.js";
+import type { ValidatedTransactionStep } from "./transaction-plan-validator.js";
+type Path = readonly (string | number)[];
+export type SqlStatementValidation = {
+    readonly ok: true;
+    readonly statement: ValidatedSqlStatement;
+} | {
+    readonly ok: false;
+    readonly response: AvOperationFailureResponse;
+};
+/** What validating a SQL step needs from the plan around it. */
+export type SqlStatementValidationContext = {
+    /** The step's position in the plan. */
+    readonly index: number;
+    /** The steps validated before it, by position. */
+    readonly earlier: readonly ValidatedTransactionStep[];
+    /** Whether the Adapter declares `sqlStatements`. */
+    readonly available: boolean;
+    readonly misuse: MisuseReporter;
+};
+/**
+ * One bindable value of a SQL step, in its runtime form, or the issues that refuse
+ * it: a primitive (a `number` only when finite), a valid `Date`, an `AvDecimal`, a
+ * `Uint8Array`, or a JSON value — a plain object or array, held to the same rules
+ * as a `json` field's value. `undefined` and anything else are no value to bind.
+ */
+export declare function normalizeSqlValue(value: unknown, path: Path): {
+    readonly ok: true;
+    readonly value: AvAdapterSqlValue;
+} | {
+    readonly ok: false;
+    readonly issues: readonly AvValidationIssue[];
+};
+/**
+ * Validates one SQL step: the Adapter runs SQL statements, the call was a genuine
+ * tagged template, its values could be copied, every value is bindable, and every
+ * `$ref` stands as a whole value and reads one field of an earlier single-row step.
+ */
+export declare function validateSqlStatement(statement: PlannedSqlStatement, context: SqlStatementValidationContext): SqlStatementValidation;
+export {};