@aventara/core 1.0.0-rc.0 → 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);
@@ -8,26 +8,12 @@ function isRecord(value) {
 function written(record, key) {
     return Object.hasOwn(record, key) && record[key] !== undefined;
 }
-function requirementsOf(table, resource) {
-    const listed = Object.hasOwn(table, resource) ? table[resource] : undefined;
-    return Array.isArray(listed) ? listed : [];
-}
 function edgesOf(table, resource) {
     const listed = Object.hasOwn(table, resource) ? table[resource] : undefined;
     return Array.isArray(listed) ? listed : [];
 }
 function referencesOf(edge) {
-    return Array.isArray(edge.references) ? edge.references : [];
-}
-function referenceFieldsOf(table, resource, relation) {
-    const edge = edgesOf(table, resource).find((candidate) => candidate.field === relation);
-    return edge === undefined ? [] : referencesOf(edge);
-}
-function storeSupplied(contract, resource, field) {
-    const found = lookupField(lookupResource(contract, resource), field);
-    return (found?.kind === "scalar" &&
-        (found.lifecycle.includes("DEFAULTED") ||
-            found.lifecycle.includes("GENERATED_ON_CREATE")));
+    return Array.isArray(edge.referenceFields) ? edge.referenceFields : [];
 }
 function creatableScalar(contract, resource, field) {
     const found = lookupField(lookupResource(contract, resource), field);
@@ -38,53 +24,104 @@ function creatableRelation(contract, resource, relation, scope) {
     return (found?.kind === "relation" &&
         advertisedDirectivesAt(found.capabilities.create, scope) !== undefined);
 }
+function blockedByPosition(contract, resource, relation, scope) {
+    return (scope !== NESTED_WRITE_SCOPE &&
+        creatableRelation(contract, resource, relation, NESTED_WRITE_SCOPE) &&
+        !creatableRelation(contract, resource, relation, scope));
+}
+function requirementsOf(contract, resource) {
+    const found = lookupResource(contract, resource)?.createRequirements;
+    return isRecord(found) ? found : undefined;
+}
+function namesOf(value) {
+    return Array.isArray(value)
+        ? value.filter((name) => typeof name === "string")
+        : [];
+}
+function suppliedThrough(requirements, via) {
+    if (via === undefined || !isRecord(requirements.parentSupplies)) {
+        return new Set();
+    }
+    const byRelation = Object.hasOwn(requirements.parentSupplies, via.resource)
+        ? requirements.parentSupplies[via.resource]
+        : undefined;
+    if (!isRecord(byRelation) || !Object.hasOwn(byRelation, via.relation)) {
+        return new Set();
+    }
+    return new Set(namesOf(byRelation[via.relation]));
+}
+function missingIssue(path, resource, field, relation, or = []) {
+    return {
+        code: "V1000",
+        path: [...path, field],
+        message: relation
+            ? `Relation "${field}" is required to create ${resource}${or.length > 0 ? `: write it, or ${or.map((name) => `"${name}"`).join(" and ")}` : ""}.`
+            : `Field "${field}" is required to create ${resource}.`,
+    };
+}
 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);
-    for (const requirement of requirementsOf(context.requirements, resource)) {
-        if (requirement.kind === "field") {
-            if (!written(record, requirement.field) &&
-                creatableScalar(contract, resource, requirement.field)) {
-                issues.push({
-                    code: "V1000",
-                    path: [...path, requirement.field],
-                    message: `Field "${requirement.field}" is required to create ${resource}.`,
-                });
+    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);
+        for (const field of namesOf(requirements.required)) {
+            if (supplied.has(field) || written(record, field)) {
+                continue;
+            }
+            if (creatableScalar(contract, resource, field)) {
+                issues.push(missingIssue(path, resource, field, false));
+            }
+            else if (!conflicted.has(field) &&
+                creatableRelation(contract, resource, field, scope)) {
+                issues.push(missingIssue(path, resource, field, true));
+            }
+            else if (blockedByPosition(contract, resource, field, scope)) {
+                const edge = edgesOf(context.references, resource).find((candidate) => candidate.field === field);
+                const references = edge === undefined ? [] : referencesOf(edge);
+                if (!references.some((name) => written(record, name))) {
+                    issues.push(missingIssue(path, resource, references[0] ?? field, false));
+                }
             }
-            continue;
-        }
-        if (conflicted.has(requirement.relation)) {
-            continue;
-        }
-        if (via !== undefined &&
-            requirement.inverse?.resource === via.resource &&
-            requirement.inverse.relation === via.relation) {
-            continue;
-        }
-        const orFields = referenceFieldsOf(context.references, resource, requirement.relation).filter((field) => !storeSupplied(contract, resource, field));
-        if (written(record, requirement.relation) ||
-            (orFields.length > 0 && orFields.every((field) => written(record, field)))) {
-            continue;
-        }
-        if (creatableRelation(contract, resource, requirement.relation, scope)) {
-            issues.push({
-                code: "V1000",
-                path: [...path, requirement.relation],
-                message: `Relation "${requirement.relation}" is required to create ${resource}${orFields.length > 0 ? `: write it, or ${orFields.map((field) => `"${field}"`).join(" and ")}` : ""}.`,
-            });
-            continue;
         }
-        const missing = orFields.find((field) => !written(record, field) && creatableScalar(contract, resource, field));
-        if (missing !== undefined) {
-            issues.push({
-                code: "V1000",
-                path: [...path, missing],
-                message: `Field "${missing}" is required to create ${resource}.`,
-            });
+        const groups = Array.isArray(requirements.oneOf) ? requirements.oneOf : [];
+        for (const group of groups) {
+            const [relation, ...references] = namesOf(group);
+            if (relation === undefined ||
+                references.length === 0 ||
+                conflicted.has(relation) ||
+                supplied.has(relation) ||
+                references.some((field) => supplied.has(field)) ||
+                written(record, relation) ||
+                references.every((field) => written(record, field))) {
+                continue;
+            }
+            if (creatableRelation(contract, resource, relation, scope)) {
+                issues.push(missingIssue(path, resource, relation, true, references));
+                continue;
+            }
+            const missing = references.find((field) => !written(record, field) &&
+                creatableScalar(contract, resource, field)) ??
+                (blockedByPosition(contract, resource, relation, scope)
+                    ? references.find((field) => !written(record, field))
+                    : undefined);
+            if (missing !== undefined) {
+                issues.push(missingIssue(path, resource, missing, false));
+            }
         }
     }
     walkNestedCreates(context, resource, record, path);
@@ -130,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;
@@ -169,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);
                     }
                 }
             }
