@plurnk/plurnk-schemes-http 1.3.12 → 1.5.0

package/dist/Http.js

@@ -1,57 +1,151 @@
-// http(s):// scheme handler — the first greenfield `@plurnk/plurnk-schemes-*`
-// sibling, authored entirely against the stable SchemeCtx contract. It never
-// imports private service modules or depends on database layout.
-//
-// Surface — the HTTP method is the OP (grammar#46): READ→GET, SEND→POST,
-// EDIT→PUT, KILL→DELETE. Every request streams its response the same way
-// (102 Processing now; the subscription accumulates; the model reads next turn).
-//   READ(http(s)://host/path)   — GET. HTML is rendered; else raw bytes stream.
-//   SEND[200](http(s)://...)    — POST the body; response streams back.
-//   EDIT(http(s)://...):body:   — PUT the body (full-resource replace; no `<L>`).
-//   KILL(http(s)://...)         — DELETE the resource.
-//   SEND[499](http(s)://...)    — cancel an in-flight request (abort the fetch).
-//   SEND[410](http(s)://...)    — delete the locally cached response entry
-//                                 (loop disposition, NOT an HTTP DELETE — that's KILL).
-//
-// Request headers ride IN the target as trailing `{Key: value}` blocks
-// (grammar#46 — `UrlPath.headers`, ordered pairs), one header per block:
-//   READ(https://api.x/v1{Authorization: Bearer T}{Accept: application/json})
-// The SEND `[code]` is loop disposition (102/200/…), never the HTTP status —
-// the real 2xx/4xx comes back in the response `header`/`body` channels.
-//
-// `fetch` is the scheme's purpose. Node owns acquisition; eventsource-parser
-// owns the WHATWG event-stream framing used by SSE responses.
+// HTTP(S) handler. Operation-to-method semantics live in {§op-surface};
+// acquisition, materialization, publication, and query flow live in
+// {§http-lifecycle}. The implementation depends only on SchemeCtx capabilities.
 var _a;
 import { createParser } from "eventsource-parser";
-import { Results } from "@plurnk/plurnk-schemes";
+import { MimetypeClassifier, NetworkAddress, ProjectionInputLimitError, Results, } from "@plurnk/plurnk-schemes";
 import { readFile } from "node:fs/promises";
-import Browser, { BROWSER_UA, requireNumEnv } from "./Browser.js";
-import WebFetcher from "./WebFetcher.js";
+import ErrorDetail from "./ErrorDetail.js";
+import WebFetcher, { DEFAULT_WEB_UA, CACHE_VARIANT_HEADER, MATERIALIZER_ID_HEADER, PROJECTION_ID_HEADER, TAVILY_CREDITS_HEADER, TAVILY_REQUEST_ID_HEADER, cacheVariantEvidence, classifyCacheVariant, WebMaterializationError, } from "./WebFetcher.js";
+import { responseMimetype } from "./ContentType.js";
+import { requireNonNegativeIntegerEnv as requireNumEnv } from "./Config.js";
 // The channel the response body streams into, and the header metadata channel.
 const BODY = "body";
 const HEADER = "header";
-// Materialization stamp line in the HEADER channel — the ONE timestamp the
-// freshness predicate reads (SPEC §revalidation). Namespaced so it can never
-// collide with a real response header.
+// Package-owned metadata appended after untrusted origin headers. Readers take
+// the last value so an origin using the same field name cannot override it.
 const FETCHED_AT = "x-plurnk-fetched-at";
