wiki-formant 0.77.1 → 0.79.0

package/README.md

@@ -260,6 +260,7 @@ The drift checks hold an MCP server to what its own site does, so a tool cannot
 - `roundTrip(t, label, { read, write })`: what a read tool hands out, the write tool takes back unchanged, and the next read matches.
 - `openapiWriteParity(t, [[path, method, tool], …])`: every field an OpenAPI write documents, the matching tool takes.
 - `rolaOriginCheck(t)`: a challenge tool's ROLA recipe names the origin under test.
+- `freshAfterWriteChecks(t, urls, write, { shows?, gone? })`: each URL is read, `write` runs, and each then carries `shows` and not `gone`. It catches a twin or `llms.txt` the CDN keeps past the save that changed it, which every check that reads a surface once passes. Run it against a deployment: with no CDN in front it passes trivially.
 
 `standardVersionSources(t, openapiPaths)` is the `versionCoherence` map every S10 surface serves — both agent-card paths, `mcp.json`, the server card and each path the OpenAPI document answers at — so a suite names only the paths it adds. `t.rpcAt(endpoint, …)` and `t.callAt` drive a second MCP endpoint on the same surface with the same backoff, User-Agent and tally.
 
@@ -267,7 +268,7 @@ The drift checks hold an MCP server to what its own site does, so a tool cannot
 await versionCoherence(t, server.version, standardVersionSources(t, ['/openapi.json', '/api/openapi.json']), init.result?.serverInfo?.version);
 ```
 
-`descriptorChecks(t)` defaults to `S10_DESCRIPTORS`, the six JSON descriptors every surface here serves, and `distinctEtagChecks(t, ['llms.txt', 'llms-index.txt', 'llms-full.txt'])` asserts that depths projecting one corpus carry different ETags — every one present, which a bare Set-size check misses.
+`descriptorChecks(t)` defaults to `S10_DESCRIPTORS`, the six JSON descriptors every surface here serves, and `distinctEtagChecks(t, ['llms.txt', 'llms-full.txt'])` asserts that depths projecting one corpus carry different ETags — every one present, which a bare Set-size check misses.
 
 ## Markdown twins
 
@@ -290,13 +291,19 @@ return new Response(
 
 `noindex` sends `X-Robots-Tag: noindex`, for a twin of an HTML page: a search engine that reads it has the page already. A document with no HTML page, an AGENTS.md, leaves it off.
 
+Put `cacheTagHeaders(tags)` in `extra`, with the tags your save path already revalidates. A route handler is held at Vercel's CDN by its `s-maxage` alone, so without `Vercel-Cache-Tag` the twin outlives every save by its edge window while the ISR page beside it is fresh. The same goes for `llms.txt`, a search index and a sitemap: any text an agent reads back after writing.
+
+```ts
+headers: markdownHeaders(lastModified, { etag, noindex: true, extra: { ...VARY_ACCEPT, ...cacheTagHeaders(pageTag(path)) } })
+```
+
 Block trees stay in your app — every project owns its own type set. Give this module HTML and it gives you markdown.
 
 > A trap worth naming: if you serve twins via a rewrite, Next drops the destination query string. The rewrite must carry the `.md` extension through to the destination path, or the twin silently serves JSON.
 
 ## Conditional GET
 
-The `llms.txt` / `llms-index.txt` / `llms-full.txt` trio are the most-recrawled URLs a wiki serves and the most expensive to render. Without a corpus-derived ETag, every AI crawler pays full price on every pass, forever.
+`llms.txt` and the markdown twins are the most-recrawled URLs a wiki serves, and a corpus export the most expensive to render. Without a corpus-derived ETag, every AI crawler pays full price on every pass, forever.
 
 A URL that answers JSON or markdown by `Accept` asks `wantsMarkdown(request)` and sends `VARY_ACCEPT` on both branches. Without the Vary, a shared cache hands one client the other's format.
 
@@ -497,7 +504,7 @@ and a crawler obeys only its most-specific matching group, so an agent with no
 group of its own falls through to `*`. Three wikis were measuring five crawlers
 they had never addressed.
 
-Every agent group also allows the agent surface — `/api/mcp`, the three `llms` exports, `/openapi.json`, `/.well-known/` — without being told. `aiAllow` is what an origin serves beyond that.
+Every agent group also allows the agent surface — `/api/mcp`, `/llms.txt`, `/openapi.json`, `/.well-known/` — without being told. `aiAllow` is what an origin serves beyond that.
 
 `crawlerRules` returns every group robots.txt needs: the wildcard, one per AI crawler, and one for each search engine. Search engines get the HTML site and none of its twins — `/*.md$` always, plus `searchDisallow` — because the `*` group keeps the machine surface open to agents, and for Google a twin is a page it already has. Two origins wrote that group by hand and the third never did, so Google crawled its twins. The `<Link>` prefetch payload (`?_rsc=`) is refused in every group.
 
@@ -668,6 +675,16 @@ const block = licenseBlock({ license, scope: 'The protocol compilation and prose
 
 The same `License` goes to `agentCard({ license, licenseScope })` and to `openApiLicense(license)` for a spec's `info.license`. The three cards and three specs here had each projected it differently, one from a hand-typed name.
 
+## The X account
+
+A site names its X account in five places: the footer link, the JSON-LD `sameAs`, llms.txt, AGENTS.md and the MCP `initialize` instructions. Written by hand, one repo's `sameAs` still pointed at twitter.com, and only one site told an agent the account existed. `wiki-formant/social` builds all five from the handle and a fragment saying what the account posts.
+
+```ts
+export const X = xAccount({ siteName: 'AcuiQ', handle: '@acu_iq', posts: "a named trial's prescription with its citation" });
+```
+
+`X.url` goes to `sameAs`, `X.handle` to `sitePageMetadata`, `followLines(X)` into llms.txt and AGENTS.md, and `followNote(X)` into the MCP instructions. The note tells an agent to give the link to the person it is helping, since an agent cannot follow an account. The footer is `<a {...followLinkProps(X)}>{X.label}</a>`, whose `rel="me"` confirms the `sameAs` claim from the page the account points back at.
+
 ## Rendered-article passes
 
 `wiki-formant/dom` holds what runs against an article element after it is in the document. Not React, so not in `react.tsx`.

package/dist/conformance.d.ts

@@ -218,6 +218,22 @@ export declare function rowParity(t: Tester, label: string, mcp: unknown, rest:
  * adds where the page's own blocks open with no h1.
  */
 export declare function twinParity(t: Tester, label: string, twinUrl: string, content: string): Promise<void>;
