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

package/dist/runtime/field-compute.d.ts

@@ -0,0 +1,64 @@
+import type { AvAdapterModel } from "../adapters/adapter-model.js";
+import type { AvAdapterFieldKey } from "../adapters/adapter-resource.js";
+import type { AvConfigAny } from "../config/any-framework-config.js";
+import type { AvEffectiveFieldKey } from "../config/effective-fields.js";
+import type { AvConfigResourceKey } from "../config/framework-field-definition.js";
+import type { AvComputeReads } from "../framework/operation-facade.js";
+import type { AvContext } from "./pipeline.js";
+import type { AvDeepReadonly } from "./readonly-value.js";
+import type { AvState } from "./request-state.js";
+/**
+ * The ctx a compute stage is told: the operation's `$` facts, a read-only view
+ * of the request's `$state`, and reads only (`ctx.<Resource>.find.<variant>(args)`,
+ * `find.count` included).
+ */
+export type AvComputeContext<M extends AvAdapterModel = AvAdapterModel> = AvComputeReads<M> & Pick<AvContext<M>, "$operation" | "$args" | "$origin" | "$requestId" | "$transport" | "$contract"> & {
+    /** The request's state, read-only: a write throws a `TypeError`. */
+    readonly $state: AvDeepReadonly<AvState>;
+};
+/**
+ * What a write-stage compute callback is told about the field it is computing.
+ */
+type ComputedWriteContext<M extends AvAdapterModel> = {
+    readonly field: string;
+    readonly value: unknown;
+    readonly data: Readonly<Record<string, unknown>>;
+    readonly ctx: AvComputeContext<M>;
+};
+/**
+ * Computes a field's value when a row is created, whether or not the caller sent
+ * it. It receives the incoming `data` and returns the value to store; returning
+ * `undefined` keeps the current value.
+ */
+export type AvComputeCreate<M extends AvAdapterModel = AvAdapterModel> = (context: ComputedWriteContext<M>) => unknown | Promise<unknown>;
+/**
+ * Computes a field's value when a row is updated, whether or not the caller sent
+ * it. It receives the incoming `data` and returns the value to store; returning
+ * `undefined` keeps the current value.
+ */
+export type AvComputeUpdate<M extends AvAdapterModel = AvAdapterModel> = (context: ComputedWriteContext<M>) => unknown | Promise<unknown>;
+/**
+ * Computes a field's value when a row is read. It receives the stored `record`
+ * and returns the value to return; returning `undefined` keeps the current value.
+ */
+export type ComputeReadFunction<M extends AvAdapterModel = AvAdapterModel, Cfg = AvConfigAny, R extends AvConfigResourceKey<M> = AvConfigResourceKey<M>> = (context: {
+    readonly field: AvEffectiveFieldKey<M, Cfg, R>;
+    readonly value: unknown;
+    readonly record: Readonly<Record<AvEffectiveFieldKey<M, Cfg, R>, unknown>>;
+    readonly ctx: AvComputeContext<M>;
+}) => unknown | Promise<unknown>;
+/** The fields of Resource `R` the adapter stores as scalars: what `dependsOn` may name. */
+type StoredScalarKey<M extends AvAdapterModel, R extends AvConfigResourceKey<M>> = string extends AvAdapterFieldKey<M, R> ? string : {
+    [F in AvAdapterFieldKey<M, R>]: M["resources"][R]["fields"][F] extends {
+        readonly kind: "scalar";
+    } ? F : never;
+}[AvAdapterFieldKey<M, R>];
+/**
+ * A read compute stage: a compute function, or `{ compute, dependsOn }` naming
+ * the fields it reads.
+ */
+export type AvComputeRead<M extends AvAdapterModel = AvAdapterModel, Cfg = AvConfigAny, R extends AvConfigResourceKey<M> = AvConfigResourceKey<M>> = ComputeReadFunction<M, Cfg, R> | {
+    readonly dependsOn?: readonly StoredScalarKey<M, R>[];
+    readonly compute: ComputeReadFunction<M, Cfg, R>;
+};
+export {};

package/dist/runtime/field-compute.js

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

package/dist/runtime/field-stage.plan.d.ts

