castrum 0.7.0 → 0.9.0

package/src/ingress/context.ts

@@ -0,0 +1,136 @@
+// src/ingress/context.ts — Result snapshotting + synthetic/error context
+// builders for the async ingress API.
+
+import type { ResponseBuildContext } from './headers/fast-templates'
+import { buildTerminalResponse } from './response/terminal'
+import { ERR_CODE_INTERNAL, ERR_CODE_RATE_LIMITED, HV_JSON, HV_CORS_SIMPLE } from './constants'
+import type { IngressOptions, IngressResult, IngressContext } from './types'
+
+const EMPTY_BODY = new Uint8Array(0)
+
+/**
+ * Deep-snapshot a result so the caller can use it after `run()` returns.
+ *
+ * Note on aliasing: the returned `body` field aliases the request body buffer
+ * (`r.body`) — it is NOT copied — while `bodyJson()` returns a stable copy
+ * (captured once at snapshot time, safe after the live result is invalidated).
+ * In the async `createIngress` path the aliased buffer is the fully-
+ * materialized request body, which lives as long as the request and is never
+ * reused, so the alias is safe. Treat `body` as read-only; use `bodyJson()`
+ * for a defensive copy.
+ */
+export function snapshotResult(r: IngressResult): IngressResult {
+  const cookies = r.cookiesJson()
+  const query = r.queryJson()
+  const bodyJson = r.bodyJson().slice()
+  const body = r.body
+
+  return {
+    status: r.status,
+    verdict: r.verdict,
+    flags: r.flags,
+    errorCode: r.errorCode,
+    terminal: r.terminal,
+    ok: r.ok,
+    https: r.https,
+    trustedProxy: r.trustedProxy,
+    hasCookies: r.hasCookies,
+    hasQuery: r.hasQuery,
+    bodyValidJson: r.bodyValidJson,
+    schemaValid: r.schemaValid,
+    corsAllowed: r.corsAllowed,
+    isPreflight: r.isPreflight,
+    rateLimited: r.rateLimited,
+    rateLimit: r.rateLimit,
+    rateRemaining: r.rateRemaining,
+    rateResetMs: r.rateResetMs,
+    retryAfterMs: r.retryAfterMs,
+    body,
+    headerVariant: r.headerVariant,
+    requestId: r.requestId,
+    bodyTruncated: r.bodyTruncated,
+
+    cookiesJson: () => cookies,
+    queryJson: () => query,
+    bodyJson: () => bodyJson,
+  }
+}
+
+/** Build a synthetic (terminal) context for body-size / error short-circuits. */
+export function syntheticContext(
+  req: Request,
+  requestId: string,
+  options: IngressOptions,
+  responseCtx: ResponseBuildContext,
+  status: number,
+  errorCode: number,
+): IngressContext {
+  const corsAllowed = staticCorsAllowed(options, req)
+  const variant = HV_JSON | (corsAllowed ? HV_CORS_SIMPLE : 0)
+
+  const base: IngressResult = {
+    status,
+    verdict: 1,
+    flags: 0,
+    errorCode,
+    terminal: true,
+    ok: false,
+    https: options.https === true,
+    trustedProxy: options.trustProxy === true || options.trustedProxies?.enabled === true,
+    hasCookies: false,
+    hasQuery: false,
+    bodyValidJson: false,
+    schemaValid: false,
+    corsAllowed,
+    isPreflight: false,
+    rateLimited: errorCode === ERR_CODE_RATE_LIMITED,
+    rateLimit: options.rateLimit?.limit ?? 0,
+    rateRemaining: 0,
+    rateResetMs: 0,
+    retryAfterMs: 0,
+    body: EMPTY_BODY,
+    headerVariant: variant,
+    requestId,
+    bodyTruncated: false,
+
+    cookiesJson: () => '{}',
+    queryJson: () => '{}',
+    bodyJson: () => EMPTY_BODY,
+  }
+
+  return {
+    ...base,
+    response: buildTerminalResponse(responseCtx, base, req, requestId),
+  }
+}
+
+/** Build the internal-error context (status 500). */
+export function internalContext(
+  req: Request,
+  requestId: string,
+  options: IngressOptions,
+  responseCtx: ResponseBuildContext,
+): IngressContext {
+  return syntheticContext(req, requestId, options, responseCtx, 500, ERR_CODE_INTERNAL)
+}
+
+/** Statically determine whether the configured CORS policy allows `req`. */
+export function staticCorsAllowed(options: IngressOptions, req: Request): boolean {
+  const cors = options.cors
+  if (!cors) return false
+
+  const origin = req.headers.get('origin')
+  if (!origin) return false
+
+  const list = cors.allowOrigin
+
+  if (!list || list.length === 0) {
+    return cors.allowCredentials !== true
+  }
+
+  if (list.includes('*')) {
+    return cors.allowCredentials !== true
+  }
+
+  return list.includes(origin)
+}