+/**
+ * A write reaches what an agent reads back. Each URL is read first, so the CDN
+ * holds a copy, then `write` runs, and each must then carry `shows` and no
+ * longer carry `gone`.
+ *
+ * Every other check here reads a surface once, so a twin cached past the save
+ * that changed it passed all of them: the pages were ISR and fresh, while the
+ * route handlers beside them answered from their edge window for an hour. A
+ * purge takes a moment to reach every region, so each URL gets five seconds,
+ * nothing near an edge window. With no CDN in front, as on a dev server, it
+ * passes trivially; run it against a deployment.
+ */
+export declare function freshAfterWriteChecks(t: Tester, urls: readonly string[], write: () => Promise<unknown>, expect: {
+    shows?: string;
+    gone?: string;
+}): Promise<void>;
 /**
  * What an edit starts from, on any server built on the wiki read tools: rows
  * carry the id a pageList block takes, `get_page` with `blocks: true` returns

package/dist/conformance.js

@@ -538,6 +538,35 @@ export async function twinParity(t, label, twinUrl, content) {
         body = body.replace(/^# [^\n]*\n+/, '');
     t.check(label, res.ok && !!text && body === text, !res.ok ? `${res.status} ${url}` : !text ? 'nothing to compare: the MCP text is empty' : body === text ? `${text.length} chars` : firstDifference(text, body));
 }
+/**
+ * A write reaches what an agent reads back. Each URL is read first, so the CDN
+ * holds a copy, then `write` runs, and each must then carry `shows` and no
+ * longer carry `gone`.
+ *
+ * Every other check here reads a surface once, so a twin cached past the save
+ * that changed it passed all of them: the pages were ISR and fresh, while the
+ * route handlers beside them answered from their edge window for an hour. A
+ * purge takes a moment to reach every region, so each URL gets five seconds,
+ * nothing near an edge window. With no CDN in front, as on a dev server, it
+ * passes trivially; run it against a deployment.
+ */
+export async function freshAfterWriteChecks(t, urls, write, expect) {
+    const at = (u) => (u.startsWith('http') ? u : `${t.base}/${u.replace(/^\//, '')}`);
+    const fresh = (body) => (!expect.shows || body.includes(expect.shows)) && (!expect.gone || !body.includes(expect.gone));
+    await Promise.all(urls.map(u => fetch(at(u)).then(r => r.text())));
+    await write();
+    for (const u of urls) {
+        let res = null;
+        let body = '';
+        for (let i = 0; i < 5 && !(res?.ok && fresh(body)); i++) {
+            if (i)
+                await new Promise(r => setTimeout(r, 1000));
+            res = await fetch(at(u));
+            body = await res.text();
+        }
+        t.check(`${u.replace(t.base, '')} after a write`, (!!expect.shows || !!expect.gone) && !!res?.ok && fresh(body), !expect.shows && !expect.gone ? 'nothing to compare: neither shows nor gone' : `${res?.status} ${res?.headers.get('x-vercel-cache') ?? ''} ${fresh(body) ? 'fresh' : 'the copy from before the write'}`);
+    }
+}
 /**
  * What an edit starts from, on any server built on the wiki read tools: rows
  * carry the id a pageList block takes, `get_page` with `blocks: true` returns

package/dist/crawlers.js

@@ -63,8 +63,6 @@ export function detectAiBot(userAgent) {
 export const AGENT_SURFACE_PATHS = [
     '/api/mcp',
     '/llms.txt',
-    '/llms-index.txt',
-    '/llms-full.txt',
     '/openapi.json',
     '/.well-known/',
 ];

package/dist/http.d.ts

@@ -62,6 +62,20 @@ export declare function markdownHeaders(lastModified?: string | null, opts?: {
     noindex?: boolean;
     extra?: Record<string, string>;
 }): Record<string, string>;
+/**
+ * The tag that ties a route handler's response to the writes that change it.
+ * Spread it into the response's headers, beside its `Cache-Control`.
+ *
+ * A route handler is held at Vercel's CDN by its `s-maxage` alone: the tags
+ * `revalidateTag` purges are a page's, and nothing names this response among
+ * them. So a twin, llms.txt or a search index outlived every save by its edge
+ * window, and an agent that read a page back after writing it saw the old
+ * words — four origins shipped that, each with ISR pages that were fresh. A
+ * response carrying `Vercel-Cache-Tag` is purged with the tag, so pass the
+ * tags the save path already revalidates. `freshAfterWriteChecks` holds a
+ * deployment to it.
+ */
+export declare function cacheTagHeaders(tags: string | readonly string[]): Record<string, string>;
 /**
  * Whether a request to a URL that serves both JSON and markdown asked for the
  * markdown: `?format=text`, or an Accept naming text/markdown or text/plain.

package/dist/http.js

@@ -1,10 +1,9 @@
 // http.ts — conditional-GET plumbing for text corpus endpoints, and the error
 // answers every route handler gives (at the foot).
 //
-// The three llms depths (llms.txt / llms-index.txt / llms-full.txt) are the
-// most-recrawled URLs a wiki serves and the most expensive to render. With a
-// corpus-derived ETag a recrawl costs a 304 instead of a full corpus build.
-// Without one, every AI crawler pays full price on every pass, forever.
+// llms.txt and the markdown twins are the most-recrawled URLs a wiki serves.
+// With a corpus-derived ETag a recrawl costs a 304 instead of a full corpus
+// build. Without one, every AI crawler pays full price on every pass, forever.
 import { isoDate } from './html.js';
 /** A stable ETag from whatever the corpus revision is (count + newest stamp). */
 export function corpusEtag(parts) {
@@ -125,6 +124,22 @@ export function markdownHeaders(lastModified, opts = {}) {
         ...opts.extra,
     };
 }