@@ -0,0 +1,15 @@
+import type { ResolvedPipelineTree } from "../config/pipeline-tree.resolver.js";
+import type { AvContract } from "../contracts/contract.js";
+/** One origin's field-stage dispatch, planned at startup. */
+export type FieldStagePlan = {
+    /** Whether any Resource registers a field pipe. */
+    readonly anyPipes: boolean;
+    /** Whether any Resource registers a guard a nested target runs: its own, its family's or a field write guard. */
+    readonly nestedGuards: boolean;
+    /** `resource`'s fields with write guards, in the Resource's field order. */
+    readonly guarded: (resource: string) => readonly string[];
+    /** `resource`'s fields with field pipes, in the Resource's field order. */
+    readonly piped: (resource: string) => readonly string[];
+};
+/** Plans the field-stage dispatch of `tree` under `contract`. */
+export declare function planFieldStages(tree: ResolvedPipelineTree, contract: AvContract): FieldStagePlan;

package/dist/runtime/field-stage.plan.js

@@ -0,0 +1,27 @@
+import { stagedFieldsOf } from "./field-stage.runtime.js";
+const NONE = Object.freeze([]);
+export function planFieldStages(tree, contract) {
+    const guarded = new Map();
+    const piped = new Map();
+    let nestedGuards = false;
+    for (const [resource, pipelines] of Object.entries(tree.resources)) {
+        const guards = stagedFieldsOf(contract, resource, pipelines.fields, "guards");
+        const pipes = stagedFieldsOf(contract, resource, pipelines.fields, "pipes");
+        if (guards.length > 0) {
+            guarded.set(resource, Object.freeze([...guards]));
+        }
+        if (pipes.length > 0) {
+            piped.set(resource, Object.freeze([...pipes]));
+        }
+        nestedGuards ||=
+            guards.length > 0 ||
+                pipelines.pipelines.some((level) => level.guards.length > 0) ||
+                Object.values(pipelines.families).some((family) => family.pipelines.some((level) => level.guards.length > 0));
+    }
+    return Object.freeze({
+        anyPipes: piped.size > 0,
+        nestedGuards,
+        guarded: (resource) => guarded.get(resource) ?? NONE,
+        piped: (resource) => piped.get(resource) ?? NONE,
+    });
+}

package/dist/runtime/field-stage.runtime.d.ts

@@ -0,0 +1,35 @@
+import type { ResolvedFieldStages } from "../config/pipeline-tree.resolver.js";
+import type { AvContract } from "../contracts/contract.js";
+import type { AvOperationFamily } from "../operations/operation-identity.js";
+import type { AvContext } from "./pipeline.js";
+export type Path = readonly (string | number)[];
+type UnknownRecord = Readonly<Record<string, unknown>>;
+/** A plain object: what a write record, or a directive's operand, is. */
+export declare function isPlainRecord(value: unknown): value is UnknownRecord;
+/** The fields of `resource` with stages, in the Resource's field order. */
+export declare function stagedFieldsOf(contract: AvContract, resource: string, stages: Readonly<Record<string, ResolvedFieldStages>>, kind: "pipes" | "guards"): readonly string[];
+/** The value at `path` in `args`, or `undefined` when nothing is there. */
+export declare function valueAt(args: unknown, path: Path): unknown;
+/** `args` with the record at `path` replaced, every container on the way copied. */
+export declare function replaceAt(args: unknown, path: Path, record: UnknownRecord): unknown;
+export type PipedFields = {
+    readonly args: unknown;
+    /** Whether a field pipe returned a value: the arguments must be held to the server's rules again. */
+    readonly changed: boolean;
+};
+/** The paths of the top-level data records of a create, update or upsert. */
+export declare function writeRecordPathsOf(family: AvOperationFamily, args: unknown): readonly Path[];
+/**
+ * Runs the field pipes of every sent field `select` admits, in the records at
+ * `records`, field by field in the Resource's order, root's pipes then
+ * overlay's. A pipe returning `undefined` keeps the value. The arguments are
+ * copied where a value changes, never written.
+ */
+export declare function pipeSentFields(stages: Readonly<Record<string, ResolvedFieldStages>>, fields: readonly string[], records: readonly Path[], args: unknown, select: (path: Path) => boolean): Promise<PipedFields>;
+/**
+ * Runs the write guards of every sent field in the records at `records`, field
+ * by field in the Resource's order and, for several records, record by record;
+ * `false` as soon as one refuses.
+ */
+export declare function guardSentFields(stages: Readonly<Record<string, ResolvedFieldStages>>, fields: readonly string[], records: readonly Path[], args: unknown, context: () => AvContext): Promise<boolean>;
+export {};