package/src/ingress/decode/baked-result.ts

@@ -0,0 +1,121 @@
+// src/ingress/decode/baked-result.ts — Zero-alloc result decoder (pre-baked
+// path).
+//
+// Decodes the native Ingress packed output (OUT_* layout in ./constants.ts)
+// into the pre-baked handler result, which carries the benchmark wire format
+// ({"ok":false,"error":{...}}).
+//
+// NOTE: this is the pre-baked-path decoder with its own status normalization.
+// The fast path has its own decoder (./fast-result.ts) — do not unify them
+// (see AGENTS.md). The two decoders DO share their section/rate-limit plumbing
+// via ./result-base.ts.
+
+import {
+  OUT_VERDICT,
+  OUT_FLAGS,
+  OUT_RATE_LIMIT,
+  OUT_RATE_REMAINING,
+  OUT_COOKIES_JSON_LEN,
+  OUT_QUERY_JSON_LEN,
+  OUT_HEADER_VARIANT,
+  OUT_BODY_JSON_LEN,
+  OUT_DATA_START,
+  FLAG_BODY_VALID_JSON,
+  FLAG_SCHEMA_VALID,
+  FLAG_CORS_ALLOWED,
+  FLAG_IS_PREFLIGHT,
+  FLAG_RATE_LIMITED,
+  FLAG_TRUSTED_PROXY,
+  FLAG_BODY_TRUNCATED,
+  HV_JSON,
+  ERR_CODE_INTERNAL as ERROR_CODE_INTERNAL,
+} from '../constants'
+import { sectionLayout } from './packed-sections'
+import { isValidResponseStatus } from '../status'
+import { IngressResultBase } from './result-base'
+
+/** Zero-alloc, reusable result decoder for the pre-baked handler path. */
+export class BakedIngressResult extends IngressResultBase {
+  refresh(buf: Uint8Array, body: Uint8Array, view: DataView): void {
+    // Defensive: the native core always writes the full fixed header
+    // (>= OUT_DATA_START bytes) before returning `written`. The cached
+    // whole-buffer DataView (see viewForArrayBuffer) would otherwise decode
+    // stale bytes if this contract is ever violated — treat as internal error.
+    if (buf.byteLength < OUT_DATA_START) {
+      this.setInternalError()
+      return
+    }
+    this.body = body
+
+    const h0 = view.getUint32(OUT_VERDICT, true)
+    const h1 = view.getUint32(OUT_FLAGS, true)
+    const h2 = view.getUint32(OUT_RATE_LIMIT, true)
+    const h3 = view.getUint32(OUT_RATE_REMAINING, true)
+
+    const cookiesLenRaw = view.getUint32(OUT_COOKIES_JSON_LEN, true)
+    const queryLenRaw = view.getUint32(OUT_QUERY_JSON_LEN, true)
+    const headerVariant = view.getUint8(OUT_HEADER_VARIANT)
+    const bodyJsonLenRaw = view.getUint32(OUT_BODY_JSON_LEN, true)
+
+    // Bounds-checked section offsets shared with the fast decoder: a
+    // malformed/truncated buffer can never produce slices past its end.
+    const layout = sectionLayout(buf.byteLength, cookiesLenRaw, queryLenRaw, bodyJsonLenRaw)
+
+    if (h0 === 0 && h1 === 0) {
+      this.verdict = 1
+      this.errorCode = ERROR_CODE_INTERNAL
+      this.status = 500
+    } else {
+      this.verdict = h0 & 0xff
+      this.errorCode = (h0 >>> 8) & 0xff
+
+      const rawStatus = (h0 >>> 16) & 0xffff
+      // Reuse the shared status-validity helper instead of re-inlining the
+      // 101/200-599 check (single source of truth in ../status.ts).
+      this.status = isValidResponseStatus(rawStatus) ? rawStatus : 500
+    }
+
+    const flags = h1
+
+    this.rateRemaining = h3
+
+    this.setRateWindow(h2, (flags & FLAG_RATE_LIMITED) !== 0, view)
+
+    this.headerVariant = headerVariant
+
+    // The baked path trusts the already-clamped section lengths, so pass the
+    // safe body len here (the fast path re-checks bounds on read instead).
+    this.setSections(buf, layout, layout.safeBodyJsonLen)
+
+    this.updateOkTerminal()
+
+    this.isPreflight = (flags & FLAG_IS_PREFLIGHT) !== 0
+    this.corsAllowed = (flags & FLAG_CORS_ALLOWED) !== 0
+    this.rateLimited = (flags & FLAG_RATE_LIMITED) !== 0
+    this.trustedProxy = (flags & FLAG_TRUSTED_PROXY) !== 0
+    this.bodyValidJson = (flags & FLAG_BODY_VALID_JSON) !== 0
+    this.schemaValid = (flags & FLAG_SCHEMA_VALID) !== 0
+
+    this.bodyTruncated = (flags & FLAG_BODY_TRUNCATED) !== 0 || layout.truncated
+  }
+
+  invalidate(): void {
+    // The baked empty state is neutral (0/0/0) — exactly what resetShared sets.
+    this.resetShared()
+  }
+
+  setInternalError(): void {
+    this.invalidate()
+    this.status = 500
+    this.verdict = 1
+    this.errorCode = ERROR_CODE_INTERNAL
+    this.headerVariant = HV_JSON
+    this.terminal = true
+    this.ok = false
+  }
+
+  bodyJson(copy: boolean): Uint8Array {
+    const slice = this.bodyJsonSlice()
+    return (copy ? slice.slice() : slice) as Uint8Array
+  }
+}