-// Deep doc lives in `docs/http.md` (the constellation's docs/<name>.md
-// convention) and is loaded into the manifest at module init — the contract
-// field stays a plain string; only the authoring source moves out of line.
-// `../docs/http.md` resolves identically from src/ (test) and dist/ (published):
-// both sit one level under the package root. Missing file → fail-hard at import.
+const REQUEST_METHOD = "x-plurnk-request-method";
+const DELTA_SECONDS_LIMIT = 2147483648n;
+const BODY_PROCESSING_FIELDS = new Set([
+    "content-encoding",
+    "content-length",
+    "content-range",
+    "content-type",
+]);
+const splitHttpList = (value) => {
+    const members = [];
+    let start = 0;
+    let quoted = false;
+    let escaped = false;
+    for (let index = 0; index < value.length; index += 1) {
+        const character = value[index];
+        if (quoted) {
+            if (escaped)
+                escaped = false;
+            else if (character === "\\")
+                escaped = true;
+            else if (character === '"')
+                quoted = false;
+        }
+        else if (character === '"') {
+            quoted = true;
+        }
+        else if (character === ",") {
+            members.push(value.slice(start, index).trim());
+            start = index + 1;
+        }
+    }
+    members.push(value.slice(start).trim());
+    return members.filter((member) => member.length > 0);
+};
+const cacheDirective = (member) => {
+    const equals = member.indexOf("=");
+    const name = member.slice(0, equals < 0 ? undefined : equals).trim().toLowerCase();
+    if (!/^[!#$%&'*+.^_`|~0-9a-z-]+$/.test(name))
+        return null;
+    if (equals < 0)
+        return { name };
+    return { name, argument: member.slice(equals + 1).trim() };
+};
+const deltaMilliseconds = (argument) => {
+    if (argument === undefined)
+        return null;
+    const match = /^(?:([0-9]+)|"([0-9]+)")$/.exec(argument);
+    const digits = match?.[1] ?? match?.[2];
+    if (digits === undefined)
+        return null;
+    const seconds = BigInt(digits);
+    return Number(seconds > DELTA_SECONDS_LIMIT ? DELTA_SECONDS_LIMIT : seconds) * 1000;
+};
+const lastHeaderValue = (header, name) => {
+    const lines = header.split(/\r?\n/);
+    for (let index = lines.length - 1; index >= 0; index -= 1) {
+        const line = lines[index];
+        const colon = line.indexOf(":");
+        if (colon < 0 || line.slice(0, colon).trim().toLowerCase() !== name)
+            continue;
+        return line.slice(colon + 1).trim();
+    }
+    return undefined;
+};
+const entityTag = (value) => {
+    const match = /^(W\/)?"([\x21\x23-\x7e\x80-\xff]*)"$/.exec(value);
+    return match === null
+        ? null
+        : { weak: match[1] !== undefined, opaque: match[2] };
+};
+const MONTHS = [
+    "Jan", "Feb", "Mar", "Apr", "May", "Jun",
+    "Jul", "Aug", "Sep", "Oct", "Nov", "Dec",
+];
+const WEEKDAYS = ["Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"];
+const IMF_FIXDATE = /^(Sun|Mon|Tue|Wed|Thu|Fri|Sat), ([0-9]{2}) (Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec) ([0-9]{4}) ([0-9]{2}):([0-9]{2}):([0-9]{2}) GMT$/;
+const RFC850_DATE = /^(Sunday|Monday|Tuesday|Wednesday|Thursday|Friday|Saturday), ([0-9]{2})-(Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec)-([0-9]{2}) ([0-9]{2}):([0-9]{2}):([0-9]{2}) GMT$/;
+const ASCTIME_DATE = /^(Sun|Mon|Tue|Wed|Thu|Fri|Sat) (Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec) (?: ([0-9])|([0-9]{2})) ([0-9]{2}):([0-9]{2}):([0-9]{2}) ([0-9]{4})$/;
+const utcHttpDate = (weekday, day, month, year, hour, minute, second) => {
+    const monthIndex = MONTHS.indexOf(month);
+    const weekdayIndex = WEEKDAYS.indexOf(weekday.slice(0, 3));
+    const numericDay = Number(day);
+    const numericHour = Number(hour);
+    const numericMinute = Number(minute);
+    const numericSecond = Number(second);
+    if (monthIndex < 0 || weekdayIndex < 0)
+        return null;
+    const date = new Date(0);
+    date.setUTCFullYear(year, monthIndex, numericDay);
+    date.setUTCHours(numericHour, numericMinute, numericSecond, 0);
+    return date.getUTCFullYear() === year
+        && date.getUTCMonth() === monthIndex
+        && date.getUTCDate() === numericDay
+        && date.getUTCHours() === numericHour
+        && date.getUTCMinutes() === numericMinute
+        && date.getUTCSeconds() === numericSecond
+        && date.getUTCDay() === weekdayIndex
+        ? date.getTime()
+        : null;
+};
+const httpDate = (value, now = Date.now()) => {
+    const preferred = IMF_FIXDATE.exec(value);
+    if (preferred !== null) {
+        return utcHttpDate(preferred[1], preferred[2], preferred[3], Number(preferred[4]), preferred[5], preferred[6], preferred[7]);
+    }
+    const rfc850 = RFC850_DATE.exec(value);
+    if (rfc850 !== null) {
+        let year = 2000 + Number(rfc850[4]);
+        if (year > new Date(now).getUTCFullYear() + 50)
+            year -= 100;
+        return utcHttpDate(rfc850[1], rfc850[2], rfc850[3], year, rfc850[5], rfc850[6], rfc850[7]);
+    }
+    const asctime = ASCTIME_DATE.exec(value);
+    return asctime === null
+        ? null
+        : utcHttpDate(asctime[1], asctime[3] ?? asctime[4], asctime[2], Number(asctime[8]), asctime[5], asctime[6], asctime[7]);
+};
+// The package-shipped model teaching is loaded verbatim and fails hard if absent.
+// The relative path is identical from src/ during development and dist/ after build.
 const documentation = await readFile(new URL("../docs/http.md", import.meta.url), "utf-8");
 class Http {
     static manifest = {
         name: "http",
         // Channel mimetypes here are SEED DEFAULTS (pre-fetch placeholders).
         // body is retyped per-call via notifyChunk's mimetype arg — to the real
-        // response Content-Type, or projected markdown for a rendered page; octet-stream
-        // is the honest "unknown until fetched". header is always the status
+        // response Content-Type or the configured readable projection type;
+        // octet-stream is the honest "unknown until fetched". header is always the status
         // line + headers (text/plain).
         channels: { [BODY]: "application/octet-stream", [HEADER]: "text/plain", html: "text/html" },
         defaultChannel: BODY,
         category: "data",
-        scope: "workspace",
         writableBy: ["model", "client"],
         volatile: true, // remote content can change between fetches
         modelVisible: true,
@@ -62,318 +156,493 @@ class Http {
             requiresWeb: true, // excluded under the loop's noWeb flag
         },
     };
-    // The render foundation (lazy chromium). Injectable for tests; one warm
-    // pool per Http instance, shared across this scheme's fetches.
-    #browser;
+    #errorDetailLimit;
     #webFetcher;
-    constructor(browser = new Browser()) {
-        this.#browser = browser;
-        this.#webFetcher = new WebFetcher(browser);
+    constructor() {
+        this.#errorDetailLimit = ErrorDetail.configuredLimit();
+        this.#webFetcher = new WebFetcher();
     }
     async ready() {
-        const mode = await this.#browser.ready?.();
-        if (mode !== undefined)
-            console.info(`http renderer: ${mode}`);
-    }
-    async close() {
-        await this.#webFetcher.close();
-    }
-    // FIND itself is the consumer's standard entry query. This hook owns only
-    // HTTP's prerequisite: an exact URL that is not already an entry must be
-    // acquired through the same guarded byte/render path used by search
-    // prefetch. Glob and regex targets only query already-known web entries.
-    async prepareFind(statement, ctx) {
-        const target = statement.target;
-        if (target === null || target.kind !== "url")
-            return { shape: "passthrough", status: 200 };
-        const pathname = _a.#pathname(target);
+        WebFetcher.validateConfiguration();
+    }
+    // Representation preparation is scope-blind. Core applies the authored READ
+    // coordinates only after this hook has either materialized a finite GET or
+    // returned 102 for a retained SSE response.
+    async prepareRepresentation(request, ctx) {
+        if (request.target.kind !== "url") {
+            return _a.#bad(400, "http", "bad-target", "READ requires an http(s):// URL target.", {
+                stage: "target-validation",
+                recovery: "Provide an http(s):// URL target.",
+                retryable: false,
+            });
+        }
+        return this.#prepareGet(request.target, request.pathname, ctx);
+    }
+    async #prepareGet(target, pathname, ctx) {
+        const address = _a.#address(target);
+        if (!(address instanceof NetworkAddress))
+            return address;
+        const { url } = address;
+        const requestHeaders = target.headers ?? [];
+        let cached;
+        const conditional = [];
         const prior = await ctx.entries.read(pathname);
-        if (prior.entry !== null)
-            return { shape: "passthrough", status: 200 };
-        const fetched = await this.#webFetcher.fetch(_a.#urlFrom(target), { signal: ctx.signal });
-        if (fetched === null) {
-            return _a.#bad(404, "http", "not_materialized", "the requested URL could not be materialized");
+        if (Results.isErrorStatus(prior.status) && prior.status !== 404) {
+            return _a.#passthrough(prior);
         }
-        let { body, mimetype } = fetched;
-        let channels = {
-            [BODY]: { content: body, mimetype },
-            ...(fetched.header === undefined ? {} : { [HEADER]: { content: fetched.header, mimetype: "text/plain" } }),
-        };
-        if (mimetype === "text/html") {
-            let projected = await ctx.projection.readable(body, mimetype);
-            if ((projected === null || projected.content.length === 0) && fetched.render !== undefined) {
-                const rendered = await fetched.render();
-                if (rendered !== null) {
-                    body = rendered.body;
-                    mimetype = rendered.mimetype;
-                    projected = await ctx.projection.readable(body, mimetype);
+        const priorBody = prior.entry?.channels[BODY];
+        const priorHeader = prior.entry?.channels[HEADER];
+        if (prior.entry !== null && _a.#requestMethod(priorHeader?.content ?? "") === undefined) {
+            return { status: 200 };
+        }
+        if (prior.entry !== null && priorBody !== undefined && priorHeader !== undefined) {
+            try {
+                if (await _a.#reusableGetRepresentation(prior.entry, requestHeaders, ctx.projection)) {
+                    cached = prior.entry;
+                    if (_a.#materializerIdentity(priorHeader.content) === undefined) {
+                        conditional.push(..._a.#validators(priorHeader.content));
+                    }
                 }
             }
-            if (projected === null || projected.content.length === 0) {
-                return _a.#bad(422, "http", "no_readable_projection", "the requested URL has no readable projection");
+            catch (cause) {
+                return _a.#materializationFailure(url, "GET", new WebMaterializationError(_a.#sourceMimetype(priorHeader.content), cause));
             }
-            channels = {
-                [BODY]: { content: projected.content, mimetype: projected.mimetype },
-                html: { content: body, mimetype },
-                ...(fetched.header === undefined ? {} : { [HEADER]: { content: fetched.header, mimetype: "text/plain" } }),
-            };
         }
-        const written = await ctx.entries.write(pathname, { channels, tags: [] });
-        return { shape: "passthrough", status: written.status };
-    }
-    // An unscoped READ fetches/revalidates. A scoped READ observes the already
-    // materialized readable entry: refetching would discard the requested range
-    // and return another asynchronous whole-body 102.
-    async read(statement, ctx) {
-        if (statement.target === null || statement.target.kind !== "url") {
-            return _a.#bad(400, "http", "bad_target", "READ requires an http(s):// URL target");
+        if (cached !== undefined && _a.#fresh(cached.channels[HEADER].content)) {
+            return { status: 200 };
         }
-        if (statement.lineMarker !== null) {
-            const prior = await ctx.entries.read(_a.#pathname(statement.target));
-            const body = prior.entry?.channels[BODY];
-            if (body === undefined || body.content.length === 0) {
-                return _a.#bad(409, "http", "scope_requires_materialization", "scoped READ requires a materialized response; READ the URL without <scope> first");
+        let fetched;
+        try {
+            fetched = await this.#webFetcher.fetch(url, {
+                signal: ctx.signal,
+                headers: requestHeaders,
+                ...(conditional.length > 0
+                    ? { conditionalHeaders: conditional }
+                    : {}),
+                guarded: false,
+                acceptHttpErrors: true,
+                preserveUnavailable: true,
+            });
+        }
+        catch (error) {
+            if (ctx.signal?.aborted === true && error === ctx.signal.reason) {
+                return _a.#cancelled(url, "GET");
             }
-            const { error, ...read } = await ctx.entries.operations.read(statement);
-            if (read.status >= 400) {
-                return _a.#bad(read.status, "http", "scoped_read_failed", error ?? read.reason ?? `scoped READ failed with status ${read.status}`);
+            throw error;
+        }
+        if (fetched === null) {
+            return _a.#bad(404, "http", "not-materialized", `The URL ${url} could not be materialized.`, {
+                target: url,
+                stage: "acquisition",
+                retryable: true,
+            });
+        }
+        if (fetched.status === 304) {
+            if (cached === undefined) {
+                return _a.#bad(502, "http", "fetch-failed", `HTTP GET ${url} returned 304 without a reusable stored representation.`, {
+                    target: url,
+                    method: "GET",
+                    stage: "acquisition",
+                    retryable: true,
+                });
+            }
+            const cachedHeader = cached.channels[HEADER].content;
+            if (_a.#materializerIdentity(cachedHeader) !== undefined) {
+                return _a.#bad(502, "http", "fetch-failed", `HTTP GET ${url} returned 304 for a stored representation that requires full reacquisition.`, {
+                    target: url,
+                    method: "GET",
+                    stage: "acquisition",
+                    retryable: true,
+                });
+            }
+            const responseHeaders = fetched.responseHeaders ?? [];
+            if (!_a.#revalidationCorresponds(cachedHeader, new Headers(responseHeaders.map(([name, value]) => [name, value])))) {
+                return _a.#bad(502, "http", "fetch-failed", `HTTP GET ${url} returned 304 without identifying the stored representation nominated for revalidation.`, {
+                    target: url,
+                    method: "GET",
+                    stage: "acquisition",
+                    retryable: true,
+                });
+            }
+            const channels = {
+                ...cached.channels,
+                [HEADER]: {
+                    ...cached.channels[HEADER],
+                    content: _a.#refreshAfter304(cachedHeader, responseHeaders, requestHeaders),
+                },
+            };
+            const written = await ctx.entries.write(pathname, {
+                channels,
+                tags: cached.tags,
+            });
+            if (Results.isErrorStatus(written.status))
+                return _a.#passthrough(written);
+            return { status: 200 };
+        }
+        if (fetched.mimetype === "text/event-stream"
+            && fetched.response?.body !== null
+            && fetched.response?.body !== undefined) {
+            return this.#openEventStream(address, fetched, ctx);
+        }
+        let materialized;
+        try {
+            materialized = await WebFetcher.materialize(fetched, ctx.projection, ctx.signal);
+        }
+        catch (error) {
+            if (ctx.signal?.aborted === true)
+                return _a.#cancelled(url, "GET");
+            if (error instanceof WebMaterializationError) {
+                return _a.#materializationFailure(url, "GET", error);
             }
-            return { shape: "passthrough", ...read };
+            throw error;
         }
-        return this.#fetchStream(statement.target, ctx, "GET", undefined);
+        if (materialized === null) {
+            return _a.#bad(415, "http", "binary-response-unsupported", `HTTP GET ${url} returned ${fetched.mimetype}. The remote response was received, but its binary body cannot be represented in a Plurnk text channel.`, {
+                target: url,
+                method: "GET",
+                mimetype: fetched.mimetype,
+                stage: "materialization",
+                recovery: "Inspect #header or use a byte-capable client.",
+                retryable: false,
+            });
+        }
+        const written = await ctx.entries.write(pathname, {
+            channels: WebFetcher.materializedChannels(materialized, { url, method: "GET" }),
+            tags: [],
+        });
+        if (Results.isErrorStatus(written.status))
+            return _a.#passthrough(written);
+        return { status: 200 };
     }