package/dist/runtime/field-stage.runtime.js

@@ -0,0 +1,143 @@
+export function isPlainRecord(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        return false;
+    }
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}
+const WRITE_KEYS = {
+    create: ["data"],
+    update: ["data"],
+    upsert: ["create", "update"],
+};
+function writeRecordsOf(family, args) {
+    const keys = WRITE_KEYS[family];
+    if (keys === undefined || !isPlainRecord(args)) {
+        return [];
+    }
+    const records = [];
+    for (const key of keys) {
+        if (!Object.hasOwn(args, key)) {
+            continue;
+        }
+        const value = args[key];
+        if (Array.isArray(value)) {
+            for (const [index, entry] of value.entries()) {
+                if (isPlainRecord(entry)) {
+                    records.push({ path: [key, index], record: entry });
+                }
+            }
+        }
+        else if (isPlainRecord(value)) {
+            records.push({ path: [key], record: value });
+        }
+    }
+    return records;
+}
+function sends(record, field) {
+    return Object.hasOwn(record, field) && record[field] !== undefined;
+}
+function isDirective(value) {
+    return (isPlainRecord(value) &&
+        Object.keys(value).some((key) => key.startsWith("$")));
+}
+export function stagedFieldsOf(contract, resource, stages, kind) {
+    const fields = Object.hasOwn(contract.resources, resource)
+        ? contract.resources[resource]?.fields
+        : undefined;
+    if (fields === undefined) {
+        return [];
+    }
+    return Object.keys(fields).filter((field) => Object.hasOwn(stages, field) && (stages[field]?.[kind].length ?? 0) > 0);
+}
+export function valueAt(args, path) {
+    let current = args;
+    for (const key of path) {
+        if (Array.isArray(current) && typeof key === "number") {
+            current = current[key];
+        }
+        else if (isPlainRecord(current) && Object.hasOwn(current, key)) {
+            current = current[key];
+        }
+        else {
+            return undefined;
+        }
+    }
+    return current;
+}
+export function replaceAt(args, path, record) {
+    const [head, ...rest] = path;
+    if (head === undefined) {
+        return record;
+    }
+    if (Array.isArray(args)) {
+        const copy = [...args];
+        copy[head] = replaceAt(copy[head], rest, record);
+        return copy;
+    }
+    const container = args;
+    return {
+        ...container,
+        [head]: replaceAt(container[head], rest, record),
+    };
+}
+export function writeRecordPathsOf(family, args) {
+    return writeRecordsOf(family, args).map((entry) => entry.path);
+}
+export async function pipeSentFields(stages, fields, records, args, select) {
+    if (fields.length === 0) {
+        return { args, changed: false };
+    }
+    let current = args;
+    let changed = false;
+    for (const path of records) {
+        const record = valueAt(current, path);
+        if (!isPlainRecord(record)) {
+            continue;
+        }
+        let piped;
+        for (const field of fields) {
+            if (!sends(record, field) ||
+                isDirective(record[field]) ||
+                !select([...path, field])) {
+                continue;
+            }
+            let value = record[field];
+            for (const pipe of stages[field]?.pipes ?? []) {
+                const next = await pipe(value);
+                if (next !== undefined) {
+                    value = next;
+                    changed = true;
+                }
+            }
+            if (value !== record[field]) {
+                piped ??= { ...record };
+                piped[field] = value;
+            }
+        }
+        if (piped !== undefined) {
+            current = replaceAt(current, path, piped);
+        }
+    }
+    return { args: current, changed };
+}
+export async function guardSentFields(stages, fields, records, args, context) {
+    if (fields.length === 0) {
+        return true;
+    }
+    const sent = records.map((path) => valueAt(args, path)).filter(isPlainRecord);
+    for (const field of fields) {
+        for (const record of sent) {
+            if (!sends(record, field)) {
+                continue;
+            }
+            for (const guard of stages[field]?.guards ?? []) {
+                const told = context();
+                if ((await guard(record[field], told)) === false) {
+                    return false;
+                }
+            }
+        }
+    }
+    return true;
+}

package/dist/runtime/field-validator.runtime.d.ts

