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

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

@@ -1,21 +1,24 @@
 import type { ValidationIssue } from "../operations/validation-code.js";
+/** Every outcome code, as a runtime list. */
 export declare const OPERATION_CODES: readonly ["A1000", "A1001", "A1002", "A1003", "A1004", "A1005", "A1006", "A1007", "A1008", "A1009", "A2000", "A2001", "A2002", "A2003", "A2004", "A2005", "A2006", "A2007", "A2008", "A2009", "A2010", "A2011", "A2012", "A2013", "A2014", "A3000", "A3001", "A3002", "A3003", "A3004", "A4000", "A4001", "A4002"];
+/**
+ * Every outcome code: `A1xxx` success, `A2xxx` caller error, `A3xxx` internal
+ * failure, `A4xxx` authentication or permission denial.
+ */
 export type OperationCode = (typeof OPERATION_CODES)[number];
+/** The success codes, `A1xxx`. */
 export type OperationSuccessCode = Extract<OperationCode, `A1${string}`>;
+/** Every outcome code that is not a success. */
 export type OperationErrorCode = Exclude<OperationCode, OperationSuccessCode>;
 /** Internal-failure family: nothing in the cause is caller-actionable. */
 export type OperationInternalErrorCode = Extract<OperationErrorCode, `A3${string}`>;
+/** Why a request failed: a message, and the validation issues when there are any. */
 export type Cause = {
     readonly message: string;
     readonly issues?: readonly ValidationIssue[];
     readonly operation?: number;
 };
-/**
- * The canonical wire envelope (spec section 13): a flat `{ data, code,
- * cause }` shape. `OperationResponse<T>` below is a discriminated union
- * derived from this one shape — every arm is a differently-constrained
- * projection of the same three fields, never an independent structure.
- */
+/** The response envelope: `{ data, code, cause }`. */
 type OperationResponseEnvelope<TData, TCode extends OperationCode, TCause extends Cause | null> = {
     readonly data: TData;
     readonly code: TCode;
@@ -23,33 +26,25 @@ type OperationResponseEnvelope<TData, TCode extends OperationCode, TCause extend
 };
 /** Success codes that carry response data (every success code but A1001). */
 export type OperationSuccessDataCode = Exclude<OperationSuccessCode, "A1001">;
-/** Arm (a): success with data — non-null data, null cause. */
+/** A success with data: `cause` is `null`. */
 export type OperationSuccessResponse<T> = OperationResponseEnvelope<T, OperationSuccessDataCode, null>;
-/** Arm (b): no-match success (A1001) — null data, null cause. */
+/** A success with no matching row (`A1001`): `data` and `cause` are `null`. */
 export type OperationNoMatchResponse = OperationResponseEnvelope<null, "A1001", null>;
-/** Arm (c): failure — null data, non-null cause. */
+/** A failure: `data` is `null` and `cause` says why. */
 export type OperationFailureResponse = OperationResponseEnvelope<null, OperationErrorCode, Cause>;
-export type OperationResponse<T = unknown> = OperationSuccessResponse<T> | OperationNoMatchResponse | OperationFailureResponse;
 /**
- * Builds the success-with-data arm. The only sanctioned way to construct
- * one: a runtime-computed `code` (e.g. from a table-driven outcome mapper)
- * still yields a well-typed {@link OperationSuccessResponse}.
+ * What an operation answers: success with data, a no-match success (`A1001`),
+ * or a failure with a cause.
  */
+export type OperationResponse<T = unknown> = OperationSuccessResponse<T> | OperationNoMatchResponse | OperationFailureResponse;
+/** Builds a success response with data. */
 export declare function operationSuccess<T>(data: T, code: OperationSuccessDataCode): OperationSuccessResponse<T>;
 /** Builds the no-match success arm (A1001). */
 export declare function operationNoMatch(): OperationNoMatchResponse;
-/**
- * Builds the failure arm. The only sanctioned way to construct one: a
- * runtime-computed error `code` still yields a well-typed
- * {@link OperationFailureResponse}.
- */
+/** Builds a failure response. */
 export declare function operationFailure(code: OperationErrorCode, cause: Cause): OperationFailureResponse;
 /** The one generic internal-failure text; every A3000 carries it. */
 export declare const INTERNAL_FAILURE_MESSAGE = "Internal framework error.";
-/**
- * The generic internal-failure envelope. Nothing about an internal failure is
- * caller-actionable, so every A3000 the framework emits is this exact value -
- * one constant rather than one restatement per boundary.
- */
+/** The response every internal failure (`A3000`) answers with. */
 export declare function internalFailure(): OperationFailureResponse;
 export {};

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