package/src/ingress/decode/fast-result.ts

@@ -0,0 +1,160 @@
+// src/ingress/decode/fast-result.ts — Zero-alloc result decoder (fast path).
+//
+// Decodes the native Ingress packed output (OUT_* layout in ./constants.ts)
+// lazily: slices are stored, strings are decoded only on demand via
+// cookiesJson()/queryJson()/bodyJson().
+//
+// NOTE: this is the fast-path decoder ({"error":{...}} wire format). The
+// pre-baked path has its own decoder (./baked-result.ts) with a different
+// wire format and status normalization — do not unify them (see AGENTS.md).
+// The two decoders DO share their section/rate-limit plumbing via
+// ./result-base.ts.
+
+import { viewForArrayBuffer } from '../../shared/bytes'
+import {
+  OUT_VERDICT,
+  OUT_ERROR_CODE,
+  OUT_STATUS,
+  OUT_FLAGS,
+  OUT_RATE_LIMIT,
+  OUT_RATE_REMAINING,
+  OUT_COOKIES_JSON_LEN,
+  OUT_QUERY_JSON_LEN,
+  OUT_HEADER_VARIANT,
+  OUT_BODY_JSON_LEN,
+  OUT_DATA_START,
+  FLAG_HAS_COOKIES,
+  FLAG_HAS_QUERY,
+  FLAG_BODY_VALID_JSON,
+  FLAG_SCHEMA_VALID,
+  FLAG_CORS_ALLOWED,
+  FLAG_IS_PREFLIGHT,
+  FLAG_RATE_LIMITED,
+  FLAG_HTTPS,
+  FLAG_TRUSTED_PROXY,
+  FLAG_BODY_TRUNCATED,
+  ERR_CODE_INTERNAL,
+} from '../constants'
+import { normalizeResponseStatus } from '../status'
+import { sectionLayout } from './packed-sections'
+import { IngressResultBase } from './result-base'
+
+/** Zero-alloc, lazy-decoding view over a native Ingress output buffer. */
+export class FastIngressResult extends IngressResultBase {
+  // Fast path's empty state is an internal-error shape (500 / verdict 1 /
+  // internal error-code). The baked decoder's empty state is neutral (0/0/0).
+  override status = 500
+  override verdict = 1
+  override errorCode = ERR_CODE_INTERNAL
+  flags = 0
+  https = false
+  hasCookies = false
+  hasQuery = false
+  rateLimit = 0
+  requestId = ''
+
+  refresh(buf: Uint8Array, body: Uint8Array, requestId: string): void {
+    // Defensive: the native core always writes the full fixed header
+    // (>= OUT_DATA_START bytes) before returning `written`. The cached
+    // whole-buffer DataView below would otherwise decode stale bytes if this
+    // contract is ever violated — treat it as an internal error instead.
+    if (buf.byteLength < OUT_DATA_START) {
+      this.setInternalError(requestId)
+      return
+    }
+    this._buf = buf
+    this.body = body
+    this.requestId = requestId
+
+    // Cached per-ArrayBuffer DataView (respects the subarray byteOffset): no
+    // per-request view alloc on the offset-0 production buffers.
+    const dv = viewForArrayBuffer(buf.buffer, buf.byteOffset)
+
+    const rawVerdict = dv.getUint8(OUT_VERDICT)
+    const rawErrorCode = dv.getUint8(OUT_ERROR_CODE)
+    const rawStatus = dv.getUint16(OUT_STATUS, true)
+    const flags = dv.getUint32(OUT_FLAGS, true)
+
+    const rateLimit = dv.getUint32(OUT_RATE_LIMIT, true)
+    const rateRemaining = dv.getUint32(OUT_RATE_REMAINING, true)
+
+    const cookiesJsonLen = dv.getUint32(OUT_COOKIES_JSON_LEN, true)
+    const queryJsonLen = dv.getUint32(OUT_QUERY_JSON_LEN, true)
+
+    const headerVariant = dv.getUint8(OUT_HEADER_VARIANT)
+    const bodyJsonLen = dv.getUint32(OUT_BODY_JSON_LEN, true)
+
+    const preflightAllowed = (flags & FLAG_IS_PREFLIGHT) !== 0 && (flags & FLAG_CORS_ALLOWED) !== 0
+
+    const normalizedStatus = normalizeResponseStatus(rawStatus, rawErrorCode, preflightAllowed)
+
+    const uninitialized = rawVerdict === 0 && rawErrorCode === 0 && rawStatus === 0 && flags === 0
+
+    if (uninitialized) {
+      this.status = 500
+      this.verdict = 1
+      this.errorCode = ERR_CODE_INTERNAL
+    } else {
+      this.status = normalizedStatus
+      this.verdict = rawVerdict
+      this.errorCode = rawErrorCode
+    }
+
+    this.flags = flags
+    this.rateLimit = rateLimit
+    this.rateRemaining = rateRemaining
+
+    this.setRateWindow(rateLimit, (flags & FLAG_RATE_LIMITED) !== 0, dv)
+
+    this.headerVariant = headerVariant
+
+    this.updateOkTerminal()
+
+    this.https = (flags & FLAG_HTTPS) !== 0
+    this.trustedProxy = (flags & FLAG_TRUSTED_PROXY) !== 0
+    this.hasCookies = (flags & FLAG_HAS_COOKIES) !== 0
+    this.hasQuery = (flags & FLAG_HAS_QUERY) !== 0
+    this.bodyValidJson = (flags & FLAG_BODY_VALID_JSON) !== 0
+    this.schemaValid = (flags & FLAG_SCHEMA_VALID) !== 0
+    this.corsAllowed = (flags & FLAG_CORS_ALLOWED) !== 0
+    this.isPreflight = (flags & FLAG_IS_PREFLIGHT) !== 0
+    this.rateLimited = (flags & FLAG_RATE_LIMITED) !== 0
+
+    // Bounds-checked section offsets shared with the pre-baked decoder: a
+    // malformed/truncated buffer can never produce slices past its end.
+    const layout = sectionLayout(buf.byteLength, cookiesJsonLen, queryJsonLen, bodyJsonLen)
+
+    // Store slices for lazy decode instead of eagerly decoding strings. The
+    // fast path trusts the RAW declared body length and re-checks bounds on
+    // read (bodyJson()), so pass the raw declared length here.
+    this.setSections(buf, layout, bodyJsonLen)
+
+    // Parity with the baked decoder: any declared section (cookies, query,
+    // OR body) that overran the buffer counts as truncated.
+    this.bodyTruncated = (flags & FLAG_BODY_TRUNCATED) !== 0 || layout.truncated
+  }
+
+  invalidate(): void {
+    this.resetShared()
+    // Fast path's empty state is an internal-error shape (500/1/internal).
+    this.status = 500
+    this.verdict = 1
+    this.errorCode = ERR_CODE_INTERNAL
+    this.flags = 0
+    this.https = false
+    this.hasCookies = false
+    this.hasQuery = false
+    this.rateLimit = 0
+    this.requestId = ''
+  }
+
+  setInternalError(requestId: string): void {
+    this.invalidate()
+    this.requestId = requestId
+  }
+
+  /** Bounds-checked body-JSON section, or an empty view when absent. */
+  bodyJson(): Uint8Array {
+    return this.bodyJsonSlice()
+  }
+}

