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

package/dist/protocol/http-request.decoder.d.ts

@@ -3,20 +3,19 @@ import type { ClientOperationRequest } from "../runtime/operation-request.js";
 import type { ClientTransactionRequest } from "../transactions/transaction-request.js";
 import type { AvProtocolResponse } from "./http-response.encoder.js";
 /**
- * One HTTP request as a host hands it to the protocol: what the decoders
- * (`protocol.decodeOperation` / `decodeTransaction`, S7) read, and what each
- * row of the fixture corpus carries as its `request`.
+ * One HTTP request as a host hands it to the protocol: what the decoders read, and
+ * what each row of the fixture corpus carries as its `request`.
  *
- * Host-independent by construction: no host's request object, only the four
- * facts every host can supply.
+ * Host-independent by construction: no host's request object, only the four facts
+ * every host can supply.
  */
 export type AvProtocolRequest = {
     /** The HTTP method as received. Anything but `POST` on a framework route is `A2012`. */
     readonly method: string;
     /**
-     * The request path RELATIVE to the configured entrypoint, as received (not
-     * yet URL-decoded): `/_resources/users/find/many`, `/_transactions`,
-     * `/_contract` (§12.1) — the space `protocol.surface()`'s paths live in.
+     * The request path RELATIVE to the configured entrypoint, as received (not yet
+     * URL-decoded): `/_resources/users/find/many`, `/_transactions`, `/_contract` —
+     * the space `protocol.surface()`'s paths live in.
      */
     readonly path: string;
     /**
@@ -26,16 +25,15 @@ export type AvProtocolRequest = {
      */
     readonly headers: Readonly<Record<string, string | readonly string[] | undefined>>;
     /**
-     * The body, in one of two explicitly named arms (Q11) — the decoder never
-     * guesses which one it was given:
+     * The body, in one of two explicitly named arms — the decoder never guesses which
+     * one it was given:
      *
-     * - `raw`: the decoded body (after content decoding, §20.1) as received,
-     *   bytes or text. The decoder enforces all of it: the size limit
-     *   (`A2010`), the content type (`A2011`), JSON syntax and the body's
-     *   shape (`A2000`). An absent body is zero bytes (`""`).
-     * - `parsed`: a value the host's own JSON parser already produced. Size,
-     *   content type and JSON syntax were the host's to enforce before the
-     *   decoder ran; the decoder still refuses a non-object shape (`A2000`).
+     * - `raw`: the decoded body as received, bytes or text. The decoder enforces all
+     *   of it: the size limit (`A2010`), the content type (`A2011`), JSON syntax and
+     *   the body's shape (`A2000`). An absent body is zero bytes (`""`).
+     * - `parsed`: a value the host's own JSON parser already produced. Size, content
+     *   type and JSON syntax were the host's to enforce before the decoder ran; the
+     *   decoder still refuses a non-object shape (`A2000`).
      */
     readonly body: {
         readonly kind: "raw";
@@ -46,10 +44,10 @@ export type AvProtocolRequest = {
     };
 };
 /**
- * What a decoder answers (§5.9, R2): the request core executes, or the
- * framework response that answers the HTTP request instead — and, either way,
- * the request id it runs or is answered under, which the host passes to the
- * encoder: `protocol.encodeOperation(response, decoded.requestId)`.
+ * What a decoder answers: the request core executes, or the framework response
+ * that answers the HTTP request instead — and, either way, the request id it runs
+ * or is answered under, which the host passes to the encoder:
+ * `protocol.encodeOperation(response, decoded.requestId)`.
  */
 type Decoded<Request> = {
     readonly ok: true;
@@ -69,55 +67,51 @@ export type DecodedOperationRequest = Extract<DecodedOperation, {
 /** What `protocol.decodeTransaction` answers. */
 export type DecodedTransaction = Decoded<ClientTransactionRequest>;
 /**
- * `protocol.decodeOperation(request)` — one operation route's HTTP request as
- * the client-origin request `framework.execute` takes, or its answer.
+ * `protocol.decodeOperation(request)` — one operation route's HTTP request as the
+ * client-origin request `framework.execute` takes, or its answer.
  *
- * Total over ANY value (the director, 2026-10-05): a value that is not an
- * `AvProtocolRequest` at all — not an object, a missing or mistyped member, a
- * member behind a getter or trap that throws — is malformed, `A2000` under a
- * minted id, before anything else is read; nothing it carries is believed.
- * Otherwise, in order, each step answering before the next runs:
+ * Total over ANY value: a value that is not an `AvProtocolRequest` at all — not an
+ * object, a missing or mistyped member, a member behind a getter or trap that
+ * throws — is malformed, `A2000` under a minted id, before anything else is read;
+ * nothing it carries is believed. Otherwise, in order, each step answering before
+ * the next runs:
  *
- * 1. the request id: `Aventara-Request-Id` adopted when it is 1–128 visible
- *    ASCII characters, otherwise minted by core's one helper — never a
- *    refusal (Q13, Q10);
+ * 1. the request id: `Aventara-Request-Id` adopted when it is 1–128 visible ASCII
+ *    characters, otherwise minted by core's one helper — never a refusal;
  * 2. the path: `/_resources/<resource>/<family>/<variant>`, each segment
  *    URL-decoded once and none empty, or `A2000`;
- * 3. identity and absence, with no body read: a request missing either
- *    identity header is malformed (`A2000`; the architect, 2026-10-05); then
- *    the protocol version (`A2006`), the ClientContract hash (`A2005`), the
- *    Resource (`A2001`) and the operation (`A2002`), each core's own
- *    envelope — so an unadvertised triple never reaches `execute`, in either
- *    route style (Q12, Q2's O3);
- * 4. the method: anything but `POST` is `A2012`, carrying `Allow: POST`
- *    (RFC 9110 §15.5.6);
- * 5. the body (Q11). On the RAW arm the decoder enforces all of it: the
- *    content type must be `application/json` (`A2011`; parameters are not
- *    read), the decoded byte count must not exceed the ClientContract's
- *    `limits.maxRequestBytes` (`A2010`, §20.1), and the bytes must be UTF-8
- *    JSON (`A2000`). On the PARSED arm the host's own parser already read the
- *    bytes, so size, content type and JSON syntax were the HOST's to enforce —
- *    answering its parser's failures with `protocol.failure` — and the decoder
- *    checks none of them. Both arms then refuse a body that is not a JSON
- *    object — an array, a scalar, `null`, or none (`A2000`). One gap is the
- *    host's by construction: a parser that turns an absent body into `{}`
- *    makes absence indistinguishable from `{}`, which is valid.
+ * 3. identity and absence, with no body read: a request missing either identity
+ *    header is malformed; then the protocol version (`A2006`), the ClientContract
+ *    hash (`A2005`), the Resource (`A2001`) and the operation (`A2002`), each
+ *    core's own envelope — so an unadvertised triple never reaches `execute`, in
+ *    either route style;
+ * 4. the method: anything but `POST` is `A2012`, carrying `Allow: POST` (RFC 9110
+ *    §15.5.6);
+ * 5. the body. On the RAW arm the decoder enforces all of it: the content type
+ *    must be `application/json` (`A2011`; parameters are not read), the decoded
+ *    byte count must not exceed the ClientContract's `limits.maxRequestBytes`, and
+ *    the bytes must be UTF-8 JSON (`A2000`). On the PARSED arm the host's own
+ *    parser already read the bytes, so size, content type and JSON syntax were the
+ *    HOST's to enforce — answering its parser's failures with `protocol.failure` —
+ *    and the decoder checks none of them. Both arms then refuse a body that is not
+ *    a JSON object — an array, a scalar, `null`, or none (`A2000`). One gap is the
+ *    host's by construction: a parser that turns an absent body into `{}` makes
+ *    absence indistinguishable from `{}`, which is valid.
  *
- * The request is client origin, always (P4): nothing the caller sends spells
- * application origin. `transport` carries `POST` and the request's headers
- * (Q7). The body is the operation's arguments verbatim (§12.3): the decoder
- * never reads into it, so routing metadata in it is core's to refuse (N16),
- * and a parsed body reaches core as the same object.
+ * The request is client origin, always: nothing the caller sends spells
+ * application origin. `transport` carries `POST` and the request's headers. The
+ * body is the operation's arguments verbatim: the decoder never reads into it, so
+ * routing metadata in it is core's to refuse, and a parsed body reaches core as
+ * the same object.
  */
 export declare function decodeOperationRequest(contracts: FrameworkContracts, received: AvProtocolRequest): DecodedOperation;
 /**
  * `protocol.decodeTransaction(request)` — the `/_transactions` request as the
- * client-origin plan request `framework.executeTransaction` takes, or its
- * answer. The same steps as {@link decodeOperationRequest}, with the path
- * exactly `/_transactions` and its absence being a ClientContract without
- * interactive transactions (`A2002` at `["operations"]`, M17). Every step of
- * the plan then runs under ClientContract rules (R1): the plan is client
- * origin and cannot say otherwise. The body is the plan verbatim.
+ * client-origin plan request `framework.executeTransaction` takes, or its answer.
+ * The same steps as {@link decodeOperationRequest}, with the path exactly
+ * `/_transactions` and its absence being a ClientContract without interactive
+ * transactions. Every step of the plan then runs under ClientContract rules: the
+ * plan is client origin and cannot say otherwise. The body is the plan verbatim.
  */
 export declare function decodeTransactionRequest(contracts: FrameworkContracts, received: AvProtocolRequest): DecodedTransaction;
 export {};

package/dist/protocol/http-request.decoder.js

@@ -2,47 +2,6 @@ import { checkOperationRoute, checkTransactionsRoute, } from "./absent-route.res
 import { readRequest } from "./http-request.reader.js";
 import { transportFailure, } from "./protocol-failure.js";
 import { headerValue } from "./protocol-headers.js";
-/**
- * `protocol.decodeOperation(request)` — one operation route's HTTP request as
- * the client-origin request `framework.execute` takes, or its answer.
- *
- * Total over ANY value (the director, 2026-10-05): a value that is not an
- * `AvProtocolRequest` at all — not an object, a missing or mistyped member, a
- * member behind a getter or trap that throws — is malformed, `A2000` under a
- * minted id, before anything else is read; nothing it carries is believed.
- * Otherwise, in order, each step answering before the next runs:
- *
- * 1. the request id: `Aventara-Request-Id` adopted when it is 1–128 visible
- *    ASCII characters, otherwise minted by core's one helper — never a
- *    refusal (Q13, Q10);
- * 2. the path: `/_resources/<resource>/<family>/<variant>`, each segment
- *    URL-decoded once and none empty, or `A2000`;
- * 3. identity and absence, with no body read: a request missing either
- *    identity header is malformed (`A2000`; the architect, 2026-10-05); then
- *    the protocol version (`A2006`), the ClientContract hash (`A2005`), the
- *    Resource (`A2001`) and the operation (`A2002`), each core's own
- *    envelope — so an unadvertised triple never reaches `execute`, in either
- *    route style (Q12, Q2's O3);
- * 4. the method: anything but `POST` is `A2012`, carrying `Allow: POST`
- *    (RFC 9110 §15.5.6);
- * 5. the body (Q11). On the RAW arm the decoder enforces all of it: the
- *    content type must be `application/json` (`A2011`; parameters are not
- *    read), the decoded byte count must not exceed the ClientContract's
- *    `limits.maxRequestBytes` (`A2010`, §20.1), and the bytes must be UTF-8
- *    JSON (`A2000`). On the PARSED arm the host's own parser already read the
- *    bytes, so size, content type and JSON syntax were the HOST's to enforce —
- *    answering its parser's failures with `protocol.failure` — and the decoder
- *    checks none of them. Both arms then refuse a body that is not a JSON
- *    object — an array, a scalar, `null`, or none (`A2000`). One gap is the
- *    host's by construction: a parser that turns an absent body into `{}`
- *    makes absence indistinguishable from `{}`, which is valid.
- *
- * The request is client origin, always (P4): nothing the caller sends spells
- * application origin. `transport` carries `POST` and the request's headers
- * (Q7). The body is the operation's arguments verbatim (§12.3): the decoder
- * never reads into it, so routing metadata in it is core's to refuse (N16),
- * and a parsed body reaches core as the same object.
- */
 export function decodeOperationRequest(contracts, received) {
     const read = readRequest(received);
     if (!read.ok) {
@@ -69,15 +28,6 @@ export function decodeOperationRequest(contracts, received) {
         }
         : refused(body.response, read.requestId);
 }
-/**
- * `protocol.decodeTransaction(request)` — the `/_transactions` request as the
- * client-origin plan request `framework.executeTransaction` takes, or its
- * answer. The same steps as {@link decodeOperationRequest}, with the path
- * exactly `/_transactions` and its absence being a ClientContract without
- * interactive transactions (`A2002` at `["operations"]`, M17). Every step of
- * the plan then runs under ClientContract rules (R1): the plan is client
- * origin and cannot say otherwise. The body is the plan verbatim.
- */
 export function decodeTransactionRequest(contracts, received) {
     const read = readRequest(received);
     if (!read.ok) {
@@ -105,21 +55,15 @@ export function decodeTransactionRequest(contracts, received) {
 function refused(response, requestId) {
     return { ok: false, response, requestId };
 }
-/** Q7: every client request carries `POST` and its headers, one spelling. */
 function transportOf(read) {
     return { method: "POST", headers: read.headers };
 }
-/**
- * Step 5, after the route checks passed: the body as a JSON object, or the
- * answer refusing it. Only the raw arm is measured, typed and parsed (Q11).
- */
 function readBody(read, contracts) {
     const code = bodyValue(read.request.body, headerValue(read.headers, "content-type"), contracts.client.limits.maxRequestBytes);
     return typeof code === "string"
         ? { ok: false, response: transportFailure(code, read.requestId) }
         : { ok: true, value: code.value };
 }
-/** The body's JSON object, or the transport code that refuses it. */
 function bodyValue(body, contentType, maxRequestBytes) {
     if (body.kind === "parsed") {
         return isJsonObject(body.value) ? { value: body.value } : "A2000";
@@ -143,18 +87,12 @@ function bodyValue(body, contentType, maxRequestBytes) {
     }
     return isJsonObject(value) ? { value } : "A2000";
 }
-/** `application/json`, in any case; parameters (`; charset=…`) are not read. */
 function isJsonMediaType(contentType) {
     return (contentType
         ?.split(";")[0]
         ?.replace(/^[ \t]+|[ \t]+$/g, "")
         .toLowerCase() === "application/json");
 }
-/**
- * An object that is not a list (§12.6: a JSON array, scalar, `null` or absent
- * body is invalid). Read without touching the value's own members, so a
- * parsed body is never traversed; a revoked proxy is no object.
- */
 function isJsonObject(value) {
     try {
         return typeof value === "object" && value !== null && !Array.isArray(value);

package/dist/protocol/http-request.reader.d.ts

@@ -2,27 +2,27 @@ import type { ClientProtocolIdentity } from "../runtime/operation-request.js";
 import type { OperationRouteSegments } from "./absent-route.responder.js";
 import type { AvProtocolRequest } from "./http-request.decoder.js";
 import type { AvProtocolResponse } from "./http-response.encoder.js";
-/** `POST <entrypoint>/_transactions` (§12.1). */
+/** `POST <entrypoint>/_transactions`. */
 export declare const TRANSACTIONS_ROUTE = "/_transactions";
-/** `GET <entrypoint>/_contract` (§12.1, §12.5). */
+/** `GET <entrypoint>/_contract`. */
 export declare const CONTRACT_ROUTE = "/_contract";
-/** The methods an operation or `/_transactions` route accepts: `POST`, only (§12.2). */
+/** The methods an operation or `/_transactions` route accepts: `POST`, only. */
 export declare const POST_ONLY: readonly string[];
-/** The methods the contract route accepts: `GET`, only (§12.2). */
+/** The methods the contract route accepts: `GET`, only. */
 export declare const GET_ONLY: readonly string[];
 /**
  * Whether a path lies in the protocol's namespace: underscore-prefixed paths
- * beneath the entrypoint are reserved for framework facilities; every other
- * path is the host's (§12.1).
+ * beneath the entrypoint are reserved for framework facilities; every other path
+ * is the host's.
  */
 export declare function isProtocolPath(path: string): boolean;
 /** A request the protocol could read, with what every route reads off it first. */
 export type ReadRequest = {
     readonly ok: true;
     readonly request: AvProtocolRequest;
-    /** Names lower-cased, repeated values joined (Q7). */
+    /** Names lower-cased, repeated values joined. */
     readonly headers: Readonly<Record<string, string>>;
-    /** Adopted from `Aventara-Request-Id` (Q13), else minted (Q10). */
+    /** Adopted from `Aventara-Request-Id`, else minted. */
     readonly requestId: string;
     /** `undefined` when either identity header is absent (`A2000`). */
     readonly protocol: ClientProtocolIdentity | undefined;
@@ -34,13 +34,12 @@ export type UnreadableRequest = {
     readonly requestId: string;
 };
 /**
- * The host's value read as a request, or — when it is not an
- * `AvProtocolRequest` at all — the `400 A2000` answering it, under a minted
- * id (the director, 2026-10-05).
+ * The host's value read as a request, or — when it is not an `AvProtocolRequest`
+ * at all — the `400 A2000` answering it, under a minted id.
  */
 export declare function readRequest(received: unknown): ReadRequest | UnreadableRequest;
 /**
- * The three segments of an operation route, each URL-decoded and none empty
- * (§12.6 refuses an empty-resource route); `undefined` when it is not one.
+ * The three segments of an operation route, each URL-decoded and none empty;
+ * `undefined` when it is not one.
  */
 export declare function operationRouteSegments(path: string): OperationRouteSegments | undefined;

package/dist/protocol/http-request.reader.js

@@ -1,36 +1,14 @@
 import { requestIdOf } from "../runtime/request-id.js";
 import { transportFailure } from "./protocol-failure.js";
 import { adoptedRequestId, normalizeHeaders, protocolIdentityOf, } from "./protocol-headers.js";
-/**
- * Reading a host's request before any route answers it: the request as a
- * value of its declared type, read once; the request id it is answered under
- * (Q13); its headers as one spelling (Q7); its identity headers; and the
- * route paths the protocol owns (§12.1). Shared by the decoders, the absence
- * responder and the contract responder, so each reads a request one way.
- */
-/** `<entrypoint>/_resources/:resource/:family/:variant` (§12.1). */
 const OPERATION_ROUTE = /^\/_resources\/([^/]*)\/([^/]*)\/([^/]*)$/;
-/** `POST <entrypoint>/_transactions` (§12.1). */
 export const TRANSACTIONS_ROUTE = "/_transactions";
-/** `GET <entrypoint>/_contract` (§12.1, §12.5). */
 export const CONTRACT_ROUTE = "/_contract";
-/** The methods an operation or `/_transactions` route accepts: `POST`, only (§12.2). */
 export const POST_ONLY = Object.freeze(["POST"]);
-/** The methods the contract route accepts: `GET`, only (§12.2). */
 export const GET_ONLY = Object.freeze(["GET"]);
-/**
- * Whether a path lies in the protocol's namespace: underscore-prefixed paths
- * beneath the entrypoint are reserved for framework facilities; every other
- * path is the host's (§12.1).
- */
 export function isProtocolPath(path) {
     return path.startsWith("/_");
 }
-/**
- * The host's value read as a request, or — when it is not an
- * `AvProtocolRequest` at all — the `400 A2000` answering it, under a minted
- * id (the director, 2026-10-05).
- */
 export function readRequest(received) {
     const request = wellFormedRequest(received);
     if (request === undefined) {
@@ -45,10 +23,6 @@ export function readRequest(received) {
         protocol: protocolIdentityOf(headers),
     };
 }
-/**
- * The three segments of an operation route, each URL-decoded and none empty
- * (§12.6 refuses an empty-resource route); `undefined` when it is not one.
- */
 export function operationRouteSegments(path) {
     const match = OPERATION_ROUTE.exec(path);
     if (match === null) {
@@ -61,7 +35,6 @@ export function operationRouteSegments(path) {
         ? { resource, family, variant }
         : undefined;
 }
-/** One path segment, URL-decoded once; `undefined` when it is not decodable. */
 function decodeSegment(segment) {
     try {
         return decodeURIComponent(segment);
@@ -70,11 +43,6 @@ function decodeSegment(segment) {
         return undefined;
     }
 }
-/**
- * The answer to a value that is not an `AvProtocolRequest`: `A2000` under a
- * freshly minted id — the value's own headers are not believed, so no id is
- * adopted from them.
- */
 function malformedRequest() {
     const requestId = requestIdOf(undefined);
     return {
@@ -83,20 +51,8 @@ function malformedRequest() {
         requestId,
     };
 }
-/**
- * The host's request, read ONCE into a value of its declared type, or
- * `undefined` when it is not one: not an object, a `method` or `path` that is
- * not text, `headers` that are not a record of text or lists of text, or a
- * `body` of neither arm (Q11) — raw content that is neither text nor bytes
- * has no byte count to measure. Each member is read once, so a getter cannot
- * answer one check and lie to the next, and one that throws — like any trap —
- * makes the request malformed rather than the decoder throw. A parsed body's
- * value is kept as the same object, never read into (§12.3).
- */
 function wellFormedRequest(received) {
     try {
-        // `null` and `undefined` throw here; any other non-object has no
-        // members, so its `method` is not text.
         const { method, path, headers, body } = received;
         const copied = headerRecord(headers);
         const armed = armedBody(body);
@@ -130,7 +86,6 @@ function headerRecord(headers) {
             return undefined;
         }
     }
-    // `fromEntries` defines each member, so a header named `__proto__` stays data.
     return Object.fromEntries(copied);
 }
 function armedBody(body) {

package/dist/protocol/http-response.encoder.d.ts

@@ -7,41 +7,40 @@ import type { TransactionResponse } from "../transactions/transaction-response.j
  * text, and adds nothing of the framework's.
  */
 export type AvProtocolResponse = {
-    /** `AvProtocol.httpStatus` of the envelope's code (§13.2). */
+    /** `AvProtocol.httpStatus` of the envelope's code. */
     readonly status: number;
     /**
      * The headers the framework owns on this response, canonically spelled:
-     * `Content-Type: application/json` and the `Aventara-Request-Id` it echoes
-     * (Q13).
+     * `Content-Type: application/json` and the `Aventara-Request-Id` it echoes.
      */
     readonly headers: Readonly<Record<string, string>>;
-    /** The JSON text of the envelope (§13.1), its data in wire forms (P1). */
+    /** The JSON text of the envelope, its data in wire forms. */
     readonly body: string;
 };
 /**
  * Where an encoder hands the raw failure behind an `A3003` — the binding's
- * diagnostics channel (the director, 2026-10-05) — with the plan step it
- * blames, if any. The wire never carries it (Q5).
+ * diagnostics channel — with the plan step it blames, if any. The wire never
+ * carries it.
  */
 export type UnencodableReport = (error: unknown, operation?: number) => void;
 /**
  * `protocol.encodeOperation(response, requestId)`: one operation's framework
- * response as the HTTP response a host writes. Status is the code's (§13.2);
- * `data` is wire-encoded (P1); `requestId` is echoed as `Aventara-Request-Id`
- * (Q13) — pass the id the request ran under, which the decoder supplies.
+ * response as the HTTP response a host writes. Status is the code's; `data` is
+ * wire-encoded; `requestId` is echoed as `Aventara-Request-Id` — pass the id the
+ * request ran under, which the decoder supplies.
  *
- * Total: a result it cannot encode — and a response whose code is not
- * allocated — answers `A3003` → 500 with the framework's own text, and none of
- * the result reaches the body.
+ * Total: a result it cannot encode — and a response whose code is not allocated —
+ * answers `A3003` → 500 with the framework's own text, and none of the result
+ * reaches the body.
  */
 export declare function encodeOperationResponse(response: OperationResponse, requestId: string, report?: UnencodableReport): AvProtocolResponse;
 /**
  * `protocol.encodeTransaction(response, requestId)`: the same for a plan's
- * response (§14). A committed plan is `200 A1009` — even when it created
- * something (P3) — with each operation's data wire-encoded in plan order by
- * the same walker as {@link encodeOperationResponse}; a rolled-back plan
- * answers its failing operation's own status (Q4). A step whose result cannot
- * be encoded answers `A3003` → 500 naming that step as `cause.operation`, as
- * every internal failure inside a plan does (Q5).
+ * response. A committed plan is `200 A1009` — even when it created something —
+ * with each operation's data wire-encoded in plan order by the same walker as
+ * {@link encodeOperationResponse}; a rolled-back plan answers its failing
+ * operation's own status. A step whose result cannot be encoded answers `A3003` →
+ * 500 naming that step as `cause.operation`, as every internal failure inside a
+ * plan does.
  */
 export declare function encodeTransactionResponse(response: TransactionResponse, requestId: string, report?: UnencodableReport): AvProtocolResponse;

package/dist/protocol/http-response.encoder.js

@@ -4,16 +4,6 @@ import { SERIALIZATION_FAILURE_MESSAGE } from "../runtime/error-boundary.js";
 import { operationFailure, } from "../runtime/operation-response.js";
 import { httpStatus } from "./http-status.table.js";
 import { headers } from "./protocol-headers.js";
-/**
- * `protocol.encodeOperation(response, requestId)`: one operation's framework
- * response as the HTTP response a host writes. Status is the code's (§13.2);
- * `data` is wire-encoded (P1); `requestId` is echoed as `Aventara-Request-Id`
- * (Q13) — pass the id the request ran under, which the decoder supplies.
- *
- * Total: a result it cannot encode — and a response whose code is not
- * allocated — answers `A3003` → 500 with the framework's own text, and none of
- * the result reaches the body.
- */
 export function encodeOperationResponse(response, requestId, report) {
     try {
         return written(response, toWire(response.data, new Set()), requestId);
@@ -23,15 +13,6 @@ export function encodeOperationResponse(response, requestId, report) {
         return written(serializationFailure(), null, requestId);
     }
 }
-/**
- * `protocol.encodeTransaction(response, requestId)`: the same for a plan's
- * response (§14). A committed plan is `200 A1009` — even when it created
- * something (P3) — with each operation's data wire-encoded in plan order by
- * the same walker as {@link encodeOperationResponse}; a rolled-back plan
- * answers its failing operation's own status (Q4). A step whose result cannot
- * be encoded answers `A3003` → 500 naming that step as `cause.operation`, as
- * every internal failure inside a plan does (Q5).
- */
 export function encodeTransactionResponse(response, requestId, report) {
     if (response.code !== "A1009") {
         return encodeOperationResponse(response, requestId, report);
@@ -53,18 +34,12 @@ export function encodeTransactionResponse(response, requestId, report) {
         return written(serializationFailure(step), null, requestId);
     }
 }
-/** The one A3003 envelope: the framework's text, plus the step in a plan. */
 function serializationFailure(operation) {
     return operationFailure("A3003", {
         message: SERIALIZATION_FAILURE_MESSAGE,
         ...(operation === undefined ? {} : { operation }),
     });
 }
-/**
- * Writes an envelope whose data is already in wire form. Throws for a code
- * with no status (only an untyped caller can supply one), which every caller
- * turns into `A3003`.
- */
 function written(response, wireData, requestId) {
     const { code, cause } = response;
     if (!Object.hasOwn(httpStatus, code)) {
@@ -79,37 +54,9 @@ function written(response, wireData, requestId) {
         body: JSON.stringify({ data: wireData, code, cause }),
     };
 }
-/**
- * What the walker throws for a value with no wire form — never past an
- * encoder, which answers `A3003` and hands it to the diagnostics channel, so
- * it names the offending value as its `cause` for the developer.
- */
 function unencodable(value) {
     return new TypeError("A result value has no wire form.", { cause: value });
 }
-/**
- * The P1 wire walker: a result's runtime value as the JSON value the wire
- * carries. Value-directed, with no Contract read: exactly four runtime classes
- * are scalars whose wire form differs from their runtime form (A6), and a
- * `json` value is a `JsonValue`, which contains none of them —
- *
- * - `bigint` → its base-10 string;
- * - `Decimal` (core's) → its decimal string (not through `toJSON`, Q16);
- * - `Date` → `toISOString()`, which must match the datetime wire grammar — an
- *   invalid Date, or a year the grammar's four digits cannot spell, has none;
- * - `Uint8Array` → canonical base64.
- *
- * Everything else must already be JSON: `null`, a boolean, a string, a finite
- * number, a list, or a plain record (prototype `Object.prototype` or `null`).
- * A record member whose value is `undefined` is omitted, as JSON omits it; any
- * other value — `undefined` in a list or a hole, a non-finite number, a
- * function, a symbol, any other object, a cycle — has no wire form, and the
- * walk throws. So does a getter or a proxy that throws; the encoders catch all
- * of it.
- *
- * `ancestors` holds the containers on the current path only, so a shared
- * reference is encoded twice, as JSON writes it, while a cycle is refused.
- */
 function toWire(value, ancestors) {
     switch (typeof value) {
         case "string":
@@ -163,11 +110,6 @@ function toWireList(list, ancestors) {
     }
     return wire;
 }
-/**
- * One list element. A hole has no wire form (JSON would write `null`), and is
- * never filled from the prototype chain; an `undefined` element has none
- * either ({@link toWire}).
- */
 function toWireElement(list, index, ancestors) {
     if (!Object.hasOwn(list, index)) {
         throw unencodable(list);
@@ -186,6 +128,5 @@ function toWireRecord(record, ancestors) {
             members.push([key, toWire(member, ancestors)]);
         }
     }
-    // `fromEntries` defines each member, so an own `__proto__` key stays data.
     return Object.fromEntries(members);
 }

package/dist/protocol/http-status.table.d.ts

@@ -1,18 +1,14 @@
 import type { OperationCode } from "../runtime/operation-response.js";
 /**
- * `AvProtocol.httpStatus` — the HTTP status each A-code carries (§13.2's
- * "default HTTP" column), as passive data.
+ * `AvProtocol.httpStatus` — the HTTP status each A-code carries, as passive data.
  *
- * Status is a function of the code alone (N14): §13.2 gives every code exactly
- * one status, and its success table's two 201s are exactly `A1002` and `A1003`.
- * So this one table serves both encoders — an operation's response and a
- * plan's — and a rolled-back plan answers its failing operation's own status
- * (Q4). The status is the coarse signal; the A-code is the exact one.
+ * So this one table serves both encoders — an operation's response and a plan's —
+ * and a rolled-back plan answers its failing operation's own status. The status is
+ * the coarse signal; the A-code is the exact one.
  *
- * Total by type: the literal `satisfies` the mapped type over `OperationCode`,
- * so a code added to core does not compile until its status is written here.
- * Passive (P5): numbers only, frozen, emitted by value where a consumer needs
- * it.
+ * Total by type: the literal `satisfies` the mapped type over `OperationCode`, so
+ * a code added to core does not compile until its status is written here. Passive:
+ * numbers only, frozen, emitted by value where a consumer needs it.
  */
 export declare const httpStatus: {
     readonly [C in OperationCode]: number;

package/dist/protocol/http-status.table.js

@@ -1,18 +1,3 @@
-/**
- * `AvProtocol.httpStatus` — the HTTP status each A-code carries (§13.2's
- * "default HTTP" column), as passive data.
- *
- * Status is a function of the code alone (N14): §13.2 gives every code exactly
- * one status, and its success table's two 201s are exactly `A1002` and `A1003`.
- * So this one table serves both encoders — an operation's response and a
- * plan's — and a rolled-back plan answers its failing operation's own status
- * (Q4). The status is the coarse signal; the A-code is the exact one.
- *
- * Total by type: the literal `satisfies` the mapped type over `OperationCode`,
- * so a code added to core does not compile until its status is written here.
- * Passive (P5): numbers only, frozen, emitted by value where a consumer needs
- * it.
- */
 export const httpStatus = Object.freeze({
     A1000: 200,
     A1001: 200,
@@ -43,6 +28,7 @@ export const httpStatus = Object.freeze({
     A3001: 500,
     A3002: 500,
     A3003: 500,
+    A3004: 500,
     A4000: 401,
     A4001: 403,
     A4002: 403,