@@ -16,8 +16,8 @@ export type OperationRuntimeDependencies<M extends AdapterModel> = {
     readonly config: ResolvedFrameworkConfig<M>;
 };
 /**
- * What a validated operation's pipeline needs: everything except the root Adapter.
- * Its single Adapter call goes through the executor passed beside it, so inside a
+ * What a validated operation's pipeline needs: everything except the root Adapter. Its
+ * single Adapter call goes through the executor passed beside it, so inside a
  * transaction plan the root Adapter is unreachable by type.
  */
 export type OperationPipelineDependencies<M extends AdapterModel> = Omit<OperationRuntimeDependencies<M>, "adapter"> & {
@@ -31,18 +31,18 @@ export type OperationPipelineDependencies<M extends AdapterModel> = Omit<Operati
  * function — reports through the same channel.
  */
 export type FrameworkOperationExecutor = (request: FrameworkOperationRequest, report: DiagnosticsReporter) => Promise<OperationResponse>;
-/** Selects the Contract of the request's execution scope for both execution seams. */
+/** Selects the Contract of the request's execution scope. */
 export declare function activeContract(contracts: FrameworkContracts, request: FrameworkOperationRequest | FrameworkTransactionRequest): Contract;
 /** Creates the transport-independent operation executor owned by core. */
 export declare function createOperationRuntime<M extends AdapterModel>(dependencies: OperationRuntimeDependencies<M>): FrameworkOperationExecutor;
-/** Validates the request-level protocol identity shared by both execution seams. */
+/** Validates the request-level protocol identity. */
 export declare function validateProtocolIdentity(contracts: FrameworkContracts, request: FrameworkOperationRequest | FrameworkTransactionRequest): OperationFailureResponse | undefined;
 /**
- * The stale-client check on one client protocol identity: the protocol version
- * first (`A2006`), then the ClientContract hash (`A2005`). Exact match only. The
- * one implementation — the protocol's decoders and absence answers
- * (`@aventara/core/protocol`) call it too, so a stale client hears the same
- * envelope whichever layer answers.
+ * The stale-client check on one client protocol identity: the protocol version first
+ * (`A2006`), then the ClientContract hash (`A2005`). Exact match only. The one
+ * implementation — the protocol's decoders and absence answers
+ * (`@aventara/core/protocol`) call it too, so a stale client hears the same envelope
+ * whichever layer answers.
  */
 export declare function protocolIdentityFailure(contracts: FrameworkContracts, protocol: ClientProtocolIdentity): OperationFailureResponse | undefined;
 export type ValidatedOperationArguments = {
@@ -52,26 +52,11 @@ export type ValidatedOperationArguments = {
     readonly ok: false;
     readonly response: OperationFailureResponse;
 };
-/** Reusable per-operation Framework Validation Layer argument seam. */
+/** Validates one operation's arguments through the Framework Validation Layer. */
 export declare function validateOperationRequest(contract: Contract, request: FrameworkOperationRequest, options?: OperationValidationOptions): ValidatedOperationArguments;
 /**
  * Everything after the Framework Validation Layer: the developer/runtime path
- * wrapped in the post-validation error boundary. Validation failures never reach
- * this function, so developer filters never see them.
- *
- * `executor` is the operation's single Adapter call site: standalone execution
- * passes the Adapter itself, a transaction plan passes the transaction-scoped
- * executor its Adapter callback received. Every call owns one AdapterBoundary, so
- * A3001/A3000 origin stays classified per operation.
- *
- * The parameter types keep two values out of reach: `dependencies` carries no root
- * Adapter, so the executor is the only Adapter this function can call, and
- * `request` carries no `arguments`, so no stage can read the unvalidated view
- * instead of `validatedArguments`.
- *
- * `argumentsPath` is the framework's own address for these arguments —
- * `["arguments"]` standalone, `["operations", i, "args"]` inside a plan. The
- * response boundary needs it to decide whether a thrower-supplied issue path
- * denotes the caller's own arguments or is unvouched text.
+ * wrapped in the post-validation error boundary. Validation failures never
+ * reach this function, so developer filters never see them.
  */
 export declare function executeValidatedOperation<M extends AdapterModel>(dependencies: OperationPipelineDependencies<M>, request: OperationExecutionRequest, contract: Contract, validatedArguments: unknown, argumentsPath: readonly (string | number)[], executor: AdapterOperationExecutor<M>, report: DiagnosticsReporter): Promise<OperationResponse>;

package/dist/runtime/pipeline.d.ts

@@ -5,40 +5,13 @@ import type { Contract } from "../contracts/contract.js";
 import type { OperationFamily } from "../operations/operation-identity.js";
 import type { FrameworkError } from "./framework-error.js";
 /**
- * What a pipeline is told about the HTTP request a client-origin operation arrived
- * on — a **deliberate exception** to core's transport-agnosticism.
- *
- * Core never parses HTTP to fill it. `@aventara/core/protocol`'s decoders do, with
- * header names **lower-cased** and a repeated header's values joined with `", "`
- * (RFC 9110 §5.3), so a pipeline reads one spelling. An application-scope request
- * carries none (`ClientOperationRequest.transport` is optional).
+ * What a pipeline is told about the HTTP request a client-origin operation arrived on.
  */
 export type PipelineTransportContext = {
     readonly method: "POST";
     readonly headers: Readonly<Record<string, string>>;
 };
-/**
- * What a pipeline callback is told about the operation it is wrapping.
- *
- * `resource` reads its key set from the **AdapterModel**, not from a `Contract`:
- * `Contract["resources"]` is an open `Record<string, …>`, so the `C extends
- * Contract` parameter this type used to take could never name the Resources an
- * author actually has — it erased to `string`. `M` can name them, and
- * configuration cannot add Resources, so `M` is the whole answer.
- *
- * A `Cfg` parameter here would be referenced nowhere — `biome` flags it
- * (`lint/correctness/noUnusedVariables`) and it would encode no semantic
- * dependency. `FrameworkScopeConfig` already has the precedent one line above
- * `pipelines`: `fields` takes `M` only.
- *
- * `contract` stays the erased {@link Contract} deliberately: a compiled Contract
- * is passive semantic data whose result "stays untyped by design". Threading
- * configuration into it would rebuild the authoring-config-to-compiled-contract
- * bridge this work bypasses.
- *
- * Under the default `M` the key set degenerates to `string`, so an unannotated
- * `PipelineContext` is what it was before.
- */
+/** What a pipeline callback is told about the operation it is wrapping. */
 export type PipelineContext<M extends AdapterModel = AdapterModel> = {
     readonly contract: Contract;
     readonly scope: RequestOrigin;
@@ -49,9 +22,21 @@ export type PipelineContext<M extends AdapterModel = AdapterModel> = {
     readonly requestId: string;
     readonly transport?: PipelineTransportContext;
 };
+/** Allows or denies an operation; returning `false` answers `A4001`. */
 export type Guard<M extends AdapterModel = AdapterModel> = (context: PipelineContext<M>) => boolean | undefined | Promise<boolean | undefined>;
+/**
+ * Transforms the arguments before the operation runs; returning `undefined`
+ * keeps them as they are.
+ */
 export type Pipe<M extends AdapterModel = AdapterModel> = (args: unknown, context: PipelineContext<M>) => unknown | Promise<unknown>;
+/** Runs just before the operation executes. */
 export type BeforeHook<M extends AdapterModel = AdapterModel> = (context: PipelineContext<M>) => void | Promise<void>;
+/** Runs after the operation succeeds, with its result. */
 export type AfterHook<M extends AdapterModel = AdapterModel> = (result: unknown, context: PipelineContext<M>) => void | Promise<void>;
+/** Wraps the operation's execution; call `next()` to run it and get its result. */
 export type Interceptor<M extends AdapterModel = AdapterModel> = (context: PipelineContext<M>, next: () => Promise<unknown>) => Promise<unknown>;
+/**
+ * Turns a thrown error into a {@link FrameworkError} to answer with; returning
+ * `undefined` passes the error on.
+ */
 export type Filter<M extends AdapterModel = AdapterModel> = (error: unknown, context: PipelineContext<M>) => FrameworkError | undefined | Promise<FrameworkError | undefined>;

package/dist/runtime/referential-action.d.ts

@@ -1,33 +1,8 @@
 /**
  * Core's referential-action vocabulary, and the transitive cascade closure the
  * transaction planner reads.
- *
- * The facts are an Adapter's: which relation edges exist, and what deleting a
- * referenced row does to the rows that reference it. So the words here are
- * Aventara's, stated as the effect on the referencing rows, and an Adapter
- * translates its own provider's vocabulary into them.
- *
- * None of this enters a Contract. It is not part of the semantic model a Contract
- * is compiled from, so it moves no Contract value and no hash; it is a planning
- * fact, read once when the Framework is constructed.
- */
-/**
- * What deleting a referenced row does to the rows that reference it.
- *
- * - `cascade` — they are deleted with it, and their own referencing rows in turn
- *   (SQL `ON DELETE CASCADE`).
- * - `restrict` — the delete is refused while they reference it (`RESTRICT`).
- * - `noAction` — the delete is refused while they reference it (`NO ACTION`).
- *   Measured identical to `restrict` on both pilot engines: neither declares the
- *   constraint `DEFERRABLE`, so the end-of-statement check answers one delete
- *   exactly as `RESTRICT` does. It stays a distinct word because it is a distinct
- *   schema fact.
- * - `setNull` — they are kept, the reference set to null (`SET NULL`).
- * - `setDefault` — they are kept, the reference set to its column default (`SET
- *   DEFAULT`).
- *
- * Only `cascade` takes rows away, so only `cascade` is followed by the closure.
  */
+/** What deleting a referenced row does to the rows that reference it. */
 export type ReferentialDeleteEffect = "cascade" | "restrict" | "noAction" | "setNull" | "setDefault";
 /**
  * One relation edge whose referencing side holds the reference.

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

@@ -1,13 +1,6 @@
 /**
- * The request id of one façade call or transaction run: the caller's
- * `ExecutionOptions.requestId` when it is a non-empty string, otherwise a minted
- * one. Nothing is refused (the call runs either way); the empty string is read
- * as absent, because it names nothing a log line or a diagnostic could be
- * correlated by.
- *
- * Read as `unknown` because the façades are total for untyped callers too: a
- * value the type refuses — a non-string id, a non-object options argument, a
- * getter that throws — is ignored rather than carried into a `string` slot or
- * thrown out of a call that must resolve.
+ * The request id of one call or transaction run: the caller's
+ * `ExecutionOptions.requestId` when it is a non-empty string, otherwise a new
+ * one. Any other value is ignored.
  */
 export declare function requestIdOf(options: unknown): string;

package/dist/runtime/scalar-runtime.d.ts

@@ -21,12 +21,12 @@ export type ScalarValueNormalizationResult = {
 type Path = readonly (string | number)[];
 /**
  * The one discriminant between an argument OBJECT and a VALUE wherever a position
- * admits both — a filter position above all: a **plain** record is an operator
- * object, and anything else — a `Date`, a core `Decimal`, a `Uint8Array` — is a
- * value, which equality shorthand then holds to the field's scalar. The validator
- * (`operation-validator-core.ts`) reads a filter position through this same
- * answer, and an adapter's filter translation is expected to, so a position cannot
- * be operators to one reader and a value to another.
+ * admits both — a filter position above all: a **plain** record is an operator object,
+ * and anything else — a `Date`, a core `Decimal`, a `Uint8Array` — is a value, which
+ * equality shorthand then holds to the field's scalar. The validator (`operation-
+ * validator-core.ts`) reads a filter position through this same answer, and an
+ * adapter's filter translation is expected to, so a position cannot be operators to
+ * one reader and a value to another.
  */
 export declare function isPlainRecord(value: unknown): value is Readonly<Record<string, unknown>>;
 /**
@@ -36,12 +36,12 @@ export declare function isPlainRecord(value: unknown): value is Readonly<Record<
 export declare function normalizeScalarFieldValue(contract: Contract, field: ScalarField<Contract>, value: unknown, scope: RequestOrigin | "runtime", path: Path): ScalarValueNormalizationResult;
 /**
  * Copies one validated runtime value of a scalar field into a value the framework
- * owns, per scalar codec: `datetime` → a new `Date`, `bytes` → a sliced
- * `Uint8Array`, `json` → a structured deep copy, and a list → a new array of
- * copied items. `decimal` keeps its identity, and strings, numbers, booleans,
- * bigints, enum members and `null` are immutable and returned unchanged. {@link
- * SCALAR_ATOM_COPIERS} is exhaustive over {@link BuiltInScalar}, so a new codec
- * cannot reach this function without declaring its copy.
+ * owns, per scalar codec: `datetime` → a new `Date`, `bytes` → a sliced `Uint8Array`,
+ * `json` → a structured deep copy, and a list → a new array of copied items. `decimal`
+ * keeps its identity, and strings, numbers, booleans, bigints, enum members and `null`
+ * are immutable and returned unchanged. {@link SCALAR_ATOM_COPIERS} is exhaustive over
+ * {@link BuiltInScalar}, so a new codec cannot reach this function without declaring
+ * its copy.
  */
 export declare function copyScalarFieldValue(field: ScalarField<Contract>, value: unknown): unknown;
 /**

package/dist/transactions/deferred-operation.d.ts

@@ -3,6 +3,7 @@ import type { ExecutionOptions } from "../runtime/execution-options.js";
 import type { OperationFailureResponse } from "../runtime/operation-response.js";
 import type { TransactionReference } from "./transaction-reference.js";
 import type { TransactionCommittedResponse } from "./transaction-response.js";
+/** An operation fingerprint: `fp1:` and a hash of the operation and its arguments. */
 export type OperationFingerprint = `fp1:${string}`;
 /** One serializable transaction-plan operation node. */
 export type DeferredOperation = OperationIdentity & {
@@ -10,36 +11,28 @@ export type DeferredOperation = OperationIdentity & {
     readonly args: unknown;
     readonly fingerprint: OperationFingerprint;
 };
+/** A transaction plan: its operations, in the order they run. */
 export type TransactionPlan = {
     readonly operations: readonly DeferredOperation[];
 };
 declare const OPERATION_RESULT: unique symbol;
 declare const OPERATION_HANDLE: unique symbol;
-/**
- * Standard-library shapes that are objects but never a projected result row.
- * `ArrayBufferView` is TypeScript's shared structural base for every typed array
- * and `DataView`, so no constructor is enumerated and the declaration stays
- * portable ES2022 with no runtime dependency.
- */
+/** Standard-library shapes that are objects but never a projected result row. */
 export type BuiltinNonRow = Date | RegExp | ReadonlyMap<unknown, unknown> | ReadonlySet<unknown> | PromiseLike<unknown> | ArrayBufferView;
 /**
- * The single row behind a supplied result type, or `never` when the result is
- * not one referenceable row. Declaration-only: arrays, functions, the
- * `BuiltinNonRow` shapes, non-objects, and objects without a string key are
- * excluded without any `instanceof` test or `Record<string, unknown>` gate,
- * which ordinary interfaces would fail.
+ * The single row behind a result type, or `never` when the result is not one
+ * referenceable row.
  */
 export type SingleRowResult<T> = NonNullable<T> extends readonly unknown[] ? never : NonNullable<T> extends (...args: never[]) => unknown ? never : NonNullable<T> extends BuiltinNonRow ? never : NonNullable<T> extends object ? Extract<keyof NonNullable<T>, string> extends never ? never : NonNullable<T> : never;
 /** The field names a result row can be referenced by. */
 export type ReferenceableField<T> = Extract<keyof SingleRowResult<T>, string>;
+/** Builds a `$ref` to one field of this handle's row, typed as that field. */
 export type ReferenceBuilder<T> = <F extends ReferenceableField<T>>(field: F) => TransactionReference<SingleRowResult<T>[F]>;
 /** Contributes `$ref` only where the result is a referenceable single row. */
 export type OperationReferenceSurface<T> = [SingleRowResult<T>] extends [never] ? {} : {
     readonly $ref: ReferenceBuilder<T>;
 };
-/**
- * An opaque deferred-operation handle.
- */
+/** An opaque deferred-operation handle. */
 export type Operation<T> = {
     readonly [OPERATION_HANDLE]: true;
     readonly [OPERATION_RESULT]?: T;
@@ -49,13 +42,9 @@ export type TransactionResults<Ops extends readonly Operation<unknown>[]> = {
     readonly [I in keyof Ops]: Ops[I] extends Operation<infer R> ? R : never;
 };
 /**
- * The one typed transaction runner — `framework.transaction`'s own type. It infers
- * the handle tuple without `as const` at the call site, and resolves what the
- * runtime answers: the committed envelope (`A1009`) with each handle's result in
- * plan order, or the failure response. Never the bare result tuple.
- *
- * The second argument is the run's `ExecutionOptions`: its `requestId` is every
- * step's, under either origin. A handle takes none.
+ * `framework.transaction`'s type. It infers the handle tuple without `as const`
+ * and resolves the committed response (`A1009`) with each handle's result in
+ * plan order, or the failure response.
  */
 export type TransactionRunner = <const Ops extends readonly Operation<unknown>[]>(operations: Ops, options?: ExecutionOptions) => Promise<TransactionCommittedResponse<TransactionResults<Ops>> | OperationFailureResponse>;
 export {};

package/dist/transactions/operation-arguments-encoder.d.ts

@@ -1,6 +1,7 @@
 import type { Contract } from "../contracts/contract.js";
 import type { OperationIdentity } from "../operations/operation-identity.js";
 import type { SemanticOperationArguments } from "../operations/operation-validator.js";
+/** Encodes validated application arguments into the wire scalar form. */
 export declare function encodeOperationArgumentsForWire(contract: Contract, operation: OperationIdentity & {
     readonly resource: string;
 }, args: SemanticOperationArguments): unknown;

package/dist/transactions/operation-fingerprint.d.ts

@@ -1,10 +1,12 @@
 import type { OperationFingerprint } from "./deferred-operation.js";
+/** What an operation fingerprint is computed from. */
 export type OperationFingerprintNode = {
     readonly resource: string;
     readonly family: string;
     readonly variant: string;
     readonly args: unknown;
 };
+/** Whether `value` is an operation fingerprint (`fp1:…`). */
 export declare function isOperationFingerprint(value: unknown): value is OperationFingerprint;
-/** Computes the v1 operation fingerprint from an already wire-form node. */
+/** Computes an operation's fingerprint from its wire-form arguments. */
 export declare function computeOperationFingerprint(node: OperationFingerprintNode): Promise<OperationFingerprint>;

package/dist/transactions/transaction-envelope.d.ts

@@ -28,10 +28,8 @@ export type TransactionOperationEntryInspection = {
     readonly issue: ValidationIssue;
 };
 /**
- * Inspects the plan's operations tuple without dereferencing untrusted array
- * properties outside a reflection boundary. The caller uses the returned
- * length and per-index inspector rather than `operations.length` or
- * `operations[index]` directly.
+ * The caller uses the returned length and per-index inspector rather than
+ * `operations.length` or `operations[index]` directly.
  */
 export declare function inspectTransactionOperations(value: unknown): TransactionOperationsInspection;
 /** Reads one operations entry through its own data descriptor. */

package/dist/transactions/transaction-integrity-error.d.ts

@@ -1,22 +1,11 @@
 /**
- * The ways an Adapter transaction can break the contract the framework's plan
- * executor depends on. Each is answered `A3002`; the violation is the only thing
- * that tells them apart, so it is structured data rather than message text.
- *
- * - `transaction-unavailable`: the Adapter's `transaction` function is gone at
- *   execution time.
- * - `resolved-after-abort`: the Adapter resolved although the framework threw its
- *   rollback request.
- * - `resolved-incomplete`: the Adapter resolved before every plan operation ran,
- *   so no committed `A1009` array exists.
- * - `foreign-abort`: the Adapter rejected with the framework's rollback request
- *   although this plan never made one.
+ * The ways an Adapter transaction can break the framework's transaction
+ * contract. Each is answered `A3002`.
  */
 export type TransactionIntegrityViolation = "transaction-unavailable" | "resolved-after-abort" | "resolved-incomplete" | "foreign-abort";
 /**
- * The framework-owned failure reported to diagnostics when an Adapter
- * transaction violates its contract. It never reaches the wire: the response
- * is always the constant `A3002` envelope.
+ * Reported to diagnostics when an Adapter transaction breaks the framework's
+ * transaction contract. The caller receives `A3002`.
  */
 export declare class TransactionIntegrityError extends Error {
     readonly violation: TransactionIntegrityViolation;

package/dist/transactions/transaction-plan-assembler.d.ts

@@ -5,6 +5,7 @@ import type { ClientProtocolIdentity } from "../runtime/operation-request.js";
 import type { OperationFailureResponse } from "../runtime/operation-response.js";
 import type { Operation, OperationFingerprint } from "./deferred-operation.js";
 import type { TransactionOperationOrigin } from "./transaction-request.js";
+/** One wire node, exactly as the transaction runtime receives it. */
 type WireOperationNode = {
     readonly resource: string;
     readonly family: string;

package/dist/transactions/transaction-plan-validator.d.ts

@@ -62,26 +62,12 @@ export type TransactionPlanValidationResult = {
     readonly response: OperationFailureResponse;
 };
 /**
- * The refusal of a plan on a Contract without transaction plans (`A2002`, one
- * `V1006` at `["operations"]`). The one spelling — the protocol's absence answer
- * for `/_transactions` is this envelope too.
+ * The refusal of a plan on a Contract without transaction plans (`A2002`, one `V1006`
+ * at `["operations"]`). The one spelling — the protocol's absence answer for
+ * `/_transactions` is this envelope too.
  */
 export declare function transactionsUnavailableFailure(): OperationFailureResponse;
 /**
  * Whole-plan Framework Validation Layer for transaction structure and identity.
- *
- * `origins` states each operation's origin by index, for a plan whose steps do
- * not all share the request's (the typed runner's mixed plans). Absent — the
- * untyped seam — every operation takes the request's own origin. Each operation
- * is validated against its own origin's Contract.
- *
- * A plan is also refused when a step depends on rows an earlier step's cascade
- * removed (`V1019`, plan-scoped: a lone operation that cascades is not a
- * defect, since nothing follows it). The analysis runs over every step whatever
- * its origin — one plan runs in one Adapter transaction, so a client step's
- * read sees an application step's cascade — and reads each step against its own
- * origin's Contract. It is a planning answer, given before any provider statement
- * is issued, and as conservative as the facts it has: a plan cannot know which
- * rows a delete will match, so it refuses at the granularity of a Resource.
  */
 export declare function validateTransactionPlan<M extends AdapterModel>(dependencies: TransactionPlanDependencies<M>, request: FrameworkTransactionRequest, origins?: readonly TransactionOperationOrigin[]): Promise<TransactionPlanValidationResult>;

package/dist/transactions/transaction-reference-resolver.d.ts

@@ -10,17 +10,14 @@ export type ResolvedTransactionArguments = {
 };
 /**
  * Substitutes every validated `$ref` placeholder of one operation from the results
- * ledger: each earlier operation's final `data`, exactly the value at its index in
- * the `A1009` results array. Validation already proved index, source fingerprint,
- * projected path and type, and none of that is re-run here; only what can change
- * at runtime is checked. A `null` or non-record source, or a source lacking the
- * referenced own key, resolves to no value at the full reference path. The result
- * is a fresh argument graph: only the ancestors of substituted slots are cloned,
- * so the validated plan is never mutated, and every substituted value is a
- * framework-owned copy of the source's value, so a dependent operation mutating
- * its arguments cannot alter the source's committed result.
- *
- * Reading final data runs developer-produced accessors; a throw from here is the
- * framework's own per-operation failure, classified by the caller.
+ * ledger: each earlier operation's final `data`, exactly the value at its index in the
+ * `A1009` results array. Validation already proved index, source fingerprint,
+ * projected path and type, and none of that is re-run here; only what can change at
+ * runtime is checked. A `null` or non-record source, or a source lacking the
+ * referenced own key, resolves to no value at the full reference path. The result is a
+ * fresh argument graph: only the ancestors of substituted slots are cloned, so the
+ * validated plan is never mutated, and every substituted value is a framework-owned
+ * copy of the source's value, so a dependent operation mutating its arguments cannot
+ * alter the source's committed result.
  */
 export declare function resolveTransactionReferences(operation: ValidatedTransactionOperation, results: readonly unknown[]): ResolvedTransactionArguments;

package/dist/transactions/transaction-reference.d.ts

@@ -5,9 +5,14 @@ import type { CreateDataInput, OperationArgumentsFor, ResourceKey, UpdateDataInp
 import type { OperationIdentity } from "../operations/operation-identity.js";
 import type { OperationFingerprint } from "./deferred-operation.js";
 declare const REFERENCE_VALUE: unique symbol;
+/** Any object with a `$ref` key, before it is validated as a reference. */
 export type TransactionReferenceCandidate = {
     readonly $ref: unknown;
 } & Readonly<Record<string, unknown>>;
+/**
+ * A reference to a field of an earlier operation's result in the same
+ * transaction plan: `{ $ref: { operation, fingerprint, path } }`.
+ */
 export type TransactionReference<Value = unknown> = {
     readonly $ref: {
         readonly operation: number;
@@ -16,6 +21,7 @@ export type TransactionReference<Value = unknown> = {
     };
     readonly [REFERENCE_VALUE]?: Value;
 };
+/** Whether a value is an ordinary value or a `$ref` candidate. */
 export type TransactionReferenceCandidateRoute = {
     readonly kind: "ordinary";
 } | {
@@ -27,15 +33,11 @@ export type TransactionReferenceCandidateRoute = {
     readonly kind: "reflection-failure";
     readonly candidate: unknown;
 };
-/**
- * Total descriptor-only routing for a scalar value at a transaction-reference
- * position.
- */
+/** Whether a scalar value at a reference position is an ordinary value or a `$ref` candidate. */
 export declare function routeTransactionReferenceCandidate(value: unknown): TransactionReferenceCandidateRoute;
+/** Whether `value` is an object with a `$ref` key; it is not validated here. */
 export declare function isTransactionReferenceCandidate(value: unknown): value is TransactionReferenceCandidate;
-/**
- * Narrows a structurally complete `$ref` object.
- */
+/** Whether `value` is a complete `$ref` object. */
 export declare function isTransactionReferenceObject(value: unknown): value is TransactionReference;
 /**
  * A scalar mutation value inside a plan: the value itself, or a reference to an
@@ -43,42 +45,35 @@ export declare function isTransactionReferenceObject(value: unknown): value is T
  */
 export type TransactionScalarValue<Value> = Value | TransactionReference<Value>;
 /**
- * A reference carries its source's final data, which every scope returns in the
- * application forms; so a client-origin builder writes wire forms and still takes
- * a `$ref` typed by the application form of the same Contract field — strict type
- * compatibility compares Contract field types, never their forms. Unstated, both
- * are the same map and this is {@link TransactionScalarValue}.
+ * A scalar value inside a plan, or a `$ref` to a field of the same type. A
+ * reference is typed by the application form of its source field, because a
+ * source's final data is always in application forms.
  */
 type ReferenceableValue<Value, ReferenceValue> = Value | TransactionReference<ReferenceValue>;
+/** `Data`'s member `Key`, or `never` when it has none. */
 type MemberOf<Data, Key> = Key extends keyof Data ? Data[Key] : never;
 /**
- * The exported {@link TransactionCreateDataInput} is it with neither form stated;
- * the typed builders state both.
+ * Create data whose top-level scalar fields may hold a `$ref`, under stated
+ * scalar forms.
  */
 export type ReferenceableCreateData<C extends Contract, K extends ResourceKey<C>, Scope extends WriteScope, Forms extends ScalarForms, ReferenceForms extends ScalarForms> = Readonly<{
     [F in keyof CreateDataInput<C, K, Scope, Forms>]: F extends WritableRelationKey<C, K, "create", Scope> ? CreateDataInput<C, K, Scope, Forms>[F] : ReferenceableValue<CreateDataInput<C, K, Scope, Forms>[F], MemberOf<CreateDataInput<C, K, Scope, ReferenceForms>, F>>;
 }>;
+/**
+ * Update data whose top-level scalar fields may hold a `$ref`, under stated
+ * scalar forms.
+ */
 export type ReferenceableUpdateData<C extends Contract, K extends ResourceKey<C>, Scope extends WriteScope, Forms extends ScalarForms, ReferenceForms extends ScalarForms> = Readonly<{
     [F in keyof UpdateDataInput<C, K, Scope, Forms>]: F extends WritableRelationKey<C, K, "update", Scope> ? UpdateDataInput<C, K, Scope, Forms>[F] : ReferenceableValue<UpdateDataInput<C, K, Scope, Forms>[F], MemberOf<UpdateDataInput<C, K, Scope, ReferenceForms>, F>>;
 }>;
 /**
- * Only top-level scalar fields accept a `$ref`; a relation field keeps its
- * relation mutation action, where a `$ref` is an ordinary invalid value.
- *
- * The position is the standalone surface's, read the same way: both surfaces read
- * one capability value and differ only in where they bind it, so a plan's flat
- * bulk write refuses a nested-only relation exactly as `create.many` does outside
- * a plan. The default is the unrestricted position, as on `CreateDataInput`.
+ * Only top-level scalar fields accept a `$ref`; a relation field keeps its relation
+ * mutation action, where a `$ref` is an ordinary invalid value.
  */
 export type TransactionCreateDataInput<C extends Contract, K extends ResourceKey<C>, Scope extends WriteScope = "nested"> = ReferenceableCreateData<C, K, Scope, ScalarForms, ScalarForms>;
-/**
- * See {@link TransactionCreateDataInput}.
- */
+/** See {@link TransactionCreateDataInput}. */
 export type TransactionUpdateDataInput<C extends Contract, K extends ResourceKey<C>, Scope extends WriteScope = "nested"> = ReferenceableUpdateData<C, K, Scope, ScalarForms, ScalarForms>;
-/**
- * The typed builders read it with both forms stated; the exported {@link
- * TransactionOperationArgumentsFor} is it with neither.
- */
+/** Operation arguments inside a transaction plan, under stated scalar forms. */
 export type ReferenceableArgumentsFor<C extends Contract, K extends ResourceKey<C>, I extends OperationIdentity, Forms extends ScalarForms, ReferenceForms extends ScalarForms> = I extends {
     family: "create";
     variant: "one";