@gradial/aci 0.1.46 → 0.1.47

package/dist/content/default-error-page.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Shipped branded-neutral default error page (authorable-error-pages
+ * REQ-4/D-5). Materialized with a loud warning when a site has no
+ * `errorPages` binding under the warn-then-enforce posture. Self-contained
+ * by construction: inline styles only, no external references (REQ-14).
+ *
+ * The human-editable source of truth is `assets/error-pages/default.html`;
+ * it is embedded here as a generated constant (default-error-page-html.ts)
+ * because bundled serverless functions cannot read package assets at
+ * runtime — webpack rewrites module-URL resolution and output file tracing
+ * does not carry the .html into the function bundle, so a runtime file read
+ * crashes the very error surface this page exists to protect.
+ */
+/** Returns the shipped branded-neutral default error page HTML. */
+export declare function defaultErrorPageHtml(): string;
+/**
+ * The shipped default page's `<body>` content as an embeddable fragment: the
+ * body element renamed to a `<div>` (its inline styles preserved) so
+ * framework error seats can inline the default INSIDE an existing document —
+ * the not-found seat and the client error seat render within the app's root
+ * layout, where a nested `<body>`/`<html>` would be invalid.
+ */
+export declare function defaultErrorPageFragmentHtml(): string;

package/dist/content/default-error-page.js

@@ -0,0 +1,34 @@
+import { DEFAULT_ERROR_PAGE_HTML } from './default-error-page-html.js';
+/**
+ * Shipped branded-neutral default error page (authorable-error-pages
+ * REQ-4/D-5). Materialized with a loud warning when a site has no
+ * `errorPages` binding under the warn-then-enforce posture. Self-contained
+ * by construction: inline styles only, no external references (REQ-14).
+ *
+ * The human-editable source of truth is `assets/error-pages/default.html`;
+ * it is embedded here as a generated constant (default-error-page-html.ts)
+ * because bundled serverless functions cannot read package assets at
+ * runtime — webpack rewrites module-URL resolution and output file tracing
+ * does not carry the .html into the function bundle, so a runtime file read
+ * crashes the very error surface this page exists to protect.
+ */
+/** Returns the shipped branded-neutral default error page HTML. */
+export function defaultErrorPageHtml() {
+    return DEFAULT_ERROR_PAGE_HTML;
+}
+/**
+ * The shipped default page's `<body>` content as an embeddable fragment: the
+ * body element renamed to a `<div>` (its inline styles preserved) so
+ * framework error seats can inline the default INSIDE an existing document —
+ * the not-found seat and the client error seat render within the app's root
+ * layout, where a nested `<body>`/`<html>` would be invalid.
+ */
+export function defaultErrorPageFragmentHtml() {
+    const match = defaultErrorPageHtml().match(/<body([^>]*)>([\s\S]*?)<\/body>/i);
+    if (!match) {
+        // The shipped asset is package-controlled; this is a packaging bug, but
+        // error surfaces must never crash — fall back to the raw document body.
+        return defaultErrorPageHtml();
+    }
+    return `<div${match[1]}>${match[2]}</div>`;
+}

package/dist/content/error-page-kind.d.ts