-    // EDIT → PUT the body (full-resource replace). `<L>` has no meaning against a
-    // remote resource — reject rather than silently ignore the model's intent.
+    async #openEventStream(address, fetched, ctx) {
+        const response = fetched.response;
+        if (response?.body === null || response?.body === undefined) {
+            throw new Error("SSE preparation lost its response body.");
+        }
+        const local = new AbortController();
+        const handle = {
+            cancel: async () => {
+                local.abort();
+                await response.body?.cancel().catch(() => { });
+            },
+        };
+        const written = await ctx.entries.write(address.pathname, _a.#seedEntry());
+        if (Results.isErrorStatus(written.status))
+            return _a.#passthrough(written);
+        const subscription = await ctx.subscriptions.open(address.pathname, handle);
+        if (fetched.header !== undefined) {
+            await subscription.notifyChunk(HEADER, fetched.header, "text/plain");
+        }
+        void _a.#settleEventStream(subscription, response, {
+            url: address.url,
+            method: "GET",
+            signal: local.signal,
+            errorDetailLimit: this.#errorDetailLimit,
+        }).catch((error) => {
+            console.error("HTTP SSE terminal cleanup failed", { url: address.url, error });
+        });
+        return { shape: "passthrough", status: 102 };
+    }
+    // EDIT -> PUT the body (full-resource replace). `<L>` has no meaning against a
+    // remote resource - reject rather than silently ignore the model's intent.
     async editBatch(statements, ctx) {
         if (statements.length !== 1) {
-            return _a.#bad(409, "http", "non_atomic_edit_batch", "multiple EDITs of one remote resource cannot be committed atomically");
+            return _a.#bad(409, "http", "non-atomic-edit-batch", `${statements.length} EDIT statements cannot be committed atomically to one remote resource.`, {
+                statements: statements.length,
+                stage: "mutation",
+                recovery: "Submit one whole-resource EDIT.",
+                retryable: false,
+            });
         }
         const statement = statements[0];
         if (statement.target === null || statement.target.kind !== "url") {
-            return _a.#bad(400, "http", "bad_target", "EDIT requires an http(s):// URL target");
+            return _a.#bad(400, "http", "bad-target", "EDIT requires an http(s):// URL target.", {
+                stage: "target-validation",
+                recovery: "Provide an http(s):// URL target.",
+                retryable: false,
+            });
         }
         if (statement.lineMarker !== null) {
-            return _a.#bad(400, "http", "no_line_edit", "EDIT on http PUTs the whole body; <L> line-editing a remote resource is unsupported");
+            return _a.#bad(400, "http", "line-edit-unsupported", "HTTP EDIT replaces the whole remote resource and does not accept a line range.", {
+                stage: "mutation",
+                recovery: "Remove the line range and submit the complete replacement body.",
+                retryable: false,
+            });
         }
-        return this.#fetchStream(statement.target, ctx, "PUT", statement.body ?? "");
+        return this.#request(statement.target, ctx, "PUT", statement.body ?? "");
     }
     async edit(statement, ctx) {
         return this.editBatch([statement], ctx);
     }
-    // KILL → DELETE the resource. Distinct from SEND[410] (which drops the local
+    // KILL -> DELETE the resource. Distinct from SEND[410] (which drops the local
     // cached entry): KILL is an HTTP DELETE request to the remote.
     async kill(statement, ctx) {
         if (statement.target === null || statement.target.kind !== "url") {
-            return _a.#bad(400, "http", "bad_target", "KILL requires an http(s):// URL target");
+            return _a.#bad(400, "http", "bad-target", "KILL requires an http(s):// URL target.", {
+                stage: "target-validation",
+                recovery: "Provide an http(s):// URL target.",
+                retryable: false,
+            });
         }
