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

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

@@ -0,0 +1,147 @@
+import { frozenCopy } from "./readonly-value.js";
+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;
+}
+export 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 told = frozenCopy(value);
+                const next = await pipe(told);
+                if (next !== undefined) {
+                    if (next !== told) {
+                        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(frozenCopy(record[field]), told)) === false) {
+                    return false;
+                }
+            }
+        }
+    }
+    return true;
+}

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

@@ -0,0 +1,29 @@
+import type { AvContract } from "../contracts/contract.js";
+import type { AvValidationIssue } from "../operations/validation-code.js";
+import { AvComputedValueError } from "./computed-value.error.js";
+import { type Path } from "./field-stage.runtime.js";
+import type { OperationExecutionRequest } from "./operation-request.js";
+import type { ReferentialActionTable } from "./referential-action.js";
+/** The write phase of a record: a created row (an upsert's `create` branch too) or an updated one. */
+type WriteStage = "create" | "update";
+/**
+ * The fields a judgment leaves for later: a plan step's (or a forced call's)
+ * literal values are judged before BEGIN, except a field a write compute stage
+ * of that phase may still change, which is judged after write compute.
+ */
+type DeferredField = (resource: string, stage: WriteStage, field: string) => boolean;
+/**
+ * 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, deferred?: DeferredField): readonly AvValidationIssue[];
+/**
+ * The server's defect when a value written to a field the active layer hides
+ * breaks its validators or its Json shape, or `undefined`.
+ */
+export declare function hiddenFieldRefusal(contracts: {
+    readonly core: AvContract;
+    readonly active: AvContract;
+}, references: ReferentialActionTable, request: OperationExecutionRequest, args: unknown, argumentsPath: Path): AvComputedValueError | undefined;
+export {};

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