@@ -0,0 +1,57 @@
+export type ErrorPageKind = 'notFound' | 'catchAll';
+/** D-14 page_type values for the error-surface `page_view` event. */
+export type ErrorPageType = 'not_found' | 'error';
+/** Maps a binding kind to its D-14 page_type. */
+export declare function errorPageType(kind: ErrorPageKind): ErrorPageType;
+declare global {
+    interface Window {
+        dataLayer?: Array<Record<string, unknown>>;
+    }
+}
+/**
+ * The D-15 policy shape: the dataLayer push for one error-surface view.
+ * Site policy lives in the tenant-owned scaffolded module
+ * `src/aci/error-page-instrumentation.mjs` (`pushErrorPageView`); the SDK
+ * ships `defaultPushErrorPageView` as the scaffolded default's twin. A push
+ * MUST be self-contained (browser globals only — no imports, no closed-over
+ * identifiers): the Astro seats and the 500.html emitter execute it
+ * STRINGIFIED via `serializeErrorPageInstrumentation`.
+ */
+export type ErrorPagePush = (pageType: ErrorPageType) => void;
+/**
+ * The SDK's copy of the D-14 default payload push — the same body the
+ * scaffolded policy module ships with. Used when no tenant module is in
+ * play: the Next `ErrorPageInstrumentation` component's default, the Astro
+ * seats' fallback, and the emitter's fallback tag. Self-contained by the
+ * ErrorPagePush contract (it serializes via toString()).
+ */
+export declare function defaultPushErrorPageView(pageType: ErrorPageType): void;
+/**
+ * SDK MECHANISM (D-15, code-organization R-14): serializes a self-contained
+ * push function into the inline analytics `<script>` tag the Astro seats
+ * inject via `<Fragment set:html>` and the Next emit-error-pages CLI stamps
+ * into `public/500.html`. The marker attribute and IIFE wrapper are
+ * SDK-owned platform contract (D-14: `data-aci-error-page` is the STABLE
+ * GTM suppression signal); the function body is site policy. `</script`,
+ * `<script` and `<!--` occurrences in the body are escaped (the script-data
+ * escaping table) so a push can neither break out of the tag nor walk the
+ * HTML parser into the escaped-script-data states (FIND-007).
+ *
+ * A non-function push degrades to the default tag with a warning
+ * (FIND-002): this is the runtime mechanism boundary and error surfaces
+ * must not crash over a broken policy value — the emitter keeps its own
+ * fail-loud stance at build time.
+ */
+export declare function serializeErrorPageInstrumentation(push: ErrorPagePush, kind: ErrorPageKind): string;
+/**
+ * The SDK DEFAULT analytics tag (D-15 amended D-14): the serialized
+ * `defaultPushErrorPageView`. Consumers fall back to it when no tenant
+ * policy module is provided — the Astro seats without
+ * `options.pushErrorPageView` and the emitter when
+ * `src/aci/error-page-instrumentation.mjs` is absent. The Next 'use client'
+ * component (`next/error-page-instrumentation.tsx`) cannot consume a script
+ * tag (RSC skips inline scripts); it calls the same default function
+ * directly, and the parity test beside it holds both deliveries in
+ * lockstep.
+ */
+export declare function errorPageInstrumentationTag(kind: ErrorPageKind): string;

package/dist/content/error-page-kind.js