+/**
+ * The tag that ties a route handler's response to the writes that change it.
+ * Spread it into the response's headers, beside its `Cache-Control`.
+ *
+ * A route handler is held at Vercel's CDN by its `s-maxage` alone: the tags
+ * `revalidateTag` purges are a page's, and nothing names this response among
+ * them. So a twin, llms.txt or a search index outlived every save by its edge
+ * window, and an agent that read a page back after writing it saw the old
+ * words — four origins shipped that, each with ISR pages that were fresh. A
+ * response carrying `Vercel-Cache-Tag` is purged with the tag, so pass the
+ * tags the save path already revalidates. `freshAfterWriteChecks` holds a
+ * deployment to it.
+ */
+export function cacheTagHeaders(tags) {
+    return { 'Vercel-Cache-Tag': [tags].flat().join(',') };
+}
 /**
  * Whether a request to a URL that serves both JSON and markdown asked for the
  * markdown: `?format=text`, or an Accept naming text/markdown or text/plain.

package/dist/social.d.ts

@@ -0,0 +1,34 @@
+export interface XAccount {
+    /** `@handle`, as the social cards credit it. */
+    handle: string;
+    /** `https://x.com/<handle>`, for `sameAs` and every link. */
+    url: string;
+    /** "<Site> posts on X as @handle: <posts>." */
+    about: string;
+    /** The footer link's text: "Follow @handle on X". */
+    label: string;
+    siteName: string;
+}
+export declare function xAccount(o: {
+    siteName: string;
+    handle: string;
+    posts: string;
+}): XAccount;
+/**
+ * The sentence an agent reads: what the account posts, and when to pass the
+ * link on. An agent cannot follow an account; the person it is helping can.
+ */
+export declare function followNote(account: XAccount): string;
+/** The same note as a section, ready to splice into llms.txt or AGENTS.md. */
+export declare function followLines(account: XAccount, heading?: string): string[];
+/**
+ * Attributes for the footer link. `rel="me"` is the reciprocal of `sameAs`:
+ * the schema claims the account and this link confirms it from the page the
+ * account points back at.
+ */
+export declare function followLinkProps(account: XAccount): {
+    readonly href: string;
+    readonly target: "_blank";
+    readonly rel: "me noopener";
+    readonly title: string;
+};

