@aventara/core 0.1.0-pilot.3 → 0.1.0-pilot.4

package/dist/protocol/protocol-headers.d.ts

@@ -1,21 +1,5 @@
 import type { ClientProtocolIdentity } from "../runtime/operation-request.js";
-/**
- * `AvProtocol.headers` — the header names the protocol owns, as passive data.
- *
- * - `protocolVersion`, `contractHash`: the two identity headers every
- *   generated-client resource and transaction request sends; the `_contract`
- *   request needs neither.
- * - `requestId`: the correlation header. A valid one is adopted as the request's
- *   id, an invalid one ignored, and every framework-produced response echoes it.
- *
- * Spelled as the canonical wire text. HTTP header names are case-insensitive, so a
- * reader matches them without regard to case; these spellings are what the
- * framework and the generated client SEND.
- *
- * Passive data: strings only, frozen, so a consumer — the client generator emits
- * it by value into generated source — can neither mutate it nor receive anything
- * `JSON.stringify` would drop or reshape.
- */
+/** `AvProtocol.headers` — the header names the protocol owns, as passive data. */
 export declare const headers: Readonly<{
     readonly protocolVersion: "Aventara-Protocol-Version";
     readonly contractHash: "Aventara-Contract-Hash";
@@ -24,46 +8,35 @@ export declare const headers: Readonly<{
 /** A request's headers as a host hands them over (`AvProtocolRequest.headers`). */
 type ReceivedHeaders = Readonly<Record<string, string | readonly string[] | undefined>>;
 /**
- * The request's headers as one spelling: names lower-cased, a repeated header's
- * values — a list, or one name received in several casings — joined with `", "` in
- * the order received (RFC 9110 §5.3), and an `undefined` entry or an empty list
- * dropped as absent. Values are otherwise as received. This is what a client
- * request's `transport.headers` carries to the developer's pipelines, and what
- * every header read below reads.
- *
- * Built with `Object.fromEntries`, so a header named `__proto__` stays data.
+ * The request's headers as one spelling: names lower-cased, a repeated header's values
+ * — a list, or one name received in several casings — joined with `", "` in the order
+ * received, and an `undefined` entry or an empty list dropped as absent. Values are
+ * otherwise as received. This is what a client request's `transport.headers` carries
+ * to the developer's pipelines, and what every header read below reads.
  */
 export declare function normalizeHeaders(received: ReceivedHeaders): Readonly<Record<string, string>>;
 /**
- * One header's value as the framework reads it, from {@link normalizeHeaders}'
- * output: surrounding spaces and tabs are not part of a field value (RFC 9110
- * §5.5), so they are removed. `undefined` when the header is absent.
+ * One header's value as the framework reads it, from {@link normalizeHeaders}' output:
+ * surrounding spaces and tabs are not part of a field value, so they are removed.
+ * `undefined` when the header is absent.
  */
 export declare function headerValue(normalized: Readonly<Record<string, string>>, name: string): string | undefined;
 /**
  * The identity headers as the `ClientProtocolIdentity` core checks, or `undefined`
- * when either is ABSENT — a request without them is malformed: it does not say
- * which protocol and ClientContract it speaks, so there is nothing to compare.
- *
- * Present values are read, never judged: whether they match is the Framework
- * Validation Layer's call (cross-phase invariant 13), made by core's one
- * stale-client check. A present version that is not a decimal integer (no sign, no
- * leading zero) reads as `NaN`, so it cannot match (`A2006`); a present hash is
- * passed as received (`A2005` unless it is the current one). Present includes
- * empty: a header sent with no value was still sent.
+ * when either is ABSENT — a request without them is malformed: it does not say which
+ * protocol and ClientContract it speaks, so there is nothing to compare.
  */
 export declare function protocolIdentityOf(normalized: Readonly<Record<string, string>>): ClientProtocolIdentity | undefined;
 /**
- * The identity headers a request did not send, in the order the framework sends
- * them — what the `A2000` answering it names (pilot.1). Empty exactly when {@link
- * protocolIdentityOf} reads an identity.
+ * The identity headers a request did not send, in the order the framework sends them —
+ * what the `A2000` answering it names. Empty exactly when {@link protocolIdentityOf}
+ * reads an identity.
  */
 export declare function missingIdentityHeaders(normalized: Readonly<Record<string, string>>): readonly IdentityHeaderName[];
 /** The two identity headers' names, as the framework spells them. */
 export type IdentityHeaderName = (typeof headers)["protocolVersion"] | (typeof headers)["contractHash"];
 /**
- * A repeated header joins with `", "`, which holds a space, so it is never
- * adopted.
+ * A repeated header joins with `", "`, which holds a space, so it is never adopted.
  */
 export declare function adoptedRequestId(normalized: Readonly<Record<string, string>>): string | undefined;
 export {};

package/dist/protocol/protocol-surface.d.ts

@@ -3,16 +3,6 @@ import { type OperationIdentity } from "../operations/operation-identity.js";
 /**
  * One route of the protocol surface: a route a host mounts for the bound
  * ClientContract, tagged by `kind`.
- *
- * - `operation`: a `(resource, family, variant)` the ClientContract advertises.
- *   `method` is always `POST` — every Resource operation is, reads included.
- *   `path` is `/_resources/<resource>/<family>/<variant>`, each segment
- *   percent-encoded exactly as the generated client sends it, so it decodes back
- *   to the exact registry key. Family and variant are one standard operation
- *   identity.
- * - `contract`: `GET /_contract` — always present.
- * - `transactions`: `POST /_transactions` — present exactly when the
- *   ClientContract's `transactions` is `"interactive"`.
  */
 export type SurfaceRoute = ({
     readonly kind: "operation";
@@ -33,17 +23,5 @@ export type SurfaceRoute = ({
  * deep-frozen — exactly the advertised operation triples in the Contract's own key
  * order, then `GET /_contract`, then `POST /_transactions` when, and only when,
  * `transactions === "interactive"`.
- *
- * Derived from the ClientContract alone — never configuration, the adapter model,
- * or another layer's Contract — so a client-hidden resource has no route, and a
- * resource whose every operation was restricted away keeps its `operations: {}`
- * and contributes nothing. Availability is read ONLY through
- * `isOperationVariantAvailable`, so a scope-qualified leaf is a route exactly as
- * `true` is, and the next widening of `OperationAvailability` reaches this reader
- * with every other. A family or variant key outside the standard operation set is
- * not a route: segments go through `parseOperationIdentity`, the same decoder that
- * reads a request's. The transaction route is tested against `"interactive"`
- * itself, never as "not `none`", so a capability value this reader does not know
- * mounts nothing.
  */
 export declare function surfaceOf(client: ClientContract): readonly SurfaceRoute[];

package/dist/protocol/protocol.binder.d.ts

@@ -6,9 +6,8 @@ import { type AvProtocolResponse } from "./http-response.encoder.js";
 import { transportFailure } from "./protocol-failure.js";
 import { type SurfaceRoute } from "./protocol-surface.js";
 /**
- * The protocol bound to ONE Framework instance — what `AvProtocol.bind` returns. A
- * host binds once, at startup, and calls these members per request; none takes a
- * Contract, an entrypoint or a limit, because the binding already read them.
+ * The protocol bound to one Framework instance, as `AvProtocol.bind` returns
+ * it. Bind once at startup and call these members per request.
  */
 export type AvProtocolBinding = {
     /**
@@ -19,10 +18,6 @@ export type AvProtocolBinding = {
      * `transactions` is `"interactive"`. Each path is relative to
      * `framework.entrypoint`. Read once at bind time: every call answers the same
      * deep-frozen list, which is passive data a host may serialize.
-     *
-     * A host that mounts one route per entry still needs a fallback for the paths it
-     * did not mount: that is the absence responder's, not a catch-all into framework
-     * handling.
      */
     readonly surface: () => readonly SurfaceRoute[];
     /**
@@ -42,9 +37,9 @@ export type AvProtocolBinding = {
     readonly decodeTransaction: (request: AvProtocolRequest) => DecodedTransaction;
     /**
      * One operation's framework response — what `framework.execute` answered — as the
-     * HTTP response a host writes: the code's status, `data` in wire forms,
-     * `Aventara-Request-Id` echoed. A result with no wire form answers `A3003` → 500.
-     * A diagnostic of one operation names it (`resource`, `family`, `variant`), so the
+     * HTTP response a host writes: the code's status, `data` in wire forms, `Aventara-
+     * Request-Id` echoed. A result with no wire form answers `A3003` → 500. A
+     * diagnostic of one operation names it (`resource`, `family`, `variant`), so the
      * `A3003` reaches the diagnostics sink only when the host passes `decoded` —
      * `decodeOperation`'s success value — as `handleOperation` does; without it the
      * answer is the same and nothing is reported.
@@ -59,9 +54,9 @@ export type AvProtocolBinding = {
     readonly encodeTransaction: (response: TransactionResponse, requestId: string) => AvProtocolResponse;
     /**
      * A transport code — `A2000`, `A2010`, `A2011` or `A2012` — as the complete
-     * framework response, with framework-authored text (ruled 2026-10-05). For a host
-     * that parses the body itself and must answer its parser's failure. `A2012`
-     * requires the methods its route allows, so every 405 carries `Allow`.
+     * framework response. For a host that parses the body itself and must answer
+     * its parser's failure. `A2012` requires the methods its route allows, so
+     * every 405 carries `Allow`.
      */
     readonly failure: typeof transportFailure;
     /**
@@ -89,22 +84,17 @@ export type AvProtocolBinding = {
      */
     readonly encodeContract: (request: AvProtocolRequest) => AvProtocolResponse;
     /**
-     * The absence responder: the fallback a host mounts for every path it did not
-     * mount from `surface()` — never a catch-all into framework handling (it reads no
-     * body, runs no pipeline, calls no Adapter). Answers what the catch-all decoder
-     * answers before a body — `A2000`, `A2006`, `A2005`, `A2001`, `A2002`, `A2012`
-     * with `Allow` — byte for byte; a route that exists reached with its own method as
-     * `500 A3000` (a host that mounted only part of the surface); and `undefined` for
-     * a path outside the protocol's namespace, which the host answers itself.
+     * The fallback for every path a host did not mount from `surface()`. It reads
+     * no body, runs no pipeline and calls no Adapter. It answers `A2000`, `A2006`,
+     * `A2005`, `A2001`, `A2002` or `A2012` (with `Allow`) as the operation routes
+     * would, `500 A3000` for a mounted route reached with its own method, and
+     * `undefined` for a path outside the protocol's namespace, which the host
+     * answers itself.
      */
     readonly answerAbsent: (request: AvProtocolRequest) => AvProtocolResponse | undefined;
 };
 /**
- * `AvProtocol.bind(framework)`: reads the instance's compiled ClientContract once
- * and returns the bound members, frozen.
- *
- * It validates nothing construction did not: `createFramework` already refused a
- * bad entrypoint and compiled the ClientContract this reads, so binding cannot
- * fail.
+ * `AvProtocol.bind(framework)`: reads the instance's compiled ClientContract
+ * once and returns the bound members, frozen.
  */
 export declare function bind(framework: Framework): AvProtocolBinding;

package/dist/protocol/protocol.handler.d.ts

@@ -5,8 +5,8 @@ import type { ClientOperationRequest } from "../runtime/operation-request.js";
 import { type AvProtocolRequest } from "./http-request.decoder.js";
 import { type AvProtocolResponse, type UnencodableReport } from "./http-response.encoder.js";
 /**
- * What the shortcuts read off the bound Framework: its compiled Contracts, the
- * execution seam, and its configured diagnostics sink.
+ * What the shortcuts read off the bound Framework: its compiled Contracts, its
+ * execution entry points and its configured diagnostics sink.
  */
 export type HandlerContext = {
     readonly contracts: FrameworkContracts;
@@ -15,34 +15,26 @@ export type HandlerContext = {
     readonly sink: FrameworkDiagnosticsSink | undefined;
 };
 /**
- * Where a plan's `A3003` goes: the Framework's diagnostics sink, as a
- * `"transaction"` diagnostic — client scope, the request id the plan ran under,
- * and the step the encoder blames as `operation` when it blames one. One spelling
- * for both `protocol.encodeTransaction` and `protocol.handleTransaction`.
+ * Where a plan's `A3003` goes: the Framework's diagnostics sink, as a `"transaction"`
+ * diagnostic — client scope, the request id the plan ran under, and the step the
+ * encoder blames as `operation` when it blames one. One spelling for both
+ * `protocol.encodeTransaction` and `protocol.handleTransaction`.
  */
 export declare function planUnencodableReport(sink: FrameworkDiagnosticsSink | undefined, requestId: string): UnencodableReport;
 /**
  * Where one operation's `A3003` goes: the Framework's diagnostics sink, as an
- * `"operation"` diagnostic carrying the decoded request's identity and id — the
- * shape the public `OperationDiagnostic` already has. One spelling for
+ * `"operation"` diagnostic carrying the decoded request's identity and id — the shape
+ * the public `OperationDiagnostic` already has. One spelling for
  * `protocol.handleOperation` and for `protocol.encodeOperation` given the decoded
  * request.
  */
 export declare function operationUnencodableReport(sink: FrameworkDiagnosticsSink | undefined, request: ClientOperationRequest): UnencodableReport;
 /**
- * `protocol.handleOperation(request)`: the three steps a host would otherwise
- * spell out — `decodeOperation` → `framework.execute` → `encodeOperation` — in one
- * call, resolving the `AvProtocolResponse` the host writes. A request the decoder
- * answers itself (a transport failure, an identity mismatch, an unadvertised
- * route) is answered without executing.
- *
- * Total over ANY value, never rejecting: the decoder answers every value,
- * `execute` resolves for every request it is handed, and the encoder answers every
- * response — a result with no wire form as `A3003` →
- * 500. That `A3003` reaches the Framework's diagnostics sink as an `"operation"`
- *      diagnostic carrying the decoded request's identity and id, which only this
- *      shortcut holds: the bare `encodeOperation` is given the response and the
- *      request id alone.
+ * `protocol.handleOperation(request)`: the three steps a host would otherwise spell
+ * out — `decodeOperation` → `framework.execute` → `encodeOperation` — in one call,
+ * resolving the `AvProtocolResponse` the host writes. A request the decoder answers
+ * itself (a transport failure, an identity mismatch, an unadvertised route) is
+ * answered without executing.
  */
 export declare function handleOperationRequest(context: HandlerContext, request: AvProtocolRequest): Promise<AvProtocolResponse>;
 /**
@@ -51,8 +43,8 @@ export declare function handleOperationRequest(context: HandlerContext, request:
  * decoded plan is client origin and cannot say otherwise, so every step runs under
  * ClientContract rules: a client-hidden field, a client-restricted variant or a
  * client-hidden Resource is refused as through its single-operation route, plus
- * `cause.operation`. A committed plan is `200 A1009`; a rolled-back one answers
- * its failing step's code at that code's status. Total over any value, as {@link
+ * `cause.operation`. A committed plan is `200 A1009`; a rolled-back one answers its
+ * failing step's code at that code's status. Total over any value, as {@link
  * handleOperationRequest} is; an `A3003` is reported through {@link
  * planUnencodableReport}.
  */

package/dist/runtime/decimal.d.ts

@@ -1,12 +1,14 @@
-/** Provider-neutral exact decimal runtime value owned by Aventara. */
+/**
+ * An exact decimal value, independent of any database driver's decimal class.
+ * Results carry `decimal` fields as `Decimal`.
+ */
 export declare class Decimal {
     #private;
     constructor(value: string);
     toString(): string;
     /**
      * The decimal string, exactly as given: what `JSON.stringify` writes for a
-     * Decimal, so a result a developer serializes by hand carries its digits rather
-     * than `{}`. The protocol's encoders do not rely on it.
+     * Decimal, so a result serialized by hand keeps its digits.
      */
     toJSON(): string;
 }

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

@@ -4,13 +4,9 @@ import type { FrameworkTransactionRequest } from "../transactions/transaction-re
 import type { FrameworkOperationRequest } from "./operation-request.js";
 import type { OperationErrorCode } from "./operation-response.js";
 /**
- * One unplanned failure as the framework saw it before sanitization: the raw
- * value, the outcome code actually emitted, and enough identity to act on it. The
- * code is usually an internal one, because the channel fires for unplanned
- * failures; it is the thrower's own code when the framework dropped something it
- * could not vouch for from an otherwise honoured deliberate outcome, which changes
- * no outcome. Server-side only — a diagnostic is never projected onto the wire,
- * which is precisely why it may carry the raw error.
+ * One unplanned failure of an operation: the raw error, the code the caller
+ * received, and the operation and request it happened in. Server-side only:
+ * diagnostics are never sent to the caller.
  */
 export type OperationDiagnostic = {
     readonly kind: "operation";
@@ -23,6 +19,10 @@ export type OperationDiagnostic = {
     readonly requestId: string;
     readonly operation?: number;
 };
+/**
+ * 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 = {
     readonly kind: "transaction";
     readonly error: unknown;
@@ -31,11 +31,11 @@ export type TransactionDiagnostic = {
     readonly requestId: string;
     readonly operation?: number;
 };
+/** One diagnostic: of an operation, or of a transaction as a whole. */
 export type FrameworkDiagnostic = OperationDiagnostic | TransactionDiagnostic;
 /**
- * The framework-owned observability channel. Configured once at the
- * configuration root: it is deliberately not a pipeline stage, so the
- * developer whose bug it reports cannot reorder, scope or remove it.
+ * Receives a diagnostic for every unplanned failure. Set once, as the root
+ * configuration's `diagnostics`.
  */
 export type FrameworkDiagnosticsSink = (diagnostic: FrameworkDiagnostic) => void | Promise<void>;
 /**
@@ -47,38 +47,18 @@ export type DiagnosticsReporter = (error: unknown, code: OperationErrorCode) =>
 /** The identifying half of a diagnostic, captured once per request. */
 type OperationDiagnosticIdentity = Omit<OperationDiagnostic, "error" | "code">;
 type TransactionDiagnosticIdentity = Omit<TransactionDiagnostic, "error" | "code">;
-/**
- * The channel bound to one diagnostic identity, as the reporters below bind
- * it. Exported for `@aventara/core/protocol`, whose binding reports a failure
- * only it can meet — a result with no wire form (`A3003`) — under the
- * identity it holds; never exported from the main entry.
- */
+/** The diagnostics channel bound to one diagnostic identity. */
 export declare function createReporter(sink: FrameworkDiagnosticsSink | undefined, identity: OperationDiagnosticIdentity | TransactionDiagnosticIdentity): DiagnosticsReporter;
 /** Records the sink `framework` was configured with; called once, at construction. */
 export declare function recordDiagnosticsSink(framework: object, sink: FrameworkDiagnosticsSink | undefined): void;
 /** The sink `framework` was configured with, or `undefined` for none. */
 export declare function diagnosticsSinkOf(framework: object): FrameworkDiagnosticsSink | undefined;
 /**
- * Binds the configured sink to one operation request.
- *
- * Identity is captured on entry rather than at report time: by the moment a
- * failure is reported the request may be exactly what broke, and a diagnostic
- * naming no operation is not actionable. A request whose own identity cannot
- * be read is past observing, so it silently yields the no-op channel — the
- * outermost totality guard still answers with the generic envelope.
- *
- * The response must be unaffected by observation, so the reporter neither
- * awaits the sink nor lets anything the sink does escape: a throw, a rejected
- * promise and a booby-trapped thenable all end here.
+ * 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;
-/**
- * The diagnostics channel of one transaction request. Like the operation
- * executor's reporter, it is bound by the framework factory, so the
- * transaction executor owns no channel and never reads configuration: it only
- * chooses which identity a report carries. The plan's identity is captured
- * once, on entry, for the same reason the operation reporter captures its own.
- */
+/** 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;

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

@@ -5,11 +5,7 @@ import type { Filter, PipelineContext } from "./pipeline.js";
 export type FailureOrigin = "adapter" | "runtime";
 /** The one generic Adapter-failure text; every unexpected A3001 carries it. */
 export declare const ADAPTER_FAILURE_MESSAGE = "Adapter execution failed.";
-/**
- * Structurally records every value thrown across the Adapter seam so the
- * final error boundary can classify origin by identity, never by inspecting
- * error text. One boundary instance belongs to one operation execution.
- */
+/** One boundary instance belongs to one operation execution. */
 export declare class AdapterBoundary {
     #private;
     /** Runs Adapter work, remembering anything it throws before re-throwing it. */
@@ -43,10 +39,10 @@ export type CallerArgumentsView = {
  */
 export declare function sanitizeOperationFailure(error: unknown, origin: FailureOrigin, report: DiagnosticsReporter, view: CallerArgumentsView): OperationFailureResponse;
 /**
- * Post-validation exception flow (spec 17.3): effective filters are stored as
- * `[root..., scoped...]`, so reverse iteration tries scoped filters in reverse
- * registration order, then root filters in reverse, then final sanitization.
- * A filter handles an error only by returning a {@link FrameworkError};
- * returning `undefined` or throwing leaves the original error unhandled.
+ * Post-validation exception flow: effective filters are stored as `[root...,
+ * scoped...]`, so reverse iteration tries scoped filters in reverse registration
+ * order, then root filters in reverse, then final sanitization. A filter handles an
+ * error only by returning a {@link FrameworkError}; returning `undefined` or throwing
+ * leaves the original error unhandled.
  */
 export declare function resolveOperationFailure(error: unknown, filters: readonly Filter[], context: PipelineContext, boundary: AdapterBoundary, report: DiagnosticsReporter, view: CallerArgumentsView): Promise<OperationFailureResponse>;

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

@@ -1,11 +1,7 @@
 /**
- * The caller's say over an in-process request it does not write by hand: the
- * second argument of every `framework.application.*` / `framework.client.*` call
- * and of `framework.transaction`.
- *
- * Not "transport options": an in-process call has no transport. A deferred handle
- * (`framework.appTx.*` / `framework.clientTx.*`) takes none — a handle is not a
- * request, and the id belongs to the run that executes it.
+ * Options for one in-process call: the optional second argument of every
+ * `framework.application.*` / `framework.client.*` call and of
+ * `framework.transaction`.
  */
 export type ExecutionOptions = {
     /**

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

@@ -6,17 +6,6 @@ import type { FrameworkResourceKey } from "../config/framework-fields-config.js"
 import type { PipelineContext } from "./pipeline.js";
 /**
  * What a write-stage compute callback is told about the field it is computing.
- *
- * `R` is the Resource the behavior is bound to and `Cfg` the authored
- * configuration literal, so `resource` is the literal Resource name and `field` —
- * like every other field-key position in the framework — is {@link
- * EffectiveFieldKey}: what the adapter discovered plus what the configuration
- * added.
- *
- * `data` is keyed on the same set and stays `unknown`-valued.
- *
- * Under the default `Cfg` the key set degenerates to `string` and this is
- * byte-for-byte the shape it was before `Cfg` existed.
  */
 type ComputedWriteContext<M extends AdapterModel, Cfg, R extends FrameworkResourceKey<M>> = {
     readonly scope: RequestOrigin;
@@ -26,11 +15,19 @@ type ComputedWriteContext<M extends AdapterModel, Cfg, R extends FrameworkResour
     readonly data: Readonly<Record<EffectiveFieldKey<M, Cfg, R>, unknown>>;
     readonly operation: PipelineContext;
 };
+/**
+ * Computes a field's value when a row is created. It receives the incoming
+ * `data` and returns the value to store.
+ */
 export type ComputeOnCreate<M extends AdapterModel = AdapterModel, Cfg = AnyFrameworkConfig, R extends FrameworkResourceKey<M> = FrameworkResourceKey<M>> = (context: ComputedWriteContext<M, Cfg, R>) => unknown | Promise<unknown>;
+/**
+ * Computes a field's value when a row is updated. It receives the incoming
+ * `data` and returns the value to store.
+ */
 export type ComputeOnUpdate<M extends AdapterModel = AdapterModel, Cfg = AnyFrameworkConfig, R extends FrameworkResourceKey<M> = FrameworkResourceKey<M>> = (context: ComputedWriteContext<M, Cfg, R>) => unknown | Promise<unknown>;
 /**
- * The read-stage counterpart. It sees the persisted `record` rather than the
- * inbound `data`, keyed on the same effective field set.
+ * Computes a field's value when a row is read. It receives the stored `record`
+ * and returns the value to return.
  */
 export type ComputeOnRead<M extends AdapterModel = AdapterModel, Cfg = AnyFrameworkConfig, R extends FrameworkResourceKey<M> = FrameworkResourceKey<M>> = (context: {
     readonly scope: RequestOrigin;
@@ -41,12 +38,8 @@ export type ComputeOnRead<M extends AdapterModel = AdapterModel, Cfg = AnyFramew
     readonly operation: PipelineContext;
 }) => unknown | Promise<unknown>;
 /**
- * A computed read, optionally declaring the fields it reads.
- *
- * `dependsOn` is a field-key position and therefore keys on
- * {@link EffectiveFieldKey} like every other one. A name outside that set is
- * an array-element assignability failure (`TS2322`), not an excess property:
- * the author wrote a `string` where a member of the key union was required.
+ * A computed read: a compute function, or `{ compute, dependsOn }` naming the
+ * fields it reads.
  */
 export type ComputedReadBehavior<M extends AdapterModel = AdapterModel, Cfg = AnyFrameworkConfig, R extends FrameworkResourceKey<M> = FrameworkResourceKey<M>> = ComputeOnRead<M, Cfg, R> | {
     readonly dependsOn?: readonly EffectiveFieldKey<M, Cfg, R>[];

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

@@ -1,7 +1,7 @@
 import type { Cause, OperationErrorCode } from "./operation-response.js";
 /**
- * Stable typed error used by server-side pipelines, behaviors and Adapters to
- * deliberately surface one framework error outcome.
+ * Throw from a pipeline, behavior or Adapter to answer the request with one
+ * framework error code and cause.
  */
 export declare class FrameworkError extends Error {
     readonly code: OperationErrorCode;

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

@@ -1,22 +1,14 @@
 /**
- * A JSON value: the runtime form of the `json` scalar, inside and out.
+ * A JSON value: the form of the `json` scalar, in arguments and results.
  *
- * It is exactly what `normalizeJsonValue` (`runtime/scalar-runtime.ts`) admits,
- * and that traversal emits only this type, so the runtime and the type are one
- * fact rather than two that agree. Measured in all three scopes alike: a `Date`,
- * a `bigint`, a `Uint8Array`, core's `Decimal`, any other class instance and an
- * `undefined` property are refused (`V1001`), and none of them is a member here.
+ * 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`).
  *
- * Two runtime refusals a type cannot carry: a non-finite `number` (`V1004`) and
- * a cycle (`V1001`).
+ * Results are fresh plain copies, so mutating one is safe.
  *
- * The containers are `readonly`, which an input accepts in either form and a
- * result under-claims: the framework hands back a fresh plain copy, so mutating
- * one is safe, but nothing is promised about it.
- *
- * A `json` FIELD's form is this without its top-level `null`
- * (`ApplicationScalarForms["json"]`): a field-level `null` is the field's
- * absence, which only `nullable: true` admits.
+ * 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;

package/dist/runtime/mutation-planner.d.ts

@@ -4,11 +4,10 @@ import type { Contract, CoreContract } from "../contracts/contract.js";
 import type { OperationExecutionRequest } from "./operation-request.js";
 import type { PipelineContext } from "./pipeline.js";
 /**
- * The two Contracts a write reads. The **Core** Contract decides what the Adapter
- * is asked to store; the **active** Contract adds the fields its scope declared
- * under `application.fields` / `client.fields`, which Core does not carry. Such a
- * field is VIRTUAL by construction (`contract.compiler.ts`), so its behaviours run
- * and its value is stripped before the Adapter call — never sent.
+ * The two Contracts a write reads. The Core Contract decides what the Adapter is asked
+ * to store; the active Contract adds the fields its scope declared under
+ * `application.fields` / `client.fields`, which Core does not carry. Such a field is
+ * virtual: its behaviours run and its value is stripped before the Adapter call.
  */
 export type WriteContracts = {
     readonly core: CoreContract;
@@ -21,13 +20,8 @@ export type RelationRecordSite = {
     readonly stage: WriteStage;
 };
 /**
- * The sole grammar for relation-mutation record operands. Every write pass
- * maps these sites with its own record leaf, leaving identifier-only
- * directives untouched. The identifier operands this table deliberately leaves
- * empty are described by `RELATION_MUTATION_SELECTOR_SITES` in
- * `transactions/operation-arguments-encoder.ts`, the only pass that has to
- * encode them; both tables are keyed by `RelationMutationDirective`, so a new
- * directive fails to compile in both places.
+ * The sole grammar for relation-mutation record operands. Every write pass maps these
+ * sites with its own record leaf, leaving identifier-only directives untouched.
  */
 export declare const RELATION_MUTATION_RECORD_SITES: {
     readonly $create: readonly [{

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

@@ -7,6 +7,7 @@ import type { PipelineTransportContext } from "./pipeline.js";
  * `ConfigLayer`; kept as an alias so existing consumers keep compiling.
  */
 export type OperationScope = RequestOrigin;
+/** The protocol version and ClientContract hash a client says it was built for. */
 export type ClientProtocolIdentity = {
     readonly version: number;
     readonly hash: string;
@@ -16,16 +17,22 @@ type RuntimeOperationBase = OperationIdentity & {
     readonly arguments: unknown;
     readonly requestId: string;
 };
+/** An in-process request, run under the Application Contract. */
 export type ApplicationOperationRequest = RuntimeOperationBase & {
     readonly scope: "application";
     readonly protocol?: never;
     readonly transport?: never;
 };
+/**
+ * A remote request, run under the Client Contract; `protocol` is the identity
+ * the client sent.
+ */
 export type ClientOperationRequest = RuntimeOperationBase & {
     readonly scope: "client";
     readonly protocol: ClientProtocolIdentity;
     readonly transport?: PipelineTransportContext;
 };
+/** One operation request, as `framework.execute` takes it. */
 export type FrameworkOperationRequest = ApplicationOperationRequest | ClientOperationRequest;
 type WithoutArguments<Request> = Request extends unknown ? Omit<Request, "arguments"> : never;
 /**