@@ -0,0 +1,106 @@
+// Authorable error pages: the kind/page_type vocabulary (REQ-12 / D-14).
+//
+// This is a deliberately dependency-free CLIENT-SAFE leaf module: the Next
+// error-surface components ('use client' — error-page-marker,
+// error-page-instrumentation, error-seat) bundle it into the browser, so it
+// must not import anything that reaches node builtins (content/error-pages.ts
+// pulls content/routes.ts → node:path, which webpack rejects in client
+// bundles). It is the SINGLE definition (quorum SIMPLE-005) — content/
+// error-pages.ts re-exports it for server-side callers, and the next/astro
+// barrels re-export from there.
+/** Maps a binding kind to its D-14 page_type. */
+export function errorPageType(kind) {
+    return kind === 'notFound' ? 'not_found' : 'error';
+}
+/**
+ * The SDK's copy of the D-14 default payload push — the same body the
+ * scaffolded policy module ships with. Used when no tenant module is in
+ * play: the Next `ErrorPageInstrumentation` component's default, the Astro
+ * seats' fallback, and the emitter's fallback tag. Self-contained by the
+ * ErrorPagePush contract (it serializes via toString()).
+ */
+export function defaultPushErrorPageView(pageType) {
+    window.dataLayer = window.dataLayer || [];
+    window.dataLayer.push({
+        event: 'page_view',
+        page_type: pageType,
+        page_path: window.location.pathname,
+        page_location: window.location.href,
+        page_referrer: document.referrer || '(direct)',
+        page_title: document.title,
+    });
+}
+/**
+ * SDK MECHANISM (D-15, code-organization R-14): serializes a self-contained
+ * push function into the inline analytics `<script>` tag the Astro seats
+ * inject via `<Fragment set:html>` and the Next emit-error-pages CLI stamps
+ * into `public/500.html`. The marker attribute and IIFE wrapper are
+ * SDK-owned platform contract (D-14: `data-aci-error-page` is the STABLE
+ * GTM suppression signal); the function body is site policy. `</script`,
+ * `<script` and `<!--` occurrences in the body are escaped (the script-data
+ * escaping table) so a push can neither break out of the tag nor walk the
+ * HTML parser into the escaped-script-data states (FIND-007).
+ *
+ * A non-function push degrades to the default tag with a warning
+ * (FIND-002): this is the runtime mechanism boundary and error surfaces
+ * must not crash over a broken policy value — the emitter keeps its own
+ * fail-loud stance at build time.
+ */
+export function serializeErrorPageInstrumentation(push, kind) {
+    const pageType = errorPageType(kind);
+    let effectivePush = push;
+    if (typeof effectivePush !== 'function') {
+        console.warn('[aci error-pages] pushErrorPageView is not a function; serializing the SDK default push instead (D-15)');
+        effectivePush = defaultPushErrorPageView;
+    }
+    const source = escapeInlineScriptSource(effectivePush.toString());
+    assertSerializablePushSource(source);
+    return `<script data-aci-error-page="${pageType}">(${source})(${JSON.stringify(pageType)});</script>`;
+}
+/**
+ * Script-data escaping (FIND-007): `</script` would close the inline tag,
+ * and `<!--`/`<script` open the escaped-script-data parser states where the
+ * real closing tag is consumed as text. All three are defused with a
+ * case-PRESERVING backslash after `<` — inside JS string literals `\/`,
+ * `\s` and `\!` decode to the original characters, so payload values
+ * survive byte-for-byte on every surface.
+ */
+function escapeInlineScriptSource(source) {
+    return source.replace(/<(\/script|script|!--)/gi, (match) => `<\\${match.slice(1)}`);
+}
+/**
+ * Serialization smoke-eval (D-16, delta FIND-006): the tag ships the push
+ * STRINGIFIED, so its toString() must parse as a standalone function
+ * expression. Bound functions (`fn.bind(...)` stringifies to
+ * `function () { [native code] }`) and method-shorthand definitions
+ * (`{ pushErrorPageView(t) {…} }` stringifies without the `function`
+ * keyword) both produce source that is not an expression — the build must
+ * fail loudly here instead of shipping a tag that throws in every visitor's
+ * browser.
+ */
+function assertSerializablePushSource(source) {
+    try {
+        // Parse-only: the function body never executes.
+        new Function(`return (${source});`);
+    }
+    catch (error) {
+        throw new Error('pushErrorPageView cannot be serialized: its toString() output does not parse as a '
+            + `function expression (${String(error)}). Likely causes: exporting a bound function `
+            + '(.bind() loses the source) or a method-shorthand definition. Export a plain '
+            + 'self-contained `function pushErrorPageView(pageType) {…}` instead (D-15 contract).');
+    }
+}
+/**
+ * The SDK DEFAULT analytics tag (D-15 amended D-14): the serialized
+ * `defaultPushErrorPageView`. Consumers fall back to it when no tenant
+ * policy module is provided — the Astro seats without
+ * `options.pushErrorPageView` and the emitter when
+ * `src/aci/error-page-instrumentation.mjs` is absent. The Next 'use client'
+ * component (`next/error-page-instrumentation.tsx`) cannot consume a script
+ * tag (RSC skips inline scripts); it calls the same default function
+ * directly, and the parity test beside it holds both deliveries in
+ * lockstep.
+ */
+export function errorPageInstrumentationTag(kind) {
+    return serializeErrorPageInstrumentation(defaultPushErrorPageView, kind);
+}

package/dist/content/error-pages.d.ts