@@ -0,0 +1,11 @@
+import type { AvContract } from "../contracts/contract.js";
+import type { AvValidationIssue } from "../operations/validation-code.js";
+import { type Path } from "./field-stage.runtime.js";
+import type { OperationExecutionRequest } from "./operation-request.js";
+import type { ReferentialActionTable } from "./referential-action.js";
+/**
+ * Every way the sent fields `select` admits break their validators: the
+ * operation's own records, then each nested write target's. Paths are the
+ * request's: `argumentsPath` and then the value's place in the arguments.
+ */
+export declare function fieldValidatorIssues(contract: AvContract, references: ReferentialActionTable, request: OperationExecutionRequest, args: unknown, argumentsPath: Path, select: (path: Path) => boolean): readonly AvValidationIssue[];

package/dist/runtime/field-validator.runtime.js

@@ -0,0 +1,87 @@
+import { validatedFieldsOf, } from "../compiler/field-validator.compiler.js";
+import { entryCheckIssues, fieldCheckIssues } from "./field-check.evaluator.js";
+import { isPlainRecord, valueAt, writeRecordPathsOf, } from "./field-stage.runtime.js";
+import { nestedWriteTargetsOf } from "./nested-write.walker.js";
+import { jsonShapeIssues } from "./scalar-runtime.js";
+function isDirective(value) {
+    return (isPlainRecord(value) &&
+        Object.keys(value).some((key) => key.startsWith("$")));
+}
+function rulesOf(contract, compiled, resource, name) {
+    const fields = Object.hasOwn(contract.resources, resource)
+        ? contract.resources[resource]?.fields
+        : undefined;
+    const field = fields !== undefined && Object.hasOwn(fields, name)
+        ? fields[name]
+        : undefined;
+    if (field?.kind === "scalar" && field.json !== undefined) {
+        return { kind: "shape", field };
+    }
+    const checks = Object.hasOwn(compiled, name) ? compiled[name] : undefined;
+    return checks === undefined
+        ? undefined
+        : { kind: "checks", compiled: checks };
+}
+function valueIssues(rules, value, at) {
+    if (rules.kind === "shape") {
+        return jsonShapeIssues(rules.field, value, at);
+    }
+    const { compiled } = rules;
+    return fieldCheckIssues(compiled.checks, value, compiled.subject ?? "string", at, compiled.list);
+}
+function entryIssues(rules, entry, at) {
+    if (rules.kind === "shape") {
+        return jsonShapeIssues(rules.field, entry, at, "entry");
+    }
+    const { compiled } = rules;
+    return entryCheckIssues(compiled.checks, entry, compiled.subject ?? "string", at);
+}
+function recordIssues(contract, resource, records, args, argumentsPath, select) {
+    const compiled = validatedFieldsOf(contract, resource);
+    const issues = [];
+    for (const path of records) {
+        const record = valueAt(args, path);
+        if (!isPlainRecord(record)) {
+            continue;
+        }
+        for (const name of Object.keys(record)) {
+            const rules = rulesOf(contract, compiled, resource, name);
+            if (rules === undefined) {
+                continue;
+            }
+            const fieldPath = [...path, name];
+            const value = record[name];
+            const at = [...argumentsPath, ...fieldPath];
+            if (!isDirective(value)) {
+                if (select(fieldPath)) {
+                    issues.push(...valueIssues(rules, value, at));
+                }
+                continue;
+            }
+            const list = rules.kind === "shape" ? rules.field.list : rules.compiled.list;
+            if (!list || !Object.hasOwn(value, "$push")) {
+                continue;
+            }
+            const operand = value.$push;
+            const pushed = Array.isArray(operand)
+                ? operand.map((entry, index) => ({
+                    entry,
+                    path: [...fieldPath, "$push", index],
+                }))
+                : [{ entry: operand, path: [...fieldPath, "$push"] }];
+            for (const { entry, path: entryPath } of pushed) {
+                if (!isDirective(entry) && (select(fieldPath) || select(entryPath))) {
+                    issues.push(...entryIssues(rules, entry, [...argumentsPath, ...entryPath]));
+                }
+            }
+        }
+    }
+    return issues;
+}
+export function fieldValidatorIssues(contract, references, request, args, argumentsPath, select) {
+    const issues = recordIssues(contract, request.resource, writeRecordPathsOf(request.family, args), args, argumentsPath, select);
+    for (const target of nestedWriteTargetsOf(contract, references, request, args)) {
+        issues.push(...recordIssues(contract, target.resource, target.records.map((site) => site.path), args, argumentsPath, select));
+    }
+    return issues;
+}