-        return this.#fetchStream(statement.target, ctx, "DELETE", statement.body ?? undefined);
+        return this.#request(statement.target, ctx, "DELETE", statement.body ?? undefined);
     }
-    // SEND dispatch — status-code-as-verb (SPEC §op-surface).
-    //   200 → request with body (POST), stream response
-    //   410 → delete the cached entry
-    //   499 → cancel in-flight (handled by the subscription's force-cancel;
+    // SEND dispatch — status-code-as-verb (SPEC {§op-surface}).
+    //   200 -> request with body (POST), stream response
+    //   410 -> delete the cached entry
+    //   499 -> cancel in-flight (handled by the subscription's force-cancel;
     //         the engine routes 499 to the registered SubscriptionHandle, so a
     //         scheme-level no-op here is correct — teardown already happened)
     async send(statement, ctx) {
         if (statement.target === null || statement.target.kind !== "url") {
-            return _a.#bad(400, "http", "bad_target", "SEND requires an http(s):// URL target");
+            return _a.#bad(400, "http", "bad-target", "SEND requires an http(s):// URL target.", {
+                stage: "target-validation",
+                recovery: "Provide an http(s):// URL target.",
+                retryable: false,
+            });
         }
         const status = statement.signal;
         if (status === 200) {
             const body = statement.body?.raw ?? "";
-            return this.#fetchStream(statement.target, ctx, "POST", body);
+            return this.#request(statement.target, ctx, "POST", body);
         }
         if (status === 410) {
-            const { status: delStatus } = await ctx.entries.delete(_a.#pathname(statement.target));
-            return { shape: "passthrough", status: delStatus };
+            const address = _a.#address(statement.target);
+            if (!(address instanceof NetworkAddress))
+                return address;
+            return _a.#passthrough(await ctx.entries.delete(address.pathname));
         }
         if (status === 499) {
             // Cancellation is routed by the engine to the subscription's
-            // SubscriptionHandle.cancel (registered in #fetchStream). Nothing
+            // SubscriptionHandle.cancel (registered by #request). Nothing
             // for the scheme to do at the op level.
             return { shape: "passthrough", status: 200 };
         }
         // Entry-bearing schemes return 501 for status codes they don't interpret.
-        return _a.#bad(501, "http", "unsupported_send", `SEND[${status}] not supported by http`);
-    }
-    // The streaming core, shared by every verb. Opens the subscription
-    // (registering the abort handle for SEND[499] routing), fetches, then EITHER
-    // renders (a GET of an HTML page is re-acquired through the browser, its
-    // readable projection becomes body, and its final DOM is archived) OR streams the raw bytes (every non-GET
-    // response and every non-HTML body). Request headers from the target's `{…}`
-    // blocks (grammar#46) ride into both the fetch and the render. Each chunk is
-    // labelled with its real mimetype via notifyChunk. Settles via close().
-    async #fetchStream(target, ctx, method, body) {
-        const url = _a.#rewriteHostileHost(_a.#urlFrom(target));
-        const pathname = _a.#pathname(target);
-        const headers = target.headers ?? []; // [key,value][] — opaque to grammar, honored here
+        return _a.#bad(501, "http", "send-status-unsupported", `The HTTP scheme does not interpret SEND status ${status}.`, {
+            requestedStatus: status,
+            stage: "dispatch",
+            retryable: false,
+        });
+    }
+    // Mutation responses use the same entry/channel and subscription primitives
+    // as every live producer; GET acquisition belongs solely to
+    // prepareRepresentation.
+    async #request(target, ctx, method, body) {
+        const address = _a.#address(target);
+        if (!(address instanceof NetworkAddress))
+            return address;
+        const { url } = address;
+        const { pathname } = address;
+        const headers = target.headers ?? [];
         const publishedChannel = target.fragment ?? _a.manifest.defaultChannel;
         if (!(publishedChannel in _a.manifest.channels)) {
-            return _a.#bad(400, "http", "unknown_channel", `no channel #${publishedChannel}; channels: ${Object.keys(_a.manifest.channels).join(", ")}`);
-        }
-        // Conditional revalidation (GET only, service#341): recover the prior
-        // fetch's validators + body from THIS scheme's own stored entry (entries
-        // cap, own namespace — sanctioned). If the origin answers 304, we re-serve
-        // the cached body and skip the expensive render. Freshness is decided ONLY
-        // by #storedCopyServable (SPEC §revalidation): within the operator TTL
-        // window the stored copy serves with zero round-trips; past it, the
-        // conditional GET revalidates (service#333/#405 landed the TTL). Captured
-        // BEFORE the seed write below overwrites the entry.
-        let cached;
-        const conditional = [];
-        if (method === "GET") {
-            const prior = await ctx.entries.read(pathname);
-            const pb = prior.entry?.channels[BODY];
-            if (pb !== undefined && pb.content.length > 0) {
-                const ph = prior.entry?.channels[HEADER]?.content ?? "";
-                const html = prior.entry?.channels.html;
-                cached = {
-                    header: ph,
-                    body: { content: pb.content, mimetype: pb.mimetype },
-                    ...(html === undefined || html.content.length === 0 ? {} : { html: { content: html.content, mimetype: html.mimetype } }),
-                };
-                conditional.push(..._a.#validators(ph));
-            }
-        }
-        // TTL fast path (the pre-fetch phase of the ONE predicate): a stored copy
-        // still inside the freshness window serves with NO round-trip at all —
-        // identical for a model READ and lane-1 prefetch (#405). Stamp unchanged:
-        // the clock only resets when the ORIGIN vouches (fetch or 304), never by
-        // serving from cache.
-        if (cached !== undefined && _a.#storedCopyServable(_a.#fetchedAt(cached.header), null)) {
-            await ctx.entries.write(pathname, _a.#seedEntry());
-            await ctx.subscriptions.open(pathname, { cancel: () => { } }, { publishedChannel });
-            await ctx.subscriptions.notifyChunk(HEADER, cached.header, "text/plain");
-            if (cached.html !== undefined)
-                await ctx.subscriptions.notifyChunk("html", cached.html.content, cached.html.mimetype);
-            await ctx.subscriptions.notifyChunk(BODY, cached.body.content, cached.body.mimetype);
-            await ctx.subscriptions.close("done", `ttl-fresh; ${cached.body.content.length} chars from cache`);
-            return { shape: "passthrough", status: 102 };
+            const availableChannels = Object.keys(_a.manifest.channels);
+            return _a.#bad(400, "http", "channel-not-found", `Channel #${publishedChannel} does not exist on HTTP responses.`, {
+                requestedChannel: publishedChannel,
+                availableChannels,
+                recovery: `Use one of the available channels: ${availableChannels.map((channel) => `#${channel}`).join(", ")}.`,
+                retryable: false,
+            });
         }
         // Local AbortController for force-cancel from outside (SEND[499]).
         const local = new AbortController();
         const handle = { cancel: () => local.abort() };