@@ -0,0 +1,88 @@
+import type { RouteEntry } from './provider.js';
+import type { KernelSiteConfig, SiteErrorPages } from './types.js';
+/**
+ * Error-page binding validation (authorable-error-pages REQ-4/REQ-5/D-5),
+ * semantically paired with the Go compiler's
+ * `internal/domain/contentbuild/error_pages.go`. Under the warn-then-enforce
+ * migration posture, absent bindings are legal: they produce a loud warning
+ * and a `defaulted: true` result so callers fall back to the shipped
+ * branded-neutral default page (`defaultErrorPageHtml()`). Present bindings
+ * are strict in every posture: malformed routes, bindings resolving to no
+ * page, unpublished bound pages, and audience/experiment overlays on bound
+ * pages all fail closed.
+ *
+ * NOTE: `src/next/error-seat-payload.ts` carries a SYNCHRONOUS twin of the
+ * binding validation below (it runs inside next.config evaluation where these
+ * async providers cannot be awaited). Keep the REQ-5 semantics of the two in
+ * lockstep when editing either; extraction into one shared core is deferred.
+ */
+/** D-5 migration posture for absent bindings; default is 'warn' today. */
+export type ErrorPagePosture = 'warn' | 'enforce';
+export { errorPageType, errorPageInstrumentationTag, defaultPushErrorPageView, serializeErrorPageInstrumentation, } from './error-page-kind.js';
+export type { ErrorPageKind, ErrorPageType, ErrorPagePush } from './error-page-kind.js';
+import type { ErrorPageKind } from './error-page-kind.js';
+/**
+ * The one D-5 posture config surface, shared by every stack: the same
+ * variable the Go content build and publish materializer read.
+ */
+export declare const ERROR_PAGES_POSTURE_ENV = "ACI_ERROR_PAGES_POSTURE";
+/** Reads the D-5 posture from ACI_ERROR_PAGES_POSTURE; throws on unknown values (fail closed). */
+export declare function errorPagePostureFromEnv(env?: Record<string, string | undefined>): ErrorPagePosture;
+/** Mirrors the site.schema.json binding pattern: "/<segment>/". */
+export declare const ERROR_PAGE_ROUTE_PATTERN: RegExp;
+/**
+ * The slice of a content provider binding resolution needs. Both
+ * FileContentProvider and S3ContentProvider satisfy it.
+ */
+export interface ErrorPageContentSource {
+    listRoutes(): Promise<RouteEntry[]>;
+    getPage<T = unknown>(route: string): Promise<T>;
+}
+export interface ResolveErrorPageBindingsOptions {
+    /** Absent-binding posture; defaults to 'warn' (D-5). */
+    posture?: ErrorPagePosture;
+    /**
+     * Compiled content to resolve bindings against. When omitted, only shape
+     * validation runs (the serve-time seam: publish status was already
+     * enforced at build time).
+     */
+    source?: ErrorPageContentSource;
+}
+export interface ErrorPageBindingsResolution {
+    /** Validated bindings; null when defaulted or invalid. */
+    bindings: SiteErrorPages | null;
+    /**
+     * True when no bindings are authored under the warn posture: callers must
+     * serve the shipped default page and surface `warnings` loudly.
+     */
+    defaulted: boolean;
+    warnings: string[];
+    errors: string[];
+}
+/**
+ * Validates the site's error-page bindings under the given posture.
+ * Never throws for validation outcomes: callers fail their build closed on a
+ * non-empty `errors` array.
+ */
+export declare function resolveErrorPageBindings(siteConfig: Pick<KernelSiteConfig, 'errorPages'> | null | undefined, options?: ResolveErrorPageBindingsOptions): Promise<ErrorPageBindingsResolution>;
+/**
+ * One kind's resolution for the serve-time seams (02-design "SDK core"):
+ * `route: null` + `defaulted: true` means "serve the shipped branded-neutral
+ * default page" (`defaultErrorPageHtml()` / `defaultErrorPageFragmentHtml()`).
+ */
+export interface ResolvedErrorPage {
+    kind: ErrorPageKind;
+    /** Bound public route path, or null when the shipped default applies. */
+    route: string | null;
+    defaulted: boolean;
+    /** Loud-warning material (REQ-4) — callers surface these, e.g. console.warn. */
+    warnings: string[];
+}
+/**
+ * Resolves one error-page kind under the warn posture (default). Unlike the
+ * build-time `resolveErrorPageBindings`, this NEVER fails: error surfaces
+ * must not crash and must not re-enter the failing system (ANTI-2), so a
+ * broken binding — which the build already failed closed on (REQ-5) —
+ * degrades to the shipped default with the problem surfaced in `warnings`.
+ */
+export declare function resolveErrorPage(kind: ErrorPageKind, siteConfig: Pick<KernelSiteConfig, 'errorPages'> | null | undefined, options?: ResolveErrorPageBindingsOptions): Promise<ResolvedErrorPage>;

package/dist/content/error-pages.js

