@aventara/core 0.1.0-pilot.0 → 0.1.0-pilot.2

package/dist/protocol/protocol-headers.js

@@ -1,44 +1,9 @@
-/**
- * The wire prefix of every framework-owned header (§12.4: "the working wire
- * prefix for v1", to be frozen before the first externally published release).
- * One place, so that freeze is a one-line change, and every name below is
- * spelled from it rather than restating it.
- */
 const WIRE_PREFIX = "Aventara";
-/**
- * `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 (§12.4); the
- *   `_contract` request needs neither.
- * - `requestId`: the correlation header (Q13). 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
- * (§12.4), so a reader matches them without regard to case; these spellings are
- * what the framework and the generated client SEND.
- *
- * Passive data (P5): 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.
- */
 export const headers = Object.freeze({
     protocolVersion: `${WIRE_PREFIX}-Protocol-Version`,
     contractHash: `${WIRE_PREFIX}-Contract-Hash`,
     requestId: `${WIRE_PREFIX}-Request-Id`,
 });
-/**
- * The request's headers as one spelling (Q7, accepted 2026-10-04): names
- * lower-cased (they are case-insensitive, §12.4), 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.
- */
 export function normalizeHeaders(received) {
     const merged = new Map();
     for (const [name, value] of Object.entries(received)) {
@@ -51,32 +16,13 @@ export function normalizeHeaders(received) {
     }
     return Object.fromEntries(Array.from(merged, ([name, values]) => [name, values.join(", ")]));
 }
-/**
- * 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.
- */
 export function headerValue(normalized, name) {
     const key = name.toLowerCase();
     return Object.hasOwn(normalized, key)
         ? normalized[key]?.replace(/^[ \t]+|[ \t]+$/g, "")
         : undefined;
 }
-/** A protocol version as the header spells it: a decimal integer, no sign, no leading zero. */
 const PROTOCOL_VERSION_TEXT = /^(?:0|[1-9]\d*)$/;
-/**
- * The identity headers (§12.4) as the `ClientProtocolIdentity` core checks, or
- * `undefined` when either is ABSENT — a request without them is malformed
- * (`A2000`; the architect, 2026-10-05): 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.
- */
 export function protocolIdentityOf(normalized) {
     const version = headerValue(normalized, headers.protocolVersion);
     const hash = headerValue(normalized, headers.contractHash);
@@ -88,14 +34,10 @@ export function protocolIdentityOf(normalized) {
         hash,
     };
 }
-/** Q13's adoptable correlation id: 1–128 characters of visible ASCII (`0x21`–`0x7E`). */
+export function missingIdentityHeaders(normalized) {
+    return [headers.protocolVersion, headers.contractHash].filter((name) => headerValue(normalized, name) === undefined);
+}
 const ADOPTABLE_REQUEST_ID = /^[\x21-\x7e]{1,128}$/;
-/**
- * Q13 (the architect's, 2026-10-04): the request's `Aventara-Request-Id` when
- * it is 1–128 characters of visible ASCII; otherwise `undefined` — the header
- * is ignored, never refused, and core mints an id instead. A repeated header
- * joins with `", "`, which holds a space, so it is never adopted.
- */
 export function adoptedRequestId(normalized) {
     const value = headerValue(normalized, headers.requestId);
     return value !== undefined && ADOPTABLE_REQUEST_ID.test(value)

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

@@ -2,20 +2,17 @@ import type { ClientContract } from "../contracts/contract.js";
 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` (the architect's ruling, 2026-10-05). Every
- * `path` is RELATIVE to the configured entrypoint, in the same space as
- * `AvProtocolRequest.path`; the canonical `framework.entrypoint` (`""` or
- * `/seg(/seg)*`, R4) joins it without a doubled slash.
+ * ClientContract, tagged by `kind`.
  *
- * - `operation`: a `(resource, family, variant)` the ClientContract
- *   advertises. `method` is always `POST` — every Resource operation is, reads
- *   included (§12.2). `path` is `/_resources/<resource>/<family>/<variant>`
- *   (§12.1), each segment percent-encoded exactly as the generated client
- *   sends it, so it decodes back to the exact registry key (§12.6). Family and
- *   variant are one standard operation identity.
- * - `contract`: `GET /_contract` (§12.1, §12.2, §12.5) — always present.
- * - `transactions`: `POST /_transactions` (§12.1, §12.2) — present exactly
- *   when the ClientContract's `transactions` is `"interactive"` (§14 item 2).
+ * - `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";
@@ -32,22 +29,21 @@ export type SurfaceRoute = ({
     readonly path: "/_transactions";
 };
 /**
- * The route list of one ClientContract (ADR 0007 DA-13): every route a host
- * mounts, from one list, 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"`.
+ * The route list of one ClientContract: every route a host mounts, from one list,
+ * 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 (M7), and a resource whose every operation was restricted away keeps
- * its `operations: {}` and contributes nothing (M6). Availability is read
- * ONLY through `isOperationVariantAvailable` (§4), 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.
+ * 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-surface.js

@@ -2,25 +2,6 @@ import { lookupOwn, lookupResource } from "../contracts/contract-lookup.js";
 import { isOperationVariantAvailable } from "../contracts/resource-operations.js";
 import { parseOperationIdentity, } from "../operations/operation-identity.js";
 const ownKeys = (record) => record === undefined ? [] : Object.keys(record);
-/**
- * The route list of one ClientContract (ADR 0007 DA-13): every route a host
- * mounts, from one list, 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 (M7), and a resource whose every operation was restricted away keeps
- * its `operations: {}` and contributes nothing (M6). Availability is read
- * ONLY through `isOperationVariantAvailable` (§4), 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 function surfaceOf(client) {
     const routes = [];
     for (const resourceName of ownKeys(client.resources)) {

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

@@ -6,38 +6,32 @@ 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 (§5.9; the type's name ruled 2026-10-05). 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.
- *
- * Grows one member per slice (§7); the exact set is pinned in
- * `index.test-d.ts`.
+ * 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.
  */
 export type AvProtocolBinding = {
     /**
-     * Every route a host mounts for the bound ClientContract, from one list,
-     * each tagged by `kind` (ADR 0007 DA-13; the architect's ruling,
-     * 2026-10-05): one `POST` `operation` route per `(resource, family,
-     * variant)` it advertises — nothing it does not — then the `contract` route
-     * `GET /_contract` (always), then the `transactions` route
-     * `POST /_transactions` exactly when its `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.
+     * Every route a host mounts for the bound ClientContract, from one list, each
+     * tagged by `kind`: one `POST` `operation` route per `(resource, family, variant)`
+     * it advertises — nothing it does not — then the `contract` route `GET /_contract`
+     * (always), then the `transactions` route `POST /_transactions` exactly when its
+     * `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.
+     * 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[];
     /**
      * An operation route's HTTP request → the client-origin request
-     * `framework.execute` takes, or the framework response that answers it
-     * instead, with the request id either way (Q13). Answers absence for an
-     * unadvertised triple without executing it (Q12), so a catch-all host is
-     * safe. Raw body: size, content type, JSON and shape enforced; parsed body:
-     * shape only — the rest was the host's parser's (Q11).
+     * `framework.execute` takes, or the framework response that answers it instead,
+     * with the request id either way. Answers absence for an unadvertised triple
+     * without executing it, so a catch-all host is safe. Raw body: size, content type,
+     * JSON and shape enforced; parsed body: shape only — the rest was the host's
+     * parser's.
      */
     readonly decodeOperation: (request: AvProtocolRequest) => DecodedOperation;
     /**
@@ -47,77 +41,70 @@ 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 (§13.2), `data` in
-     * wire forms (P1), `Aventara-Request-Id` echoed (Q13). 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 (the architect, 2026-10-05); without
-     * it the answer is the same and nothing is reported.
+     * 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
+     * `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.
      */
     readonly encodeOperation: (response: OperationResponse, requestId: string, decoded?: DecodedOperationRequest) => AvProtocolResponse;
     /**
-     * The same for `/_transactions` — what `framework.executeTransaction`
-     * answered. A second encoder by the architect's choice (§5.9); both share
-     * the one status table and the one wire walker. An `A3003` is reported to
-     * the Framework's diagnostics sink as a `"transaction"` diagnostic — client
-     * scope, this `requestId`, the step it blames as `operation` — with the
-     * value that had no wire form (or what its getter threw) as `error`.
+     * The same for `/_transactions` — what `framework.executeTransaction` answered. An
+     * `A3003` is reported to the Framework's diagnostics sink as a `"transaction"`
+     * diagnostic — client scope, this `requestId`, the step it blames as `operation` —
+     * with the value that had no wire form (or what its getter threw) as `error`.
      */
     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` (the director, 2026-10-05).
+     * 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`.
      */
     readonly failure: typeof transportFailure;
     /**
-     * The shortcut (R2): `decodeOperation` → `framework.execute` →
-     * `encodeOperation`, resolving the response the host writes for an
-     * operation route. A decode failure is answered without executing; an
-     * `A3003` is reported to the diagnostics sink with the operation's
-     * identity and request id. Total over any value an untyped host hands it:
-     * one that is not an `AvProtocolRequest` answers `400 A2000`; it never
-     * rejects.
+     * The shortcut: `decodeOperation` → `framework.execute` → `encodeOperation`,
+     * resolving the response the host writes for an operation route. A decode failure
+     * is answered without executing; an `A3003` is reported to the diagnostics sink
+     * with the operation's identity and request id. Total over any value an untyped
+     * host hands it: one that is not an `AvProtocolRequest` answers `400 A2000`; it
+     * never rejects.
      */
     readonly handleOperation: (request: AvProtocolRequest) => Promise<AvProtocolResponse>;
     /**
      * The same for `/_transactions`: `decodeTransaction` →
-     * `framework.executeTransaction` → `encodeTransaction`. Every step runs
-     * under ClientContract rules (R1); a committed plan is `200 A1009`, a
-     * rolled-back one its failing step's own status.
+     * `framework.executeTransaction` → `encodeTransaction`. Every step runs under
+     * ClientContract rules; a committed plan is `200 A1009`, a rolled-back one its
+     * failing step's own status.
      */
     readonly handleTransaction: (request: AvProtocolRequest) => Promise<AvProtocolResponse>;
     /**
-     * The `GET /_contract` responder (Q8): the bound ClientContract's
-     * JCS-canonical bytes, `ETag` its quoted hash, `Cache-Control: no-cache`,
-     * and `304` with no body when `If-None-Match` matches (weak comparison, a
-     * list, `*`). Requires no identity header; any other method is `405
-     * A2012` with `Allow: GET`. The bytes are written once, at bind time.
+     * The `GET /_contract` responder: the bound ClientContract's JCS-canonical bytes,
+     * `ETag` its quoted hash, `Cache-Control: no-cache`, and `304` with no body when
+     * `If-None-Match` matches (weak comparison, a list, `*`). Requires no identity
+     * header; any other method is `405 A2012` with `Allow: GET`. The bytes are written
+     * once, at bind time.
      */
     readonly encodeContract: (request: AvProtocolRequest) => AvProtocolResponse;
     /**
-     * The absence responder (Q2's O3): 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 architect,
-     * 2026-10-05).
+     * 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.
      */
     readonly answerAbsent: (request: AvProtocolRequest) => AvProtocolResponse | undefined;
 };
 /**
- * `AvProtocol.bind(framework)`: reads the instance's compiled ClientContract
- * once and returns the bound members, frozen.
+ * `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 (R4) and compiled the ClientContract this reads, so binding
- * cannot fail.
+ * It validates nothing construction did not: `createFramework` already refused a
+ * bad entrypoint and compiled the ClientContract this reads, so binding cannot
+ * fail.
  */
 export declare function bind(framework: Framework): AvProtocolBinding;

package/dist/protocol/protocol.binder.js

@@ -6,14 +6,6 @@ import { encodeOperationResponse, encodeTransactionResponse, } from "./http-resp
 import { handleOperationRequest, handleTransactionRequest, operationUnencodableReport, planUnencodableReport, } from "./protocol.handler.js";
 import { transportFailure } from "./protocol-failure.js";
 import { surfaceOf } from "./protocol-surface.js";
-/**
- * `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 (R4) and compiled the ClientContract this reads, so binding
- * cannot fail.
- */
 export function bind(framework) {
     const { contracts } = framework;
     const surface = surfaceOf(contracts.client);

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

@@ -16,48 +16,44 @@ export type HandlerContext = {
 };
 /**
  * Where a plan's `A3003` goes: the Framework's diagnostics sink, as a
- * `"transaction"` diagnostic — client scope (the protocol has no other
- * origin, P4), 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`.
+ * `"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
- * `protocol.handleOperation` and for `protocol.encodeOperation` given the
- * decoded request (the architect, 2026-10-05).
+ * `"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)` (§5.9, R2; S8): 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.
+ * `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 (one
- * that is not an `AvProtocolRequest` as `400 A2000`; the director,
- * 2026-10-05), `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 (the director, 2026-10-05),
- * which only this shortcut holds: the bare `encodeOperation` is given the
- * response and the request id alone.
+ * 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.
  */
 export declare function handleOperationRequest(context: HandlerContext, request: AvProtocolRequest): Promise<AvProtocolResponse>;
 /**
- * `protocol.handleTransaction(request)` (§5.9, R2; S9): the same shortcut for
- * `/_transactions` — `decodeTransaction` → `framework.executeTransaction` →
- * `encodeTransaction`. The decoded plan is client origin and cannot say
- * otherwise, so every step runs under ClientContract rules (R1): 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` (P3); a rolled-back one
- * answers its failing step's code at that code's status (Q4). Total over any
- * value, as {@link handleOperationRequest} is; an `A3003` is
- * reported through {@link planUnencodableReport}.
+ * `protocol.handleTransaction(request)`: the same shortcut for `/_transactions` —
+ * `decodeTransaction` → `framework.executeTransaction` → `encodeTransaction`. The
+ * 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
+ * handleOperationRequest} is; an `A3003` is reported through {@link
+ * planUnencodableReport}.
  */
 export declare function handleTransactionRequest(context: HandlerContext, request: AvProtocolRequest): Promise<AvProtocolResponse>;

package/dist/protocol/protocol.handler.js

@@ -1,13 +1,6 @@
 import { createDiagnosticsReporter, createReporter, } from "../runtime/diagnostics-reporter.js";
 import { decodeOperationRequest, decodeTransactionRequest, } from "./http-request.decoder.js";
 import { encodeOperationResponse, encodeTransactionResponse, } from "./http-response.encoder.js";
-/**
- * Where a plan's `A3003` goes: the Framework's diagnostics sink, as a
- * `"transaction"` diagnostic — client scope (the protocol has no other
- * origin, P4), 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 function planUnencodableReport(sink, requestId) {
     return (error, operation) => createReporter(sink, {
         kind: "transaction",
@@ -16,33 +9,9 @@ export function planUnencodableReport(sink, requestId) {
         ...(operation === undefined ? {} : { operation }),
     })(error, "A3003");
 }
-/**
- * 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
- * `protocol.handleOperation` and for `protocol.encodeOperation` given the
- * decoded request (the architect, 2026-10-05).
- */
 export function operationUnencodableReport(sink, request) {
     return (error) => createDiagnosticsReporter(sink, request)(error, "A3003");
 }
-/**
- * `protocol.handleOperation(request)` (§5.9, R2; S8): 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 (one
- * that is not an `AvProtocolRequest` as `400 A2000`; the director,
- * 2026-10-05), `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 (the director, 2026-10-05),
- * which only this shortcut holds: the bare `encodeOperation` is given the
- * response and the request id alone.
- */
 export async function handleOperationRequest(context, request) {
     const decoded = decodeOperationRequest(context.contracts, request);
     if (!decoded.ok) {
@@ -51,18 +20,6 @@ export async function handleOperationRequest(context, request) {
     const response = await context.execute(decoded.request);
     return encodeOperationResponse(response, decoded.requestId, operationUnencodableReport(context.sink, decoded.request));
 }
-/**
- * `protocol.handleTransaction(request)` (§5.9, R2; S9): the same shortcut for
- * `/_transactions` — `decodeTransaction` → `framework.executeTransaction` →
- * `encodeTransaction`. The decoded plan is client origin and cannot say
- * otherwise, so every step runs under ClientContract rules (R1): 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` (P3); a rolled-back one
- * answers its failing step's code at that code's status (Q4). Total over any
- * value, as {@link handleOperationRequest} is; an `A3003` is
- * reported through {@link planUnencodableReport}.
- */
 export async function handleTransactionRequest(context, request) {
     const decoded = decodeTransactionRequest(context.contracts, request);
     if (!decoded.ok) {

package/dist/runtime/computed-read-runtime.js

@@ -35,17 +35,6 @@ function supportsProjection(request) {
     }
     return request.variant !== "count";
 }
-/**
- * Plan one scalar of the read. Two Contracts answer two different questions:
- * the **active** Contract decides what the read RETURNS, and the **Core**
- * Contract decides what the Adapter is ASKED for — only a field it stores.
- *
- * A field added at a scope (`application.fields`) exists in that scope's
- * Contract and not in Core, and is VIRTUAL by construction
- * (`contract.compiler.ts`), so it is returned and computed, never requested.
- * Resolving the returned field against Core instead dropped it from the default
- * read and sent an explicit `select` of it to the Adapter as a column (D2).
- */
 function addScalarProjection(core, active, behaviors, resourceName, fieldName, adapterSelect, requested, computed) {
     const activeField = lookupField(lookupResource(active, resourceName), fieldName);
     if (activeField?.kind !== "scalar") {
@@ -253,13 +242,6 @@ function replaceWithInternalSelect(args, select) {
     internal.select = select;
     return internal;
 }
-/**
- * Clone the caller projection into the internal Adapter projection: the read
- * set the Adapter is asked for, always explicit for a projecting variant, plus
- * whatever computed scalar fields need to materialize. Caller-visible arguments
- * are never mutated and hidden dependencies are resolved through the Core
- * Contract.
- */
 export function planReadOperation(core, active, behaviors, request, args) {
     if (!isRecord(args) || !supportsProjection(request)) {
         return { arguments: args, projection: undefined, materialize: false };
@@ -285,11 +267,6 @@ export function planReadOperation(core, active, behaviors, request, args) {
             materialize: true,
         };
     }
-    // No caller projection: the read set is the default projection, issued
-    // explicitly and unconditionally. Leaving it unspecified would mean "whatever
-    // the Adapter's provider reads by default", which is every stored column —
-    // including one the active scope has removed from reads, fetched into server
-    // memory before the output validator could refuse it (D1).
     const defaults = defaultProjectionLevel(core, active, behaviors, request.resource);
     return {
         arguments: { ...args, select: defaults.select },
@@ -319,8 +296,6 @@ async function materializeRecord(active, behaviors, request, plan, value, contex
     if (!isRecord(value)) {
         return value;
     }
-    // The active Contract planned this read, so it is the one that knows every
-    // computed field in it — a field added at its scope included (D2).
     const resource = lookupResource(active, plan.resource);
     if (resource === undefined) {
         return value;
@@ -359,10 +334,6 @@ async function materializeRecord(active, behaviors, request, plan, value, contex
         .filter((fieldName) => Object.hasOwn(record, fieldName))
         .map((fieldName) => [fieldName, record[fieldName]]));
 }
-/**
- * Materialize computed scalar reads and remove internal dependency fields,
- * against `active` — the Contract `planReadOperation` was given as `active`.
- */
 export async function materializeReadOperation(active, behaviors, request, plan, value, contextFactory) {
     const projection = plan.projection;
     if (!plan.materialize || projection === undefined) {