@@ -0,0 +1,126 @@
+import { hasFieldValidators, validatedFieldsOf, } from "../compiler/field-validator.compiler.js";
+import { AvComputedValueError } from "./computed-value.error.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 === undefined) {
+        return 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, deferred) {
+    const compiled = validatedFieldsOf(contract, resource);
+    const issues = [];
+    for (const { path, stage } 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 || deferred?.(resource, stage, name) === true) {
+                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, deferred) {
+    const issues = recordIssues(contract, request.resource, writeRecordPathsOf(request.family, args).map((path) => ({
+        path,
+        stage: request.family === "create" || path[0] === "create"
+            ? "create"
+            : "update",
+    })), args, argumentsPath, select, deferred);
+    for (const target of nestedWriteTargetsOf(contract, references, request, args)) {
+        issues.push(...recordIssues(contract, target.resource, target.records, args, argumentsPath, select, deferred));
+    }
+    return issues;
+}
+function holdsField(contract, resource, field) {
+    const fields = Object.hasOwn(contract.resources, resource)
+        ? contract.resources[resource]?.fields
+        : undefined;
+    return fields !== undefined && Object.hasOwn(fields, field);
+}
+export function hiddenFieldRefusal(contracts, references, request, args, argumentsPath) {
+    const { core, active } = contracts;
+    if (core === active || !hasFieldValidators(core)) {
+        return undefined;
+    }
+    const judged = [];
+    const issues = fieldValidatorIssues(core, references, request, args, argumentsPath, () => true, (resource, stage, field) => {
+        if (holdsField(active, resource, field)) {
+            return true;
+        }
+        judged.push({ resource, stage, field });
+        return false;
+    });
+    const [first] = issues;
+    if (first === undefined) {
+        return undefined;
+    }
+    const path = first.path ?? [];
+    const at = judged.find(({ field }) => path.includes(field)) ?? judged[0];
+    if (at === undefined) {
+        return undefined;
+    }
+    return new AvComputedValueError(at.resource, at.field, at.stage, issues, `compute.${at.stage} on ${at.resource}.${at.field}, a field the ${request.origin} layer hides, returned a value its validators refuse (${first.code}: ${first.message})`);
+}

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,41 @@
-export class FrameworkError extends Error {
+import { brandCoreClass } from "./core-class.brand.js";
+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";
+}
+brandCoreClass(AvError, "AvError");
+brandCoreClass(AvValidationError, "AvValidationError");
+brandCoreClass(AvNotFoundError, "AvNotFoundError");
+brandCoreClass(AvConflictError, "AvConflictError");
+brandCoreClass(AvAuthError, "AvAuthError");
+brandCoreClass(AvInternalError, "AvInternalError");
+brandCoreClass(AvProtocolError, "AvProtocolError");
+brandCoreClass(AvContractMismatchError, "AvContractMismatchError");

package/dist/runtime/framework-warning.emitter.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Emits a framework warning: through `process.emitWarning` (type
+ * `AventaraWarning`, `code` as given) where the runtime has it, else through
+ * `console.warn`. A warning changes no behaviour.
+ */
+export declare function emitFrameworkWarning(message: string, code: string): void;

package/dist/runtime/framework-warning.emitter.js

@@ -0,0 +1,8 @@
+export function emitFrameworkWarning(message, code) {
+    const emitWarning = globalThis.process?.emitWarning;
+    if (typeof emitWarning === "function") {
+        emitWarning(message, { type: "AventaraWarning", code });
+        return;
+    }
+    globalThis.console?.warn(`AventaraWarning: ${message}`);
+}

package/dist/runtime/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,15 +1,20 @@
 /**
  * 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
- * instance and an `undefined` property are refused (`V1001`), as are a
- * non-finite `number` (`V1004`) and a cycle (`V1001`).
+ * A `Date`, a `bigint`, a `Uint8Array`, a {@link AvDecimal} and any other class
+ * instance are refused (`V1001`), as are a non-finite `number` (`V1004`) and a
+ * cycle (`V1001`). An `undefined` inside the value is what JSON makes of it: a key
+ * holding it is left out, an array element holding it (or a hole) is `null`. The
+ * type admits a key holding `undefined`, so an object with an optional property is
+ * a JSON value; an array element stays typed without it, as JSON has no such
+ * value.
  *
- * Results are fresh plain copies, so mutating one is safe.
+ * Results are fresh plain copies, so mutating one is safe; a result never holds a
+ * key whose value is `undefined`.
  *
  * 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 | undefined;
 };

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

@@ -0,0 +1,26 @@
+/** One level's lifecycle registrations, as an operation or a transaction level holds them. */
+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). Each after hook is told its own 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>;
+export {};

package/dist/runtime/level-lifecycle.runtime.js

@@ -0,0 +1,40 @@
+import { frozenCopy } from "./readonly-value.js";
+export async function runLevelLifecycle(levels, context, inner, settle, reuse, refuse) {
+    const once = (run) => {
+        let called = false;
+        return () => {
+            if (called) {
+                const refusal = refuse();
+                reuse.refusal ??= refusal;
+                return Promise.reject(refusal);
+            }
+            called = true;
+            return run();
+        };
+    };
+    const hooked = async () => {
+        for (const level of levels) {
+            for (const hook of level.hooks.before) {
+                await hook(context());
+            }
+        }
+        const result = await settle(await inner());
+        const after = [...levels].reverse().flatMap((level) => level.hooks.after);
+        const settled = after.length > 0 ? frozenCopy(result, true) : undefined;
+        for (const [index, hook] of after.entries()) {
+            await hook(index === after.length - 1 ? settled : frozenCopy(settled), context());
+        }
+        return result;
+    };
+    const interceptors = levels.flatMap((level) => level.interceptors);
+    let next = hooked;
+    for (let index = interceptors.length - 1; index >= 0; index -= 1) {
+        const interceptor = interceptors[index];
+        if (interceptor === undefined) {
+            continue;
+        }
+        const continuation = once(next);
+        next = () => interceptor(context(), async () => settle(await continuation()));
+    }
+    return next();
+}