@@ -0,0 +1,120 @@
+import { normalizeRoute } from './routes.js';
+// The kind/page_type vocabulary is defined once (quorum SIMPLE-005) in the
+// client-safe leaf module ./error-page-kind.ts — THIS module reaches
+// node:path via routes.js, so 'use client' components must import the leaf
+// directly. Re-exported here as the canonical server-side import site.
+export { errorPageType, errorPageInstrumentationTag, defaultPushErrorPageView, serializeErrorPageInstrumentation, } from './error-page-kind.js';
+const ERROR_PAGE_KINDS = ['notFound', 'catchAll'];
+/**
+ * The one D-5 posture config surface, shared by every stack: the same
+ * variable the Go content build and publish materializer read.
+ */
+export const ERROR_PAGES_POSTURE_ENV = 'ACI_ERROR_PAGES_POSTURE';
+/**
+ * Normalizes a raw posture value exactly like the Go side
+ * (`contentbuild.normalizeErrorPagePosture`): absent/empty means warn, and an
+ * unknown value throws so a config typo cannot silently disable enforcement.
+ */
+function normalizeErrorPagePosture(raw) {
+    const value = raw ?? '';
+    if (value === '' || value === 'warn')
+        return 'warn';
+    if (value === 'enforce')
+        return 'enforce';
+    throw new Error(`unknown errorPages validation posture ${JSON.stringify(value)} (want "warn" or "enforce")`);
+}
+/** Reads the D-5 posture from ACI_ERROR_PAGES_POSTURE; throws on unknown values (fail closed). */
+export function errorPagePostureFromEnv(env = process.env) {
+    return normalizeErrorPagePosture(env[ERROR_PAGES_POSTURE_ENV]);
+}
+/** Mirrors the site.schema.json binding pattern: "/<segment>/". */
+export const ERROR_PAGE_ROUTE_PATTERN = /^\/(?:[A-Za-z0-9._~-]+\/)+$/;
+const ERROR_PAGES_ABSENT_WARNING = 'site config has no errorPages bindings; the shipped branded-neutral default error page will be served for 404/5xx — author /404/ and /error/ pages and bind them via site.json#errorPages before the enforce posture lands (authorable-error-pages REQ-4/D-5)';
+/**
+ * Validates the site's error-page bindings under the given posture.
+ * Never throws for validation outcomes: callers fail their build closed on a
+ * non-empty `errors` array.
+ */
+export async function resolveErrorPageBindings(siteConfig, options = {}) {
+    const warnings = [];
+    const errors = [];
+    // Unknown posture values fail closed (quorum BUG-002, Go parity): a typo
+    // in ACI_ERROR_PAGES_POSTURE must never silently mean "warn".
+    let posture;
+    try {
+        posture = normalizeErrorPagePosture(options.posture);
+    }
+    catch (error) {
+        errors.push(error instanceof Error ? error.message : String(error));
+        return { bindings: null, defaulted: false, warnings, errors };
+    }
+    const raw = siteConfig?.errorPages;
+    if (raw == null) {
+        if (posture === 'enforce') {
+            errors.push('site config requires errorPages.notFound and errorPages.catchAll bindings (posture "enforce")');
+            return { bindings: null, defaulted: false, warnings, errors };
+        }
+        warnings.push(ERROR_PAGES_ABSENT_WARNING);
+        return { bindings: null, defaulted: true, warnings, errors };
+    }
+    // Present bindings are strict in every posture (REQ-5).
+    for (const kind of ERROR_PAGE_KINDS) {
+        const route = raw[kind];
+        if (typeof route !== 'string' || route === '') {
+            errors.push(`errorPages.${kind} binding is required`);
+        }
+        else if (!ERROR_PAGE_ROUTE_PATTERN.test(route)) {
+            errors.push(`errorPages.${kind} "${route}" is not a route path (want "/<segment>/")`);
+        }
+    }
+    if (errors.length > 0) {
+        return { bindings: null, defaulted: false, warnings, errors };
+    }
+    const bindings = { notFound: raw.notFound, catchAll: raw.catchAll };
+    if (options.source) {
+        const routes = await options.source.listRoutes();
+        const byPath = new Map(routes.map((entry) => [entry.path, entry]));
+        for (const kind of ERROR_PAGE_KINDS) {
+            const route = bindings[kind];
+            const normalized = normalizeRoute(route);
+            const entry = byPath.get(normalized);
+            if (!entry) {
+                errors.push(`errorPages.${kind} "${route}" does not resolve to any page`);
+                continue;
+            }
+            if (entry.variants && Object.keys(entry.variants).length > 0) {
+                errors.push(`errorPages.${kind} "${route}" must not have audience or experiment overlays`);
+                continue;
+            }
+            const page = await options.source
+                .getPage(normalized)
+                .catch(() => null);
+            if (!page || page.status !== 'published') {
+                errors.push(`errorPages.${kind} "${route}" must be a published page (status "${page?.status ?? 'unknown'}")`);
+            }
+        }
+    }
+    if (errors.length > 0) {
+        return { bindings: null, defaulted: false, warnings, errors };
+    }
+    return { bindings, defaulted: false, warnings, errors };
+}
+/**
+ * Resolves one error-page kind under the warn posture (default). Unlike the
+ * build-time `resolveErrorPageBindings`, this NEVER fails: error surfaces
+ * must not crash and must not re-enter the failing system (ANTI-2), so a
+ * broken binding — which the build already failed closed on (REQ-5) —
+ * degrades to the shipped default with the problem surfaced in `warnings`.
+ */
+export async function resolveErrorPage(kind, siteConfig, options = {}) {
+    const resolution = await resolveErrorPageBindings(siteConfig, options);
+    if (resolution.errors.length > 0 || resolution.defaulted || !resolution.bindings) {
+        return {
+            kind,
+            route: null,
+            defaulted: true,
+            warnings: [...resolution.warnings, ...resolution.errors]
+        };
+    }
+    return { kind, route: resolution.bindings[kind], defaulted: false, warnings: resolution.warnings };
+}