-        // Materialize the streaming target BEFORE subscribing (http#3). open()
-        // binds an EXISTING entry — only the scheme knows its channel shape, so
-        // it seeds them. Mirror exec's create-then-subscribe: write a seed entry
-        // whose channels are the manifest's (body: octet-stream placeholder,
-        // header: text/plain) — the same channels notifyChunk then populates.
-        await ctx.entries.write(pathname, _a.#seedEntry());
+        // {§http-lifecycle} open() binds an existing entry, so the handler seeds
+        // its manifest-owned channel shape before subscribing.
+        const written = await ctx.entries.write(pathname, _a.#seedEntry());
+        if (Results.isErrorStatus(written.status))
+            return _a.#passthrough(written);
         // open() returns the worker+teardown-composed signal — fires on loop.cancel
-        // OR our local teardown. Wire it so either path aborts the fetch/render.
-        const composed = await ctx.subscriptions.open(pathname, handle, { publishedChannel });
+        // OR our local teardown. Wire it so either path aborts acquisition.
+        const subscription = await ctx.subscriptions.open(pathname, handle);
         const onAbort = () => local.abort();
-        composed.addEventListener("abort", onAbort, { once: true });
+        subscription.addEventListener("abort", onAbort, { once: true });
         try {
             const response = await fetch(url, {
                 method,
                 body,
-                // One browser identity on the wire (never Node's default "node"
-                // UA — a loud automated-client fingerprint). The model's own
-                // {User-Agent: …} block wins when present.
                 headers: headers.some(([k]) => k.toLowerCase() === "user-agent")
-                    ? [...headers, ...conditional]
-                    : [["User-Agent", BROWSER_UA], ...headers, ...conditional],
+                    ? headers
+                    : [["User-Agent", DEFAULT_WEB_UA], ...headers],
                 signal: local.signal,
                 redirect: "follow",
             });
-            // Origin confirms the cached copy is current → re-serve it, skip the
-            // render/stream. A 304-serve is a first-class READ: the model sees the
-            // stored body as an ordinary streaming result, never a cache status
-            // (service#341). `revalidated 304` rides the close summary for the log
-            // meta line + digest. notifyChunk appends onto the freshly-seeded empty
-            // channels, restoring the cached header + body.
-            if (cached !== undefined && _a.#storedCopyServable(_a.#fetchedAt(cached.header), response)) {
-                await ctx.subscriptions.notifyChunk(HEADER, _a.#stamp(cached.header), "text/plain");
-                if (cached.html !== undefined)
-                    await ctx.subscriptions.notifyChunk("html", cached.html.content, cached.html.mimetype);
-                await ctx.subscriptions.notifyChunk(BODY, cached.body.content, cached.body.mimetype);
-                await ctx.subscriptions.close("done", `revalidated 304; ${cached.body.content.length} chars from cache`);
-                return { shape: "passthrough", status: 102 };
-            }
-            const contentType = response.headers.get("content-type") ?? "";
-            // Always-render: a GET of an HTML page is re-acquired through the
-            // browser so the body is projected from the final rendered DOM. The probe-fetch
-            // body is discarded — the browser does its own navigation. Only GET
-            // renders; POST/PUT/DELETE can't be replayed as a browser navigation.
-            const isHtml = method === "GET"
-                && /^(?:text\/html|application\/xhtml\+xml)\b/i.test(contentType);
-            if (isHtml) {
-                await response.body?.cancel();
-                const result = await this.#browser.render(url, { workerId: ctx.workerId, signal: local.signal, headers });
-                const projected = await ctx.projection.readable(result.html, "text/html");
-                if (projected === null)
-                    throw new Error("rendered HTML has no readable projection");
-                await _a.#writeHeader(ctx, result.status, result.statusText, result.headers);
-                await ctx.subscriptions.notifyChunk("html", result.html, "text/html");
-                await ctx.subscriptions.notifyChunk(BODY, projected.content, projected.mimetype);
-                await ctx.subscriptions.close("done", `rendered HTTP ${result.status}; ${projected.content.length} readable chars`);
-                return { shape: "passthrough", status: 102 };
-            }
-            // SSE: an event stream is parsed into its `data` payloads (SPEC §sse),
-            // one notifyChunk per event with the `data:`/comment framing stripped,
-            // so the model reads event content and not the transport. A long-lived
-            // GET; events land in the body channel as they arrive across turns,
-            // until the origin closes. Only GET — a POST reply is never an SSE READ.
-            if (method === "GET" && /^text\/event-stream\b/i.test(contentType)) {
-                await _a.#writeHeader(ctx, response.status, response.statusText, [...response.headers]);
-                return await _a.#streamEvents(ctx, response);
-            }
-            // Byte path: stream the body labelled with its real content type.
-            await _a.#writeHeader(ctx, response.status, response.statusText, [...response.headers]);
-            const bodyMime = contentType.split(";")[0].trim() || "application/octet-stream";
+            const responseMime = responseMimetype(response.headers.get("content-type"));
+            // {§http-lifecycle}/{§mimetype-classifier} String channels retain
+            // textual response data. Binary input is transient: an installed
+            // reader may derive Unicode, otherwise the durable body is a typed
+            // empty marker rather than a fabricated byte channel.
+            await _a.#writeHeader(subscription, method, response.status, response.statusText, [...response.headers], headers);
+            const bodyMime = responseMime;
             if (response.body === null) {
-                await ctx.subscriptions.close("done", `HTTP ${response.status}; empty body`);
+                await subscription.close({ status: 200 }, `HTTP ${response.status}; empty body`);
                 return { shape: "passthrough", status: 102 };
             }
+            const responseBody = response.body;
+            const byteBody = {
+                chunks: responseBody,
+                cancel: () => responseBody.cancel(),
+            };
+            const binary = await WebFetcher.classifyBinary(byteBody, bodyMime, ctx.projection);
+            if (binary) {
+                let projected;
+                try {
+                    projected = await WebFetcher.projectBytes(byteBody, bodyMime, ctx.projection);
+                }
+                catch (error) {
+                    await subscription.notifyChunk(BODY, "", bodyMime);
+                    throw error;
+                }
+                if (projected !== null) {
+                    await _a.#writeProjectionIdentity(subscription, projected.projectionIdentity);
+                    await subscription.notifyChunk(BODY, projected.content, projected.mimetype);
+                    await subscription.close({ status: 200 }, `HTTP ${response.status}; ${projected.content.length} readable chars from ${bodyMime}`);
+                    return { shape: "passthrough", status: 102 };
+                }
+                await subscription.notifyChunk(BODY, "", bodyMime);
+                const detail = `HTTP ${method} ${url} returned ${bodyMime}. The remote response was received, but its binary body cannot be represented in a Plurnk text channel.`;
+                const result = _a.#bad(415, "http", "binary-response-unsupported", detail, {
+                    target: url,
+                    method,
+                    mimetype: bodyMime,
+                    stage: "materialization",
+                    recovery: "Do not retry the request solely to retrieve this body; inspect #header or use a byte-capable client.",
+                    retryable: false,
+                });
+                await subscription.close(result, detail);
+                return result;
+            }
+            // {§http-text-decoding} Fetch text is replacement-mode UTF-8;
+            // Content-Type charset remains response evidence, not a second decoder.
             let bytes = 0;
             const decoder = new TextDecoder();
-            for await (const chunk of response.body) {
+            for await (const chunk of responseBody) {
                 bytes += chunk.length;
-                await ctx.subscriptions.notifyChunk(BODY, decoder.decode(chunk, { stream: true }), bodyMime);
+                await subscription.notifyChunk(BODY, decoder.decode(chunk, { stream: true }), bodyMime);
             }
             const tail = decoder.decode();
             if (tail.length > 0)
-                await ctx.subscriptions.notifyChunk(BODY, tail, bodyMime);
-            await ctx.subscriptions.close("done", `HTTP ${response.status}; ${bytes} bytes`);
+                await subscription.notifyChunk(BODY, tail, bodyMime);
+            await subscription.close({ status: 200 }, `HTTP ${response.status}; ${bytes} bytes`);
             return { shape: "passthrough", status: 102 };
         }
         catch (err) {
             const aborted = local.signal.aborted;
-            const reason = aborted ? "aborted" : err instanceof Error ? err.message : String(err);
-            await ctx.subscriptions.close(aborted ? "cancelled" : "error", reason);
-            // 499 for client-cancelled, 502 for upstream/network/render failure.
-            return _a.#bad(aborted ? 499 : 502, "http", aborted ? "aborted" : "fetch_failed", reason);
+            if (aborted) {
+                const result = _a.#cancelled(url, method);
+                await subscription.close(result, result.problem?.detail);
+                return result;
+            }
+            if (err instanceof WebMaterializationError) {
+                const result = _a.#materializationFailure(url, method, err);
+                await subscription.close(result, result.problem?.detail);
+                return result;
+            }
+            console.error("HTTP acquisition failed", { method, url, err });
+            const cause = ErrorDetail.preview(err, this.#errorDetailLimit);
+            const reason = `HTTP ${method} ${url} failed: ${cause}`;
+            // The remaining catch owns acquisition failure; cancellation and
+            // typed materialization failures settled above.
+            const result = _a.#bad(502, "http", "fetch-failed", reason, {
+                target: url,
+                method,
+                stage: "acquisition",
+                retryable: true,
+            });
+            await subscription.close(result, reason);
+            return result;
         }
         finally {
-            composed.removeEventListener("abort", onAbort);
+            subscription.removeEventListener("abort", onAbort);
         }
     }
