aimeat 3.2.0 → 3.3.0

package/dist/src/utils/http-range.d.ts

@@ -0,0 +1,151 @@
+/**
+ * @file src/utils/http-range.ts
+ * @description HTTP byte-range parsing for the stored-file download paths, in one place.
+ *
+ *   WHAT WAS WRONG. Three download handlers each carried the same four lines, and those four lines
+ *   were `/bytes=(\d+)-(\d*)/`. That regex does not match `bytes=-8` — the SUFFIX range, which is
+ *   exactly the request a Parquet reader makes first, because the footer is at the end of the file.
+ *   A client asking for the last eight bytes got status 200 and the whole file, with no header
+ *   anywhere saying the request had not been honoured. That is a silent fallback: the reader
+ *   believes it is streaming and is in fact downloading everything, once per range it asks for.
+ *   The fourth path, `GET /v1/pub`, never looked at `Range` at all.
+ *
+ *   And no path ever sent `Accept-Ranges`. A client cannot discover range support by guessing, so
+ *   DuckDB, pandas and every HTTP range reader concluded the node does not do ranges — correctly,
+ *   from the evidence they had.
+ *
+ *   THE RULES THIS ENCODES, and why each one is what it is:
+ *
+ *   - `bytes=N-M`, `bytes=N-` and `bytes=-N` all parse. `M` past the end clamps to the last byte,
+ *     which RFC 9110 §14.1.2 requires; `-N` larger than the file means the whole file, same clause.
+ *   - A range unit that is NOT `bytes` is IGNORED and the full representation is sent. RFC 9110
+ *     §14.2 says MUST on this, and it is not a covering fallback: `Accept-Ranges: bytes` on the
+ *     same response has already told the client which unit this server speaks.
+ *   - A `bytes=` header that does not parse, or that starts past the end of the file, is
+ *     UNSATISFIABLE. That answers 416 with a `Content-Range` of `bytes STAR/size`, never a 200. This is
+ *     the case the old regex covered up.
+ *   - A MULTI-range request (`bytes=0-9, 20-29`) is refused with 416 rather than served as one
+ *     coalesced span or silently reduced to its first range. A `multipart/byteranges` body is not
+ *     implemented here, and answering a two-range request with one range's bytes, under a status
+ *     code that claims the request was honoured, is the same class of defect this file exists to
+ *     remove. No stored-file client on this node sends one.
+ * @structure parseRangeHeader() — the verdict · sendPartialContent() / setAcceptRanges() /
+ *   rangeNotSatisfiable() — the three response shapes a door needs · serveStoredFile() — all three,
+ *   plus the read, in the one order that does not load a file to send part of it
+ * @usage
+ *   const file = await storage.getStorageFileMeta(gaii, key);      // no bytes yet
+ *   if (!file) { …404… }
+ *   res.setHeader('Cache-Control', 'public, max-age=300');          // this door's own headers first
+ *   const served = await serveStoredFile(res, file, req.headers.range, {
+ *       range: (start, length) => storage.readStorageFileRange(gaii, key, start, length),
+ *       all: () => storage.getStorageFile(gaii, key).then(f => f?.data ?? null),
+ *   });
+ *   if (!served) { …404… }                                         // it vanished mid-request
+ * @version-history
+ *   v1.1.0 -- 2026-08-15 -- TARGET-063: serveStoredFile(), so a range is read as a range. The four
+ *     doors each carried the same three-line dance and each began by loading the whole file.
+ *   v1.0.0 -- 2026-08-15 -- TARGET-063 A1: extracted from the three copies in routes/storage-files.ts,
+ *     with suffix ranges, 416 and Accept-Ranges added. GET /v1/pub gains range support for the first
+ *     time; it is the door a program reading a data package from its permanent address knocks at.
+ */
+import type { Response } from 'express';
+/** What a `Range` header means for one representation of a known size. */
+export type RangeVerdict = 
+/** No usable range: absent header, or a unit this server does not speak. Send the whole thing, 200. */
+{
+    kind: 'full';
+}
+/** Inclusive byte offsets into the representation. Send 206. */
+ | {
+    kind: 'partial';
+    start: number;
+    end: number;
+}
+/** The header named `bytes` and could not be honoured. Send 416 — never 200. */
+ | {
+    kind: 'unsatisfiable';
+    reason: string;
+};
+/**
+ * Decide what a `Range` header asks for.
+ *
+ * `size` is the complete length of the representation. A zero-length file makes every byte range
+ * unsatisfiable, which is what RFC 9110 §15.5.17 describes and what a client needs to hear rather
+ * than a 200 with no bytes and a status that says it was a partial answer.
+ */
+export declare function parseRangeHeader(header: string | undefined | null, size: number): RangeVerdict;
+/**
+ * Announce range support. Belongs on EVERY response that carries (or describes) stored bytes,
+ * including the 200 and the HEAD: a client decides whether to range-read from this header, and a
+ * server that answers ranges without advertising them is a server nothing ranges against.
+ */
+export declare function setAcceptRanges(res: Response): void;
+/**
+ * 416 with the one header that makes it actionable: a `Content-Range` of `bytes STAR/size` tells the
+ * client how long the representation actually is, so its next request can be a valid one.
+ *
+ * Deliberately NOT the envelope. This is a byte-serving path, the caller may be a database engine
+ * rather than a browser, and the status plus Content-Range is the whole message.
+ */
+export declare function rangeNotSatisfiable(res: Response, size: number, reason: string): void;
+/**
+ * 206 with the slice.
+ *
+ * `chunk` is the slice and `file` describes the WHOLE representation, which is the distinction the
+ * Content-Range header itself makes. `setStoredFileHeaders` follows the same rule: it takes the
+ * file's stored UTF-8 verdict when there is one, so this response names the same content type the
+ * full GET does. Sniffing the slice would not — a multi-byte character straddling the boundary
+ * fails a decode that the whole file passes.
+ */
+export declare function sendPartialContent(res: Response, file: {
+    key: string;
+    mimeType: string;
+    size: number;
+    data?: Buffer;
+    utf8Verified?: boolean;
+}, range: {
+    start: number;
+    end: number;
+}, chunk: Buffer): void;
+/**
+ * Does naming this file's content type still require reading it?
+ *
+ * Only for a row written before the UTF-8 verdict was recorded, and only for a type whose served
+ * form the verdict would change. Everything written since answers from metadata alone, and this
+ * shrinks to nothing as old rows are rewritten.
+ */
+export declare function needsBytesForType(file: {
+    mimeType: string;
+    utf8Verified?: boolean;
+}): boolean;
+/** How a door gets at the bytes it is about to serve. Both halves come from the storage layer, and
+ *  a range read never touches the rest of the file. */
+export interface StoredFileReader {
+    /** `length` bytes from byte offset `start`. Null only if the file has disappeared. */
+    range(start: number, length: number): Promise<Buffer | null>;
+    /** The whole representation. Null only if the file has disappeared. */
+    all(): Promise<Buffer | null>;
+}
+/**
+ * Serve one stored file, honouring `Range`, from METADATA plus a reader.
+ *
+ * WHY THE READER IS A CALLBACK AND NOT A BUFFER. Every door here used to load the entire file and
+ * then decide what part of it to send, which meant an eight-byte suffix request — the first thing a
+ * Parquet reader asks for — read 25 MB out of the database to answer it. Measured on Postgres:
+ * 181 ms that way, 3 ms as a database-side substring, and the gap widens with the file. Taking the
+ * reader rather than the bytes is what lets the decision come BEFORE the read.
+ *
+ * The caller sets its own caching and CORS headers first; they differ per door and these do not.
+ * Returns false when the file vanished between the metadata read and the bytes, and sends nothing —
+ * the caller owns the 404 because only it knows which shape of "not found" that door tells.
+ */
+export declare function serveStoredFile(res: Response, file: {
+    key: string;
+    mimeType: string;
+    size: number;
+    utf8Verified?: boolean;
+    createdAt?: string;
+}, rangeHeader: string | undefined, read: StoredFileReader, opts?: {
+    headOnly?: boolean;
+}): Promise<boolean>;
+//# sourceMappingURL=http-range.d.ts.map