package/dist/content/index.d.ts

@@ -5,3 +5,5 @@ export * from './personalization.js';
 export * from './cache.js';
 export * from './resolve-slots.js';
 export * from './assets.js';
+export * from './default-error-page.js';
+export * from './error-pages.js';

package/dist/content/index.js

@@ -5,3 +5,5 @@ export * from './personalization.js';
 export * from './cache.js';
 export * from './resolve-slots.js';
 export * from './assets.js';
+export * from './default-error-page.js';
+export * from './error-pages.js';

package/dist/content/types.d.ts

@@ -85,9 +85,21 @@ export interface KernelSiteConfig {
         description?: string;
         siteName?: string;
     };
+    /**
+     * Error-page route bindings (authorable-error-pages REQ-1). Both values
+     * are public route paths (`/<segment>/`) resolving to ordinary published
+     * pages. Optional under the warn-then-enforce posture (REQ-4/D-5):
+     * absence is legal and produces a loud build/publish warning plus the
+     * shipped branded-neutral default page.
+     */
+    errorPages?: SiteErrorPages;
     /** Personalization collect-tag config (design/04); absent = disabled. */
     personalization?: SitePersonalizationConfig;
 }
+export interface SiteErrorPages {
+    notFound: string;
+    catchAll: string;
+}
 export interface KernelRouteMetadata {
     title: string;
     description: string;

package/dist/next/config.js

@@ -2,6 +2,7 @@ import { readdirSync, existsSync } from 'fs';
 import { join, relative } from 'path';
 import { createRequire } from 'module';
 import { createContentWatchWebpackPlugin } from './content-watch.js';
+import { buildErrorSeatPayload } from './error-seat-payload.js';
 const require = createRequire(import.meta.url);
 export function withAci(nextConfig = {}, options = {}) {
     if (process.env.TURBOPACK) {
@@ -11,6 +12,21 @@ export function withAci(nextConfig = {}, options = {}) {
             '`next dev` / `next build` without --turbopack.');
     }
     const publicPaths = collectPublicPaths(join(process.cwd(), 'public'));
+    // Authorable error pages (D-9): the Next error seat is client-only, so the
+    // bound catchAll page's content is serialized here — while next.config is
+    // evaluated — and injected into the bundle via DefinePlugin below. The D-5
+    // posture rides ACI_ERROR_PAGES_POSTURE (the same variable the Go stack
+    // reads): under warn (default), absent bindings/content and non-REQ-5
+    // serialization failures warn and serialize the shipped default (REQ-4);
+    // under enforce they fail the build closed, and unknown posture values
+    // fail closed too. Present-but-broken bindings fail closed always (REQ-5).
+    const errorSeat = buildErrorSeatPayload(undefined, process.env.ACI_ERROR_PAGES_POSTURE);
+    if (errorSeat.errors.length > 0) {
+        throw new Error(`ACI errorPages bindings are invalid (site.json#errorPages):\n- ${errorSeat.errors.join('\n- ')}`);
+    }
+    for (const warning of errorSeat.warnings) {
+        console.warn(`\n[aci error-pages] WARNING: ${warning}\n`);
+    }
     const passthroughRoutes = normalizePassthroughRoutes(options.passthroughRoutes ?? []);
     const assetPrefix = options.assetPrefix || '/.gradial-dam';
     const assetOrigin = options.assetOrigin || '';
@@ -82,6 +98,7 @@ export function withAci(nextConfig = {}, options = {}) {
                 '__ACI_PUBLIC_PATHS__': JSON.stringify(publicPaths),
                 '__ACI_PASSTHROUGH_ROUTES__': JSON.stringify(passthroughRoutes),
                 '__ACI_ASSET_PREFIX__': JSON.stringify(assetPrefix),
+                '__ACI_ERROR_PAGE__': JSON.stringify(errorSeat.payload),
             }));
             return typeof userWebpack === 'function'
                 ? userWebpack(config, context)