-    // Seed entry mirroring the manifest's channels — empty content + the seed
-    // mimetypes (body: octet-stream until the fetch retypes it via notifyChunk,
-    // header: text/plain). This is the channel-shape knowledge open() lacks; the
-    // scheme materializes the target so the subscription binds an existing entry
-    // (http#3). Fresh stream target → no tags.
+    // {§http-manifest}/{§http-lifecycle} Seed the declared channel shape before
+    // open(); notifyChunk later welds acquired content to its actual mimetype.
     static #seedEntry() {
-        const channels = Object.fromEntries(Object.entries(_a.manifest.channels).map(([name, mimetype]) => [name, { content: "", mimetype }]));
+        const channels = Object.fromEntries(Object.entries(_a.manifest.channels).map(([name, mimetype]) => [name, {
+                content: "",
+                mimetype,
+                state: "active",
+            }]));
         return { channels, tags: [] };
     }
-    // Record the response status line + headers into the HEADER channel (text/plain).
-    static async #writeHeader(ctx, status, statusText, headers) {
+    // {§revalidation} The body and header must have settled successfully. An
+    // auxiliary channel may have terminally failed without invalidating body.
+    static #representationComplete(entry) {
+        const bodyState = entry.channels[BODY]?.state;
+        const headerState = entry.channels[HEADER]?.state;
+        const successful = (state) => state === "static" || state === "closed";
+        const terminal = (state) => successful(state) || state === "errored";
+        return successful(bodyState)
+            && successful(headerState)
+            && Object.values(entry.channels).every(({ state }) => terminal(state));
+    }
+    // {§revalidation} Direct READ and exact FIND share the complete reusable
+    // representation predicate; freshness only decides how READ uses a match.
+    static async #reusableGetRepresentation(entry, requestHeaders, projection) {
+        const body = entry.channels[BODY];
+        const header = entry.channels[HEADER];
+        if (body === undefined || header === undefined)
+            return false;
+        return _a.#representationComplete(entry)
+            && _a.#requestMethod(header.content) === "GET"
+            && requestHeaders.length === 0
+            && _a.#cacheVariant(header.content) === "default"
+            && !_a.#storedCachePolicy(header.content).noStore
+            && await _a.#projectionCurrent(header.content, projection);
+    }
+    // {§revalidation} Origin headers come first; authoritative package method
+    // and acquisition metadata are appended last.
+    static async #writeHeader(subscription, method, status, statusText, responseHeaders, requestHeaders) {
+        await subscription.notifyChunk(HEADER, _a.#responseHeader(method, status, statusText, responseHeaders, requestHeaders), "text/plain");
+    }
+    static #responseHeader(method, status, statusText, responseHeaders, requestHeaders) {
         const lines = [`HTTP ${status} ${statusText}`];
-        for (const [k, v] of headers)
+        for (const [k, v] of responseHeaders)
             lines.push(`${k}: ${v}`);
+        lines.push(`${REQUEST_METHOD}: ${method}`);
         lines.push(`${FETCHED_AT}: ${new Date().toISOString()}`);
-        await ctx.subscriptions.notifyChunk(HEADER, lines.join("\n"), "text/plain");
-    }
-    // Drain an SSE body through the standard streaming parser and dispatch one
-    // BODY chunk per event. event/id/retry/comments remain transport metadata:
-    // this projection publishes data, not the wire, and does not reconnect.
-    static async #streamEvents(ctx, response) {
-        if (response.body === null) {
-            await ctx.subscriptions.close("done", "SSE stream; empty body");
-            return { shape: "passthrough", status: 102 };
+        lines.push(cacheVariantEvidence(classifyCacheVariant(requestHeaders, responseHeaders)));
+        return lines.join("\n");
+    }
+    static async #writeProjectionIdentity(subscription, identity) {
+        await subscription.notifyChunk(HEADER, `\n${WebFetcher.projectionEvidence(identity)}`, "text/plain");
+    }
+    // Drain an acquired SSE body and settle its retained subscription. The READ
+    // has already returned 102, so terminal failure is durable stream state.
+    static async #settleEventStream(subscription, response, options) {
+        try {
+            const events = await _a.#streamEvents(subscription, response);
+            if (options.signal.aborted) {
+                const result = _a.#cancelled(options.url, options.method);
+                await subscription.close(result, result.problem?.detail);
+                return;
+            }
+            await subscription.close({ status: 200 }, `SSE stream; ${events} events`);
+        }
+        catch (error) {
+            if (options.signal.aborted) {
+                const result = _a.#cancelled(options.url, options.method);
+                await subscription.close(result, result.problem?.detail);
+                return;
+            }
+            console.error("HTTP SSE stream failed", { method: options.method, url: options.url, error });
+            const cause = ErrorDetail.preview(error, options.errorDetailLimit);
+            const reason = `HTTP ${options.method} ${options.url} failed: ${cause}`;
+            const result = _a.#bad(502, "http", "fetch-failed", reason, {
+                target: options.url,
+                method: options.method,
+                stage: "transfer",
+                retryable: true,
+            });
+            await subscription.close(result, reason);
         }
+    }
+    // event/id/retry/comments remain transport metadata: this projection
+    // publishes event data, not the wire, and does not reconnect.
+    static async #streamEvents(subscription, response) {
+        if (response.body === null)
+            return 0;
         const decoder = new TextDecoder();
         const pending = [];
         let fatal = null;