package/src/ingress/decode/packed-sections.ts

@@ -0,0 +1,56 @@
+// src/ingress/decode/packed-sections.ts — Shared bounds-checked section layout.
+//
+// Both decoders (fast-result.ts and baked-result.ts) walk the same OUT_* data
+// region: [cookies JSON][query JSON][body JSON], each u32-length-prefixed in
+// the fixed header. This helper centralizes the bounds-checked offset math so
+// a malformed/truncated buffer can never produce slices past its end.
+
+import { OUT_DATA_START } from '../constants'
+
+/** Bounds-checked section offsets for one ingress output buffer. */
+export interface PackedSectionLayout {
+  /** Cookie-JSON length clamped to the buffer (0 if none / out of range). */
+  safeCookiesLen: number
+  /** Byte offset where the query-JSON section begins. */
+  queryStart: number
+  /** Query-JSON length clamped to the buffer (0 if none / out of range). */
+  safeQueryLen: number
+  /** Byte offset where the body-JSON section begins. */
+  bodyJsonStart: number
+  /** Body-JSON length clamped to the buffer (0 if none / out of range). */
+  safeBodyJsonLen: number
+  /** Whether any declared section length overran the buffer. */
+  truncated: boolean
+}
+
+/**
+ * Compute bounds-checked section offsets for an ingress output buffer.
+ *
+ * Given the raw u32 section lengths (already read from the fixed header) and
+ * the actual buffer length, returns safe (clamped-to-buffer) lengths and the
+ * body-JSON start offset. Any length that would run past the end of the
+ * buffer is clamped to 0 and reported via `truncated`, so callers never read
+ * stale or out-of-bounds bytes.
+ */
+export function sectionLayout(
+  bufLen: number,
+  cookiesLen: number,
+  queryLen: number,
+  bodyLen: number,
+): PackedSectionLayout {
+  const safeCookiesLen = cookiesLen > 0 && OUT_DATA_START + cookiesLen <= bufLen ? cookiesLen : 0
+  const queryStart = OUT_DATA_START + safeCookiesLen
+  const safeQueryLen = queryLen > 0 && queryStart + queryLen <= bufLen ? queryLen : 0
+  const bodyJsonStart = queryStart + safeQueryLen
+  const safeBodyJsonLen = bodyLen > 0 && bodyJsonStart + bodyLen <= bufLen ? bodyLen : 0
+
+  return {
+    safeCookiesLen,
+    queryStart,
+    safeQueryLen,
+    bodyJsonStart,
+    safeBodyJsonLen,
+    truncated:
+      safeCookiesLen !== cookiesLen || safeQueryLen !== queryLen || safeBodyJsonLen !== bodyLen,
+  }
+}