package/dist/src/utils/http-range.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http-range.d.ts","sourceRoot":"","sources":["../../../src/utils/http-range.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AACH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAIxC,0EAA0E;AAC1E,MAAM,MAAM,YAAY;AACpB,uGAAuG;AACrG;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE;AAClB,gEAAgE;GAC9D;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE;AACjD,gFAAgF;GAC9E;IAAE,IAAI,EAAE,eAAe,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAEhD;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,EAAE,IAAI,EAAE,MAAM,GAAG,YAAY,CAyC9F;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,QAAQ,GAAG,IAAI,CAEnD;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAMrF;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAC9B,GAAG,EAAE,QAAQ,EACb,IAAI,EAAE;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,YAAY,CAAC,EAAE,OAAO,CAAA;CAAE,EAC5F,KAAK,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,EACrC,KAAK,EAAE,MAAM,GACd,IAAI,CAON;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,YAAY,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,OAAO,CAE7F;AAED;uDACuD;AACvD,MAAM,WAAW,gBAAgB;IAC7B,sFAAsF;IACtF,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAC7D,uEAAuE;IACvE,GAAG,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;CACjC;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,eAAe,CACjC,GAAG,EAAE,QAAQ,EACb,IAAI,EAAE;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,YAAY,CAAC,EAAE,OAAO,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,EACjG,WAAW,EAAE,MAAM,GAAG,SAAS,EAC/B,IAAI,EAAE,gBAAgB,EACtB,IAAI,GAAE;IAAE,QAAQ,CAAC,EAAE,OAAO,CAAA;CAAO,GAClC,OAAO,CAAC,OAAO,CAAC,CAoElB"}