@@ -177,21 +293,43 @@ function walkNestedCreates(context, resource, record, path) {
     }
 }
 export function recordWriteFactsOf(adapter) {
+    const resources = adapter.model?.resources ?? {};
     return {
-        requirements: adapter.createRequirements ?? {},
         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,
-        requirements: facts.requirements,
         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;
@@ -206,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

@@ -1,8 +1,8 @@
 /**
  * An exact decimal value, independent of any database driver's decimal class.
- * Results carry `decimal` fields as `Decimal`.
+ * Results carry `decimal` fields as `AvDecimal`.
  */
-export declare class Decimal {
+export declare class AvDecimal {
     #private;
     constructor(value: string);
     toString(): string;
@@ -12,3 +12,17 @@ export declare class Decimal {
      */
     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";
-export class Decimal {
+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 Decimal {
         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,27 +1,27 @@
-import type { RequestOrigin } from "../config/config-layer.js";
-import type { OperationFamily } from "../operations/operation-identity.js";
-import type { FrameworkTransactionRequest } from "../transactions/transaction-request.js";
-import type { FrameworkOperationRequest } from "./operation-request.js";
-import type { OperationErrorCode } from "./operation-response.js";
+import type { AvRequestOrigin } from "../config/config-layer.js";
+import type { AvOperationFamily } from "../operations/operation-identity.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
- * received, and the operation and request it happened in — or a developer's
- * deliberate internal failure, marked `deliberate`. Server-side only:
+ * received, and the operation and request it happened in. It can also be a
+ * developer's deliberate internal failure, marked `deliberate`. Server-side only:
  * diagnostics are never sent to the caller.
  */
-export type OperationDiagnostic = {
+export type AvOperationDiagnostic = {
     readonly kind: "operation";
     readonly error: unknown;
-    readonly code: OperationErrorCode;
-    readonly origin: RequestOrigin;
+    readonly code: AvOperationErrorCode;
+    readonly origin: AvRequestOrigin;
     readonly resource: string;
-    readonly family: OperationFamily;
+    readonly family: AvOperationFamily;
     readonly variant: string;
     readonly requestId: string;
     readonly operation?: number;
     /**
-     * `true` when `error` is a `FrameworkError` its thrower — a pipeline
-     * callback, a behavior, a filter or an Adapter — raised deliberately with an
+     * `true` when `error` is an `AvError` its thrower (a pipeline
+     * callback, a compute stage, a filter or an Adapter) raised deliberately with an
      * internal (`A3xxx`) code: the developer's own failure, whose message and
      * issues the caller never receives. Absent for a failure the framework did not
      * expect.
@@ -32,55 +32,116 @@ export type OperationDiagnostic = {
  * One unplanned failure of a transaction: the raw error, the code the caller
  * received, and the step it is blamed on (`operation`) when there is one.
  */
-export type TransactionDiagnostic = {
+export type AvTransactionDiagnostic = {
     readonly kind: "transaction";
     readonly error: unknown;
-    readonly code: OperationErrorCode;
-    readonly origin: RequestOrigin;
+    readonly code: AvOperationErrorCode;
+    readonly origin: AvRequestOrigin;
     readonly requestId: string;
     readonly operation?: number;
     /**
      * Never present: only an operation diagnostic is marked `deliberate`. Declared
-     * so the mark can be read on any {@link FrameworkDiagnostic}.
+     * so the mark can be read on any {@link AvDiagnostic}.
      */
     readonly deliberate?: never;
 };
-/** One diagnostic: of an operation, or of a transaction as a whole. */
-export type FrameworkDiagnostic = OperationDiagnostic | TransactionDiagnostic;
+/**
+ * One unplanned failure of the MCP endpoint itself, outside any tool call's
+ * 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";
+    readonly error: unknown;
+    /** Always `A3000`: an internal failure, with nothing more specific to say. */
+    readonly code: "A3000";
+    readonly origin: "agent";
+    /** Minted for the report: the MCP request carries no Aventara request id. */
+    readonly requestId: string;
+    /** Never present: no operation of a plan is involved. */
+    readonly operation?: never;
+    /** Never present: only an operation diagnostic is marked `deliberate`. */
+    readonly deliberate?: never;
+};
+/**
+ * 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`.
  */
-export type FrameworkDiagnosticsSink = (diagnostic: FrameworkDiagnostic) => void | Promise<void>;
+export type AvDiagnosticsSink = (diagnostic: AvDiagnostic) => void | Promise<void>;
 /**
  * The channel as the runtime holds it: bound to one request, told the raw
  * error and the code being emitted. Total by construction — it returns
  * before the sink has finished and swallows everything the sink does.
  */
-export type DiagnosticsReporter = (error: unknown, code: OperationErrorCode, marks?: DiagnosticMarks) => void;
+export type DiagnosticsReporter = (error: unknown, code: AvOperationErrorCode, marks?: DiagnosticMarks) => void;
 /** What a report states about its error beyond the code: today, whether it was deliberate. */
-export type DiagnosticMarks = Pick<OperationDiagnostic, "deliberate">;
+export type DiagnosticMarks = Pick<AvOperationDiagnostic, "deliberate">;
 /** The identifying half of a diagnostic, captured once per request. */
-type OperationDiagnosticIdentity = Omit<OperationDiagnostic, "error" | "code">;
-type TransactionDiagnosticIdentity = Omit<TransactionDiagnostic, "error" | "code">;
+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: FrameworkDiagnosticsSink | 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
+ * answers the response the caller receives instead: the generic `A3000`, which
+ * carries nothing of the error. Total: it returns before the sink has finished
+ * and swallows everything the sink does. A Framework without a sink gets a
+ * channel that observes nothing and still answers the `A3000`.
+ */
+export declare function mcpFailureReporterOf(framework: object): (error: unknown) => AvOperationFailureResponse;
 /** Records the sink `framework` was configured with; called once, at construction. */
-export declare function recordDiagnosticsSink(framework: object, sink: FrameworkDiagnosticsSink | undefined): void;
+export declare function recordDiagnosticsSink(framework: object, sink: AvDiagnosticsSink | undefined): void;
 /** The sink `framework` was configured with, or `undefined` for none. */
-export declare function diagnosticsSinkOf(framework: object): FrameworkDiagnosticsSink | undefined;
+export declare function diagnosticsSinkOf(framework: object): AvDiagnosticsSink | undefined;
 /**
  * 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: FrameworkDiagnosticsSink | 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: FrameworkDiagnosticsSink | undefined, request: FrameworkTransactionRequest): TransactionDiagnosticsChannel;
+export declare function createTransactionDiagnosticsChannel(sink: AvDiagnosticsSink | undefined, request: AvTransactionRequest): TransactionDiagnosticsChannel;
 export {};

package/dist/runtime/diagnostics-reporter.js

@@ -1,3 +1,6 @@
+import { coreBrandOf } from "./core-class.brand.js";
+import { internalFailure, } from "./operation-response.js";
+import { requestIdOf } from "./request-id.js";
 const IGNORE_DIAGNOSTIC = () => undefined;
 function isThenable(value) {
     if ((typeof value !== "object" || value === null) &&
@@ -29,7 +32,40 @@ 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) => {
+        if (sink !== undefined) {
+            try {
+                const settled = sink({
+                    kind: "mcp",
+                    error,
+                    code: "A3000",
+                    origin: "agent",
+                    requestId: requestIdOf(undefined),
+                });
+                if (isThenable(settled)) {
+                    settled.then(undefined, () => undefined);
+                }
+            }
+            catch {
+            }
+        }
+        return internalFailure();
+    };
+}
 export function recordDiagnosticsSink(framework, sink) {
     if (sink !== undefined) {
         CONFIGURED_SINKS.set(framework, sink);