@txco/web-abi 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,83 @@
-# Temporary Holding Version
+# @txco/web-abi
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The conformance kit for the [Thanks, Computer](https://www.thanks.computer) (TxCo) Web ABI: the contract a framework's build
+produces so `txco` can deploy it.
+
+```
+<out>/
+  txco-web.json     the manifest: what the build is, never its routing
+  public/           files, installed as the stack's FILES/
+  server/           an optional Fetch handler: export default { fetch(request, ctx) }
+  ops/              ordinary .txcl, in scope directories (ops/900000/…)
+```
+
+The kit has three parts:
+
+- **The manifest schema** (`txco-web.schema.json`) and a validator. `txco`
+  embeds the same schema file, and both validators pass the same test corpus.
+- **The envelope ↔ Fetch bridge**, which every runner uses. It turns the
+  chassis's request envelope into a Fetch `Request`, calls the handler, and
+  turns the `Response` into the delta the chassis merges.
+- **A harness** that checks a build's `server/` before any runner exists, and
+  serves a build locally.
+
+`txco web check <out>` checks the rest: the files, the ops, and every request
+the build has to answer.
+
+## The manifest
+
+```json
+{
+  "abi": 1,
+  "server": { "entry": "server/index.mjs" },
+  "immutable": ["_app/immutable/"]
+}
+```
+
+| Field          | Meaning                                                                               |
+| -------------- | ------------------------------------------------------------------------------------- |
+| `abi`          | `1`                                                                                   |
+| `server.entry` | The handler module, under `server/`. Leave it out for a static build.                 |
+| `immutable`    | `public/` prefixes whose file names carry a content hash. They are cached for a year. |
+
+Keys starting with `x-` are free for producers. Any other key is an error.
+
+## The server contract
+
+```js
+export default {
+  async fetch(request, ctx) {
+    // a Fetch Request; ctx = { client: { ip } }
+    return new Response("…");
+  },
+};
+```
+
+- **Buffered both ways.** An answer is capped at about 3 MiB of body.
+- **Cookies.** Each `Set-Cookie` arrives on its own line.
+- **Errors.** A handler that throws, or returns something other than a
+  `Response`, answers `500` without revealing why.
+
+## Use
+
+```sh
+npx txco-web-abi validate <out>                 # the manifest
+npx txco-web-abi check-server <out> [--json]    # drive server/ through the bridge
+npx txco-web-abi serve <out> [--port 8787]      # public/ first, then server/
+```
+
+```js
+import {
+  dispatch,
+  envelopeToRequest,
+  responseToDelta,
+} from "@txco/web-abi/bridge";
+import { validateManifest } from "@txco/web-abi/manifest";
+```
+
+## Develop
+
+```sh
+npm install
+npm test     # tsc, then node --test (Node 20+)
+```

package/dist/bridge.d.ts

@@ -0,0 +1,25 @@
+import type { FetchHandler, TxcContext, TxcDelta, TxcEnvelope } from "./envelope.js";
+/** An op answer is capped at 4 MiB (--op-payload-max); the body is base64 inside it. */
+export declare const DEFAULT_MAX_ANSWER_BYTES: number;
+export interface RequestOptions {
+    /** Refuse a request body larger than this (bytes). Default: no limit. */
+    maxBodyBytes?: number;
+}
+/** Builds the Fetch Request an envelope describes. */
+export declare function envelopeToRequest(env: TxcEnvelope, opts?: RequestOptions): Request;
+/** The handler's context: only what the contract defines. */
+export declare function contextFrom(env: TxcEnvelope): TxcContext;
+export interface DeltaOptions {
+    /** The request's method: a HEAD answer carries no body. */
+    method?: string;
+    /** Refuse a body larger than this (bytes). */
+    maxAnswerBytes?: number;
+}
+/** Turns a Response into the chassis delta. */
+export declare function responseToDelta(res: Response, opts?: DeltaOptions): Promise<TxcDelta>;
+/**
+ * Runs one request through a handler, end to end. A handler that throws, or
+ * returns something other than a Response, answers 500; the error is never
+ * shown to the client.
+ */
+export declare function dispatch(handler: FetchHandler, env: TxcEnvelope, opts?: RequestOptions & DeltaOptions): Promise<TxcDelta>;

package/dist/bridge.js

@@ -0,0 +1,103 @@
+// The envelope ↔ Fetch bridge. A runner hands it the chassis's request
+// envelope; it builds a Fetch Request, calls the server entry, and turns the
+// Response into the delta the chassis merges. Every runner uses this one
+// mapping, so a handler sees the same Request wherever it runs.
+/** An op answer is capped at 4 MiB (--op-payload-max); the body is base64 inside it. */
+export const DEFAULT_MAX_ANSWER_BYTES = 3 * 1024 * 1024;
+// Hop-by-hop headers (RFC 9110 §7.6.1) and those the Request computes.
+const DROPPED_HEADERS = new Set([
+    "connection", "keep-alive", "proxy-connection", "transfer-encoding", "te", "trailer",
+    "upgrade", "content-length", "host",
+]);
+/** Builds the Fetch Request an envelope describes. */
+export function envelopeToRequest(env, opts = {}) {
+    const req = env._txc?.web?.req ?? {};
+    const method = (req.method ?? "GET").toUpperCase();
+    let url = req.url?.full;
+    if (!url) {
+        const host = req.host ?? "localhost";
+        const raw = req.url?.query?.raw;
+        url = `http://${host}${req.url?.path ?? "/"}${raw ? "?" + raw : ""}`;
+    }
+    const headers = new Headers();
+    for (const [name, value] of Object.entries(req.headers ?? {})) {
+        if (DROPPED_HEADERS.has(name.toLowerCase()))
+            continue;
+        for (const v of Array.isArray(value) ? value : [value])
+            headers.append(name, v);
+    }
+    let body;
+    if (req.body && method !== "GET" && method !== "HEAD") {
+        const bytes = Buffer.from(req.body, "base64");
+        if (opts.maxBodyBytes !== undefined && bytes.byteLength > opts.maxBodyBytes) {
+            throw new Error(`request body is ${bytes.byteLength} bytes, over ${opts.maxBodyBytes}`);
+        }
+        body = new ArrayBuffer(bytes.byteLength);
+        new Uint8Array(body).set(bytes);
+    }
+    return new Request(url, { method, headers, body });
+}
+/** The handler's context: only what the contract defines. */
+export function contextFrom(env) {
+    return Object.freeze({ client: Object.freeze({ ip: env._txc?.client?.ip ?? "" }) });
+}
+/** Turns a Response into the chassis delta. */
+export async function responseToDelta(res, opts = {}) {
+    const headers = {};
+    res.headers.forEach((value, name) => {
+        if (name === "set-cookie")
+            return; // each cookie on its own line, below
+        (headers[name] ??= []).push(value);
+    });
+    const cookies = res.headers.getSetCookie();
+    if (cookies.length > 0)
+        headers["set-cookie"] = cookies;
+    const delta = { _txc: { web: { res: { status: res.status, headers } }, halt: true } };
+    const noBody = (opts.method ?? "GET").toUpperCase() === "HEAD" || res.status === 204 || res.status === 304;
+    if (!noBody) {
+        const bytes = Buffer.from(await res.arrayBuffer());
+        const max = opts.maxAnswerBytes ?? DEFAULT_MAX_ANSWER_BYTES;
+        if (bytes.byteLength > max) {
+            throw new Error(`response body is ${bytes.byteLength} bytes, over the ${max}-byte answer limit`);
+        }
+        if (bytes.byteLength > 0)
+            delta._txc.web.res.body = bytes.toString("base64");
+    }
+    return delta;
+}
+function errorDelta(status, message, method) {
+    const res = { status, headers: { "content-type": ["text/plain; charset=utf-8"] } };
+    if (method.toUpperCase() !== "HEAD")
+        res.body = Buffer.from(message + "\n").toString("base64");
+    return { _txc: { web: { res }, halt: true } };
+}
+/**
+ * Runs one request through a handler, end to end. A handler that throws, or
+ * returns something other than a Response, answers 500; the error is never
+ * shown to the client.
+ */
+export async function dispatch(handler, env, opts = {}) {
+    const method = env._txc?.web?.req?.method ?? "GET";
+    let request;
+    try {
+        request = envelopeToRequest(env, opts);
+    }
+    catch {
+        return errorDelta(413, "request body too large", method);
+    }
+    let res;
+    try {
+        res = await handler.fetch(request, contextFrom(env));
+    }
+    catch {
+        return errorDelta(500, "internal error", method);
+    }
+    if (!(res instanceof Response))
+        return errorDelta(500, "internal error", method);
+    try {
+        return await responseToDelta(res, { ...opts, method: request.method });
+    }
+    catch {
+        return errorDelta(502, "response too large", method);
+    }
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,67 @@
+#!/usr/bin/env node
+// txco-web-abi: validate a manifest, check a build's server/, or serve a
+// build locally.
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { checkServer, serve } from "./harness.js";
+import { MANIFEST_NAME, validateManifest } from "./manifest.js";
+const USAGE = `Usage: txco-web-abi <command> <abi-dir>
+
+Commands:
+  validate <abi-dir>                 check txco-web.json against the Web ABI schema
+  check-server <abi-dir> [--json]    drive the build's server/ entry through the bridge
+  serve <abi-dir> [--port N]         serve public/ and server/ locally
+`;
+async function main(argv) {
+    const [cmd, dir, ...rest] = argv;
+    if (!cmd || !dir) {
+        process.stderr.write(USAGE);
+        return 2;
+    }
+    switch (cmd) {
+        case "validate": {
+            let doc;
+            try {
+                doc = JSON.parse(await readFile(join(dir, MANIFEST_NAME), "utf8"));
+            }
+            catch (e) {
+                process.stderr.write(`${MANIFEST_NAME}: ${e.message}\n`);
+                return 1;
+            }
+            const r = validateManifest(doc);
+            if (r.ok) {
+                process.stdout.write(`${MANIFEST_NAME}: ok\n`);
+                return 0;
+            }
+            for (const p of r.errors)
+                process.stdout.write(`${p.pointer || "/"}: ${p.message}\n`);
+            return 1;
+        }
+        case "check-server": {
+            const results = await checkServer(dir);
+            if (rest.includes("--json")) {
+                process.stdout.write(JSON.stringify({ ok: results.every((r) => r.ok), results }, null, 2) + "\n");
+            }
+            else {
+                for (const r of results)
+                    process.stdout.write(`${r.ok ? "✓" : "✗"} ${r.name}${r.detail ? "  " + r.detail : ""}\n`);
+            }
+            return results.every((r) => r.ok) ? 0 : 1;
+        }
+        case "serve": {
+            const i = rest.indexOf("--port");
+            const port = i >= 0 ? Number(rest[i + 1]) : 8787;
+            const server = await serve(dir, { port });
+            const addr = server.address();
+            process.stdout.write(`serving ${dir} on http://127.0.0.1:${typeof addr === "object" && addr ? addr.port : port}\n`);
+            return await new Promise(() => { }); // until interrupted
+        }
+        default:
+            process.stderr.write(USAGE);
+            return 2;
+    }
+}
+main(process.argv.slice(2)).then((code) => process.exit(code), (e) => {
+    process.stderr.write(`txco-web-abi: ${e.message}\n`);
+    process.exit(1);
+});

package/dist/envelope.d.ts

@@ -0,0 +1,57 @@
+/** The parts of the chassis's request envelope the bridge reads. */
+export interface TxcEnvelope {
+    _txc?: {
+        client?: {
+            ip?: string;
+        };
+        web?: {
+            req?: {
+                method?: string;
+                host?: string;
+                url?: {
+                    full?: string;
+                    path?: string;
+                    query?: {
+                        raw?: string;
+                    };
+                };
+                /** Header name → values, one per line. */
+                headers?: Record<string, string[] | string>;
+                /** The body, base64; absent when empty. */
+                body?: string;
+            };
+        };
+    };
+    [k: string]: unknown;
+}
+/** The response half: what an op writes to answer an HTTP request. */
+export interface TxcWebRes {
+    status: number;
+    /** Lower-case header name → values. */
+    headers: Record<string, string[]>;
+    /** The body, base64; absent for HEAD, 204 and 304. */
+    body?: string;
+}
+/**
+ * The bridge's answer: a delta the chassis merges into the run, never the
+ * envelope echoed back (op answers merge by appending arrays, so an echo
+ * would duplicate every header).
+ */
+export interface TxcDelta {
+    _txc: {
+        web: {
+            res: TxcWebRes;
+        };
+        halt: true;
+    };
+}
+/** What a server entry gets beside the Request. Deliberately minimal. */
+export interface TxcContext {
+    readonly client: {
+        readonly ip: string;
+    };
+}
+/** The server/ entry's default export. */
+export interface FetchHandler {
+    fetch(request: Request, ctx: TxcContext): Response | Promise<Response>;
+}

package/dist/envelope.js

@@ -0,0 +1,3 @@
+// The chassis's side of the contract: the request envelope a runner hands
+// the bridge, and the delta the bridge answers with.
+export {};

package/dist/harness.d.ts

@@ -0,0 +1,32 @@
+import { type Server } from "node:http";
+import type { FetchHandler, TxcEnvelope } from "./envelope.js";
+/** Imports a build's server entry and checks its default export. */
+export declare function loadServer(abiDir: string): Promise<FetchHandler>;
+/** Builds an envelope the way the chassis's web head does, for a request. */
+export declare function envelopeFor(method: string, path: string, init?: {
+    headers?: Record<string, string[]>;
+    body?: Uint8Array;
+    host?: string;
+    ip?: string;
+}): TxcEnvelope;
+export interface CheckResult {
+    name: string;
+    ok: boolean;
+    detail?: string;
+}
+/**
+ * Drives a server entry with the requests every handler must answer, through
+ * the bridge, and checks each answer is a valid delta: a status in
+ * 100–599, headers as arrays, no echo of the request envelope, a body only
+ * where one is allowed.
+ */
+export declare function checkServer(abiDir: string): Promise<CheckResult[]>;
+/**
+ * Serves a build locally: public/ files first (as the chassis's static
+ * serving answers first), everything else through the bridge to server/.
+ * For local development; not a chassis.
+ */
+export declare function serve(abiDir: string, opts?: {
+    port?: number;
+    host?: string;
+}): Promise<Server>;

package/dist/harness.js

@@ -0,0 +1,144 @@
+// The harness: load a build's server/ entry and check it honours the
+// contract, before any runner exists; and serve a build locally behind the
+// same bridge a runner will use.
+import { createServer } from "node:http";
+import { readFile, stat } from "node:fs/promises";
+import { extname, join, normalize, sep } from "node:path";
+import { pathToFileURL } from "node:url";
+import { dispatch } from "./bridge.js";
+import { readManifest } from "./manifest.js";
+/** Imports a build's server entry and checks its default export. */
+export async function loadServer(abiDir) {
+    const m = await readManifest(abiDir);
+    if (!m.server)
+        throw new Error("the manifest names no server.entry: this is a static build");
+    const mod = await import(pathToFileURL(join(abiDir, m.server.entry)).href);
+    const h = mod.default;
+    if (!h || typeof h.fetch !== "function") {
+        throw new Error(`${m.server.entry}: the default export must be { fetch(request, ctx) }`);
+    }
+    return h;
+}
+/** Builds an envelope the way the chassis's web head does, for a request. */
+export function envelopeFor(method, path, init = {}) {
+    const host = init.host ?? "localhost";
+    const q = path.indexOf("?");
+    return {
+        _txc: {
+            client: { ip: init.ip ?? "127.0.0.1" },
+            web: {
+                req: {
+                    method,
+                    host,
+                    url: { full: `http://${host}${path}`, path: q < 0 ? path : path.slice(0, q), query: { raw: q < 0 ? "" : path.slice(q + 1) } },
+                    headers: init.headers ?? {},
+                    body: init.body && init.body.byteLength > 0 ? Buffer.from(init.body).toString("base64") : undefined,
+                },
+            },
+        },
+    };
+}
+/**
+ * Drives a server entry with the requests every handler must answer, through
+ * the bridge, and checks each answer is a valid delta: a status in
+ * 100–599, headers as arrays, no echo of the request envelope, a body only
+ * where one is allowed.
+ */
+export async function checkServer(abiDir) {
+    const results = [];
+    let handler;
+    try {
+        handler = await loadServer(abiDir);
+        results.push({ name: "load", ok: true });
+    }
+    catch (e) {
+        return [{ name: "load", ok: false, detail: e.message }];
+    }
+    const probes = [
+        ["GET /", envelopeFor("GET", "/", { headers: { accept: ["text/html"] } }), "GET"],
+        ["GET unknown page", envelopeFor("GET", "/txco-web-abi-check-unknown", { headers: { accept: ["text/html"] } }), "GET"],
+        ["POST unknown", envelopeFor("POST", "/txco-web-abi-check-unknown", { headers: { "content-type": ["application/json"] }, body: new TextEncoder().encode("{}") }), "POST"],
+        ["HEAD /", envelopeFor("HEAD", "/"), "HEAD"],
+    ];
+    for (const [name, env, method] of probes) {
+        const delta = await dispatch(handler, env);
+        const res = delta?._txc?.web?.res;
+        const problems = [];
+        if (!res || !Number.isInteger(res.status) || res.status < 100 || res.status > 599)
+            problems.push("no valid status");
+        if (res && Object.values(res.headers).some((v) => !Array.isArray(v)))
+            problems.push("headers must be arrays");
+        if (delta._txc.web.req !== undefined)
+            problems.push("the answer echoes the request");
+        if (method === "HEAD" && res?.body)
+            problems.push("a HEAD answer carries a body");
+        if (res?.status === 500 && (method === "HEAD" || (res.body && Buffer.from(res.body, "base64").toString() === "internal error\n"))) {
+            problems.push("the handler threw or returned no Response (a 500 from the bridge)");
+        }
+        try {
+            JSON.stringify(delta);
+        }
+        catch {
+            problems.push("the delta isn't serialisable");
+        }
+        results.push({ name, ok: problems.length === 0, detail: problems.join("; ") || `→ ${res?.status}` });
+    }
+    return results;
+}
+const TYPES = {
+    ".html": "text/html; charset=utf-8", ".css": "text/css", ".js": "text/javascript", ".mjs": "text/javascript",
+    ".json": "application/json", ".svg": "image/svg+xml", ".png": "image/png", ".jpg": "image/jpeg",
+    ".webp": "image/webp", ".ico": "image/x-icon", ".txt": "text/plain; charset=utf-8", ".woff2": "font/woff2",
+};
+async function readBody(req) {
+    const chunks = [];
+    for await (const c of req)
+        chunks.push(c);
+    return Buffer.concat(chunks);
+}
+/**
+ * Serves a build locally: public/ files first (as the chassis's static
+ * serving answers first), everything else through the bridge to server/.
+ * For local development; not a chassis.
+ */
+export async function serve(abiDir, opts = {}) {
+    const handler = await loadServer(abiDir);
+    const pub = join(abiDir, "public");
+    const server = createServer(async (req, res) => {
+        const method = (req.method ?? "GET").toUpperCase();
+        const path = new URL(req.url ?? "/", "http://localhost").pathname;
+        if (method === "GET" || method === "HEAD") {
+            const segs = path.split("/").filter(Boolean);
+            if (!segs.some((s) => s.startsWith("."))) {
+                const file = normalize(join(pub, ...segs, path.endsWith("/") ? "index.html" : ""));
+                if (file.startsWith(pub + sep) || file === pub) {
+                    try {
+                        if ((await stat(file)).isFile()) {
+                            const bytes = await readFile(file);
+                            res.writeHead(200, { "content-type": TYPES[extname(file)] ?? "application/octet-stream" });
+                            res.end(method === "HEAD" ? undefined : bytes);
+                            return;
+                        }
+                    }
+                    catch {
+                        // not a file: the server answers
+                    }
+                }
+            }
+        }
+        const headers = {};
+        for (let i = 0; i < req.rawHeaders.length; i += 2) {
+            (headers[req.rawHeaders[i].toLowerCase()] ??= []).push(req.rawHeaders[i + 1]);
+        }
+        const delta = await dispatch(handler, envelopeFor(method, req.url ?? "/", {
+            headers, body: await readBody(req), host: req.headers.host, ip: req.socket.remoteAddress ?? "",
+        }));
+        const out = delta._txc.web.res;
+        for (const [name, values] of Object.entries(out.headers))
+            res.setHeader(name, values);
+        res.writeHead(out.status);
+        res.end(out.body ? Buffer.from(out.body, "base64") : undefined);
+    });
+    await new Promise((resolve) => server.listen(opts.port ?? 0, opts.host ?? "127.0.0.1", resolve));
+    return server;
+}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./manifest.js";
+export * from "./envelope.js";
+export * from "./bridge.js";
+export * from "./harness.js";

package/dist/index.js

@@ -0,0 +1,4 @@
+export * from "./manifest.js";
+export * from "./envelope.js";
+export * from "./bridge.js";
+export * from "./harness.js";

package/dist/manifest.d.ts

@@ -0,0 +1,36 @@
+/** The manifest's file name at the root of an ABI directory. */
+export declare const MANIFEST_NAME = "txco-web.json";
+/** The manifest's abi value this kit reads. */
+export declare const ABI_VERSION = 1;
+/** Producers' ops live in the band starting here, after every author op. */
+export declare const PRODUCER_SCOPE = 900000;
+export interface Manifest {
+    abi: 1;
+    server?: {
+        entry: string;
+    };
+    immutable?: string[];
+    [extension: `x-${string}`]: unknown;
+}
+export interface Problem {
+    /** A JSON pointer into the manifest ("" is the root). */
+    pointer: string;
+    message: string;
+}
+export type ValidationResult = {
+    ok: true;
+    manifest: Manifest;
+} | {
+    ok: false;
+    errors: Problem[];
+};
+/** Validates a parsed manifest. */
+export declare function validateManifest(doc: unknown): ValidationResult;
+/** Reads and validates <dir>/txco-web.json. Throws on an unreadable or invalid manifest. */
+export declare function readManifest(dir: string): Promise<Manifest>;
+/**
+ * The private root of a public/ path: cut at the end of its first "_"
+ * segment ("" when it has none). The installer writes one public marker per
+ * root, so `_app/x.js` → `_app`, `assets/_Dk3.js` → itself.
+ */
+export declare function publicRoot(rel: string): string;

package/dist/manifest.js

@@ -0,0 +1,116 @@
+// The Web ABI manifest (txco-web.json): what a build is, never its routing.
+// This validator mirrors txco-web.schema.json plus the rules a schema can't
+// express, and is held to the same fixture corpus as the Go validator
+// (chassis/webabi), so the two agree.
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+/** The manifest's file name at the root of an ABI directory. */
+export const MANIFEST_NAME = "txco-web.json";
+/** The manifest's abi value this kit reads. */
+export const ABI_VERSION = 1;
+/** Producers' ops live in the band starting here, after every author op. */
+export const PRODUCER_SCOPE = 900000;
+const ENTRY_RE = /^server\/[^/\\][^\\]*\.m?js$/;
+const PREFIX_RE = /^[^/\\][^\\]*\/$/;
+function cleanPath(p) {
+    if (p === "" || p.startsWith("/") || p.endsWith("/"))
+        return false;
+    return p.split("/").every((seg) => seg !== "" && !seg.startsWith("."));
+}
+/** Validates a parsed manifest. */
+export function validateManifest(doc) {
+    const errors = [];
+    if (typeof doc !== "object" || doc === null || Array.isArray(doc)) {
+        return { ok: false, errors: [{ pointer: "", message: "the manifest must be a JSON object" }] };
+    }
+    const m = doc;
+    for (const key of Object.keys(m)) {
+        if (!["$schema", "abi", "server", "immutable"].includes(key) && !key.startsWith("x-")) {
+            errors.push({ pointer: "", message: `unknown property "${key}" (a manifest describes the build, never its routing; extensions start with x-)` });
+        }
+    }
+    if (!("abi" in m)) {
+        errors.push({ pointer: "", message: 'missing required property "abi"' });
+    }
+    else if (m.abi !== ABI_VERSION) {
+        errors.push({ pointer: "/abi", message: `abi must be ${ABI_VERSION}` });
+    }
+    if ("$schema" in m && typeof m.$schema !== "string") {
+        errors.push({ pointer: "/$schema", message: "must be a string" });
+    }
+    if ("server" in m) {
+        const s = m.server;
+        if (typeof s !== "object" || s === null || Array.isArray(s)) {
+            errors.push({ pointer: "/server", message: "must be an object" });
+        }
+        else {
+            const so = s;
+            for (const key of Object.keys(so)) {
+                if (key !== "entry")
+                    errors.push({ pointer: "/server", message: `unknown property "${key}"` });
+            }
+            if (typeof so.entry !== "string") {
+                errors.push({ pointer: "/server", message: 'missing required property "entry"' });
+            }
+            else if (!ENTRY_RE.test(so.entry) || so.entry.length > 512) {
+                errors.push({ pointer: "/server/entry", message: "must be a .js or .mjs module under server/" });
+            }
+            else if (!cleanPath(so.entry)) {
+                errors.push({ pointer: "/server/entry", message: "the entry must be a clean path under server/" });
+            }
+        }
+    }
+    if ("immutable" in m) {
+        const im = m.immutable;
+        if (!Array.isArray(im)) {
+            errors.push({ pointer: "/immutable", message: "must be an array of prefixes" });
+        }
+        else {
+            if (new Set(im).size !== im.length) {
+                errors.push({ pointer: "/immutable", message: "items must be unique" });
+            }
+            im.forEach((p, i) => {
+                const ptr = `/immutable/${i}`;
+                if (typeof p !== "string" || p.length < 2 || p.length > 512 || !PREFIX_RE.test(p)) {
+                    errors.push({ pointer: ptr, message: "a prefix is a relative path ending in '/'" });
+                }
+                else if (!cleanPath(p.replace(/\/$/, ""))) {
+                    errors.push({ pointer: ptr, message: "a prefix must be a clean path, with no '.' or '..' segment" });
+                }
+                else if (p.split("/")[0] === "_txco") {
+                    errors.push({ pointer: ptr, message: "_txco/ is reserved for the installer" });
+                }
+            });
+        }
+    }
+    return errors.length > 0 ? { ok: false, errors } : { ok: true, manifest: m };
+}
+/** Reads and validates <dir>/txco-web.json. Throws on an unreadable or invalid manifest. */
+export async function readManifest(dir) {
+    const raw = await readFile(join(dir, MANIFEST_NAME), "utf8");
+    let doc;
+    try {
+        doc = JSON.parse(raw);
+    }
+    catch (e) {
+        throw new Error(`${MANIFEST_NAME}: not valid JSON: ${e.message}`);
+    }
+    const r = validateManifest(doc);
+    if (!r.ok) {
+        throw new Error(`${MANIFEST_NAME}: ` + r.errors.map((p) => `${p.pointer || "/"}: ${p.message}`).join("; "));
+    }
+    return r.manifest;
+}
+/**
+ * The private root of a public/ path: cut at the end of its first "_"
+ * segment ("" when it has none). The installer writes one public marker per
+ * root, so `_app/x.js` → `_app`, `assets/_Dk3.js` → itself.
+ */
+export function publicRoot(rel) {
+    const segs = rel.split("/");
+    for (let i = 0; i < segs.length; i++) {
+        if (segs[i].startsWith("_"))
+            return segs.slice(0, i + 1).join("/");
+    }
+    return "";
+}

package/package.json

@@ -1,6 +1,53 @@
 {
   "name": "@txco/web-abi",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "The TxCo Web ABI conformance kit: the txco-web.json schema and validator, the envelope ↔ Fetch bridge every runner uses, and a harness that checks a build's server/ Fetch handler.",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "keywords": ["txco", "thanks-computer", "web-abi", "fetch", "conformance"],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/LoremLabs/thanks-computer.git",
+    "directory": "sdk/web-abi"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "files": ["dist", "src", "txco-web.schema.json", "README.md"],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./manifest": {
+      "types": "./dist/manifest.d.ts",
+      "default": "./dist/manifest.js"
+    },
+    "./bridge": {
+      "types": "./dist/bridge.d.ts",
+      "default": "./dist/bridge.js"
+    },
+    "./harness": {
+      "types": "./dist/harness.d.ts",
+      "default": "./dist/harness.js"
+    },
+    "./schema.json": "./txco-web.schema.json"
+  },
+  "bin": {
+    "txco-web-abi": "./dist/cli.js"
+  },
+  "scripts": {
+    "clean": "rm -rf dist",
+    "build": "tsc -p tsconfig.json",
+    "test": "npm run build && node --test test/*.test.mjs",
+    "prepublishOnly": "npm run clean && npm run build"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.4.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/bridge.ts

@@ -0,0 +1,115 @@
+// The envelope ↔ Fetch bridge. A runner hands it the chassis's request
+// envelope; it builds a Fetch Request, calls the server entry, and turns the
+// Response into the delta the chassis merges. Every runner uses this one
+// mapping, so a handler sees the same Request wherever it runs.
+
+import type { FetchHandler, TxcContext, TxcDelta, TxcEnvelope } from "./envelope.js";
+
+/** An op answer is capped at 4 MiB (--op-payload-max); the body is base64 inside it. */
+export const DEFAULT_MAX_ANSWER_BYTES = 3 * 1024 * 1024;
+
+// Hop-by-hop headers (RFC 9110 §7.6.1) and those the Request computes.
+const DROPPED_HEADERS = new Set([
+  "connection", "keep-alive", "proxy-connection", "transfer-encoding", "te", "trailer",
+  "upgrade", "content-length", "host",
+]);
+
+export interface RequestOptions {
+  /** Refuse a request body larger than this (bytes). Default: no limit. */
+  maxBodyBytes?: number;
+}
+
+/** Builds the Fetch Request an envelope describes. */
+export function envelopeToRequest(env: TxcEnvelope, opts: RequestOptions = {}): Request {
+  const req = env._txc?.web?.req ?? {};
+  const method = (req.method ?? "GET").toUpperCase();
+  let url = req.url?.full;
+  if (!url) {
+    const host = req.host ?? "localhost";
+    const raw = req.url?.query?.raw;
+    url = `http://${host}${req.url?.path ?? "/"}${raw ? "?" + raw : ""}`;
+  }
+  const headers = new Headers();
+  for (const [name, value] of Object.entries(req.headers ?? {})) {
+    if (DROPPED_HEADERS.has(name.toLowerCase())) continue;
+    for (const v of Array.isArray(value) ? value : [value]) headers.append(name, v);
+  }
+  let body: ArrayBuffer | undefined;
+  if (req.body && method !== "GET" && method !== "HEAD") {
+    const bytes = Buffer.from(req.body, "base64");
+    if (opts.maxBodyBytes !== undefined && bytes.byteLength > opts.maxBodyBytes) {
+      throw new Error(`request body is ${bytes.byteLength} bytes, over ${opts.maxBodyBytes}`);
+    }
+    body = new ArrayBuffer(bytes.byteLength);
+    new Uint8Array(body).set(bytes);
+  }
+  return new Request(url, { method, headers, body });
+}
+
+/** The handler's context: only what the contract defines. */
+export function contextFrom(env: TxcEnvelope): TxcContext {
+  return Object.freeze({ client: Object.freeze({ ip: env._txc?.client?.ip ?? "" }) });
+}
+
+export interface DeltaOptions {
+  /** The request's method: a HEAD answer carries no body. */
+  method?: string;
+  /** Refuse a body larger than this (bytes). */
+  maxAnswerBytes?: number;
+}
+
+/** Turns a Response into the chassis delta. */
+export async function responseToDelta(res: Response, opts: DeltaOptions = {}): Promise<TxcDelta> {
+  const headers: Record<string, string[]> = {};
+  res.headers.forEach((value, name) => {
+    if (name === "set-cookie") return; // each cookie on its own line, below
+    (headers[name] ??= []).push(value);
+  });
+  const cookies = res.headers.getSetCookie();
+  if (cookies.length > 0) headers["set-cookie"] = cookies;
+
+  const delta: TxcDelta = { _txc: { web: { res: { status: res.status, headers } }, halt: true } };
+  const noBody = (opts.method ?? "GET").toUpperCase() === "HEAD" || res.status === 204 || res.status === 304;
+  if (!noBody) {
+    const bytes = Buffer.from(await res.arrayBuffer());
+    const max = opts.maxAnswerBytes ?? DEFAULT_MAX_ANSWER_BYTES;
+    if (bytes.byteLength > max) {
+      throw new Error(`response body is ${bytes.byteLength} bytes, over the ${max}-byte answer limit`);
+    }
+    if (bytes.byteLength > 0) delta._txc.web.res.body = bytes.toString("base64");
+  }
+  return delta;
+}
+
+function errorDelta(status: number, message: string, method: string): TxcDelta {
+  const res: TxcDelta["_txc"]["web"]["res"] = { status, headers: { "content-type": ["text/plain; charset=utf-8"] } };
+  if (method.toUpperCase() !== "HEAD") res.body = Buffer.from(message + "\n").toString("base64");
+  return { _txc: { web: { res }, halt: true } };
+}
+
+/**
+ * Runs one request through a handler, end to end. A handler that throws, or
+ * returns something other than a Response, answers 500; the error is never
+ * shown to the client.
+ */
+export async function dispatch(handler: FetchHandler, env: TxcEnvelope, opts: RequestOptions & DeltaOptions = {}): Promise<TxcDelta> {
+  const method = env._txc?.web?.req?.method ?? "GET";
+  let request: Request;
+  try {
+    request = envelopeToRequest(env, opts);
+  } catch {
+    return errorDelta(413, "request body too large", method);
+  }
+  let res: unknown;
+  try {
+    res = await handler.fetch(request, contextFrom(env));
+  } catch {
+    return errorDelta(500, "internal error", method);
+  }
+  if (!(res instanceof Response)) return errorDelta(500, "internal error", method);
+  try {
+    return await responseToDelta(res, { ...opts, method: request.method });
+  } catch {
+    return errorDelta(502, "response too large", method);
+  }
+}

package/src/cli.ts

@@ -0,0 +1,71 @@
+#!/usr/bin/env node
+// txco-web-abi: validate a manifest, check a build's server/, or serve a
+// build locally.
+
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+
+import { checkServer, serve } from "./harness.js";
+import { MANIFEST_NAME, validateManifest } from "./manifest.js";
+
+const USAGE = `Usage: txco-web-abi <command> <abi-dir>
+
+Commands:
+  validate <abi-dir>                 check txco-web.json against the Web ABI schema
+  check-server <abi-dir> [--json]    drive the build's server/ entry through the bridge
+  serve <abi-dir> [--port N]         serve public/ and server/ locally
+`;
+
+async function main(argv: string[]): Promise<number> {
+  const [cmd, dir, ...rest] = argv;
+  if (!cmd || !dir) {
+    process.stderr.write(USAGE);
+    return 2;
+  }
+  switch (cmd) {
+    case "validate": {
+      let doc: unknown;
+      try {
+        doc = JSON.parse(await readFile(join(dir, MANIFEST_NAME), "utf8"));
+      } catch (e) {
+        process.stderr.write(`${MANIFEST_NAME}: ${(e as Error).message}\n`);
+        return 1;
+      }
+      const r = validateManifest(doc);
+      if (r.ok) {
+        process.stdout.write(`${MANIFEST_NAME}: ok\n`);
+        return 0;
+      }
+      for (const p of r.errors) process.stdout.write(`${p.pointer || "/"}: ${p.message}\n`);
+      return 1;
+    }
+    case "check-server": {
+      const results = await checkServer(dir);
+      if (rest.includes("--json")) {
+        process.stdout.write(JSON.stringify({ ok: results.every((r) => r.ok), results }, null, 2) + "\n");
+      } else {
+        for (const r of results) process.stdout.write(`${r.ok ? "✓" : "✗"} ${r.name}${r.detail ? "  " + r.detail : ""}\n`);
+      }
+      return results.every((r) => r.ok) ? 0 : 1;
+    }
+    case "serve": {
+      const i = rest.indexOf("--port");
+      const port = i >= 0 ? Number(rest[i + 1]) : 8787;
+      const server = await serve(dir, { port });
+      const addr = server.address();
+      process.stdout.write(`serving ${dir} on http://127.0.0.1:${typeof addr === "object" && addr ? addr.port : port}\n`);
+      return await new Promise<number>(() => {}); // until interrupted
+    }
+    default:
+      process.stderr.write(USAGE);
+      return 2;
+  }
+}
+
+main(process.argv.slice(2)).then(
+  (code) => process.exit(code),
+  (e) => {
+    process.stderr.write(`txco-web-abi: ${(e as Error).message}\n`);
+    process.exit(1);
+  },
+);

package/src/envelope.ts

@@ -0,0 +1,49 @@
+// The chassis's side of the contract: the request envelope a runner hands
+// the bridge, and the delta the bridge answers with.
+
+/** The parts of the chassis's request envelope the bridge reads. */
+export interface TxcEnvelope {
+  _txc?: {
+    client?: { ip?: string };
+    web?: {
+      req?: {
+        method?: string;
+        host?: string;
+        url?: { full?: string; path?: string; query?: { raw?: string } };
+        /** Header name → values, one per line. */
+        headers?: Record<string, string[] | string>;
+        /** The body, base64; absent when empty. */
+        body?: string;
+      };
+    };
+  };
+  [k: string]: unknown;
+}
+
+/** The response half: what an op writes to answer an HTTP request. */
+export interface TxcWebRes {
+  status: number;
+  /** Lower-case header name → values. */
+  headers: Record<string, string[]>;
+  /** The body, base64; absent for HEAD, 204 and 304. */
+  body?: string;
+}
+
+/**
+ * The bridge's answer: a delta the chassis merges into the run, never the
+ * envelope echoed back (op answers merge by appending arrays, so an echo
+ * would duplicate every header).
+ */
+export interface TxcDelta {
+  _txc: { web: { res: TxcWebRes }; halt: true };
+}
+
+/** What a server entry gets beside the Request. Deliberately minimal. */
+export interface TxcContext {
+  readonly client: { readonly ip: string };
+}
+
+/** The server/ entry's default export. */
+export interface FetchHandler {
+  fetch(request: Request, ctx: TxcContext): Response | Promise<Response>;
+}

package/src/harness.ts

@@ -0,0 +1,149 @@
+// The harness: load a build's server/ entry and check it honours the
+// contract, before any runner exists; and serve a build locally behind the
+// same bridge a runner will use.
+
+import { createServer, type IncomingMessage, type Server } from "node:http";
+import { readFile, stat } from "node:fs/promises";
+import { extname, join, normalize, sep } from "node:path";
+import { pathToFileURL } from "node:url";
+
+import { dispatch } from "./bridge.js";
+import type { FetchHandler, TxcEnvelope } from "./envelope.js";
+import { readManifest } from "./manifest.js";
+
+/** Imports a build's server entry and checks its default export. */
+export async function loadServer(abiDir: string): Promise<FetchHandler> {
+  const m = await readManifest(abiDir);
+  if (!m.server) throw new Error("the manifest names no server.entry: this is a static build");
+  const mod = await import(pathToFileURL(join(abiDir, m.server.entry)).href);
+  const h = mod.default as FetchHandler | undefined;
+  if (!h || typeof h.fetch !== "function") {
+    throw new Error(`${m.server.entry}: the default export must be { fetch(request, ctx) }`);
+  }
+  return h;
+}
+
+/** Builds an envelope the way the chassis's web head does, for a request. */
+export function envelopeFor(method: string, path: string, init: { headers?: Record<string, string[]>; body?: Uint8Array; host?: string; ip?: string } = {}): TxcEnvelope {
+  const host = init.host ?? "localhost";
+  const q = path.indexOf("?");
+  return {
+    _txc: {
+      client: { ip: init.ip ?? "127.0.0.1" },
+      web: {
+        req: {
+          method,
+          host,
+          url: { full: `http://${host}${path}`, path: q < 0 ? path : path.slice(0, q), query: { raw: q < 0 ? "" : path.slice(q + 1) } },
+          headers: init.headers ?? {},
+          body: init.body && init.body.byteLength > 0 ? Buffer.from(init.body).toString("base64") : undefined,
+        },
+      },
+    },
+  };
+}
+
+export interface CheckResult {
+  name: string;
+  ok: boolean;
+  detail?: string;
+}
+
+/**
+ * Drives a server entry with the requests every handler must answer, through
+ * the bridge, and checks each answer is a valid delta: a status in
+ * 100–599, headers as arrays, no echo of the request envelope, a body only
+ * where one is allowed.
+ */
+export async function checkServer(abiDir: string): Promise<CheckResult[]> {
+  const results: CheckResult[] = [];
+  let handler: FetchHandler;
+  try {
+    handler = await loadServer(abiDir);
+    results.push({ name: "load", ok: true });
+  } catch (e) {
+    return [{ name: "load", ok: false, detail: (e as Error).message }];
+  }
+  const probes: Array<[string, TxcEnvelope, string]> = [
+    ["GET /", envelopeFor("GET", "/", { headers: { accept: ["text/html"] } }), "GET"],
+    ["GET unknown page", envelopeFor("GET", "/txco-web-abi-check-unknown", { headers: { accept: ["text/html"] } }), "GET"],
+    ["POST unknown", envelopeFor("POST", "/txco-web-abi-check-unknown", { headers: { "content-type": ["application/json"] }, body: new TextEncoder().encode("{}") }), "POST"],
+    ["HEAD /", envelopeFor("HEAD", "/"), "HEAD"],
+  ];
+  for (const [name, env, method] of probes) {
+    const delta = await dispatch(handler, env);
+    const res = delta?._txc?.web?.res;
+    const problems: string[] = [];
+    if (!res || !Number.isInteger(res.status) || res.status < 100 || res.status > 599) problems.push("no valid status");
+    if (res && Object.values(res.headers).some((v) => !Array.isArray(v))) problems.push("headers must be arrays");
+    if ((delta as unknown as { _txc: { web: { req?: unknown } } })._txc.web.req !== undefined) problems.push("the answer echoes the request");
+    if (method === "HEAD" && res?.body) problems.push("a HEAD answer carries a body");
+    if (res?.status === 500 && (method === "HEAD" || (res.body && Buffer.from(res.body, "base64").toString() === "internal error\n"))) {
+      problems.push("the handler threw or returned no Response (a 500 from the bridge)");
+    }
+    try {
+      JSON.stringify(delta);
+    } catch {
+      problems.push("the delta isn't serialisable");
+    }
+    results.push({ name, ok: problems.length === 0, detail: problems.join("; ") || `→ ${res?.status}` });
+  }
+  return results;
+}
+
+const TYPES: Record<string, string> = {
+  ".html": "text/html; charset=utf-8", ".css": "text/css", ".js": "text/javascript", ".mjs": "text/javascript",
+  ".json": "application/json", ".svg": "image/svg+xml", ".png": "image/png", ".jpg": "image/jpeg",
+  ".webp": "image/webp", ".ico": "image/x-icon", ".txt": "text/plain; charset=utf-8", ".woff2": "font/woff2",
+};
+
+async function readBody(req: IncomingMessage): Promise<Uint8Array> {
+  const chunks: Buffer[] = [];
+  for await (const c of req) chunks.push(c as Buffer);
+  return Buffer.concat(chunks);
+}
+
+/**
+ * Serves a build locally: public/ files first (as the chassis's static
+ * serving answers first), everything else through the bridge to server/.
+ * For local development; not a chassis.
+ */
+export async function serve(abiDir: string, opts: { port?: number; host?: string } = {}): Promise<Server> {
+  const handler = await loadServer(abiDir);
+  const pub = join(abiDir, "public");
+  const server = createServer(async (req, res) => {
+    const method = (req.method ?? "GET").toUpperCase();
+    const path = new URL(req.url ?? "/", "http://localhost").pathname;
+    if (method === "GET" || method === "HEAD") {
+      const segs = path.split("/").filter(Boolean);
+      if (!segs.some((s) => s.startsWith("."))) {
+        const file = normalize(join(pub, ...segs, path.endsWith("/") ? "index.html" : ""));
+        if (file.startsWith(pub + sep) || file === pub) {
+          try {
+            if ((await stat(file)).isFile()) {
+              const bytes = await readFile(file);
+              res.writeHead(200, { "content-type": TYPES[extname(file)] ?? "application/octet-stream" });
+              res.end(method === "HEAD" ? undefined : bytes);
+              return;
+            }
+          } catch {
+            // not a file: the server answers
+          }
+        }
+      }
+    }
+    const headers: Record<string, string[]> = {};
+    for (let i = 0; i < req.rawHeaders.length; i += 2) {
+      (headers[req.rawHeaders[i].toLowerCase()] ??= []).push(req.rawHeaders[i + 1]);
+    }
+    const delta = await dispatch(handler, envelopeFor(method, req.url ?? "/", {
+      headers, body: await readBody(req), host: req.headers.host, ip: req.socket.remoteAddress ?? "",
+    }));
+    const out = delta._txc.web.res;
+    for (const [name, values] of Object.entries(out.headers)) res.setHeader(name, values);
+    res.writeHead(out.status);
+    res.end(out.body ? Buffer.from(out.body, "base64") : undefined);
+  });
+  await new Promise<void>((resolve) => server.listen(opts.port ?? 0, opts.host ?? "127.0.0.1", resolve));
+  return server;
+}

package/src/index.ts

@@ -0,0 +1,4 @@
+export * from "./manifest.js";
+export * from "./envelope.js";
+export * from "./bridge.js";
+export * from "./harness.js";

package/src/manifest.ts

@@ -0,0 +1,127 @@
+// The Web ABI manifest (txco-web.json): what a build is, never its routing.
+// This validator mirrors txco-web.schema.json plus the rules a schema can't
+// express, and is held to the same fixture corpus as the Go validator
+// (chassis/webabi), so the two agree.
+
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+
+/** The manifest's file name at the root of an ABI directory. */
+export const MANIFEST_NAME = "txco-web.json";
+/** The manifest's abi value this kit reads. */
+export const ABI_VERSION = 1;
+/** Producers' ops live in the band starting here, after every author op. */
+export const PRODUCER_SCOPE = 900000;
+
+export interface Manifest {
+  abi: 1;
+  server?: { entry: string };
+  immutable?: string[];
+  [extension: `x-${string}`]: unknown;
+}
+
+export interface Problem {
+  /** A JSON pointer into the manifest ("" is the root). */
+  pointer: string;
+  message: string;
+}
+
+export type ValidationResult = { ok: true; manifest: Manifest } | { ok: false; errors: Problem[] };
+
+const ENTRY_RE = /^server\/[^/\\][^\\]*\.m?js$/;
+const PREFIX_RE = /^[^/\\][^\\]*\/$/;
+
+function cleanPath(p: string): boolean {
+  if (p === "" || p.startsWith("/") || p.endsWith("/")) return false;
+  return p.split("/").every((seg) => seg !== "" && !seg.startsWith("."));
+}
+
+/** Validates a parsed manifest. */
+export function validateManifest(doc: unknown): ValidationResult {
+  const errors: Problem[] = [];
+  if (typeof doc !== "object" || doc === null || Array.isArray(doc)) {
+    return { ok: false, errors: [{ pointer: "", message: "the manifest must be a JSON object" }] };
+  }
+  const m = doc as Record<string, unknown>;
+  for (const key of Object.keys(m)) {
+    if (!["$schema", "abi", "server", "immutable"].includes(key) && !key.startsWith("x-")) {
+      errors.push({ pointer: "", message: `unknown property "${key}" (a manifest describes the build, never its routing; extensions start with x-)` });
+    }
+  }
+  if (!("abi" in m)) {
+    errors.push({ pointer: "", message: 'missing required property "abi"' });
+  } else if (m.abi !== ABI_VERSION) {
+    errors.push({ pointer: "/abi", message: `abi must be ${ABI_VERSION}` });
+  }
+  if ("$schema" in m && typeof m.$schema !== "string") {
+    errors.push({ pointer: "/$schema", message: "must be a string" });
+  }
+  if ("server" in m) {
+    const s = m.server;
+    if (typeof s !== "object" || s === null || Array.isArray(s)) {
+      errors.push({ pointer: "/server", message: "must be an object" });
+    } else {
+      const so = s as Record<string, unknown>;
+      for (const key of Object.keys(so)) {
+        if (key !== "entry") errors.push({ pointer: "/server", message: `unknown property "${key}"` });
+      }
+      if (typeof so.entry !== "string") {
+        errors.push({ pointer: "/server", message: 'missing required property "entry"' });
+      } else if (!ENTRY_RE.test(so.entry) || so.entry.length > 512) {
+        errors.push({ pointer: "/server/entry", message: "must be a .js or .mjs module under server/" });
+      } else if (!cleanPath(so.entry)) {
+        errors.push({ pointer: "/server/entry", message: "the entry must be a clean path under server/" });
+      }
+    }
+  }
+  if ("immutable" in m) {
+    const im = m.immutable;
+    if (!Array.isArray(im)) {
+      errors.push({ pointer: "/immutable", message: "must be an array of prefixes" });
+    } else {
+      if (new Set(im).size !== im.length) {
+        errors.push({ pointer: "/immutable", message: "items must be unique" });
+      }
+      im.forEach((p, i) => {
+        const ptr = `/immutable/${i}`;
+        if (typeof p !== "string" || p.length < 2 || p.length > 512 || !PREFIX_RE.test(p)) {
+          errors.push({ pointer: ptr, message: "a prefix is a relative path ending in '/'" });
+        } else if (!cleanPath(p.replace(/\/$/, ""))) {
+          errors.push({ pointer: ptr, message: "a prefix must be a clean path, with no '.' or '..' segment" });
+        } else if (p.split("/")[0] === "_txco") {
+          errors.push({ pointer: ptr, message: "_txco/ is reserved for the installer" });
+        }
+      });
+    }
+  }
+  return errors.length > 0 ? { ok: false, errors } : { ok: true, manifest: m as unknown as Manifest };
+}
+
+/** Reads and validates <dir>/txco-web.json. Throws on an unreadable or invalid manifest. */
+export async function readManifest(dir: string): Promise<Manifest> {
+  const raw = await readFile(join(dir, MANIFEST_NAME), "utf8");
+  let doc: unknown;
+  try {
+    doc = JSON.parse(raw);
+  } catch (e) {
+    throw new Error(`${MANIFEST_NAME}: not valid JSON: ${(e as Error).message}`);
+  }
+  const r = validateManifest(doc);
+  if (!r.ok) {
+    throw new Error(`${MANIFEST_NAME}: ` + r.errors.map((p) => `${p.pointer || "/"}: ${p.message}`).join("; "));
+  }
+  return r.manifest;
+}
+
+/**
+ * The private root of a public/ path: cut at the end of its first "_"
+ * segment ("" when it has none). The installer writes one public marker per
+ * root, so `_app/x.js` → `_app`, `assets/_Dk3.js` → itself.
+ */
+export function publicRoot(rel: string): string {
+  const segs = rel.split("/");
+  for (let i = 0; i < segs.length; i++) {
+    if (segs[i].startsWith("_")) return segs.slice(0, i + 1).join("/");
+  }
+  return "";
+}

package/txco-web.schema.json

@@ -0,0 +1,44 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://thanks.computer/schemas/txco-web-1.json",
+  "title": "TxCo Web ABI manifest (txco-web.json)",
+  "description": "Describes a Web ABI directory: public/ (files), an optional server/ Fetch entry, and ops/ (.txcl). It describes the artifact, never its routing: web behaviour is ops.",
+  "type": "object",
+  "required": ["abi"],
+  "properties": {
+    "$schema": { "type": "string" },
+    "abi": {
+      "description": "The ABI version.",
+      "const": 1
+    },
+    "server": {
+      "description": "The application server, a Fetch handler module: export default { fetch(request, ctx) }. Absent for a static build.",
+      "type": "object",
+      "required": ["entry"],
+      "additionalProperties": false,
+      "properties": {
+        "entry": {
+          "description": "The ES module, relative to the ABI directory and under server/.",
+          "type": "string",
+          "maxLength": 512,
+          "pattern": "^server/[^/\\\\][^\\\\]*\\.m?js$"
+        }
+      }
+    },
+    "immutable": {
+      "description": "public/ prefixes whose files carry a content hash in their name, served with a year-long immutable cache. Each ends in '/'.",
+      "type": "array",
+      "uniqueItems": true,
+      "items": {
+        "type": "string",
+        "minLength": 2,
+        "maxLength": 512,
+        "pattern": "^[^/\\\\][^\\\\]*/$"
+      }
+    }
+  },
+  "patternProperties": {
+    "^x-": true
+  },
+  "additionalProperties": false
+}