package/dist/runtime/framework-error-class.table.d.ts

@@ -0,0 +1,33 @@
+import type { AvOperationErrorCode } from "./operation-response.js";
+/** The `AvError` subclass every error code is thrown as, by class name. */
+export declare const FRAMEWORK_ERROR_CLASS_OF: {
+    readonly A2000: "AvProtocolError";
+    readonly A2001: "AvProtocolError";
+    readonly A2002: "AvProtocolError";
+    readonly A2003: "AvNotFoundError";
+    readonly A2004: "AvValidationError";
+    readonly A2005: "AvContractMismatchError";
+    readonly A2006: "AvProtocolError";
+    readonly A2007: "AvValidationError";
+    readonly A2008: "AvConflictError";
+    readonly A2009: "AvValidationError";
+    readonly A2010: "AvProtocolError";
+    readonly A2011: "AvProtocolError";
+    readonly A2012: "AvProtocolError";
+    readonly A2013: "AvConflictError";
+    readonly A2014: "AvConflictError";
+    readonly A3000: "AvInternalError";
+    readonly A3001: "AvInternalError";
+    readonly A3002: "AvInternalError";
+    readonly A3003: "AvInternalError";
+    readonly A3004: "AvInternalError";
+    readonly A4000: "AvAuthError";
+    readonly A4001: "AvAuthError";
+    readonly A4002: "AvAuthError";
+};
+/** The name of one `AvError` subclass. */
+export type AvErrorClassName = (typeof FRAMEWORK_ERROR_CLASS_OF)[AvOperationErrorCode];
+/** The error codes `AvError` subclass `N` is thrown for. */
+export type AvErrorCodeOf<N extends AvErrorClassName> = {
+    readonly [C in AvOperationErrorCode]: (typeof FRAMEWORK_ERROR_CLASS_OF)[C] extends N ? C : never;
+}[AvOperationErrorCode];

package/dist/runtime/framework-error-class.table.js

@@ -0,0 +1,25 @@
+export const FRAMEWORK_ERROR_CLASS_OF = {
+    A2000: "AvProtocolError",
+    A2001: "AvProtocolError",
+    A2002: "AvProtocolError",
+    A2003: "AvNotFoundError",
+    A2004: "AvValidationError",
+    A2005: "AvContractMismatchError",
+    A2006: "AvProtocolError",
+    A2007: "AvValidationError",
+    A2008: "AvConflictError",
+    A2009: "AvValidationError",
+    A2010: "AvProtocolError",
+    A2011: "AvProtocolError",
+    A2012: "AvProtocolError",
+    A2013: "AvConflictError",
+    A2014: "AvConflictError",
+    A3000: "AvInternalError",
+    A3001: "AvInternalError",
+    A3002: "AvInternalError",
+    A3003: "AvInternalError",
+    A3004: "AvInternalError",
+    A4000: "AvAuthError",
+    A4001: "AvAuthError",
+    A4002: "AvAuthError",
+};

package/dist/runtime/framework-error.d.ts

@@ -1,12 +1,19 @@
-import type { Cause, OperationErrorCode } from "./operation-response.js";
+import type { AvErrorCodeOf } from "./framework-error-class.table.js";
+import type { AvCause, AvOperationErrorCode } from "./operation-response.js";
 /**
- * Throw from a pipeline, behavior or Adapter to answer the request with one
- * framework error code and cause.
+ * Throw from a pipeline, compute stage or Adapter to answer the request with one
+ * framework error code and cause. Every in-process call that fails
+ * (`framework.application`, `framework.client`, `framework.transaction`, a ctx
+ * call) throws one too, as the subclass of its code's class:
+ * {@link AvValidationError}, {@link AvNotFoundError}, {@link AvConflictError},
+ * {@link AvAuthError}, {@link AvInternalError}, {@link AvProtocolError} or
+ * {@link AvContractMismatchError}. Branch on the class or on `code`, never on the
+ * message.
  *
  * For any code outside `A3xxx`, `cause.message` is sent to the caller exactly as
  * written: put nothing in it you would not show the caller (no database text,
  * SQL, stack, path or secret). So is each issue's `message`, when your own code
- * (a pipe, guard, hook, interceptor, filter or behavior) throws it and it is not
+ * (a pipe, guard, hook, interceptor, filter or compute stage) throws it and it is not
  * blank and at most 1,000 characters; otherwise, and for an issue an Adapter
  * throws, the caller receives the framework's own text for the issue's code. An
  * issue's `code` must be a validation code (`V1000` and up) and its `path` must
@@ -15,8 +22,61 @@ import type { Cause, OperationErrorCode } from "./operation-response.js";
  * message instead, and nothing of the cause; the error itself reaches the root
  * `diagnostics` sink once, marked `deliberate: true`.
  */