package/dist/src/utils/http-range.js

@@ -0,0 +1,190 @@
+import { setStoredFileHeaders } from './file-download-headers.js';
+import { needsUtf8Verdict } from './app-content-type.js';
+/**
+ * Decide what a `Range` header asks for.
+ *
+ * `size` is the complete length of the representation. A zero-length file makes every byte range
+ * unsatisfiable, which is what RFC 9110 §15.5.17 describes and what a client needs to hear rather
+ * than a 200 with no bytes and a status that says it was a partial answer.
+ */
+export function parseRangeHeader(header, size) {
+    const raw = (header ?? '').trim();
+    if (!raw)
+        return { kind: 'full' };
+    // A unit we do not speak. RFC 9110 §14.2: ignore it and answer with the full representation.
+    // `Accept-Ranges: bytes` is on that same response, so the client is not left guessing.
+    if (!/^bytes\s*=/i.test(raw))
+        return { kind: 'full' };
+    const spec = raw.slice(raw.indexOf('=') + 1).trim();
+    if (spec.includes(',')) {
+        return {
+            kind: 'unsatisfiable',
+            reason: 'This server serves one byte range per request. A multipart/byteranges response is '
+                + 'not implemented, and answering part of what was asked under a success status would '
+                + 'hide that. Ask for one range at a time.',
+        };
+    }
+    // suffix-byte-range-spec: "-N" — the LAST N bytes. The shape a Parquet reader opens with.
+    const suffix = /^-(\d+)$/.exec(spec);
+    if (suffix) {
+        const wanted = parseInt(suffix[1], 10);
+        if (!Number.isFinite(wanted) || wanted <= 0 || size === 0) {
+            return { kind: 'unsatisfiable', reason: `suffix range "${spec}" against a ${size}-byte representation` };
+        }
+        // Asking for more than there is means the whole thing (RFC 9110 §14.1.2), not an error.
+        return { kind: 'partial', start: Math.max(0, size - wanted), end: size - 1 };
+    }
+    // int-byte-range-spec: "N-" or "N-M".
+    const explicit = /^(\d+)-(\d*)$/.exec(spec);
+    if (!explicit) {
+        return { kind: 'unsatisfiable', reason: `unparseable byte range "${spec}"` };
+    }
+    const start = parseInt(explicit[1], 10);
+    // An absent last-byte-pos means "to the end"; one past the end clamps to the last byte.
+    const end = explicit[2] === '' ? size - 1 : Math.min(parseInt(explicit[2], 10), size - 1);
+    if (!Number.isFinite(start) || size === 0 || start >= size || end < start) {
+        return { kind: 'unsatisfiable', reason: `byte range "${spec}" against a ${size}-byte representation` };
+    }
+    return { kind: 'partial', start, end };
+}
+/**
+ * Announce range support. Belongs on EVERY response that carries (or describes) stored bytes,
+ * including the 200 and the HEAD: a client decides whether to range-read from this header, and a
+ * server that answers ranges without advertising them is a server nothing ranges against.
+ */
+export function setAcceptRanges(res) {
+    res.setHeader('Accept-Ranges', 'bytes');
+}
+/**
+ * 416 with the one header that makes it actionable: a `Content-Range` of `bytes STAR/size` tells the
+ * client how long the representation actually is, so its next request can be a valid one.
+ *
+ * Deliberately NOT the envelope. This is a byte-serving path, the caller may be a database engine
+ * rather than a browser, and the status plus Content-Range is the whole message.
+ */
+export function rangeNotSatisfiable(res, size, reason) {
+    res.status(416);
+    setAcceptRanges(res);
+    res.setHeader('Content-Range', `bytes */${size}`);
+    res.setHeader('Content-Type', 'text/plain; charset=utf-8');
+    res.end(`416 Range Not Satisfiable: ${reason}\n`);
+}
+/**
+ * 206 with the slice.
+ *
+ * `chunk` is the slice and `file` describes the WHOLE representation, which is the distinction the
+ * Content-Range header itself makes. `setStoredFileHeaders` follows the same rule: it takes the
+ * file's stored UTF-8 verdict when there is one, so this response names the same content type the
+ * full GET does. Sniffing the slice would not — a multi-byte character straddling the boundary
+ * fails a decode that the whole file passes.
+ */
+export function sendPartialContent(res, file, range, chunk) {
+    res.status(206);
+    setStoredFileHeaders(res, file);
+    setAcceptRanges(res);
+    res.setHeader('Content-Range', `bytes ${range.start}-${range.end}/${file.size}`);
+    res.setHeader('Content-Length', chunk.length);
+    res.end(chunk);
+}
+/**
+ * Does naming this file's content type still require reading it?
+ *
+ * Only for a row written before the UTF-8 verdict was recorded, and only for a type whose served
+ * form the verdict would change. Everything written since answers from metadata alone, and this
+ * shrinks to nothing as old rows are rewritten.
+ */
+export function needsBytesForType(file) {
+    return file.utf8Verified === undefined && needsUtf8Verdict(file.mimeType);
+}
+/**
+ * Serve one stored file, honouring `Range`, from METADATA plus a reader.
+ *
+ * WHY THE READER IS A CALLBACK AND NOT A BUFFER. Every door here used to load the entire file and
+ * then decide what part of it to send, which meant an eight-byte suffix request — the first thing a
+ * Parquet reader asks for — read 25 MB out of the database to answer it. Measured on Postgres:
+ * 181 ms that way, 3 ms as a database-side substring, and the gap widens with the file. Taking the
+ * reader rather than the bytes is what lets the decision come BEFORE the read.
+ *
+ * The caller sets its own caching and CORS headers first; they differ per door and these do not.
+ * Returns false when the file vanished between the metadata read and the bytes, and sends nothing —
+ * the caller owns the 404 because only it knows which shape of "not found" that door tells.
+ */
+export async function serveStoredFile(res, file, rangeHeader, read, opts = {}) {
+    // A validator, on every representation of the file. A ranged reader keeps one of these between
+    // requests to know the bytes did not move under it, and DuckDB reads Last-Modified straight off
+    // the probe. It costs nothing: the write time is already in the metadata.
+    if (file.createdAt) {
+        const at = new Date(file.createdAt);
+        if (!Number.isNaN(at.getTime()))
+            res.setHeader('Last-Modified', at.toUTCString());
+    }
+    // ONE decision, made before anything is sent: can this file's content type be named without its
+    // bytes? With a stored verdict, yes, and nothing outside the requested range is ever read. For a
+    // file written before the verdict existed the charset still lives in the content, so the whole
+    // file is read — the same cost as before this change, paid only by rows that predate it, and
+    // gone the next time each one is written.
+    //
+    // Getting this wrong is not a slow response but a false one. An earlier draft passed the
+    // metadata record straight through, and its `data` is an EMPTY buffer: the sniffer decoded zero
+    // bytes, found them valid UTF-8, and stamped `charset=utf-8` on a range reply. On a genuinely
+    // cp1252 file that declares an encoding the file does not have, over a GET of the same file that
+    // correctly declares nothing.
+    const whole = needsBytesForType(file) ? await read.all() : null;
+    if (needsBytesForType(file) && !whole)
+        return false;
+    const described = whole ? { ...file, data: whole } : file;
+    const verdict = parseRangeHeader(rangeHeader, file.size);
+    // A HEAD answers out of the metadata and reads nothing more. Express auto-handles HEAD through
+    // the GET handler, so /v1/pub was loading the entire file and discarding the body: 114 ms
+    // measured, for a 10 MB file, to send zero bytes.
+    //
+    // IT STILL HONOURS `Range`, and that is not pedantry about RFC 9110's "same headers a GET would
+    // send". A HEAD carrying `Range: bytes=0-` is how a client ASKS whether this server does ranges,
+    // and DuckDB-Wasm's own words for the answer are `if (contentLength !== null && status == 206)`.
+    // An earlier version of this function short-circuited before reading the Range header, so that
+    // probe got 200 and the full length. DuckDB read it as "no ranges here" and downloaded an 8.45 MB
+    // Parquet file in one request to answer a two-column aggregate — and with full reads disabled it
+    // refused to open the file at all. A fast HEAD that lies about ranges is worse than a slow one.
+    if (opts.headOnly) {
+        if (verdict.kind === 'unsatisfiable') {
+            rangeNotSatisfiable(res, file.size, verdict.reason);
+            return true;
+        }
+        setStoredFileHeaders(res, described);
+        setAcceptRanges(res);
+        if (verdict.kind === 'partial') {
+            res.status(206);
+            res.setHeader('Content-Range', `bytes ${verdict.start}-${verdict.end}/${file.size}`);
+            res.setHeader('Content-Length', verdict.end - verdict.start + 1);
+        }
+        else {
+            res.setHeader('Content-Length', file.size);
+        }
+        res.end();
+        return true;
+    }
+    if (verdict.kind === 'unsatisfiable') {
+        rangeNotSatisfiable(res, file.size, verdict.reason);
+        return true;
+    }
+    if (verdict.kind === 'partial') {
+        // When the file is already in hand there is nothing to gain from asking the database for a
+        // slice of it, so the second read is skipped rather than repeated.
+        const chunk = whole
+            ? whole.subarray(verdict.start, verdict.end + 1)
+            : await read.range(verdict.start, verdict.end - verdict.start + 1);
+        if (!chunk)
+            return false;
+        sendPartialContent(res, described, verdict, chunk);
+        return true;
+    }
+    const data = whole ?? await read.all();
+    if (!data)
+        return false;
+    setStoredFileHeaders(res, { ...described, data });
+    setAcceptRanges(res);
+    res.setHeader('Content-Length', file.size);
+    res.end(data);
+    return true;
+}
+//# sourceMappingURL=http-range.js.map