package/src/ingress/decode/result-base.ts

@@ -0,0 +1,172 @@
+// src/ingress/decode/result-base.ts — Shared zero-alloc decoder plumbing.
+//
+// Both ingress result decoders (fast-result.ts, baked-result.ts) walk the SAME
+// native OUT_* layout and share: lazy cookie/query JSON section decoding, the
+// bounds-checked body-JSON slice, the rate-limit window fields, and the
+// flag-derived booleans. This base holds that identical plumbing so the two
+// paths cannot drift on section handling.
+//
+// The WIRE FORMAT and STATUS NORMALIZATION intentionally differ between the
+// two decoders ({"error":{...}} fast path vs {"ok":false,...} baked path) —
+// those stay in the subclasses (see AGENTS.md; do not unify them).
+
+import { decoder } from '../../shared/bytes'
+import { OUT_DATA_START, OUT_RATE_RESET, OUT_RETRY_AFTER } from '../constants'
+import type { PackedSectionLayout } from './packed-sections'
+
+const EMPTY_BODY = new Uint8Array(0)
+
+/**
+ * Zero-alloc, reusable result decoder shared base.
+ *
+ * Holds the fields and lazy-decoding helpers that both the fast-path
+ * (`FastIngressResult`) and pre-baked (`BakedIngressResult`) decoders consume
+ * identically from the native OUT_* output buffer. Concrete subclasses own the
+ * status normalization, the exposed extras (requestId, flags, ...) and the
+ * wire-format-specific body/error accessors.
+ */
+export abstract class IngressResultBase {
+  /** Raw native verdict byte (0 = accepted). */
+  verdict = 0
+  /** Raw native error-code byte. */
+  errorCode = 0
+  /** Normalized HTTP status. */
+  status = 0
+  /** Header template variant byte emitted by the native core. */
+  headerVariant = 0
+  /** Remaining rate-limit budget (count). */
+  rateRemaining = 0
+  /** Rate-limit window reset (ms epoch). */
+  rateResetMs = 0
+  /** Retry-After value (ms). */
+  retryAfterMs = 0
+  /** True when the pipeline returned a terminal (error) verdict. */
+  terminal = true
+  /** True when the pipeline accepted the request (verdict 0 + 2xx/3xx). */
+  ok = false
+  /** True when the request was a CORS preflight. */
+  isPreflight = false
+  /** True when the CORS engine allowed the request origin. */
+  corsAllowed = false
+  /** True when the request was rate-limited. */
+  rateLimited = false
+  /** True when the request came from a trusted proxy. */
+  trustedProxy = false
+  /** True when the request body parsed as valid JSON. */
+  bodyValidJson = false
+  /** True when the request body validated against the ingress schema. */
+  schemaValid = false
+  /** True when a declared output section overran the buffer. */
+  bodyTruncated = false
+  /** Request body bytes (may be an empty view). */
+  body: Uint8Array = EMPTY_BODY
+
+  protected _buf: Uint8Array = EMPTY_BODY
+  protected _bodyJsonStart = OUT_DATA_START
+  protected _bodyJsonLen = 0
+  private _cookiesBuf: Uint8Array | null = null
+  private _queryBuf: Uint8Array | null = null
+  private _cookiesDecoded: string | null = null
+  private _queryDecoded: string | null = null
+
+  /** Reset the shared fields to their empty state (call from subclass `invalidate`). */
+  protected resetShared(): void {
+    this.verdict = 0
+    this.errorCode = 0
+    this.status = 0
+    this.headerVariant = 0
+    this.rateRemaining = 0
+    this.rateResetMs = 0
+    this.retryAfterMs = 0
+    this.terminal = true
+    this.ok = false
+    this.isPreflight = false
+    this.corsAllowed = false
+    this.rateLimited = false
+    this.trustedProxy = false
+    this.bodyValidJson = false
+    this.schemaValid = false
+    this.bodyTruncated = false
+    this.body = EMPTY_BODY
+    this._buf = EMPTY_BODY
+    this._bodyJsonStart = OUT_DATA_START
+    this._bodyJsonLen = 0
+    this._cookiesBuf = null
+    this._queryBuf = null
+    this._cookiesDecoded = null
+    this._queryDecoded = null
+  }
+
+  /** Recompute `terminal`/`ok` from the (subclass-set) verdict + status. */
+  protected updateOkTerminal(): void {
+    this.terminal = this.verdict !== 0 || this.status >= 400
+    this.ok = this.verdict === 0 && this.status >= 200 && this.status < 400
+  }
+
+  /**
+   * Store the rate-limit window fields. Both decoders read the same OUT_*
+   * slots and gate them on the same conditions (a positive budget OR the
+   * rate-limited flag), so the read cannot drift between paths.
+   */
+  protected setRateWindow(rateLimit: number, rateLimited: boolean, view: DataView): void {
+    if (rateLimit > 0 || rateLimited) {
+      this.rateResetMs = Number(view.getBigUint64(OUT_RATE_RESET, true))
+      this.retryAfterMs = Number(view.getBigUint64(OUT_RETRY_AFTER, true))
+    } else {
+      this.rateResetMs = 0
+      this.retryAfterMs = 0
+    }
+  }
+
+  /**
+   * Store the bounds-checked cookie/query/body JSON sections from `layout`.
+   *
+   * `bodyJsonLen` is the body-JSON length to trust for `bodyJson()`: the fast
+   * path passes the RAW declared length (it re-checks bounds on read), the
+   * baked path passes the already-clamped `layout.safeBodyJsonLen`. Sections
+   * are stored as slices and decoded lazily by `cookiesJson()`/`queryJson()`.
+   */
+  protected setSections(buf: Uint8Array, layout: PackedSectionLayout, bodyJsonLen: number): void {
+    this._buf = buf
+    this._bodyJsonStart = layout.bodyJsonStart
+    this._bodyJsonLen = bodyJsonLen
+    this._cookiesBuf =
+      layout.safeCookiesLen > 0
+        ? buf.subarray(OUT_DATA_START, OUT_DATA_START + layout.safeCookiesLen)
+        : null
+    this._cookiesDecoded = null
+    this._queryBuf =
+      layout.safeQueryLen > 0
+        ? buf.subarray(layout.queryStart, layout.queryStart + layout.safeQueryLen)
+        : null
+    this._queryDecoded = null
+  }
+
+  /** Decoded cookies-JSON section, or `"{}"` when absent. */
+  cookiesJson(): string {
+    if (this._cookiesDecoded !== null) return this._cookiesDecoded
+    if (this._cookiesBuf !== null) {
+      this._cookiesDecoded = decoder.decode(this._cookiesBuf)
+      return this._cookiesDecoded
+    }
+    return '{}'
+  }
+
+  /** Decoded query-JSON section, or `"{}"` when absent. */
+  queryJson(): string {
+    if (this._queryDecoded !== null) return this._queryDecoded
+    if (this._queryBuf !== null) {
+      this._queryDecoded = decoder.decode(this._queryBuf)
+      return this._queryDecoded
+    }
+    return '{}'
+  }
+
+  /** Bounds-checked body-JSON slice (empty when absent / out of range). */
+  protected bodyJsonSlice(): Uint8Array {
+    if (this._bodyJsonLen === 0) return EMPTY_BODY
+    const end = this._bodyJsonStart + this._bodyJsonLen
+    if (end > this._buf.byteLength) return EMPTY_BODY
+    return this._buf.subarray(this._bodyJsonStart, end)
+  }
+}