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

package/dist/runtime/create-requirement.js

@@ -1,6 +1,6 @@
 import { lookupField, lookupResource } from "../contracts/contract-lookup.js";
 import { advertisedDirectivesAt } from "../contracts/field.js";
-import { NESTED_WRITE_SCOPE, resolveWriteScope, } from "../operations/write-scope.resolver.js";
+import { LOOPBACK_WRITE_SCOPE, NESTED_WRITE_SCOPE, resolveWriteScope, } from "../operations/write-scope.resolver.js";
 import { isRelationMutationDirective, RELATION_MUTATION_RECORD_SITES, } from "./mutation-planner.js";
 function isRecord(value) {
     return value !== null && typeof value === "object" && !Array.isArray(value);
@@ -13,7 +13,7 @@ function edgesOf(table, resource) {
     return Array.isArray(listed) ? listed : [];
 }
 function referencesOf(edge) {
-    return Array.isArray(edge.references) ? edge.references : [];
+    return Array.isArray(edge.referenceFields) ? edge.referenceFields : [];
 }
 function creatableScalar(contract, resource, field) {
     const found = lookupField(lookupResource(contract, resource), field);
@@ -63,9 +63,19 @@ function checkCreateRecord(context, resource, record, path, scope, via) {
     if (!isRecord(record)) {
         return;
     }
+    if (context.computed !== undefined) {
+        computedRequirementGaps(context, resource, record, path, via);
+        walkNestedCreates(context, resource, record, path);
+        return;
+    }
     const { contract, issues } = context;
-    const conflicted = referenceConflicts(context, resource, record, path);
-    mixedReferenceWrites(context, resource, record, path, conflicted);
+    const looped = loopbackWrites(context, resource, record, path, via, "create");
+    const conflicted = looped.size > 0
+        ? looped
+        : referenceConflicts(context, resource, record, path);
+    if (looped.size === 0) {
+        mixedReferenceWrites(context, resource, record, path, conflicted);
+    }
     const requirements = requirementsOf(contract, resource);
     if (requirements !== undefined) {
         const supplied = suppliedThrough(requirements, via);
@@ -157,14 +167,93 @@ function mixedReferenceWrites(context, resource, record, path, conflicted) {
         });
     }
 }
-function checkUpdateRecord(context, resource, record, path) {
+function checkUpdateRecord(context, resource, record, path, via) {
     if (!isRecord(record)) {
         return;
     }
-    const conflicted = referenceConflicts(context, resource, record, path);
-    mixedReferenceWrites(context, resource, record, path, conflicted);
+    if (context.computed === undefined &&
+        loopbackWrites(context, resource, record, path, via, "update").size === 0) {
+        const conflicted = referenceConflicts(context, resource, record, path);
+        mixedReferenceWrites(context, resource, record, path, conflicted);
+    }
     walkNestedCreates(context, resource, record, path);
 }
+function loopbackWrites(context, resource, record, path, via, stage) {
+    const refused = new Set();
+    if (via === undefined) {
+        return refused;
+    }
+    const { contract } = context;
+    const edge = lookupField(lookupResource(contract, via.resource), via.relation);
+    if (edge?.kind !== "relation" || typeof edge.inverse !== "string") {
+        return refused;
+    }
+    const inverse = edge.inverse;
+    const other = lookupField(lookupResource(contract, resource), inverse);
+    if (other?.kind === "relation" &&
+        advertisedDirectivesAt(other.capabilities[stage], LOOPBACK_WRITE_SCOPE) !==
+            undefined) {
+        return refused;
+    }
+    const references = edgesOf(context.references, resource).find((candidate) => candidate.field === inverse) ?? undefined;
+    for (const field of [
+        inverse,
+        ...(references === undefined ? [] : referencesOf(references)),
+    ]) {
+        if (!written(record, field)) {
+            continue;
+        }
+        refused.add(field);
+        context.issues.push({
+            code: "V1012",
+            path: [...path, field],
+            message: field === inverse
+                ? `Relation "${field}" is the relation this ${resource} is written through, from its other end ("${via.resource}.${via.relation}"): the write it sits in supplies it.`
+                : `Field "${field}" holds the reference of "${inverse}", the relation this ${resource} is written through ("${via.resource}.${via.relation}"): the write it sits in supplies it.`,
+        });
+    }
+    return refused;
+}
+function computedRequirementGaps(context, resource, record, path, via) {
+    const reader = context.computed;
+    const computed = reader?.computed(resource);
+    const stated = reader?.stated(resource);
+    if (computed === undefined || computed.size === 0 || stated === undefined) {
+        return;
+    }
+    const supplied = suppliedThrough(stated, via);
+    const gap = (field) => {
+        context.gaps?.push({
+            resource,
+            field,
+            issue: {
+                code: "V1000",
+                path: [...path, field],
+                message: `compute.create on ${resource}.${field} returned undefined for a required field.`,
+            },
+        });
+    };
+    for (const field of namesOf(stated.required)) {
+        if (computed.has(field) &&
+            !supplied.has(field) &&
+            !written(record, field)) {
+            gap(field);
+        }
+    }
+    const groups = Array.isArray(stated.oneOf) ? stated.oneOf : [];
+    for (const group of groups) {
+        const [relation, ...references] = namesOf(group);
+        const left = references.find((field) => computed.has(field) && !written(record, field));
+        if (relation === undefined ||
+            left === undefined ||
+            supplied.has(relation) ||
+            references.some((field) => supplied.has(field)) ||
+            written(record, relation)) {
+            continue;
+        }
+        gap(left);
+    }
+}
 function walkNestedCreates(context, resource, record, path) {
     if (!isRecord(record)) {
         return;
@@ -196,7 +285,7 @@ function walkNestedCreates(context, resource, record, path) {
                         checkCreateRecord(context, field.target, siteRecord, sitePath, NESTED_WRITE_SCOPE, via);
                     }
                     else {
-                        checkUpdateRecord(context, field.target, siteRecord, sitePath);
+                        checkUpdateRecord(context, field.target, siteRecord, sitePath, via);
                     }
                 }
             }
@@ -204,17 +293,43 @@ function walkNestedCreates(context, resource, record, path) {
     }
 }
 export function recordWriteFactsOf(adapter) {
-    return { references: adapter.referentialActions ?? {} };
+    const resources = adapter.model?.resources ?? {};
+    return {
+        references: adapter.referentialActions ?? {},
+        stated: (resource) => {
+            const found = Object.hasOwn(resources, resource)
+                ? resources[resource]
+                : undefined;
+            const stated = isRecord(found) ? found.createRequirements : undefined;
+            return isRecord(stated) ? stated : undefined;
+        },
+    };
 }
 export function createRequirementIssues(contract, facts, request, args, argumentsPath) {
-    if (!isRecord(args)) {
-        return [];
-    }
     const context = {
         contract,
         references: facts.references,
         issues: [],
     };
+    walkOperation(context, request, args, argumentsPath);
+    return context.issues;
+}
+export function computedRequirementGapsOf(contract, facts, request, args, argumentsPath, computed) {
+    const gaps = [];
+    walkOperation({
+        contract,
+        references: facts.references,
+        issues: [],
+        computed: { stated: facts.stated, computed },
+        gaps,
+    }, request, args, argumentsPath);
+    return gaps;
+}
+function walkOperation(context, request, args, argumentsPath) {
+    if (!isRecord(args)) {
+        return;
+    }
+    const contract = context.contract;
     const scope = resolveWriteScope(lookupResource(contract, request.resource), request);
     if (request.family === "create" && written(args, "data")) {
         const data = args.data;
@@ -229,16 +344,9 @@ export function createRequirementIssues(contract, facts, request, args, argument
     }
     if (request.family === "upsert") {
         checkCreateRecord(context, request.resource, args.create, [...argumentsPath, "create"], scope, undefined);
-        checkUpdateRecord(context, request.resource, args.update, [
-            ...argumentsPath,
-            "update",
-        ]);
+        checkUpdateRecord(context, request.resource, args.update, [...argumentsPath, "update"], undefined);
     }
     if (request.family === "update") {
-        checkUpdateRecord(context, request.resource, args.data, [
-            ...argumentsPath,
-            "data",
-        ]);
+        checkUpdateRecord(context, request.resource, args.data, [...argumentsPath, "data"], undefined);
     }
-    return context.issues;
 }

package/dist/runtime/decimal.d.ts

@@ -12,3 +12,17 @@ export declare class AvDecimal {
      */
     toJSON(): string;
 }
+/**
+ * Whether `value` is an `AvDecimal`, made by this copy of core or by another of
+ * its major: one `in`, for the hot paths that ask about every value.
+ */
+export declare function isAvDecimal(value: unknown): value is AvDecimal;
+/**
+ * The digits of `value`, read without running anything the caller could have put
+ * on it when this copy made it. Another copy's decimal is read through its own
+ * `toString`, which only that copy can answer; what it returns is checked as a
+ * decimal string, so the caller's copy keeps the grammar.
+ *
+ * @throws TypeError when another copy's decimal does not answer a decimal string.
+ */
+export declare function decimalDigitsOf(value: AvDecimal): string;

package/dist/runtime/decimal.js

@@ -1,6 +1,11 @@
 import { WIRE_SCALAR_PATTERNS } from "../contracts/wire-scalar-format.js";
+import { brandCoreClass, hasCoreBrand } from "./core-class.brand.js";
+let ownDigitsOf;
 export class AvDecimal {
     #value;
+    static {
+        ownDigitsOf = (value) => (#value in value ? value.#value : undefined);
+    }
     constructor(value) {
         if (typeof value !== "string") {
             throw new TypeError("Decimal value must be a string.");
@@ -17,3 +22,19 @@ export class AvDecimal {
         return this.#value;
     }
 }
+const DECIMAL_BRAND = brandCoreClass(AvDecimal, "AvDecimal");
+export function isAvDecimal(value) {
+    return hasCoreBrand(value, DECIMAL_BRAND);
+}
+export function decimalDigitsOf(value) {
+    const own = ownDigitsOf(value);
+    if (own !== undefined) {
+        return own;
+    }
+    const digits = value.toString();
+    if (typeof digits !== "string" ||
+        !WIRE_SCALAR_PATTERNS.decimal.test(digits)) {
+        throw new TypeError("Decimal value must be a valid decimal string.");
+    }
+    return digits;
+}

package/dist/runtime/diagnostics-reporter.d.ts

@@ -1,7 +1,7 @@
 import type { AvRequestOrigin } from "../config/config-layer.js";
 import type { AvOperationFamily } from "../operations/operation-identity.js";
-import type { FrameworkTransactionRequest } from "../transactions/transaction-request.js";
-import type { FrameworkOperationRequest } from "./operation-request.js";
+import type { AvTransactionRequest } from "../transactions/transaction-request.js";
+import type { AvOperationRequest } from "./operation-request.js";
 import { type AvOperationErrorCode, type AvOperationFailureResponse } from "./operation-response.js";
 /**
  * One unplanned failure of an operation: the raw error, the code the caller
@@ -47,7 +47,8 @@ export type AvTransactionDiagnostic = {
 };
 /**
  * One unplanned failure of the MCP endpoint itself, outside any tool call's
- * operation: the raw error, answered `500` with no detail.
+ * operation: the raw error, answered `500` with no detail, or `401` when it is
+ * the throw of `mcp.authorization.verify`.
  */
 export type AvMcpDiagnostic = {
     readonly kind: "mcp";
@@ -62,8 +63,40 @@ export type AvMcpDiagnostic = {
     /** Never present: only an operation diagnostic is marked `deliberate`. */
     readonly deliberate?: never;
 };
-/** One diagnostic: of an operation, of a transaction as a whole, or of the MCP endpoint. */
-export type AvDiagnostic = AvOperationDiagnostic | AvTransactionDiagnostic | AvMcpDiagnostic;
+/**
+ * One unplanned failure of a `POST /_access/can` request: the raw error, the
+ * code the caller received, and, when one question met it, that question's
+ * index (`question`), Resource and action; none of the three when the batch
+ * as a whole failed.
+ */
+export type AvCanDiagnostic = {
+    readonly kind: "can";
+    readonly error: unknown;
+    readonly code: AvOperationErrorCode;
+    /** The route is the clients': an agent has no `can` route. */
+    readonly origin: "client";
+    readonly requestId: string;
+    /** Never present: no operation of a plan is involved (see `question`). */
+    readonly operation?: never;
+    /** Never present: only an operation diagnostic is marked `deliberate`. */
+    readonly deliberate?: never;
+} & ({
+    /** The index of the question in `questions` the failure is blamed on. */
+    readonly question: number;
+    /** That question's Resource. */
+    readonly resource: string;
+    /** That question's action. */
+    readonly action: "read" | "create" | "update" | "delete";
+} | {
+    readonly question?: never;
+    readonly resource?: never;
+    readonly action?: never;
+});
+/**
+ * One diagnostic: of an operation, of a transaction as a whole, of a `can`
+ * request, or of the MCP endpoint.
+ */
+export type AvDiagnostic = AvOperationDiagnostic | AvTransactionDiagnostic | AvCanDiagnostic | AvMcpDiagnostic;
 /**
  * Receives a diagnostic for every unplanned failure. Set once, as the root
  * configuration's `diagnostics`.
@@ -80,8 +113,10 @@ export type DiagnosticMarks = Pick<AvOperationDiagnostic, "deliberate">;
 /** The identifying half of a diagnostic, captured once per request. */
 type OperationDiagnosticIdentity = Omit<AvOperationDiagnostic, "error" | "code">;
 type TransactionDiagnosticIdentity = Omit<AvTransactionDiagnostic, "error" | "code">;
+/** A `can` request's identity: its batch's, or one question's. */
+type CanDiagnosticIdentity = AvCanDiagnostic extends infer Diagnostic ? Diagnostic extends unknown ? Omit<Diagnostic, "error" | "code"> : never : never;
 /** The diagnostics channel bound to one diagnostic identity. */
-export declare function createReporter(sink: AvDiagnosticsSink | undefined, identity: OperationDiagnosticIdentity | TransactionDiagnosticIdentity): DiagnosticsReporter;
+export declare function createReporter(sink: AvDiagnosticsSink | undefined, identity: OperationDiagnosticIdentity | TransactionDiagnosticIdentity | CanDiagnosticIdentity): DiagnosticsReporter;
 /**
  * The MCP endpoint's failure channel for `framework`: each call reports one
  * {@link AvMcpDiagnostic} to its configured sink, under a minted request id, and
@@ -99,14 +134,14 @@ export declare function diagnosticsSinkOf(framework: object): AvDiagnosticsSink
  * Binds the configured sink to one operation request. The sink is not awaited,
  * and nothing it throws or rejects with reaches the response.
  */
-export declare function createDiagnosticsReporter(sink: AvDiagnosticsSink | undefined, request: FrameworkOperationRequest, operation?: number): DiagnosticsReporter;
+export declare function createDiagnosticsReporter(sink: AvDiagnosticsSink | undefined, request: AvOperationRequest, operation?: number): DiagnosticsReporter;
 /** The diagnostics channel of one transaction request. */
 export type TransactionDiagnosticsChannel = {
     /** A plan-level report; `operation` attributes it to a recorded failing index. */
     readonly transaction: (operation?: number) => DiagnosticsReporter;
     /** A report carrying one plan operation's own identity and index. */
-    readonly operation: (request: FrameworkOperationRequest, operation: number) => DiagnosticsReporter;
+    readonly operation: (request: AvOperationRequest, operation: number) => DiagnosticsReporter;
 };
 /** Binds the configured sink to one transaction request and its plan operations. */
-export declare function createTransactionDiagnosticsChannel(sink: AvDiagnosticsSink | undefined, request: FrameworkTransactionRequest): TransactionDiagnosticsChannel;
+export declare function createTransactionDiagnosticsChannel(sink: AvDiagnosticsSink | undefined, request: AvTransactionRequest): TransactionDiagnosticsChannel;
 export {};

package/dist/runtime/diagnostics-reporter.js

@@ -1,3 +1,4 @@
+import { coreBrandOf } from "./core-class.brand.js";
 import { internalFailure, } from "./operation-response.js";
 import { requestIdOf } from "./request-id.js";
 const IGNORE_DIAGNOSTIC = () => undefined;
@@ -31,7 +32,18 @@ export function createReporter(sink, identity) {
         }
     };
 }
-const CONFIGURED_SINKS = new WeakMap();
+const CONFIGURED_SINKS = sharedSinkRegistry();
+function sharedSinkRegistry() {
+    const key = coreBrandOf("diagnostics");
+    const holder = globalThis;
+    const existing = holder[key];
+    if (existing instanceof WeakMap) {
+        return existing;
+    }
+    const registry = new WeakMap();
+    Object.defineProperty(holder, key, { value: registry });
+    return registry;
+}
 export function mcpFailureReporterOf(framework) {
     const sink = CONFIGURED_SINKS.get(framework);
     return (error) => {

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

@@ -3,7 +3,7 @@ import { AvError } from "./framework-error.js";
 import type { AvCause, AvOperationErrorCode, AvOperationFailureResponse } from "./operation-response.js";
 import type { AvContext } from "./pipeline.js";
 /** Where an unexpected post-validation exception originated. */
-export type FailureOrigin = "adapter" | "runtime";
+type FailureOrigin = "adapter" | "runtime";
 /** The one generic Adapter-failure text; every unexpected A3001 carries it. */
 export declare const ADAPTER_FAILURE_MESSAGE = "Adapter execution failed.";
 /** One boundary instance belongs to one operation execution. */
@@ -50,6 +50,13 @@ type DeliberateOutcome = {
      */
     readonly unvouched: readonly unknown[];
 };
+/**
+ * The refusal code `error` deliberately carries, vetted as every boundary vets
+ * it ({@link vetDeliberateOutcome}): a recognised error code that is no
+ * internal (`A3xxx`) one, with a well-formed cause. `undefined` for anything
+ * else, which the caller answers as the defect it is.
+ */
+export declare function deliberateRefusalCode(error: unknown): AvOperationErrorCode | undefined;
 /**
  * Final framework sanitization, shared by every boundary. A deliberate
  * {@link AvError} carries its own stable outcome; anything else is
@@ -100,7 +107,7 @@ export declare function resolveUnhandledFailure(failure: UnhandledFailure, chain
  * A chain of filters and the context they are told, tried in reverse: the first
  * that returns an {@link AvError} handles the error.
  */
-export type FilterChain = {
+type FilterChain = {
     readonly attempt: (error: unknown, view: CallerArgumentsView, boundary: AdapterBoundary) => Promise<FilteredOutcome | undefined>;
 };
 /** The chain of `filters` (stored outer to inner, tried in reverse), told `context`. */

package/dist/runtime/error-boundary.js

@@ -1,3 +1,4 @@
+import { isDatabaseRefusalMessage } from "../operations/database-refusal.js";
 import { VALIDATION_CODE_MESSAGES, VALIDATION_CODES, } from "../operations/validation-code.js";
 import { AvError } from "./framework-error.js";
 import { INTERNAL_FAILURE_MESSAGE, internalFailure, OPERATION_CODES, operationFailure, } from "./operation-response.js";
@@ -164,6 +165,9 @@ function projectIssue(value, unvouched, view, author) {
             unvouched.push(supplied);
         }
     }
+    else if (isDatabaseRefusalMessage(code, supplied)) {
+        message = supplied;
+    }
     if (rawPath === undefined) {
         return { code, message };
     }
@@ -238,6 +242,14 @@ function vetDeliberateOutcome(error, view, author) {
     const cause = projectCause(rawCause, unvouched, view, author);
     return cause === undefined ? MALFORMED_OUTCOME : { code, cause, unvouched };
 }
+export function deliberateRefusalCode(error) {
+    const outcome = vetDeliberateOutcome(error, { path: [], arguments: undefined }, "developer");
+    return outcome === undefined ||
+        outcome === MALFORMED_OUTCOME ||
+        isInternalCode(outcome.code)
+        ? undefined
+        : outcome.code;
+}
 function reportUnvouched(outcome, report) {
     for (const value of outcome.unvouched) {
         report(value, outcome.code);

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

@@ -0,0 +1,12 @@
+/** Why a code is answered, and what the one who meets it should do. */
+export type ErrorCodeGuidance = {
+    /** What typically produced the code, in a sentence or two. */
+    readonly cause: string;
+    /** What to change so it does not happen again. */
+    readonly fix: string;
+};
+/** Guidance for a code whose table holds no message of its own. */
+export type ErrorCodeDescription = ErrorCodeGuidance & {
+    /** The code's meaning, in one short sentence. */
+    readonly message: string;
+};

package/dist/runtime/error-guidance.js

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

package/dist/runtime/error.catalog.d.ts

@@ -0,0 +1,49 @@
+import type { AvAdapterDiscoveryDiagnosticCode } from "../adapters/adapter-discovery-diagnostic.js";
+import type { AvContractCompilerDiagnosticCode } from "../compiler/contract-compiler-diagnostic.js";
+import type { AvConfigDiagnosticCode } from "../config/config-diagnostic.js";
+import type { AvConstructionStage } from "../framework/framework-construction.error.js";
+import { type AvValidationCode } from "../operations/validation-code.js";
+import { type AvOperationCode } from "./operation-response.js";
+/**
+ * The documentation page every catalog entry links into. Each code has its own
+ * anchor there: the code in lower case (`#a2004`, `#config_required`).
+ */
+export declare const ERROR_CODES_DOCS_URL = "https://aventara-framework.vercel.app/docs/error-codes";
+/**
+ * What kind of code an entry is: an outcome code's family (`success` `A1xxx`,
+ * `request` `A2xxx`, `internal` `A3xxx`, `auth` `A4xxx`), a `validation` issue
+ * code (`V1xxx`), or a startup code, by the construction stage that reports it.
+ */
+export type AvErrorKind = "success" | "request" | "internal" | "auth" | "validation" | AvConstructionStage;
+/** Every code the catalog describes: outcome, validation and startup codes. */
+export type AvErrorCatalogCode = AvOperationCode | AvValidationCode | AvConfigDiagnosticCode | AvAdapterDiscoveryDiagnosticCode | AvContractCompilerDiagnosticCode;
+/** One code: what it means, why it happens, what to do, and where it is documented. */
+export type AvErrorCatalogEntry<C extends AvErrorCatalogCode = AvErrorCatalogCode> = {
+    readonly code: C;
+    readonly kind: AvErrorKind;
+    /** Its meaning in one sentence; for a V-code, the framework's message for it. */
+    readonly message: string;
+    /** What typically produces it. */
+    readonly cause: string;
+    /** What to change. */
+    readonly fix: string;
+    /** Its entry on the error-codes page. */
+    readonly docs: string;
+};
+/** The error catalog's type: one entry per code. */
+export type AvErrorCatalog = {
+    readonly [C in AvErrorCatalogCode]: AvErrorCatalogEntry<C>;
+};
+/** The documentation URL of one code: the error-codes page at its anchor. */
+export declare function errorDocsUrl(code: AvErrorCatalogCode): string;
+/**
+ * Every code Aventara answers or refuses with, by code: its `kind`, `message`,
+ * `cause`, `fix` and `docs` URL. An operation's `code`, a validation issue's
+ * `code` and a startup diagnostic's `code` are all keys of it:
+ *
+ * ```ts
+ * AvErrorCatalog[error.code].fix;
+ * AvErrorCatalog.V1000.docs; // https://aventara-framework.vercel.app/docs/error-codes#v1000
+ * ```
+ */
+export declare const AvErrorCatalog: AvErrorCatalog;

package/dist/runtime/error.catalog.js

@@ -0,0 +1,49 @@
+import { ADAPTER_DISCOVERY_DIAGNOSTIC_GUIDANCE } from "../adapters/adapter-discovery-diagnostic.guidance.js";
+import { CONTRACT_COMPILER_DIAGNOSTIC_GUIDANCE } from "../compiler/contract-compiler-diagnostic.guidance.js";
+import { CONFIG_DIAGNOSTIC_GUIDANCE } from "../config/config-diagnostic.guidance.js";
+import { VALIDATION_CODE_GUIDANCE } from "../operations/validation-code.guidance.js";
+import { VALIDATION_CODE_MESSAGES, VALIDATION_CODES, } from "../operations/validation-code.js";
+import { OPERATION_CODE_GUIDANCE } from "./operation-code.guidance.js";
+import { OPERATION_CODES } from "./operation-response.js";
+export const ERROR_CODES_DOCS_URL = "https://aventara-framework.vercel.app/docs/error-codes";
+export function errorDocsUrl(code) {
+    return `${ERROR_CODES_DOCS_URL}#${code.toLowerCase()}`;
+}
+const OUTCOME_KIND = {
+    "1": "success",
+    "2": "request",
+    "3": "internal",
+    "4": "auth",
+};
+function entry(code, kind, description) {
+    return Object.freeze({
+        code,
+        kind,
+        message: description.message,
+        cause: description.cause,
+        fix: description.fix,
+        docs: errorDocsUrl(code),
+    });
+}
+function entriesOf(table, kind) {
+    return Object.keys(table).map((code) => [
+        code,
+        entry(code, kind, table[code]),
+    ]);
+}
+export const AvErrorCatalog = Object.freeze(Object.fromEntries([
+    ...OPERATION_CODES.map((code) => [
+        code,
+        entry(code, OUTCOME_KIND[code[1]], OPERATION_CODE_GUIDANCE[code]),
+    ]),
+    ...VALIDATION_CODES.map((code) => [
+        code,
+        entry(code, "validation", {
+            message: VALIDATION_CODE_MESSAGES[code],
+            ...VALIDATION_CODE_GUIDANCE[code],
+        }),
+    ]),
+    ...entriesOf(CONFIG_DIAGNOSTIC_GUIDANCE, "configuration"),
+    ...entriesOf(ADAPTER_DISCOVERY_DIAGNOSTIC_GUIDANCE, "discovery"),
+    ...entriesOf(CONTRACT_COMPILER_DIAGNOSTIC_GUIDANCE, "contract-compilation"),
+]));

package/dist/runtime/execution-options.d.ts

@@ -18,4 +18,12 @@ export type AvExecutionOptions = {
      * object), the Framework starts the request with `{}`.
      */
     readonly state?: AvState & object;
+    /**
+     * The principal the call or run is checked as by the configuration's
+     * `policy`. An application call names one to opt in: left out, it is server
+     * code and the policy does not check it. A `framework.client.*` call is
+     * checked either way, and `as` replaces the principal `policy.principal`
+     * would derive from its state. `null` is the anonymous principal.
+     */
+    readonly as?: unknown;
 };

package/dist/runtime/field-check.evaluator.d.ts

@@ -24,6 +24,4 @@ export declare function fieldCheckIssue(check: AvFieldCheck, subject: FieldCheck
 export declare function fieldCheckIssues(checks: readonly AvFieldCheck[], value: unknown, subject: FieldCheckSubject, path: Path, list: boolean): readonly AvValidationIssue[];
 /** The issues of the checks one value — a whole value, or a list's entry — breaks. */
 export declare function entryCheckIssues(checks: readonly AvFieldCheck[], value: unknown, subject: FieldCheckSubject, path: Path): readonly AvValidationIssue[];
-/** Whether a check judges a list's own length (`AvZ.minItems`/`AvZ.maxItems`). */
-export declare function isListCheck(check: AvFieldCheck): boolean;
 export {};

package/dist/runtime/field-check.evaluator.js

@@ -515,7 +515,7 @@ export function entryCheckIssues(checks, value, subject, path) {
     }
     return issues;
 }
-export function isListCheck(check) {
+function isListCheck(check) {
     return ((check.check === "max_length" || check.check === "min_length") &&
         check.list === true);
 }

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

@@ -17,26 +17,27 @@ export type AvComputeContext<M extends AvAdapterModel = AvAdapterModel> = AvComp
     readonly $state: AvDeepReadonly<AvState>;
 };
 /**
- * What a write-stage compute callback is told about the field it is computing.
+ * 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.
  */
-type ComputedWriteContext<M extends AvAdapterModel> = {
+export type AvComputeCreate<M extends AvAdapterModel = AvAdapterModel> = (context: {
     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>;
+}) => 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>;
+export type AvComputeUpdate<M extends AvAdapterModel = AvAdapterModel> = (context: {
+    readonly field: string;
+    readonly value: unknown;
+    readonly data: Readonly<Record<string, unknown>>;
+    readonly ctx: AvComputeContext<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.

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

@@ -6,13 +6,15 @@ 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 containers a family writes, by argument key. */
+export declare const WRITE_KEYS: Readonly<Partial<Record<AvOperationFamily, readonly string[]>>>;
 /** 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 = {
+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;