package/dist/src/utils/http-range.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"http-range.js","sourceRoot":"","sources":["../../../src/utils/http-range.ts"],"names":[],"mappings":"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"}

package/dist/src/utils/page-head.d.ts

@@ -19,6 +19,11 @@
  * @usage
  *   html = injectPageHead(html, findPublicPage('/v1/connect'), config, nonceAttr);
  * @version-history
+ *   v1.1.0 — 2026-08-16 — The per-page WebPage JSON-LD is emitted again. Its guard was "the
+ *     document has no ld+json at all", and spa.html always ships SoftwareApplication +
+ *     Organization, so on every SPA route — which is every page in the registry — the per-page
+ *     block was silently skipped. Guard is now the WebPage marker itself. Adds the llmstxt.org
+ *     v2 rel="describedby" link beside the markdown alternate.
  *   v1.0.0 — 2026-07-28 — Initial (agent-readability phases 07 + 08)
  */
 import type { AimeatConfig } from '../config.js';

package/dist/src/utils/page-head.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"page-head.d.ts","sourceRoot":"","sources":["../../../src/utils/page-head.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AACjD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAc1D;;;GAGG;AACH,wBAAgB,cAAc,CAC5B,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,UAAU,EAChB,MAAM,EAAE,YAAY,EACpB,SAAS,SAAK,GACb,MAAM,CAqCR"}
+{"version":3,"file":"page-head.d.ts","sourceRoot":"","sources":["../../../src/utils/page-head.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AACjD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAc1D;;;GAGG;AACH,wBAAgB,cAAc,CAC5B,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,UAAU,EAChB,MAAM,EAAE,YAAY,EACpB,SAAS,SAAK,GACb,MAAM,CAgDR"}

package/dist/src/utils/page-head.js

@@ -30,7 +30,16 @@ export function injectPageHead(html, page, config, nonceAttr = '') {
     if (page.markdown) {
         out = upsert(out, /<link rel="alternate" type="text\/markdown"[^>]*>/i, `<link rel="alternate" type="text/markdown" href="${mirror}">`);
     }
-    if (!/application\/ld\+json/i.test(out)) {
+    // llmstxt.org v2 names rel="describedby" as the link from a page to the llms.txt that covers it,
+    // beside the markdown alternate above. A reader that finds one convention and not the other has
+    // to guess the path.
+    out = upsert(out, /<link rel="describedby"[^>]*>/i, `<link rel="describedby" type="text/plain" href="${b}/llms.txt">`);
+    // The WebPage block describes THIS page and is separate from the site-level SoftwareApplication
+    // and Organization blocks that spa.html ships. This used to be guarded by "does the document
+    // already contain any ld+json", which spa.html always does — so on every SPA route, which is
+    // every page in the registry, the per-page structured data was never emitted. Multiple ld+json
+    // blocks in one document are legal, and are how you say two different things.
+    if (!/"@type"\s*:\s*"WebPage"/.test(out)) {
         const jsonLd = JSON.stringify({
             '@context': 'https://schema.org',
             '@type': 'WebPage',

package/dist/src/utils/page-head.js.map

@@ -1 +1 @@
-{"version":3,"file":"page-head.js","sourceRoot":"","sources":["../../../src/utils/page-head.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"page-head.js","sourceRoot":"","sources":["../../../src/utils/page-head.ts"],"names":[],"mappings":"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"}

package/dist/src/utils/reserved-keys.d.ts

@@ -16,6 +16,9 @@
  *   appMayWriteKey(roles, key, delegatedOwnerWrite?, reservedAllowed?)
  * @usage import { appMayWriteKey } from '../utils/reserved-keys.js';
  * @version-history
+ *   v1.4.0 — 2026-08-16 — `chat.` joins the list. A conversation is what the person said and what
+ *     the agent did on their behalf, and an app-grant token that could append to one could put
+ *     words in either mouth — including instructions the next turn would read as the person's own.
  *   v1.3.0 — 2026-08-11 — `finance.` and `commerce.` join the list (August 2026 audit H-6, H-23).
  *     Both became server-trusted after the list was written and neither was added.
  *     `finance.accountants` is the CROSS-OWNER authorization list for the whole finance area:
@@ -57,7 +60,7 @@
  * write that never passes through this gate, which is what the openrouter, finance and commerce
  * keys all use.
  */
-export declare const RESERVED_OWNER_KEY_PREFIXES: readonly ["openrouter.", "ai-usage.", "profile.", "finance.", "commerce."];
+export declare const RESERVED_OWNER_KEY_PREFIXES: readonly ["openrouter.", "ai-usage.", "profile.", "finance.", "commerce.", "chat."];
 /** True iff `key` falls under a reserved, server-trusted owner-namespace prefix. */
 export declare function isReservedServerKey(key: string): boolean;
 /**

package/dist/src/utils/reserved-keys.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"reserved-keys.d.ts","sourceRoot":"","sources":["../../../src/utils/reserved-keys.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AAEH;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,2BAA2B,4EAE9B,CAAC;AAEX,oFAAoF;AACpF,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAExD;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,MAAM,EAAE,EAAE,GAAG,EAAE,MAAM,EAAE,mBAAmB,UAAQ,EAAE,eAAe,UAAQ,GACjF,OAAO,CAQT"}
+{"version":3,"file":"reserved-keys.d.ts","sourceRoot":"","sources":["../../../src/utils/reserved-keys.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AAEH;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,2BAA2B,qFAE9B,CAAC;AAEX,oFAAoF;AACpF,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAExD;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,MAAM,EAAE,EAAE,GAAG,EAAE,MAAM,EAAE,mBAAmB,UAAQ,EAAE,eAAe,UAAQ,GACjF,OAAO,CAQT"}

package/dist/src/utils/reserved-keys.js

@@ -16,6 +16,9 @@
  *   appMayWriteKey(roles, key, delegatedOwnerWrite?, reservedAllowed?)
  * @usage import { appMayWriteKey } from '../utils/reserved-keys.js';
  * @version-history
+ *   v1.4.0 — 2026-08-16 — `chat.` joins the list. A conversation is what the person said and what
+ *     the agent did on their behalf, and an app-grant token that could append to one could put
+ *     words in either mouth — including instructions the next turn would read as the person's own.
  *   v1.3.0 — 2026-08-11 — `finance.` and `commerce.` join the list (August 2026 audit H-6, H-23).
  *     Both became server-trusted after the list was written and neither was added.
  *     `finance.accountants` is the CROSS-OWNER authorization list for the whole finance area:
@@ -58,7 +61,7 @@
  * keys all use.
  */
 export const RESERVED_OWNER_KEY_PREFIXES = [
-    'openrouter.', 'ai-usage.', 'profile.', 'finance.', 'commerce.',
+    'openrouter.', 'ai-usage.', 'profile.', 'finance.', 'commerce.', 'chat.',
 ];
 /** True iff `key` falls under a reserved, server-trusted owner-namespace prefix. */
 export function isReservedServerKey(key) {

package/dist/src/utils/reserved-keys.js.map

@@ -1 +1 @@
-{"version":3,"file":"reserved-keys.js","sourceRoot":"","sources":["../../../src/utils/reserved-keys.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AAEH;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,MAAM,2BAA2B,GAAG;IACzC,aAAa,EAAE,WAAW,EAAE,UAAU,EAAE,UAAU,EAAE,WAAW;CACvD,CAAC;AAEX,oFAAoF;AACpF,MAAM,UAAU,mBAAmB,CAAC,GAAW;IAC7C,OAAO,2BAA2B,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,GAAG,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC;AAC9E,CAAC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,cAAc,CAC5B,KAAe,EAAE,GAAW,EAAE,mBAAmB,GAAG,KAAK,EAAE,eAAe,GAAG,KAAK;IAElF,MAAM,cAAc,GAAG,KAAK,CAAC,QAAQ,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC;IAC3G,IAAI,cAAc;QAAE,OAAO,IAAI,CAAC;IAChC,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,mBAAmB;QAAE,OAAO,IAAI,CAAC;IAChE,+FAA+F;IAC/F,kFAAkF;IAClF,IAAI,eAAe;QAAE,OAAO,IAAI,CAAC;IACjC,OAAO,CAAC,mBAAmB,CAAC,GAAG,CAAC,CAAC;AACnC,CAAC"}
+{"version":3,"file":"reserved-keys.js","sourceRoot":"","sources":["../../../src/utils/reserved-keys.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AAEH;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,MAAM,2BAA2B,GAAG;IACzC,aAAa,EAAE,WAAW,EAAE,UAAU,EAAE,UAAU,EAAE,WAAW,EAAE,OAAO;CAChE,CAAC;AAEX,oFAAoF;AACpF,MAAM,UAAU,mBAAmB,CAAC,GAAW;IAC7C,OAAO,2BAA2B,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,GAAG,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC;AAC9E,CAAC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,cAAc,CAC5B,KAAe,EAAE,GAAW,EAAE,mBAAmB,GAAG,KAAK,EAAE,eAAe,GAAG,KAAK;IAElF,MAAM,cAAc,GAAG,KAAK,CAAC,QAAQ,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC;IAC3G,IAAI,cAAc;QAAE,OAAO,IAAI,CAAC;IAChC,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,mBAAmB;QAAE,OAAO,IAAI,CAAC;IAChE,+FAA+F;IAC/F,kFAAkF;IAClF,IAAI,eAAe;QAAE,OAAO,IAAI,CAAC;IACjC,OAAO,CAAC,mBAAmB,CAAC,GAAG,CAAC,CAAC;AACnC,CAAC"}