@@ -391,7 +660,7 @@ class Http {
         const publish = async () => {
             for (const data of pending.splice(0)) {
                 events += 1;
-                await ctx.subscriptions.notifyChunk(BODY, `${data}\n`, "text/plain");
+                await subscription.notifyChunk(BODY, `${data}\n`, "text/plain");
             }
         };
         for await (const chunk of response.body) {
@@ -407,89 +676,306 @@ class Http {
         if (fatal !== null)
             throw fatal;
         await publish();
-        await ctx.subscriptions.close("done", `SSE stream; ${events} events`);
-        return { shape: "passthrough", status: 102 };
+        return events;
     }
-    // Reconstruct the absolute URL from the parsed UrlPath. `raw` is the
-    // grammar's verbatim URL — authoritative; the decomposed fields are a
-    // convenience. Use raw so query strings / auth / port survive exactly.
-    static #urlFrom(target) {
-        return target.raw;
-    }
-    // Entry storage has no authority column. The host is part of a web
-    // resource's identity, so fold it into the pathname exactly as the search
-    // prefetch sink does. Routing (`https` rides the HTTP handler) remains
-    // separate from storage (`https` remains https).
-    static #pathname(target) {
-        const folded = target.hostname ? `/${target.hostname}${target.pathname}` : target.pathname;
-        // `%28`/`%29` are the grammar-safe transport spelling of literal path
-        // parentheses. Entry storage is canonical; the packet renderer encodes
-        // them again when presenting an address to the model.
-        return folded.replace(/%28/giu, "(").replace(/%29/giu, ")");
-    }
-    // Known-hostile-host rewrite — the ONE bounded, first-party exception
-    // (SPEC §host-rewrite, schemes-http#4). A GitHub blob page is a CSP-locked JS SPA that renders
-    // nothing useful, and code wants SOURCE (line-navigable) not markdown pulled
-    // from a rendered code-viewer; raw.githubusercontent serves the exact bytes
-    // on the byte path. Measured through the extractor: blob → SPA/JSON noise,
-    // raw → clean source. The `{ref}/{path}` tail carries through verbatim, so
-    // slash-bearing branch refs map correctly. Wikipedia was measured too and
-    // deliberately gets NO rewrite — desktop already extracts to the full clean
-    // article; every rewrite (action=render, mobile-html) regressed it.
-    static #rewriteHostileHost(url) {
-        const gh = /^https:\/\/github\.com\/([^/]+)\/([^/]+)\/blob\/(.+)$/.exec(url);
-        if (gh !== null)
-            return `https://raw.githubusercontent.com/${gh[1]}/${gh[2]}/${gh[3]}`;
-        return url;
-    }
-    // The single freshness-predicate boundary (service#341, #333). Today a
-    // conditional-GET `304 Not Modified` proves the stored copy is current, so it
-    // is servable without a re-fetch/re-render. service#333's per-URL TTL lands
-    // HERE as the SAME predicate (a pre-fetch branch) — one stamp, one rule,
-    // identical at every entry point. Never add a second freshness check elsewhere.
-    // Pre-fetch phase (response === null): fresh iff the stamp is inside the
-    // operator TTL window; PLURNK_SCHEMES_HTTP_TTL_MS=0 disables the window so
-    // every read revalidates (the pre-TTL behavior). Post-fetch phase: a 304 is
-    // the origin vouching for the stored copy.
-    static #storedCopyServable(fetchedAtMs, response) {
-        if (response === null) {
-            const ttl = requireNumEnv("PLURNK_SCHEMES_HTTP_TTL_MS");
-            return ttl > 0 && fetchedAtMs !== undefined && Date.now() - fetchedAtMs < ttl;
-        }
-        return response.status === 304;
-    }
-    // Parse the materialization stamp out of a stored HEADER channel; undefined
-    // when absent (pre-TTL entries, execs-materialized pages) — those simply
-    // never TTL-serve and revalidate instead.
+    static #address(target) {
+        let address;
+        try {
+            address = NetworkAddress.from(target);
+        }
+        catch {
+            return _a.#bad(400, "http", "bad-target", "HTTP operations require an http(s):// URL with an authority.", {
+                stage: "target-validation",
+                recovery: "Provide an http(s):// URL with a host.",
+                retryable: false,
+            });
+        }
+        if (address.scheme !== "http" && address.scheme !== "https") {
+            return _a.#bad(400, "http", "bad-target", "HTTP operations require an http(s):// URL target.", {
+                stage: "target-validation",
+                recovery: "Provide an http(s):// URL target.",
+                retryable: false,
+            });
+        }
+        if (address.hasCredentials) {
+            return _a.#bad(400, "http", "userinfo-not-allowed", "HTTP URL userinfo is not allowed.", {
+                target: address.url,
+                stage: "target-validation",
+                recovery: "Remove credentials from the URL and use request metadata where authorization is required.",
+                retryable: false,
+            });
+        }
+        return address;
+    }
+    // {§revalidation} Validation-free reuse requires both the operator's local
+    // ceiling and the origin's response policy to remain live.
+    static #fresh(header, now = Date.now()) {
+        const fetchedAt = _a.#fetchedAt(header);
+        const ttl = requireNumEnv("PLURNK_SCHEMES_HTTP_TTL_MS");
+        if (fetchedAt === undefined || ttl <= 0)
+            return false;
+        const residentTime = Math.max(0, now - fetchedAt);
+        if (residentTime >= ttl)
+            return false;
+        const policy = _a.#storedCachePolicy(header);
+        if (policy.noStore || policy.noCache)
+            return false;
+        return policy.freshnessLifetimeMs === undefined
+            || _a.#currentAge(header, fetchedAt, now) < policy.freshnessLifetimeMs;
+    }
+    // Package metadata is appended after origin headers, so the last value wins.
     static #fetchedAt(priorHeader) {
-        const m = new RegExp(`^${FETCHED_AT}:[ \\t]*(.+)$`, "im").exec(priorHeader);
-        if (m === null)
+        const value = lastHeaderValue(priorHeader, FETCHED_AT);
+        if (value === undefined)
             return undefined;
-        const ms = Date.parse(m[1].trim());
+        const ms = Date.parse(value);
         return Number.isNaN(ms) ? undefined : ms;
     }
