@gradial/aci 0.1.46 → 0.1.48

package/README.md

@@ -1,6 +1,6 @@
 # Agentic Content Infrastructure SDK
 
-`@gradial/aci` `0.1.45` is a pre-1.0 public-surface reset for the ACI
+`@gradial/aci` `0.1.48` is a pre-1.0 public-surface reset for the ACI
 client SDK. Breaking changes from the old `0.1.x` accidental surface are
 intentional: the root import is framework-neutral, framework runtime behavior is
 behind explicit subpaths, and the first required customer path is React/Next.
@@ -8,7 +8,7 @@ behind explicit subpaths, and the first required customer path is React/Next.
 ## Install
 
 ```bash
-npm install @gradial/aci@0.1.45 zod@^4
+npm install @gradial/aci@0.1.48 zod@^4
 ```
 
 ## Root Import
@@ -85,13 +85,13 @@ go through an app-owned HTTP endpoint backed server-side by a `ContentProvider`.
 The first RC scaffold path is Next:
 
 ```bash
-npx @gradial/aci@0.1.45 init my-site --template next-starter
+npx @gradial/aci@0.1.48 init my-site --template next-starter
 ```
 
 List available templates:
 
 ```bash
-npx @gradial/aci@0.1.45 init --list
+npx @gradial/aci@0.1.48 init --list
 ```
 
 ## Personalization: The One-Tag Install

package/dist/astro/error-page.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Astro error-page render helper (authorable-error-pages REQ-7 / REQ-11 /
+ * D-10 / D-11; 02-design "SDK core"). The Astro counterpart of the Next
+ * seams in `src/next/error-pages.tsx`: resolve the page bound by
+ * `site.json#errorPages[kind]` and load it through the normal page pipeline
+ * (`getPageData`) so the template's `404.astro`/`500.astro` stay thin —
+ * the spike's hand-rolled binding resolution and siteConfig casting live
+ * here instead (spike A kill list).
+ *
+ * Never throws: an error surface must not crash and must not re-enter the
+ * failing system (ANTI-2). Any failure — no bindings (REQ-4 warn posture),
+ * unreadable content, a bound page missing at render time — degrades to the
+ * shipped branded-neutral default fragment with the problem surfaced via
+ * console.warn.
+ *
+ * REQ-11: error pages are base-audience with no personalization, so the
+ * returned page data always carries empty collect/assignment tags.
+ */
+import { type AstroGlobal, type PageData } from './page.js';
+import { type ErrorPageKind, type ErrorPagePush, type ErrorPageType } from '../content/error-pages.js';
+import type { KernelRouteMetadata } from '../content/types.js';
+export interface AstroErrorPageData {
+    kind: ErrorPageKind;
+    /** D-14 page_type for the seat's instrumentation script. */
+    pageType: ErrorPageType;
+    /**
+     * Pre-rendered D-14 analytics `<script>` tag: the site's push function
+     * (`options.pushErrorPageView`, D-15 — normally the tenant-owned
+     * `src/aci/error-page-instrumentation.mjs`; the SDK default when omitted)
+     * serialized via `serializeErrorPageInstrumentation`. The seat injects it
+     * via `<Fragment set:html={...}>` — Astro serves real HTML documents, so
+     * the inline script executes.
+     */
+    instrumentationTag: string;
+    /**
+     * The bound page loaded through the normal pipeline, with collect and
+     * assignment tags suppressed (REQ-11). Null when the shipped default
+     * applies — render `fallbackHtml` instead.
+     */
+    data: PageData | null;
+    /** Shipped branded-neutral default fragment (REQ-4) when `data` is null. */
+    fallbackHtml: string | null;
+    /** Document metadata for the layout shell, valid in either branch. */
+    meta: KernelRouteMetadata;
+}
+/**
+ * Resolves and loads the error page bound to `kind` for Astro's native
+ * error seats (`404.astro` / `500.astro`). `astro` is the seat's Astro
+ * global; the bound route's content is loaded as if it were the requested
+ * route, so static builds emit it into `dist/404.html`/`dist/500.html` and
+ * server output renders it at error time from local compiled content — no
+ * CMS fetch on the failing path (ANTI-2).
+ */
+export declare function getErrorPageData(astro: AstroGlobal, kind: ErrorPageKind, options?: {
+    pushErrorPageView?: ErrorPagePush;
+}): Promise<AstroErrorPageData>;