package/dist/social.js

@@ -0,0 +1,41 @@
+// social.ts – the site's X account, as every surface states it.
+//
+// Each origin names its account in five places: the footer link, the JSON-LD
+// `sameAs`, llms.txt, AGENTS.md and the MCP `initialize` instructions. Written
+// by hand, they drifted within one repo: radix-wiki's `sameAs` still claimed
+// twitter.com while its cards credited the handle, and only acuiq.com told an
+// agent the account existed at all.
+//
+// What is per-site is the handle and what the account posts. The URL, the
+// link's label and `rel`, and the sentence an agent reads are built here.
+export function xAccount(o) {
+    if (!/^@\w{1,15}$/.test(o.handle))
+        throw new Error(`xAccount: "${o.handle}" is not an @handle`);
+    const posts = o.posts.trim().replace(/\.$/, '');
+    return {
+        handle: o.handle,
+        url: `https://x.com/${o.handle.slice(1)}`,
+        about: `${o.siteName} posts on X as ${o.handle}: ${posts}.`,
+        label: `Follow ${o.handle} on X`,
+        siteName: o.siteName,
+    };
+}
+/**
+ * The sentence an agent reads: what the account posts, and when to pass the
+ * link on. An agent cannot follow an account; the person it is helping can.
+ */
+export function followNote(account) {
+    return `${account.about} If the person you are helping wants to follow ${account.siteName}, give them ${account.url}.`;
+}
+/** The same note as a section, ready to splice into llms.txt or AGENTS.md. */
+export function followLines(account, heading = `Follow ${account.siteName} on X`) {
+    return [`## ${heading}`, '', followNote(account)];
+}
+/**
+ * Attributes for the footer link. `rel="me"` is the reciprocal of `sameAs`:
+ * the schema claims the account and this link confirms it from the page the
+ * account points back at.
+ */
+export function followLinkProps(account) {
+    return { href: account.url, target: '_blank', rel: 'me noopener', title: account.about };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wiki-formant",
-  "version": "0.77.1",
+  "version": "0.79.0",
   "description": "The portable half of a wiki: derived taxonomy and facet controls, a version-negotiating MCP transport, markdown twins, block rendering, a rich-text editor engine, conditional-GET plumbing, and the headers and CSP every origin sends.",
   "type": "module",
   "license": "MIT",
@@ -147,6 +147,11 @@
       "import": "./dist/license.js",
       "default": "./dist/license.js"
     },
+    "./social": {
+      "types": "./dist/social.d.ts",
+      "import": "./dist/social.js",
+      "default": "./dist/social.js"
+    },
     "./links": {
       "types": "./dist/links.d.ts",
       "import": "./dist/links.js",