package/dist/next/error-page-instrumentation.d.ts

@@ -0,0 +1,23 @@
+import { type ErrorPageKind, type ErrorPagePush } from '../content/error-page-kind.js';
+/**
+ * Error-surface analytics MECHANISM (authorable-error-pages REQ-12 / D-14 /
+ * D-15): calls the site's push function exactly ONCE per error view with
+ * the D-14 page_type. The push BODY is site policy — the seats forward the
+ * tenant-owned scaffolded module's `pushErrorPageView` via `push`; without
+ * it, `defaultPushErrorPageView` (the scaffolded default's twin) runs.
+ *
+ * Delivery MUST be a 'use client' useEffect: the not-found seat is
+ * client-rendered from the RSC flight payload, where React skips execution
+ * of inline script elements (spike A learning 3). The SDK error seats mount
+ * this only with error render context; ordinary routes — including direct
+ * GET /404/ and /error/ previews — never render it (REQ-12).
+ *
+ * Renders nothing. The seats (createNotFound, ErrorSeat) render the inert
+ * `data-aci-error-page` marker themselves — server-side where possible, so
+ * gates can assert it in fetched documents (a client component's output
+ * never appears in the serialized flight text).
+ */
+export declare function ErrorPageInstrumentation({ kind, push, }: {
+    kind: ErrorPageKind;
+    push?: ErrorPagePush;
+}): null;

package/dist/next/error-page-instrumentation.js

@@ -0,0 +1,36 @@
+'use client';
+import { useEffect } from 'react';
+// Client-safe leaf import — see error-page-marker.tsx.
+import { defaultPushErrorPageView, errorPageType, } from '../content/error-page-kind.js';
+/**
+ * Error-surface analytics MECHANISM (authorable-error-pages REQ-12 / D-14 /
+ * D-15): calls the site's push function exactly ONCE per error view with
+ * the D-14 page_type. The push BODY is site policy — the seats forward the
+ * tenant-owned scaffolded module's `pushErrorPageView` via `push`; without
+ * it, `defaultPushErrorPageView` (the scaffolded default's twin) runs.
+ *
+ * Delivery MUST be a 'use client' useEffect: the not-found seat is
+ * client-rendered from the RSC flight payload, where React skips execution
+ * of inline script elements (spike A learning 3). The SDK error seats mount
+ * this only with error render context; ordinary routes — including direct
+ * GET /404/ and /error/ previews — never render it (REQ-12).
+ *
+ * Renders nothing. The seats (createNotFound, ErrorSeat) render the inert
+ * `data-aci-error-page` marker themselves — server-side where possible, so
+ * gates can assert it in fetched documents (a client component's output
+ * never appears in the serialized flight text).
+ */
+export function ErrorPageInstrumentation({ kind, push, }) {
+    const pageType = errorPageType(kind);
+    useEffect(() => {
+        let effectivePush = push ?? defaultPushErrorPageView;
+        if (typeof effectivePush !== 'function') {
+            // FIND-002: a non-function push (broken config plumbing) must degrade
+            // to the default, never crash the error surface itself.
+            console.warn('[aci error-pages] pushErrorPageView is not a function; using the SDK default push (D-15)');
+            effectivePush = defaultPushErrorPageView;
+        }
+        effectivePush(pageType);
+    }, [pageType, push]);
+    return null;
+}

package/dist/next/error-page-marker.d.ts