package/dist/astro/error-page.js

@@ -0,0 +1,79 @@
+/**
+ * Astro error-page render helper (authorable-error-pages REQ-7 / REQ-11 /
+ * D-10 / D-11; 02-design "SDK core"). The Astro counterpart of the Next
+ * seams in `src/next/error-pages.tsx`: resolve the page bound by
+ * `site.json#errorPages[kind]` and load it through the normal page pipeline
+ * (`getPageData`) so the template's `404.astro`/`500.astro` stay thin —
+ * the spike's hand-rolled binding resolution and siteConfig casting live
+ * here instead (spike A kill list).
+ *
+ * Never throws: an error surface must not crash and must not re-enter the
+ * failing system (ANTI-2). Any failure — no bindings (REQ-4 warn posture),
+ * unreadable content, a bound page missing at render time — degrades to the
+ * shipped branded-neutral default fragment with the problem surfaced via
+ * console.warn.
+ *
+ * REQ-11: error pages are base-audience with no personalization, so the
+ * returned page data always carries empty collect/assignment tags.
+ */
+import { getPageData } from './page.js';
+import { defaultPushErrorPageView, errorPageType, resolveErrorPage, serializeErrorPageInstrumentation, } from '../content/error-pages.js';
+import { defaultErrorPageFragmentHtml } from '../content/default-error-page.js';
+const FALLBACK_META = {
+    notFound: {
+        title: 'Page not found',
+        description: 'The page you requested does not exist.',
+    },
+    catchAll: {
+        title: 'Something went wrong',
+        description: 'The page you requested could not be served right now.',
+    },
+};
+/**
+ * Resolves and loads the error page bound to `kind` for Astro's native
+ * error seats (`404.astro` / `500.astro`). `astro` is the seat's Astro
+ * global; the bound route's content is loaded as if it were the requested
+ * route, so static builds emit it into `dist/404.html`/`dist/500.html` and
+ * server output renders it at error time from local compiled content — no
+ * CMS fetch on the failing path (ANTI-2).
+ */
+export async function getErrorPageData(astro, kind, options = {}) {
+    const pageType = errorPageType(kind);
+    const instrumentationTag = serializeErrorPageInstrumentation(options.pushErrorPageView ?? defaultPushErrorPageView, kind);
+    try {
+        const { FileContentProvider } = await import('../providers/file.js');
+        const siteConfig = await new FileContentProvider().getSiteConfig();
+        const resolved = await resolveErrorPage(kind, siteConfig);
+        for (const warning of resolved.warnings) {
+            console.warn(`[aci error-pages] ${warning}`);
+        }
+        if (resolved.route) {
+            const slug = resolved.route.replace(/^\/+|\/+$/g, '');
+            const data = await getPageData({
+                params: { slug },
+                request: astro.request,
+                url: astro.url,
+            });
+            return {
+                kind,
+                pageType,
+                instrumentationTag,
+                // Base audience, no personalization on error surfaces (REQ-11).
+                data: { ...data, collectTag: '', assignmentsTag: '' },
+                fallbackHtml: null,
+                meta: data.meta,
+            };
+        }
+    }
+    catch (error) {
+        console.warn(`[aci error-pages] bound ${kind} page failed to load; serving the shipped default: ${String(error)}`);
+    }
+    return {
+        kind,
+        pageType,
+        instrumentationTag,
+        data: null,
+        fallbackHtml: defaultErrorPageFragmentHtml(),
+        meta: { ...FALLBACK_META[kind], siteName: 'Gradial' },
+    };
+}

package/dist/astro/index.d.ts

@@ -36,6 +36,10 @@ export declare function getGradialStaticPaths(): Promise<Array<{
 }>>;
 export declare function getPageRuntimeRenderInput(request: Request): RenderInput | null;
 export { getPageData, type PageData, type AstroGlobal, type GetPageDataOptions, } from './page.js';
+export { getErrorPageData, type AstroErrorPageData, } from './error-page.js';
+export { errorPageType, type ErrorPageType } from '../content/error-pages.js';
+export type { ErrorPageKind } from '../content/error-pages.js';
+export { PageNotFoundError } from '../content/provider.js';
 export { createRegistry, registryLookup } from '../registry.js';
 export type { Registry, RegistryEntry, AnyComponent } from '../registry.js';
 export type { BlockRef } from '../types/block-ref.js';

package/dist/astro/index.js