-    // Re-stamp a stored HEADER to now — used when the ORIGIN vouches (304).
-    static #stamp(header) {
-        const line = `${FETCHED_AT}: ${new Date().toISOString()}`;
-        const re = new RegExp(`^${FETCHED_AT}:.*$`, "im");
-        return re.test(header) ? header.replace(re, line) : `${header}\n${line}`;
+    static #headerField(line) {
+        const colon = line.indexOf(":");
+        if (colon < 0)
+            return null;
+        const name = line.slice(0, colon).trim().toLowerCase();
+        if (name.length === 0)
+            return null;
+        return { name, value: line.slice(colon + 1).trim(), line };
+    }
+    static #packageStart(lines) {
+        let stampIndex = -1;
+        for (const [index, line] of lines.entries()) {
+            if (_a.#headerField(line)?.name === FETCHED_AT)
+                stampIndex = index;
+        }
+        if (stampIndex < 0)
+            return lines.length;
+        return _a.#headerField(lines[stampIndex - 1] ?? "")?.name === REQUEST_METHOD
+            ? stampIndex - 1
+            : stampIndex;
+    }
+    static #originFields(header) {
+        const lines = header.split(/\r?\n/);
+        return lines.slice(1, _a.#packageStart(lines))
+            .map((line) => _a.#headerField(line))
+            .filter((field) => field !== null);
+    }
+    static #originValues(fields, name) {
+        return fields.filter((field) => field.name === name).map(({ value }) => value);
+    }
+    static #storedCachePolicy(header) {
+        const fields = _a.#originFields(header);
+        const directives = _a.#originValues(fields, "cache-control")
+            .flatMap((value) => splitHttpList(value))
+            .map((member) => cacheDirective(member))
+            .filter((directive) => directive !== null);
+        const maxAges = directives.filter(({ name }) => name === "max-age");
+        let freshnessLifetimeMs;
+        if (maxAges.length > 0) {
+            freshnessLifetimeMs = maxAges.length === 1
+                ? deltaMilliseconds(maxAges[0].argument) ?? 0
+                : 0;
+        }
+        else {
+            const expiresValues = _a.#originValues(fields, "expires");
+            if (expiresValues.length > 0) {
+                const expires = expiresValues.length === 1
+                    ? httpDate(expiresValues[0])
+                    : null;
+                const fetchedAt = _a.#fetchedAt(header);
+                if (expires === null || fetchedAt === undefined) {
+                    freshnessLifetimeMs = 0;
+                }
+                else {
+                    const dateValues = _a.#originValues(fields, "date");
+                    const parsedDate = dateValues.length === 1
+                        ? httpDate(dateValues[0])
+                        : null;
+                    const generatedAt = parsedDate ?? fetchedAt;
+                    freshnessLifetimeMs = Math.max(0, expires - generatedAt);
+                }
+            }
+        }
+        return {
+            noStore: directives.some(({ name }) => name === "no-store"),
+            noCache: directives.some(({ name }) => name === "no-cache"),
+            ...(freshnessLifetimeMs === undefined ? {} : { freshnessLifetimeMs }),
+        };
+    }
+    static #currentAge(header, fetchedAt, now) {
+        const fields = _a.#originFields(header);
+        const dateValues = _a.#originValues(fields, "date");
+        const date = dateValues.length === 1 ? httpDate(dateValues[0]) : null;
+        const apparentAge = date === null ? 0 : Math.max(0, fetchedAt - date);
+        const ageMember = _a.#originValues(fields, "age").flatMap(splitHttpList)[0];
+        const ageValue = deltaMilliseconds(ageMember) ?? 0;
+        return Math.max(apparentAge, ageValue) + Math.max(0, now - fetchedAt);
+    }
+    static #requestMethod(priorHeader) {
+        return lastHeaderValue(priorHeader, REQUEST_METHOD)?.toUpperCase();
+    }
+    // Package evidence is authoritative only after the package acquisition
+    // stamp. An origin field with the same name remains inert.
+    static #packageHeaderValue(priorHeader, field) {
+        const lines = priorHeader.split(/\r?\n/);
+        let stampIndex = -1;
+        for (const [index, line] of lines.entries()) {
+            const colon = line.indexOf(":");
+            if (colon < 0)
+                continue;
+            const name = line.slice(0, colon).trim().toLowerCase();
+            if (name === FETCHED_AT)
+                stampIndex = index;
+        }
+        if (stampIndex < 0)
+            return undefined;
+        let value;
+        for (const line of lines.slice(stampIndex + 1)) {
+            const colon = line.indexOf(":");
+            if (colon < 0 || line.slice(0, colon).trim().toLowerCase() !== field)
+                continue;
+            value = line.slice(colon + 1).trim();
+        }
+        return value === "" ? undefined : value;
+    }
+    static #projectionIdentity(priorHeader) {
+        return _a.#packageHeaderValue(priorHeader, PROJECTION_ID_HEADER);
+    }
+    static #materializerIdentity(priorHeader) {
+        return _a.#packageHeaderValue(priorHeader, MATERIALIZER_ID_HEADER);
+    }
+    static #cacheVariant(priorHeader) {
+        const value = _a.#packageHeaderValue(priorHeader, CACHE_VARIANT_HEADER);
+        return value === "default" || value === "bypass" ? value : undefined;
+    }
+    static #sourceMimetype(header) {
+        return responseMimetype(lastHeaderValue(header, "content-type") ?? null);
+    }
+    static async #projectionCurrent(header, projection) {
+        const sourceMimetype = _a.#sourceMimetype(header);
+        const isHtml = MimetypeClassifier.isHtml(sourceMimetype);
+        const materializerIdentity = _a.#materializerIdentity(header);
+        if (materializerIdentity !== undefined) {
+            if (!WebFetcher.materializerCurrent(materializerIdentity))
+                return false;
+            if (materializerIdentity.startsWith("tavily-extract:")
+                || materializerIdentity === "origin-markdown:v1")
+                return true;
+        }
+        if (isHtml && materializerIdentity === undefined)
+            return false;
+        const storedIdentity = _a.#projectionIdentity(header);
+        if (storedIdentity === undefined)
+            return !isHtml;
+        return await projection.identity(sourceMimetype) === storedIdentity;
+    }
+    // RFC 9111 §3.2 permits a processed cache to retain the metadata that its
+    // stored body depends upon. Other 304 fields update by name; package-owned
+    // evidence is then rebuilt after the origin block. {§revalidation}
+    static #refreshAfter304(header, responseHeaders, requestHeaders) {
+        const lines = header.split(/\r?\n/);
+        const origin = _a.#originFields(header);
+        const updates = responseHeaders.filter(([name]) => !BODY_PROCESSING_FIELDS.has(name.toLowerCase()));
+        const updatedNames = new Set(updates.map(([name]) => name.toLowerCase()));
+        const retained = origin.filter(({ name }) => !updatedNames.has(name));
+        const merged = [
+            ...retained.map(({ name, value }) => [name, value]),
+            ...updates,
+        ];
+        const packageEvidence = [
+            MATERIALIZER_ID_HEADER,
+            PROJECTION_ID_HEADER,
+            TAVILY_REQUEST_ID_HEADER,
+            TAVILY_CREDITS_HEADER,
+        ].flatMap((field) => {
+            const value = _a.#packageHeaderValue(header, field);
+            return value === undefined ? [] : [`${field}: ${value}`];
+        });
+        return [
+            lines[0] ?? "HTTP 200 OK",
+            ...retained.map(({ line }) => line),
+            ...updates.map(([name, value]) => `${name}: ${value}`),
+            `${REQUEST_METHOD}: GET`,
+            `${FETCHED_AT}: ${new Date().toISOString()}`,
+            cacheVariantEvidence(classifyCacheVariant(requestHeaders, merged)),
+            ...packageEvidence,
+        ].join("\n");
+    }
+    static #revalidationCorresponds(priorHeader, responseHeaders) {
+        const fields = _a.#originFields(priorHeader);
+        const responseTagValue = responseHeaders.get("etag");
+        if (responseTagValue !== null) {
+            const storedTagValues = _a.#originValues(fields, "etag");
+            const responseTag = entityTag(responseTagValue);
+            const storedTag = storedTagValues.length === 1
+                ? entityTag(storedTagValues[0])
+                : null;
+            if (responseTag === null || storedTag === null)
+                return false;
+            return responseTag.opaque === storedTag.opaque
+                && (responseTag.weak || !storedTag.weak);
+        }
+        const responseModifiedValue = responseHeaders.get("last-modified");
+        const storedModifiedValues = _a.#originValues(fields, "last-modified");
+        const responseModified = responseModifiedValue === null
+            ? null
+            : httpDate(responseModifiedValue);
+        const storedModified = storedModifiedValues.length === 1
+            ? httpDate(storedModifiedValues[0])
+            : null;
+        return responseModified !== null
+            && storedModified !== null
+            && responseModified === storedModified;
     }
     // Conditional-request headers from the prior fetch's stored response headers
     // (the HEADER channel text #writeHeader wrote): ETag → If-None-Match,
     // Last-Modified → If-Modified-Since. Empty when neither is present — the
     // origin then just 200s with a full body, which is correct.
     static #validators(priorHeader) {
+        const fields = _a.#originFields(priorHeader);
         const out = [];
-        const etag = /^etag:[ \t]*(.+)$/im.exec(priorHeader);
-        if (etag !== null)
-            out.push(["If-None-Match", etag[1].trim()]);
-        const lastModified = /^last-modified:[ \t]*(.+)$/im.exec(priorHeader);
-        if (lastModified !== null)
-            out.push(["If-Modified-Since", lastModified[1].trim()]);
+        const etags = _a.#originValues(fields, "etag");
+        if (etags.length === 1 && entityTag(etags[0]) !== null) {
+            out.push(["If-None-Match", etags[0]]);
+        }
+        const lastModified = _a.#originValues(fields, "last-modified");
+        if (lastModified.length === 1 && httpDate(lastModified[0]) !== null) {
+            out.push(["If-Modified-Since", lastModified[0]]);
+        }
         return out;
     }
-    static #bad(status, scheme, kind, message) {
-        return { shape: "passthrough", status, error: Results.error(scheme, kind, message) };
+    static #passthrough(result) {
+        return Results.assert({ ...result, shape: "passthrough" });
+    }
+    static #cancelled(url, method) {
+        return _a.#bad(499, "http", "cancelled", `HTTP ${method} ${url} was cancelled.`, {
+            target: url,
+            method,
+            stage: "acquisition",
+            retryable: false,
+        });
+    }
+    static #materializationFailure(url, method, error) {
+        if (error.stage === "projection" && error.cause instanceof ProjectionInputLimitError) {
+            return _a.#bad(413, "http", "projection-input-limit", `HTTP ${method} ${url} exceeded the ${error.cause.maximumBytes}-byte readable-projection input limit.`, {
+                target: url,
+                method,
+                mimetype: error.cause.mimetype,
+                maximumBytes: error.cause.maximumBytes,
+                observedBytes: error.cause.observedBytes,
+                stage: "projection",
+                retryable: false,
+            });
+        }
+        console.error("HTTP materialization failed", { method, url, error });
+        return _a.#bad(500, "http", "projection-failed", `HTTP ${method} ${url} acquired content, but its readable projection failed.`, {
+            target: url,
+            method,
+            mimetype: error.mimetype,
+            stage: "projection",
+            retryable: false,
+        });
+    }
+    static #bad(status, scheme, kind, message, extensions = {}) {
+        return Results.failure(`scheme:${scheme}`, kind, status, message, { shape: "passthrough" }, extensions);
     }
 }
 _a = Http;