-export declare class FrameworkError extends Error {
-    readonly code: OperationErrorCode;
-    readonly cause: Cause;
-    constructor(code: OperationErrorCode, cause: Cause | string);
+export declare class AvError<C extends AvOperationErrorCode = AvOperationErrorCode> extends Error {
+    readonly name: string;
+    /** The outcome code. Branch on this, never on the message. */
+    readonly code: C;
+    /** The cause: its message, and its issues or failing step when there are any. */
+    readonly cause: AvCause;
+    constructor(code: C, cause: AvCause | string);
+}
+/**
+ * The request broke a Contract rule: a field, type, capability, projection,
+ * reference or limit. The cause's issues say which, by code and path. Thrown for
+ * A2004, A2007 and A2009.
+ */
+export declare class AvValidationError extends AvError<AvErrorCodeOf<"AvValidationError">> {
+    readonly name: string;
+}
+/** A strict unique target does not exist. Thrown for A2003. */
+export declare class AvNotFoundError extends AvError<AvErrorCodeOf<"AvNotFoundError">> {
+    readonly name: string;
+}
+/**
+ * The operation conflicted with stored state, and nothing was written. A2008
+ * fails the same way if sent again; A2013 and A2014 may succeed if sent again,
+ * and no retry is automatic. Thrown for A2008, A2013 and A2014.
+ */
+export declare class AvConflictError extends AvError<AvErrorCodeOf<"AvConflictError">> {
+    readonly name: string;
+}
+/**
+ * The caller is not authenticated, or is not permitted to run the operation.
+ * Thrown for A4000, A4001 and A4002.
+ */
+export declare class AvAuthError extends AvError<AvErrorCodeOf<"AvAuthError">> {
+    readonly name: string;
+}
+/**
+ * The server failed. Nothing in its cause is actionable; the diagnostics are in
+ * the `diagnostics` sink. Thrown for A3000 to A3004.
+ */
+export declare class AvInternalError extends AvError<AvErrorCodeOf<"AvInternalError">> {
+    readonly name: string;
+}
+/**
+ * The request was not one the server could route or interpret: an unknown
+ * Resource or operation, a protocol version it does not speak, or a body, media
+ * type, size or method it refuses. Thrown for A2000, A2001, A2002, A2006, A2010,
+ * A2011 and A2012.
+ */
+export declare class AvProtocolError extends AvError<AvErrorCodeOf<"AvProtocolError">> {
+    readonly name: string;
+}
+/**
+ * The caller's ClientContract hash is not the one the server serves (a stale
+ * generated client). Thrown for A2005.
+ */
+export declare class AvContractMismatchError extends AvError<AvErrorCodeOf<"AvContractMismatchError">> {
+    readonly name: string;
 }

package/dist/runtime/framework-error.factory.d.ts

@@ -0,0 +1,4 @@
+import { type AvError } from "./framework-error.js";
+import type { AvOperationFailureResponse } from "./operation-response.js";
+/** The `AvError` subclass a failure response throws in process, with its code and cause. */
+export declare function thrownFailure(response: AvOperationFailureResponse): AvError;

package/dist/runtime/framework-error.factory.js

@@ -0,0 +1,15 @@
+import { AvAuthError, AvConflictError, AvContractMismatchError, AvInternalError, AvNotFoundError, AvProtocolError, AvValidationError, } from "./framework-error.js";
+import { FRAMEWORK_ERROR_CLASS_OF, } from "./framework-error-class.table.js";
+const ERROR_CLASSES = {
+    AvAuthError,
+    AvConflictError,
+    AvContractMismatchError,
+    AvInternalError,
+    AvNotFoundError,
+    AvProtocolError,
+    AvValidationError,
+};
+export function thrownFailure(response) {
+    const ErrorClass = ERROR_CLASSES[FRAMEWORK_ERROR_CLASS_OF[response.code]];
+    return new ErrorClass(response.code, response.cause);
+}

package/dist/runtime/framework-error.js

@@ -1,11 +1,32 @@
-export class FrameworkError extends Error {
+export class AvError extends Error {
+    name = "AvError";
     code;
     cause;
     constructor(code, cause) {
         const normalizedCause = typeof cause === "string" ? { message: cause } : cause;
         super(normalizedCause.message);
-        this.name = "FrameworkError";
         this.code = code;
         this.cause = normalizedCause;
     }
 }
+export class AvValidationError extends AvError {
+    name = "AvValidationError";
+}
+export class AvNotFoundError extends AvError {
+    name = "AvNotFoundError";
+}
+export class AvConflictError extends AvError {
+    name = "AvConflictError";
+}
+export class AvAuthError extends AvError {
+    name = "AvAuthError";
+}
+export class AvInternalError extends AvError {
+    name = "AvInternalError";
+}
+export class AvProtocolError extends AvError {
+    name = "AvProtocolError";
+}
+export class AvContractMismatchError extends AvError {
+    name = "AvContractMismatchError";
+}

package/dist/runtime/interceptor-next.error.d.ts

@@ -0,0 +1,5 @@
+/** What the diagnostics channel receives when an operation interceptor calls `next()` twice. */
+export declare class AvInterceptorNextError extends Error {
+    readonly name = "AvInterceptorNextError";
+    constructor();
+}

package/dist/runtime/interceptor-next.error.js

@@ -0,0 +1,6 @@
+export class AvInterceptorNextError extends Error {
+    name = "AvInterceptorNextError";
+    constructor() {
+        super("An interceptor called next() more than once; next() runs the operation once.");
+    }
+}

package/dist/runtime/json-value.d.ts

@@ -1,7 +1,7 @@
 /**
  * A JSON value: the form of the `json` scalar, in arguments and results.
  *
- * A `Date`, a `bigint`, a `Uint8Array`, a {@link Decimal}, any other class
+ * A `Date`, a `bigint`, a `Uint8Array`, a {@link AvDecimal}, any other class
  * instance and an `undefined` property are refused (`V1001`), as are a
  * non-finite `number` (`V1004`) and a cycle (`V1001`).
  *
@@ -10,6 +10,6 @@
  * A `json` field's value is this without its top-level `null`: a field-level
  * `null` is the field's absence, which only `nullable: true` admits.
  */
-export type JsonValue = string | number | boolean | null | readonly JsonValue[] | {
-    readonly [key: string]: JsonValue;
+export type AvJsonValue = string | number | boolean | null | readonly AvJsonValue[] | {
+    readonly [key: string]: AvJsonValue;
 };

package/dist/runtime/level-lifecycle.runtime.d.ts

@@ -0,0 +1,25 @@
+/** One level's lifecycle registrations, as an operation or a transaction level holds them. */
+export type LifecycleLevel<Context> = {
+    readonly hooks: {
+        readonly before: readonly ((context: Context) => unknown)[];
+        readonly after: readonly ((result: unknown, context: Context) => unknown)[];
+    };
+    readonly interceptors: readonly ((context: Context, next: () => Promise<unknown>) => Promise<unknown>)[];
+};
+/**
+ * The record of a `next()` called more than once: the first refusal, kept so a
+ * caller can refuse the whole call even when the interceptor swallowed it.
+ */
+export type NextReuse<Refusal extends Error = Error> = {
+    refusal: Refusal | undefined;
+};
+/**
+ * Runs `levels`' lifecycle around `inner`: every interceptor, outer to inner,
+ * around every before hook, `inner`, and every after hook. `settle` turns what
+ * `inner` or an interceptor below resolved into what the stage above sees (the
+ * operation read-materializes it). An after hook is told a deep-frozen copy of
+ * the result; the result itself goes on to the interceptors, which may answer a
+ * different one. Every `next()` is single use: a second call rejects with
+ * `refuse()`'s error, recorded in `reuse`, and runs nothing.
+ */
+export declare function runLevelLifecycle<Context, Refusal extends Error>(levels: readonly LifecycleLevel<Context>[], context: () => Context, inner: () => Promise<unknown>, settle: (result: unknown) => Promise<unknown>, reuse: NextReuse<Refusal>, refuse: () => Refusal): Promise<unknown>;