@@ -37,6 +37,15 @@ export function getPageRuntimeRenderInput(request) {
 // ---------------------------------------------------------------------------
 export { getPageData, } from './page.js';
 // ---------------------------------------------------------------------------
+// Authorable error pages (specs/features/authorable-error-pages, REQ-7/D-10)
+// — the seats' resolve+render helper, and PageNotFoundError so the catch-all
+// can map content misses to a 404 response in server output.
+// ---------------------------------------------------------------------------
+export { getErrorPageData, } from './error-page.js';
+// Single definition of the kind→page_type mapping (quorum SIMPLE-005).
+export { errorPageType } from '../content/error-pages.js';
+export { PageNotFoundError } from '../content/provider.js';
+// ---------------------------------------------------------------------------
 // Registry helpers
 // ---------------------------------------------------------------------------
 export { createRegistry, registryLookup } from '../registry.js';

package/dist/cli/emit-error-pages.d.mts

@@ -0,0 +1,39 @@
+#!/usr/bin/env node
+/**
+ * D-15 policy resolution for the 500.html instrumentation tag (page_type
+ * "error"; self-contained inline delivery — this copy is a real static
+ * document where inline scripts execute). Convention path: the tenant-owned
+ * `src/aci/error-page-instrumentation.mjs` exporting `pushErrorPageView` is
+ * serialized via the SDK mechanism; absent → the SDK default tag. A module
+ * that EXISTS but fails to import or lacks the export fails the emit loudly:
+ * a typo'd policy module silently reverting to the default is the failure
+ * mode D-15 guards against. The source used is logged either way.
+ *
+ * Exported for unit tests; `content` injects the SDK content functions so
+ * tests stay dist-free (at runtime they arrive through the same lazy dist
+ * import every other SDK internal uses here, sdkContent).
+ */
+export function resolveInstrumentationTag(root: string | undefined, content: any): Promise<any>;
+/**
+ * D-16 prepare-phase artifact: serializes BOTH kinds' instrumentation tags
+ * (tenant module when present, SDK default otherwise) into
+ * error-pages/instrumentation.json under the compiled content root. The
+ * AWS-lane code capsule packs source/.aci/compiled/**, so the Go publish
+ * materializer reads this file from the capsule and stamps the kind-matching
+ * tag into the CDN error artifacts — the tag crosses the JS→Go boundary as
+ * data. Serialization failures (bind/method-shorthand exports, FIND-006)
+ * throw before anything is written.
+ *
+ * Exported for unit tests; `content` and `outRoot` are injected there like
+ * resolveInstrumentationTag's `content`.
+ */
+export function writeInstrumentationArtifact(root: string | undefined, content: any, outRoot?: string): Promise<string>;
+/**
+ * Appends the D-14 instrumentation script tag and the generation marker
+ * before </body>. Exported for unit tests (the tag is a parameter so the
+ * function stays synchronous and dist-free there). Throws when the document
+ * has no </body> (quorum BUG-003): writing an UNMARKED 500.html would poison
+ * every later build via the skip-if-present contract, so the emit fails
+ * loudly instead.
+ */
+export function stampInstrumentation(html: any, instrumentationTag: any): any;

package/dist/cli/emit-error-pages.mjs

@@ -0,0 +1,402 @@
+#!/usr/bin/env node
+// Authorable error pages — build integration (spec:
+// specs/features/authorable-error-pages, T3/T11; REQ-10/REQ-11/REQ-14, D-9,
+// D-16).
+//
+// Two phases. The Next template wires both around `next build`; the Astro
+// template runs only `prepare` before `astro build` (its 404/500 seats
+// render through the framework, but the D-16 instrumentation artifact must
+// still reach the compiled content root for the AWS lane):
+//
+//   prepare  (before `next build`)
+//     Ensures compiled content exists at .aci/compiled so withAci() can
+//     serialize the bound catchAll page for the client-only error seat
+//     (D-9). Compiles ./.content via the platform CLI when needed; when
+//     neither compiled content nor authored content exists, it warns and
+//     leaves the shipped default in play (REQ-4, warn posture). Then writes
+//     error-pages/instrumentation.json (both kinds' serialized tags) into
+//     the compiled content root so the tag crosses the JS→Go boundary as
+//     data: the AWS-lane code capsule packs source/.aci/compiled/** and the
+//     Go publish materializer stamps the kind-matching tag into the CDN
+//     error artifacts (D-16). An unserializable tenant push fails the build
+//     loudly here (delta FIND-006).
+//
+//   emit     (after `next build`)
+//     Materializes `public/500.html` from the page bound to
+//     site.json#errorPages.catchAll by booting the standalone build,
+//     fetching the bound route, and post-processing the document. Boot-and-
+//     fetch beats re-rendering the page here because the standalone server
+//     is the only renderer that produces the document exactly as served
+//     (layout shell, resolved fragments, RSC-injected head and styles).
+//     Post-processing:
+//       - all script tags and preload/prefetch links stripped — this
+//         removes the collect and assignment tags (REQ-11) along with the
+//         framework runtime, which is useless in a statically served copy;
+//       - same-origin stylesheets inlined from .next/static (REQ-14 spirit:
+//         inline styles; note @font-face/image URLs inside the CSS keep
+//         their same-origin paths — this copy is served by the Vercel
+//         platform on the deployment that owns those assets);
+//       - one self-contained inline script appended pushing the D-14
+//         `page_view` (page_type "error") — a static document executes
+//         inline scripts, unlike the flight-rendered not-found seat. The
+//         push body is site policy (D-15): the tenant-owned
+//         src/aci/error-page-instrumentation.mjs when present, the SDK
+//         default otherwise;
+//       - hard size budget: ≤150 KB raw (REQ-14) — exceeding it fails the
+//         build; trimming the design system or falling back to system
+//         fonts is the sanctioned escape hatch.
+//     Skips when the site already provides its own public/500.html (a file
+//     without the generation marker); regenerates its own prior output.
+//     Absent bindings emit the shipped branded-neutral default (REQ-4).
+//     Vercel picks static per-status files out of the build output
+//     ("file presence = configuration"); on the current Pro plan the file
+//     serves app-level 500s only and lights up for platform 5xx on a plan
+//     upgrade (REQ-10, P-1).
+//
+// Usage: node ./node_modules/@gradial/aci/src/cli/emit-error-pages.mjs <prepare|emit>
+import { execFileSync, spawn } from 'node:child_process';
+import fs from 'node:fs';
+import net from 'node:net';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+const MARKER = '<!-- aci:error-pages generated -->';
+const SIZE_BUDGET = 150 * 1024;
+const BOOT_DEADLINE_MS = 60_000;
+const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
+const siteRoot = process.cwd();
+const contentRoot = path.resolve(siteRoot, process.env.ACI_CONTENT_ROOT || '.aci/compiled');
+function log(message) {
+    console.log(`[aci error-pages] ${message}`);
+}
+function warn(message) {
+    console.warn(`\n[aci error-pages] WARNING: ${message}\n`);
+}
+function fail(message) {
+    console.error(`\n[aci error-pages] ERROR: ${message}\n`);
+    process.exit(1);
+}
+async function sdkContent() {
+    return await import(pathToFileURL(path.join(packageRoot, 'dist', 'content', 'index.js')).href);
+}
+function hasCompiledContent() {
+    return fs.existsSync(path.join(contentRoot, 'manifest.json'));
+}
+// ---------------------------------------------------------------------------
+// prepare
+// ---------------------------------------------------------------------------
+async function prepare() {
+    if (hasCompiledContent()) {
+        log(`compiled content present at ${contentRoot}`);
+    }
+    else {
+        const authored = path.join(siteRoot, '.content');
+        if (!fs.existsSync(authored)) {
+            warn(`neither compiled content (${contentRoot}) nor authored content (./.content) exists; `
+                + 'the error seat and 500.html will serve the shipped default page (REQ-4)');
+        }
+        else {
+            log('compiling ./.content for the error-page build steps');
+            execFileSync('node', [path.join(packageRoot, 'bin', 'aci.js'), 'content', 'compile', '--content', authored, '--out', contentRoot], { cwd: siteRoot, stdio: 'inherit' });
+        }
+    }
+    // D-16: the instrumentation artifact rides the compiled content root into
+    // the AWS-lane code capsule (source/.aci/compiled/**). Written even when
+    // content is absent — the tenant policy module is independent of authored
+    // content, and an artifact the Go materializer never receives silently
+    // degrades to the default tags (the exact gap D-16 closes).
+    try {
+        await writeInstrumentationArtifact();
+    }
+    catch (error) {
+        fail(error.message);
+    }
+}
+// ---------------------------------------------------------------------------
+// emit
+// ---------------------------------------------------------------------------
+async function resolveCatchAllRoute() {
+    const { resolveErrorPageBindings, defaultErrorPageHtml, errorPagePostureFromEnv } = await sdkContent();
+    // D-5 posture: the one shared config surface (ACI_ERROR_PAGES_POSTURE);
+    // unknown values fail closed here just like the Go stack.
+    let posture;
+    try {
+        posture = errorPagePostureFromEnv();
+    }
+    catch (error) {
+        fail(error.message);
+    }
+    if (!hasCompiledContent()) {
+        if (posture === 'enforce') {
+            fail(`no compiled content at ${contentRoot}; the enforce posture fails closed (D-5)`);
+        }
+        warn(`no compiled content at ${contentRoot}; emitting the shipped default 500.html (REQ-4)`);
+        return { route: null, defaultHtml: defaultErrorPageHtml() };
+    }
+    const { FileContentProvider } = await import(pathToFileURL(path.join(packageRoot, 'dist', 'providers', 'file.js')).href);
+    const provider = new FileContentProvider(contentRoot);
+    const siteConfig = await provider.getSiteConfig();
+    const resolution = await resolveErrorPageBindings(siteConfig, { source: provider, posture });
+    if (resolution.errors.length > 0) {
+        fail(`errorPages bindings are invalid (REQ-5, fail closed):\n- ${resolution.errors.join('\n- ')}`);
+    }
+    for (const warning of resolution.warnings)
+        warn(warning);
+    if (resolution.defaulted || !resolution.bindings) {
+        return { route: null, defaultHtml: defaultErrorPageHtml() };
+    }
+    return { route: resolution.bindings.catchAll, defaultHtml: defaultErrorPageHtml() };
+}
+async function freePort() {
+    return new Promise((resolve, reject) => {
+        const server = net.createServer();
+        server.unref();
+        server.on('error', reject);
+        server.listen(0, '127.0.0.1', () => {
+            const { port } = server.address();
+            server.close(() => resolve(port));
+        });
+    });
+}
+async function fetchRenderedRoute(route) {
+    const serverPath = path.join(siteRoot, '.next', 'standalone', 'server.js');
+    if (!fs.existsSync(serverPath)) {
+        fail(`${serverPath} missing — the emit phase must run after \`next build\` (withAci uses standalone output)`);
+    }
+    const port = await freePort();
+    const logChunks = [];
+    const child = spawn('node', [serverPath], {
+        cwd: siteRoot,
+        detached: true,
+        stdio: ['ignore', 'pipe', 'pipe'],
+        env: {
+            ...process.env,
+            NODE_ENV: 'production',
+            PORT: String(port),
+            HOSTNAME: '127.0.0.1',
+            ACI_CONTENT_PROVIDER: 'file',
+            ACI_CONTENT_ROOT: contentRoot,
+        },
+    });
+    child.stdout.on('data', (c) => logChunks.push(String(c)));
+    child.stderr.on('data', (c) => logChunks.push(String(c)));
+    const exited = new Promise((resolve) => {
+        child.on('exit', resolve);
+        child.on('error', (error) => {
+            logChunks.push(`spawn failed: ${error.message}\n`);
+            resolve(null);
+        });
+    });
+    try {
+        const url = `http://127.0.0.1:${port}${route}`;
+        const start = Date.now();
+        let last = 'no attempt made';
+        while (Date.now() - start < BOOT_DEADLINE_MS) {
+            try {
+                const response = await fetch(url, { redirect: 'follow' });
+                if (response.status === 200)
+                    return await response.text();
+                last = `status ${response.status}`;
+            }
+            catch (error) {
+                last = error.message;
+            }
+            await new Promise((r) => setTimeout(r, 500));
+        }
+        fail(`GET ${url} did not render within ${BOOT_DEADLINE_MS}ms (last: ${last})\n--- server output ---\n${logChunks.join('').slice(-4000)}`);
+        return '';
+    }
+    finally {
+        const killGroup = (signal) => {
+            if (!child.pid)
+                return;
+            try {
+                process.kill(-child.pid, signal);
+            }
+            catch { /* gone */ }
+        };
+        killGroup('SIGTERM');
+        const killTimer = setTimeout(() => killGroup('SIGKILL'), 10_000);
+        await exited;
+        clearTimeout(killTimer);
+        killGroup('SIGKILL');
+    }
+}
+function inlineStylesheets(html) {
+    return html.replace(/<link\b[^>]*rel="stylesheet"[^>]*>/gi, (tag) => {
+        const href = tag.match(/href="([^"]+)"/i)?.[1];
+        if (!href || !href.startsWith('/_next/')) {
+            warn(`dropping non-inlinable stylesheet ${href ?? '<unknown>'} from 500.html (self-containment, REQ-14)`);
+            return '';
+        }
+        const cssPath = path.join(siteRoot, '.next', href.replace(/^\/_next\//, ''));
+        if (!fs.existsSync(cssPath)) {
+            warn(`stylesheet ${href} not found in .next output; dropping it from 500.html`);
+            return '';
+        }
+        return `<style>${fs.readFileSync(cssPath, 'utf8')}</style>`;
+    });
+}
+// Relative convention path of the tenant-owned instrumentation policy
+// module (D-15, code-organization R-14).
+const INSTRUMENTATION_MODULE = path.join('src', 'aci', 'error-page-instrumentation.mjs');
+/**
+ * D-15 policy resolution for the 500.html instrumentation tag (page_type
+ * "error"; self-contained inline delivery — this copy is a real static
+ * document where inline scripts execute). Convention path: the tenant-owned
+ * `src/aci/error-page-instrumentation.mjs` exporting `pushErrorPageView` is
+ * serialized via the SDK mechanism; absent → the SDK default tag. A module
+ * that EXISTS but fails to import or lacks the export fails the emit loudly:
+ * a typo'd policy module silently reverting to the default is the failure
+ * mode D-15 guards against. The source used is logged either way.
+ *
+ * Exported for unit tests; `content` injects the SDK content functions so
+ * tests stay dist-free (at runtime they arrive through the same lazy dist
+ * import every other SDK internal uses here, sdkContent).
+ */
+export async function resolveInstrumentationTag(root = siteRoot, content) {
+    const sdk = content ?? (await sdkContent());
+    const push = await resolveInstrumentationPush(root);
+    if (!push)
+        return sdk.errorPageInstrumentationTag('catchAll');
+    return sdk.serializeErrorPageInstrumentation(push, 'catchAll');
+}
+/**
+ * Resolves the tenant policy module's push function by the D-15 convention
+ * path. Absent module → null (callers fall back to the SDK default); a
+ * module that exists but fails to import or lacks the export throws — a
+ * typo'd policy module silently reverting to the default is the failure
+ * mode D-15 guards against. The source used is logged either way.
+ */
+async function resolveInstrumentationPush(root = siteRoot) {
+    const modulePath = path.join(root, INSTRUMENTATION_MODULE);
+    if (!fs.existsSync(modulePath)) {
+        log(`instrumentation source: SDK default (no ${INSTRUMENTATION_MODULE})`);
+        return null;
+    }
+    let policy;
+    try {
+        policy = await import(pathToFileURL(modulePath).href);
+    }
+    catch (error) {
+        throw new Error(`${INSTRUMENTATION_MODULE} exists but failed to import: ${error.message}\n`
+            + 'A broken policy module must not silently revert to the SDK default (D-15); '
+            + 'fix the module or delete it to use the default.');
+    }
+    if (typeof policy.pushErrorPageView !== 'function') {
+        throw new Error(`${INSTRUMENTATION_MODULE} does not export a pushErrorPageView function (D-15 policy contract); `
+            + 'export one or delete the file to use the SDK default.');
+    }
+    log(`instrumentation source: site module ${INSTRUMENTATION_MODULE}`);
+    return policy.pushErrorPageView;
+}
+/**
+ * D-16 prepare-phase artifact: serializes BOTH kinds' instrumentation tags
+ * (tenant module when present, SDK default otherwise) into
+ * error-pages/instrumentation.json under the compiled content root. The
+ * AWS-lane code capsule packs source/.aci/compiled/**, so the Go publish
+ * materializer reads this file from the capsule and stamps the kind-matching
+ * tag into the CDN error artifacts — the tag crosses the JS→Go boundary as
+ * data. Serialization failures (bind/method-shorthand exports, FIND-006)
+ * throw before anything is written.
+ *
+ * Exported for unit tests; `content` and `outRoot` are injected there like
+ * resolveInstrumentationTag's `content`.
+ */
+export async function writeInstrumentationArtifact(root = siteRoot, content, outRoot = contentRoot) {
+    const sdk = content ?? (await sdkContent());
+    const push = await resolveInstrumentationPush(root);
+    const tagFor = (kind) => (push
+        ? sdk.serializeErrorPageInstrumentation(push, kind)
+        : sdk.errorPageInstrumentationTag(kind));
+    const artifact = {
+        version: 1,
+        notFound: tagFor('notFound'),
+        error: tagFor('catchAll'),
+    };
+    const dir = path.join(outRoot, 'error-pages');
+    fs.mkdirSync(dir, { recursive: true });
+    const target = path.join(dir, 'instrumentation.json');
+    fs.writeFileSync(target, `${JSON.stringify(artifact)}\n`);
+    log(`wrote ${path.relative(root, target) || target} (D-16 instrumentation transport)`);
+    return target;
+}
+/**
+ * Appends the D-14 instrumentation script tag and the generation marker
+ * before </body>. Exported for unit tests (the tag is a parameter so the
+ * function stays synchronous and dist-free there). Throws when the document
+ * has no </body> (quorum BUG-003): writing an UNMARKED 500.html would poison
+ * every later build via the skip-if-present contract, so the emit fails
+ * loudly instead.
+ */
+export function stampInstrumentation(html, instrumentationTag) {
+    const stamped = html.replace(/<\/body>/i, `${instrumentationTag}\n${MARKER}\n</body>`);
+    if (!stamped.includes(MARKER)) {
+        throw new Error('rendered HTML has no </body> tag, so the instrumentation script and generation marker '
+            + 'could not be appended; refusing to write an unmarked public/500.html (skip-if-present contract)');
+    }
+    return stamped;
+}
+function postProcess(html, instrumentationTag) {
+    let out = html;
+    // Strip every script tag: framework runtime chunks are dead weight in a
+    // statically served copy, and this removes the collect script and the
+    // data-aci-assignments tag (REQ-11) in one sweep.
+    out = out.replace(/<script\b[\s\S]*?<\/script>/gi, '');
+    out = out.replace(/<link\b[^>]*rel="(?:preload|modulepreload|prefetch)"[^>]*>/gi, '');
+    out = out.replace(/<meta\b[^>]*name="aci-render-proof"[^>]*>/gi, '');
+    out = inlineStylesheets(out);
+    return stampInstrumentation(out, instrumentationTag);
+}
+async function emit() {
+    const publicDir = path.join(siteRoot, 'public');
+    const target = path.join(publicDir, '500.html');
+    if (fs.existsSync(target) && !fs.readFileSync(target, 'utf8').includes(MARKER)) {
+        log('public/500.html already provided by the site; leaving it untouched (skip-if-present)');
+        return;
+    }
+    const { route, defaultHtml } = await resolveCatchAllRoute();
+    let instrumentationTag;
+    try {
+        instrumentationTag = await resolveInstrumentationTag();
+    }
+    catch (error) {
+        fail(error.message);
+    }
+    let html;
+    try {
+        if (!route) {
+            // The shipped default is already self-contained; it gets the same
+            // instrumentation-plus-marker append used for rendered pages.
+            html = stampInstrumentation(defaultHtml, instrumentationTag);
+        }
+        else {
+            log(`rendering bound catchAll page ${route} for public/500.html`);
+            html = postProcess(await fetchRenderedRoute(route), instrumentationTag);
+        }
+    }
+    catch (error) {
+        fail(error.message);
+    }
+    const size = Buffer.byteLength(html);
+    if (size > SIZE_BUDGET) {
+        fail(`public/500.html is ${size} bytes, over the ${SIZE_BUDGET}-byte budget (REQ-14). `
+            + 'Trim the bound page/design-system CSS or fall back to system fonts (the sanctioned escape hatch).');
+    }
+    fs.mkdirSync(publicDir, { recursive: true });
+    fs.writeFileSync(target, html);
+    log(`wrote public/500.html (${size} bytes${route ? `, from ${route}` : ', shipped default'})`);
+}
+// Run only when executed as a CLI — the module is also imported by unit
+// tests for stampInstrumentation.
+const isMain = process.argv[1] && import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href;
+if (isMain) {
+    const phase = process.argv[2];
+    if (phase !== 'prepare' && phase !== 'emit') {
+        console.error('usage: emit-error-pages.mjs <prepare|emit>');
+        process.exit(2);
+    }
+    if (phase === 'prepare')
+        await prepare();
+    else
+        await emit();
+}