@@ -0,0 +1,11 @@
+import { type ErrorPageKind } from '../content/error-page-kind.js';
+/**
+ * Inert, invisible marker naming the error surface
+ * (`data-aci-error-page="not_found"|"error"`). Rendered by the seats next to
+ * ErrorPageInstrumentation as the fetch-level assertion hook for build and
+ * serve gates; its absence on ordinary routes proves direct /404/ and
+ * /error/ visits carry no error-typed instrumentation (REQ-12).
+ */
+export declare function ErrorPageMarker({ kind }: {
+    kind: ErrorPageKind;
+}): import("react").JSX.Element;

package/dist/next/error-page-marker.js

@@ -0,0 +1,20 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+// Deliberately NO 'use client' directive: this module is shared by the
+// server-rendered not-found seat and the client-only error seat. At the
+// not-found seat the marker must be a SERVER-rendered element so it lands in
+// the RSC flight payload — a client component's rendered output never
+// appears in the serialized document, which is exactly why the build/serve
+// gates could not assert a marker owned by ErrorPageInstrumentation.
+// Import the client-safe leaf directly: content/error-pages.js reaches
+// node:path via routes.js, which webpack rejects in browser bundles.
+import { errorPageType } from '../content/error-page-kind.js';
+/**
+ * Inert, invisible marker naming the error surface
+ * (`data-aci-error-page="not_found"|"error"`). Rendered by the seats next to
+ * ErrorPageInstrumentation as the fetch-level assertion hook for build and
+ * serve gates; its absence on ordinary routes proves direct /404/ and
+ * /error/ visits carry no error-typed instrumentation (REQ-12).
+ */
+export function ErrorPageMarker({ kind }) {
+    return _jsx("span", { hidden: true, "data-aci-error-page": errorPageType(kind) });
+}

package/dist/next/error-pages.d.ts

@@ -0,0 +1,52 @@
+import type { ReactElement } from 'react';
+import { type FetchConfig } from './server.js';
+import { type ErrorPageKind, type ErrorPagePush, type ResolvedErrorPage } from '../content/error-pages.js';
+import type { KernelSiteConfig } from '../content/types.js';
+import type { Registry } from '../registry.js';
+/**
+ * Next runtime seams for authorable error pages (REQ-6, 02-design "SDK
+ * core"): `resolveErrorPage(kind)` + `renderPageForRoute(route)` — the pair
+ * both spike wrappers hand-rolled — plus `createNotFound(registry)`, which
+ * composes them so the starter's `not-found.tsx` stays thin.
+ */
+export interface NextResolvedErrorPage extends ResolvedErrorPage {
+    siteConfig: KernelSiteConfig | null;
+}
+/**
+ * Resolves one error-page binding from the active site config under the
+ * warn posture (D-5). Never throws: an unreachable site config degrades to
+ * the shipped default — an error surface must not re-enter the failing
+ * system (ANTI-2).
+ */
+export declare function resolveErrorPage(kind: ErrorPageKind, config?: FetchConfig): Promise<NextResolvedErrorPage>;
+/**
+ * Renders the content page bound to `route` through the normal page
+ * pipeline (createPage: layout slots, fragments, registry blocks, collect/
+ * assignments tags), resolving to the same tree the catch-all route would
+ * serve. Throws whatever the pipeline throws — including the notFound()
+ * control error for missing content — so callers at error seats must wrap
+ * it (createNotFound does).
+ */
+export declare function renderPageForRoute(registry: Registry, route: string): Promise<ReactElement>;
+/**
+ * The shipped branded-neutral default error page (REQ-4/D-5) as an inline
+ * fragment — used when no binding exists or the bound content cannot be
+ * rendered. Self-contained by construction (inline styles only, REQ-14).
+ */
+export declare function DefaultErrorPageContent(): import("react").JSX.Element;
+/**
+ * Builds the component for Next's native not-found seat
+ * (`src/app/not-found.tsx`). The SDK catch-all invokes `notFound()` on
+ * missing content, so this renders with a real HTTP 404 (REQ-3/REQ-6).
+ *
+ * Fallback contract: if the bound notFound content is itself missing or
+ * fails to render at request time, the shipped default renders INLINE —
+ * the seat never re-invokes notFound() (a recursive seat was the spike's
+ * kill-list item) and never throws.
+ *
+ * `pushErrorPageView` (D-15): the tenant-owned policy module's push,
+ * forwarded to ErrorPageInstrumentation; omitted → the SDK default.
+ */
+export declare function createNotFound(registry: Registry, config?: FetchConfig & {
+    pushErrorPageView?: ErrorPagePush;
+}): () => Promise<ReactElement>;