@storystick/client 0.0.0-stage → 0.2.0-rc.0

package/dist/signed-webhook.js

@@ -0,0 +1,54 @@
+/** Shared HTTP boundary for framework delivery adapters. No cache or queue policy. */
+export async function signWebhookBody(body, secret) {
+    const key = await crypto.subtle.importKey('raw', new TextEncoder().encode(secret), { name: 'HMAC', hash: 'SHA-256' }, false, ['sign']);
+    const signature = await crypto.subtle.sign('HMAC', key, new TextEncoder().encode(body));
+    return `sha256=${Array.from(new Uint8Array(signature), byte => byte.toString(16).padStart(2, '0')).join('')}`;
+}
+export async function readSignedWebhook(request, options) {
+    const limit = 1024 * 1024;
+    const failure = (status, error) => ({ ok: false, status, error });
+    if (Number(request.headers.get('content-length')) > limit)
+        return failure(413, 'payload_too_large');
+    const signature = request.headers.get(options.signatureHeader ?? 'x-storystick-signature')?.trim().replace(/^sha256=/, '');
+    if (!signature || !/^[a-f0-9]{64}$/i.test(signature))
+        return failure(401, 'invalid_signature');
+    const chunks = [];
+    let size = 0;
+    const reader = request.body?.getReader();
+    try {
+        if (reader)
+            while (true) {
+                const { done, value } = await reader.read();
+                if (done)
+                    break;
+                size += value.byteLength;
+                if (size > limit) {
+                    await reader.cancel();
+                    return failure(413, 'payload_too_large');
+                }
+                chunks.push(value);
+            }
+    }
+    catch {
+        return failure(400, 'invalid_body');
+    }
+    finally {
+        reader?.releaseLock();
+    }
+    const bytes = new Uint8Array(size);
+    let offset = 0;
+    for (const chunk of chunks) {
+        bytes.set(chunk, offset);
+        offset += chunk.length;
+    }
+    const key = await crypto.subtle.importKey('raw', new TextEncoder().encode(options.secret), { name: 'HMAC', hash: 'SHA-256' }, false, ['verify']);
+    const candidate = Uint8Array.from(signature.match(/../g), byte => parseInt(byte, 16));
+    if (!await crypto.subtle.verify('HMAC', key, candidate, bytes))
+        return failure(401, 'invalid_signature');
+    try {
+        return { ok: true, payload: JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(bytes)) };
+    }
+    catch {
+        return failure(400, 'invalid_json');
+    }
+}

package/dist/transport.d.ts

@@ -0,0 +1,29 @@
+import type { PublicTransport, TransportResponse } from './types.js';
+export interface HttpTransportOptions {
+    /** Project short ID expected by this client; this never selects a server tenant. */
+    projectId: string;
+    /** Explicit CDN origin for public Query V2 only. */
+    deliveryEndpoint?: string;
+    /** Resolved Storystick HTTP gateway URL. */
+    endpoint: string;
+    /** Caller's long-lived API key (`ss_sk_live_*` or `ss_pk_live_*`). */
+    apiKey: string;
+    /** Exact customer application build, transmitted with every published read. */
+    applicationBuildId?: string;
+    /**
+     * Optional override of `globalThis.fetch`. Tests pass a stub here
+     * to observe wire shape without hitting the network.
+     */
+    fetchImpl?: typeof fetch;
+}
+/**
+ * Build the default Pattern D HTTP transport. Shape matches the
+ * `Transport` interface; the configured client wires this up by
+ * default and the user can substitute a mock via
+ * `createClient({ schema, transport: customTransport })`.
+ */
+export declare function createHttpTransportV2(opts: HttpTransportOptions): PublicTransport;
+/** Shared consumption boundary, including injected transports and null results. */
+export declare function assertResponseProject(response: TransportResponse, expected: string): void;
+/** Check nested SDK transport bindings before the inner transport can observe data. */
+export declare function assertProjectMatch(expected: string, actual: string): void;

package/dist/transport.js

@@ -0,0 +1,584 @@
+import { isExactPublicQueryResultV2, queryResultHttpStatus, QUERY_HTTP_PROTOCOL_HEADER, QUERY_HTTP_PROTOCOL, QUERY_PROJECT_ID_HEADER } from '@storystick/types/delivery-contract';
+import { isPublicReadIdentity, PUBLIC_DELIVERY_IDENTITY_HEADER } from '@storystick/types/public-delivery';
+/** Shared HTTP reads: direct API keys in production, delegated JWTs in Preview. */
+import { contentShapeCapabilityHeaders } from '@storystick/types';
+import { StorystickError } from './errors.js';
+import { httpFailureRetryable, isTemporaryHttpStatus, parseRetryAfter } from '@storystick/types/http-failure';
+import { hasUsablePreviewToken } from './preview-scope.js';
+import { PROJECT_ID_MISMATCH } from '@storystick/types/errors/codes';
+import { attachPreviewReadObservation } from './preview-read-observation.js';
+import { encodePreviewGatewayContext, PREVIEW_GATEWAY_CONTEXT_HEADER, PREVIEW_QUERY_RECEIPT_HEADER, } from '@storystick/types/preview-query-targeting';
+// ─────────────────────────────────────────────
+// UDF path routing
+// ─────────────────────────────────────────────
+/**
+ * Map a Convex-style udf path to a Pattern D HTTP endpoint descriptor.
+ * Mirrors the routes Central's `gateway_queries.ts` httpActions register
+ * at `/api/q/*` and the consolidated wire layer in
+ * `packages/next/src/server.ts` consumed today.
+ *
+ * `getRouteByPathname` (ADR-094 §1.bis) routes cross-storytype URL lookups
+ * to the same family of indexes — one indexed call regardless of how many
+ * URL-routable storytypes the project declares (ADR-086 invariant).
+ */
+function endpointForUdf(udfPath) {
+    switch (udfPath) {
+        case 'queries:getRouteByPathname':
+            return { method: 'GET', path: '/api/q/getRouteByPathname' };
+        case 'queries:listPublishedLocaleRoutes':
+            return { method: 'GET', path: '/api/q/listPublishedLocaleRoutes' };
+        case 'locales:get':
+            return { method: 'GET', path: '/api/q/locales/settings' };
+        case 'queries:queryV2':
+            return { method: 'POST', path: '/api/q/queryV2' };
+        case 'queries:schemas.current':
+            // ADR-131 Amendment 002 §3.1 — schema delivery via the existing
+            // `/api/q/schemas/current` HTTP action (gateway_queries.ts::schemasCurrent).
+            // Consumed by `fetchCurrentSchema` (packages/client/src/schemas.ts).
+            return { method: 'GET', path: '/api/q/schemas/current' };
+        default:
+            throw new StorystickError(`Unknown query path "${udfPath}". Expected one of: ` +
+                `queries:queryV2, queries:getRouteByPathname, queries:listPublishedLocaleRoutes, queries:schemas.current, locales:get.`, { code: 'storystick/INVALID_UDF_PATH', category: 'validation' });
+    }
+}
+/**
+ * Build the default Pattern D HTTP transport. Shape matches the
+ * `Transport` interface; the configured client wires this up by
+ * default and the user can substitute a mock via
+ * `createClient({ schema, transport: customTransport })`.
+ */
+export function createHttpTransportV2(opts) {
+    if (!opts.projectId?.trim())
+        throw new TypeError('storystick/QUERY_INVALID: projectId is required.');
+    const { endpoint, apiKey, applicationBuildId, fetchImpl } = opts;
+    const fetchFn = fetchImpl ?? globalThis.fetch.bind(globalThis);
+    async function request(input) {
+        assertProjectMatch(input.expectedProjectId ?? opts.projectId, opts.projectId);
+        const { udfPath, args, options, requestContext, signal: signalArg } = input;
+        const { method, path } = endpointForUdf(udfPath);
+        // Use the shared `hasUsablePreviewToken` predicate so the builder's
+        // `assertPreviewIntent` guard and this preview-path switch agree on
+        // what counts as "bound": a non-empty string. `previewToken: ''`
+        // and runtime `null` previously slipped through `!!previewToken` and
+        // produced production reads on a preview-intent client.
+        const isPreview = hasUsablePreviewToken(requestContext);
+        const previewToken = isPreview ? requestContext.previewToken : undefined;
+        const token = isPreview ? previewToken : apiKey;
+        // Wire shape build.
+        const readEndpoint = !isPreview && udfPath === 'queries:queryV2' && opts.deliveryEndpoint
+            ? opts.deliveryEndpoint : endpoint;
+        const url = buildUrl({ endpoint: readEndpoint, path, method, args, options, isPreview });
+        const body = method === 'POST'
+            ? buildPostBody(args, options, isPreview, udfPath !== 'queries:queryV2')
+            : undefined;
+        const signal = signalArg ?? options?.signal;
+        const fetchInit = buildFetchInit({
+            method,
+            token,
+            applicationBuildId,
+            isPreview,
+            udfPath,
+            requestContext,
+            options,
+            body,
+            signal,
+        });
+        const response = await fetchTransportResponse(fetchFn, url, fetchInit);
+        // Only a delegated Preview token can be refreshed. A rejected API key
+        // must surface immediately; no mint, fallback or hidden auth retry.
+        if (isPreview && await shouldRefreshAndRetry(response)) {
+            const refresh = requestContext?.refreshPreviewToken;
+            const retryToken = refresh ? await refresh(previewToken) : undefined;
+            if (typeof retryToken !== 'string' || retryToken.length === 0) {
+                throw new StorystickError('Preview token expired and could not be refreshed. Re-enter Studio preview to obtain a fresh token.', { code: 'storystick/PREVIEW_TOKEN_EXPIRED', category: 'auth', recoverable: true, retryable: false });
+            }
+            const retryInit = buildFetchInit({
+                method,
+                token: retryToken,
+                isPreview,
+                udfPath,
+                requestContext,
+                options,
+                body,
+                signal,
+            });
+            const retry = await fetchTransportResponse(fetchFn, url, retryInit);
+            return decode(retry, input, isPreview);
+        }
+        return decode(response, input, isPreview);
+    }
+    async function decode(response, input, isPreview) {
+        let data;
+        if (!response.ok) {
+            // Only the closed Query V2 result protocol can survive a non-2xx status.
+            // Other errors (including HTML 503s and auth errors) retain their normal path.
+            const cardinality = input.args.query?.cardinality;
+            if (input.udfPath === 'queries:queryV2' &&
+                (response.status === 503 || response.status === 422) &&
+                (cardinality === 'one' || cardinality === 'many')) {
+                const candidate = await response.clone().json().catch(() => null);
+                if (isExactPublicQueryResultV2(candidate, cardinality) &&
+                    candidate.exactness !== 'exact' && queryResultHttpStatus(candidate) === response.status) {
+                    data = candidate;
+                }
+            }
+            if (data === undefined)
+                throw await buildStorystickError(response);
+        }
+        else {
+            try {
+                data = await response.json();
+            }
+            catch (error) {
+                if ((input.signal ?? input.options?.signal)?.aborted)
+                    throw error;
+                const protocol = error instanceof SyntaxError;
+                throw new StorystickError(protocol ? 'The Storystick gateway returned invalid JSON.' : 'The Storystick response stream was interrupted.', {
+                    code: protocol ? 'storystick/QUERY_PROTOCOL' : 'storystick/QUERY_NETWORK',
+                    category: 'system', retryable: !protocol, status: response.status,
+                });
+            }
+        }
+        let publicReadIdentity;
+        if (!isPreview && ['queries:queryV2', 'queries:getRouteByPathname', 'queries:listPublishedLocaleRoutes'].includes(input.udfPath) && response.headers.has(PUBLIC_DELIVERY_IDENTITY_HEADER)) {
+            let value = null;
+            try {
+                value = JSON.parse(response.headers.get(PUBLIC_DELIVERY_IDENTITY_HEADER));
+            }
+            catch { /* Rejected by the identity validator below. */ }
+            if (!isPublicReadIdentity(value))
+                throw new StorystickError('Invalid public read identity.', { code: 'storystick/QUERY_PROTOCOL', category: 'system', retryable: false });
+            publicReadIdentity = value;
+        }
+        const result = {
+            data, ...queryResponseMetadata(input.udfPath, response),
+            projectId: response.headers.get(QUERY_PROJECT_ID_HEADER) ?? publicReadIdentity?.projectShortId,
+            ...(publicReadIdentity ? { publicReadIdentity } : {}),
+        };
+        assertResponseProject(result, opts.projectId);
+        fireOnAccessedContent({
+            udfPath: input.udfPath, args: input.args, data, response,
+            requestContext: input.requestContext, isPreview,
+        });
+        return result;
+    }
+    return { request };
+}
+/** Shared consumption boundary, including injected transports and null results. */
+export function assertResponseProject(response, expected) {
+    if (!response || typeof response !== 'object' || Array.isArray(response)) {
+        throw new StorystickError('The Storystick response has no project identity.', {
+            code: 'storystick/QUERY_PROTOCOL', category: 'system', retryable: false,
+        });
+    }
+    const identity = response.publicReadIdentity;
+    if (identity !== undefined && !isPublicReadIdentity(identity)) {
+        throw new StorystickError('Invalid public read identity.', { code: 'storystick/QUERY_PROTOCOL', category: 'system', retryable: false });
+    }
+    const actual = response.projectId ?? identity?.projectShortId;
+    if (typeof actual !== 'string' || !actual.trim() || actual.length > 1024 ||
+        (identity && identity.projectShortId !== actual)) {
+        throw new StorystickError('The Storystick response has no consistent project identity.', {
+            code: 'storystick/QUERY_PROTOCOL', category: 'system', retryable: false,
+        });
+    }
+    assertProjectMatch(expected, actual);
+}
+/** Check nested SDK transport bindings before the inner transport can observe data. */
+export function assertProjectMatch(expected, actual) {
+    if (actual !== expected) {
+        throw new StorystickError('The Storystick response belongs to a different project.', {
+            code: PROJECT_ID_MISMATCH.code, category: PROJECT_ID_MISMATCH.category,
+            recoverable: PROJECT_ID_MISMATCH.recoverable, retryable: PROJECT_ID_MISMATCH.retryable,
+        });
+    }
+}
+async function fetchTransportResponse(fetchFn, url, init) {
+    try {
+        return await fetchFn(url, init);
+    }
+    catch (error) {
+        if (init.signal?.aborted ||
+            (error instanceof Error && error.name === 'AbortError')) {
+            throw error;
+        }
+        throw new StorystickError('The Storystick gateway is unreachable.', {
+            code: 'storystick/QUERY_NETWORK',
+            category: 'system',
+            recoverable: true,
+            retryable: true,
+        });
+    }
+}
+function queryResponseMetadata(udfPath, response) {
+    if (udfPath !== 'queries:queryV2')
+        return {};
+    const queryHash = response.headers.get('X-Storystick-Query-Hash');
+    const readScopeIdentity = response.headers.get('X-Storystick-Read-Scope-Identity');
+    const receiptId = response.headers.get(PREVIEW_QUERY_RECEIPT_HEADER);
+    return {
+        ...(queryHash && readScopeIdentity
+            ? { executionIdentity: { queryHash, readScopeIdentity } }
+            : {}),
+        ...(receiptId ? { previewQueryReceiptId: receiptId } : {}),
+    };
+}
+// ─────────────────────────────────────────────
+// Internal helpers (URL build, fetch init, retry decision, error build)
+// ─────────────────────────────────────────────
+function buildUrl(args) {
+    const { endpoint, path, method, args: queryArgs, options, isPreview } = args;
+    let url = `${endpoint}${path}`;
+    if (method !== 'GET')
+        return url;
+    const params = new URLSearchParams();
+    for (const [key, value] of Object.entries(queryArgs)) {
+        if (key === 'preview')
+            continue; // gateway derives preview from JWT env claim
+        if (value === undefined || value === null)
+            continue;
+        if (value === true) {
+            params.set(key, '1');
+        }
+        else if (value === false) {
+            // skip — gateway treats absence as false (matches legacy behavior)
+            continue;
+        }
+        else if (Array.isArray(value)) {
+            params.set(key, value.join(','));
+        }
+        else if (typeof value === 'object') {
+            params.set(key, JSON.stringify(value));
+        }
+        else {
+            params.set(key, String(value));
+        }
+    }
+    const locale = normalizeRequestLocale(options?.locale);
+    if (locale && !params.has('locale'))
+        params.set('locale', locale);
+    if (isPreview)
+        params.set('preview', '1');
+    if ([...params.keys()].length > 0) {
+        url += `?${params.toString()}`;
+    }
+    return url;
+}
+function buildPostBody(args, options, isPreview, includePreview = true) {
+    const { preview: _stripped, ...rest } = args;
+    void _stripped;
+    const locale = normalizeRequestLocale(options?.locale);
+    return JSON.stringify({
+        ...rest,
+        ...(locale && rest.locale === undefined ? { locale } : {}),
+        ...(includePreview ? { preview: isPreview } : {}),
+    });
+}
+function normalizeRequestLocale(value) {
+    if (typeof value !== 'string')
+        return undefined;
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : undefined;
+}
+function buildFetchInit(args) {
+    const { method, token, isPreview, udfPath, requestContext, options, body, signal, } = args;
+    const headers = {
+        Authorization: `Bearer ${token}`,
+        'X-Storystick-Client': 'sdk',
+        ...(!isPreview ? contentShapeCapabilityHeaders('api', undefined, args.applicationBuildId) : {}),
+    };
+    if (udfPath === 'queries:queryV2')
+        headers[QUERY_HTTP_PROTOCOL_HEADER] = QUERY_HTTP_PROTOCOL;
+    if (isPreview)
+        headers['X-Storystick-Preview'] = '1';
+    if (isPreview &&
+        (udfPath === 'queries:queryV2' || udfPath === 'queries:getRouteByPathname') &&
+        requestContext?.previewReadContext &&
+        requestContext.previewQueryConsumer) {
+        headers[PREVIEW_GATEWAY_CONTEXT_HEADER] = encodePreviewGatewayContext({
+            version: 2,
+            contextId: requestContext.previewReadContext.contextId,
+            revision: requestContext.previewReadContext.revision,
+            ...(requestContext.previewSessionId ? { sessionId: requestContext.previewSessionId } : {}),
+            ...(requestContext.variantId
+                ? { variantId: requestContext.variantId }
+                : {}),
+            ...(requestContext.releaseId
+                ? { releaseId: requestContext.releaseId }
+                : {}),
+            queryConsumer: requestContext.previewQueryConsumer,
+            ...(requestContext.previewReadContext.perspective.kind === 'published' ? { published: true } : {}),
+            ...(requestContext.previewReadContext.perspective.kind !== 'published' && requestContext.previewLiveQueryOverlayEnabled === true
+                ? { liveQueryOverlay: true }
+                : {}),
+        });
+    }
+    if (method === 'POST')
+        headers['Content-Type'] = 'application/json';
+    const init = {
+        method,
+        headers,
+        body,
+    };
+    if (signal)
+        init.signal = signal;
+    if (isPreview) {
+        // Preview reads must never enter Next's persistent fetch cache.
+        // `Cache-Control: no-store` + `cache: 'no-store'` win over any
+        // caller-supplied directives by being applied LAST (ADR-091
+        // Consequences > preview semantics).
+        init.cache = 'no-store';
+        headers['Cache-Control'] = 'no-store';
+        return init;
+    }
+    // Production path — honor user-supplied cache and next.* directives.
+    if (options?.cache)
+        init.cache = options.cache;
+    if (options?.deliveryCache === 'bypass') {
+        headers['x-storystick-delivery-fresh'] = '1';
+        init.cache = 'no-store';
+        return init;
+    }
+    if (options?.next) {
+        const next = {};
+        if (options.next.revalidate !== undefined)
+            next.revalidate = options.next.revalidate;
+        if (options.next.tags && options.next.tags.length > 0)
+            next.tags = options.next.tags;
+        if (Object.keys(next).length > 0)
+            init.next = next;
+    }
+    return init;
+}
+/**
+ * Refresh-vs-retry decision per ADR-091 / Tension #5 lock B.
+ *
+ * Decision tree (codex Lane A finding 2 — canonical metadata wins):
+ *   - Body parses + carries a canonical `category` field → trust it.
+ *     Refresh+retry iff `category === 'auth' && retryable === true`.
+ *     `category === 'auth' && retryable === false` (e.g. ACCESS_DENIED)
+ *     does NOT trigger refresh — the original error is surfaced.
+ *   - Body absent / unparseable / no `category` field → legacy
+ *     status-based fallback for pre-batch-4 deployments. HTTP 401/403
+ *     means refreshable.
+ *
+ * Re-clones the response so the body can be re-read by the caller's
+ * StorystickError construction path.
+ */
+async function shouldRefreshAndRetry(response) {
+    if (response.ok)
+        return false;
+    let canonicalSeen = false;
+    try {
+        const cloned = response.clone();
+        const bodyJson = (await cloned.json().catch(() => null));
+        const wrapped = bodyJson?.error;
+        const candidate = wrapped ?? bodyJson ?? undefined;
+        if (candidate && candidate.category !== undefined) {
+            canonicalSeen = true;
+            return candidate.category === 'auth' && candidate.retryable === true;
+        }
+    }
+    catch {
+        /* canonical-envelope absent — fall through */
+    }
+    if (canonicalSeen)
+        return false;
+    // Pre-batch-4 deployments: status-based legacy fallback.
+    return response.status === 401 || response.status === 403;
+}
+function errorRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value)
+        ? value : {};
+}
+/** Read-only transport: explicit metadata wins; HTTP remains usable without it. */
+async function buildStorystickError(response) {
+    const body = errorRecord(await response.json().catch(() => null));
+    const wrapped = errorRecord(body.error);
+    const code = typeof wrapped.code === 'string' ? wrapped.code
+        : typeof body.code === 'string' ? body.code : `HTTP_${response.status}`;
+    const message = typeof wrapped.message === 'string' ? wrapped.message
+        : typeof body.message === 'string' ? body.message : response.statusText || 'Request failed';
+    const temporary = isTemporaryHttpStatus(response.status);
+    const category = typeof wrapped.category === 'string' &&
+        ['validation', 'conflict', 'auth', 'system', 'cancel'].includes(wrapped.category)
+        ? wrapped.category : undefined;
+    return new StorystickError(`${code} — ${message}`, {
+        ref: typeof wrapped.ref === 'string' ? wrapped.ref : response.headers.get('X-Storystick-Error-Ref') || undefined,
+        code,
+        category: category ?? (temporary ? 'system' : undefined),
+        recoverable: typeof wrapped.recoverable === 'boolean' ? wrapped.recoverable : undefined,
+        retryable: httpFailureRetryable({ operation: 'read', status: response.status,
+            retryable: typeof wrapped.retryable === 'boolean' ? wrapped.retryable : undefined }),
+        payload: wrapped.payload,
+        status: response.status,
+        retryAfterMs: parseRetryAfter(response.headers.get('Retry-After'), Date.now()),
+    });
+}
+// ─────────────────────────────────────────────
+// onAccessedDocuments tap
+// ─────────────────────────────────────────────
+/**
+ * Fire the `onAccessedDocuments` tap with extracted documentIds when
+ * the preview path is bound. Fire-and-forget — never blocks, never
+ * throws. Production calls do NOT fire the tap; observation is a
+ * preview-only telemetry channel (ADR-131 §D3.1b R2b item 16).
+ *
+ * Gated invariant: callback signature is sync-only by design. If a
+ * future adapter wants an async tap, the adapter wraps `Promise.allSettled`
+ * inside the sync callback — this layer must never block the request
+ * response on telemetry I/O.
+ */
+function fireOnAccessedContent(input) {
+    if (!input.isPreview)
+        return;
+    const documentIds = extractAccessedDocumentIds(input.udfPath, input.data);
+    const legacyTap = input.requestContext?.onAccessedDocuments;
+    if (legacyTap && documentIds.length > 0) {
+        try {
+            legacyTap(documentIds);
+        }
+        catch {
+            // Same fire-and-forget isolation as the enriched tap below.
+        }
+    }
+    const codeVersion = input.requestContext?.previewCodeVersion;
+    const observationId = input.requestContext?.previewObservationId;
+    const watermarkHeader = input.response.headers.get('X-Storystick-Preview-Read-Watermark');
+    const renderWatermark = watermarkHeader === null ? Number.NaN : Number(watermarkHeader);
+    // Amendment-003-style fence: a mixed old/new SDK pair emits no enriched
+    // observation. It must never attach an unversioned watermark to a frame.
+    if (typeof codeVersion !== 'string' ||
+        codeVersion.length === 0 ||
+        typeof observationId !== 'string' ||
+        observationId.length === 0 ||
+        !Number.isFinite(renderWatermark))
+        return;
+    const receiptId = input.response.headers.get(PREVIEW_QUERY_RECEIPT_HEADER);
+    const observation = {
+        ...(input.requestContext?.previewReadContext
+            ? { readContext: input.requestContext.previewReadContext }
+            : {}),
+        ...(receiptId && /^pqr_[a-f0-9]{64}$/.test(receiptId) ? { receiptId } : {}),
+        documentIds,
+        storyTypes: extractAccessedStoryTypes(input.udfPath, input.args, input.data),
+        codeVersion,
+        observationId,
+        renderWatermark,
+    };
+    attachPreviewReadObservation(input.data, observation);
+    const tap = input.requestContext?.onAccessedContent;
+    if (!tap)
+        return;
+    // A zero-document list is still a read dependency on its story type. The
+    // first document created for that type must wake the displayed frame.
+    if (observation.documentIds.length === 0 &&
+        observation.storyTypes.length === 0)
+        return;
+    try {
+        tap(observation);
+    }
+    catch {
+        // Tap implementation threw — swallow. The tap is fire-and-forget
+        // by contract; an exception there must never propagate into the
+        // RSC render path.
+    }
+}
+function extractAccessedStoryTypes(udfPath, args, data) {
+    const seen = new Set();
+    const add = (value) => {
+        if (typeof value === 'string' && value.trim().length > 0) {
+            seen.add(value.trim());
+        }
+    };
+    const addFromDocument = (value) => {
+        if (value && typeof value === 'object') {
+            add(value.storyType);
+        }
+    };
+    switch (udfPath) {
+        case 'queries:getRouteByPathname':
+            if (Array.isArray(args.storyTypes)) {
+                for (const storyType of args.storyTypes)
+                    add(storyType);
+            }
+            break;
+        case 'queries:queryV2':
+            if (args.query && typeof args.query === 'object') {
+                const target = args.query.target;
+                if (target && typeof target === 'object') {
+                    add(target.storyType);
+                }
+            }
+            break;
+        default:
+            break;
+    }
+    if (Array.isArray(data)) {
+        for (const row of data)
+            addFromDocument(row);
+    }
+    else if (data && typeof data === 'object') {
+        addFromDocument(data);
+        const items = data.data;
+        if (Array.isArray(items)) {
+            for (const row of items)
+                addFromDocument(row);
+        }
+        const document = data.document;
+        addFromDocument(document);
+        const documents = data.documents;
+        if (Array.isArray(documents)) {
+            for (const row of documents)
+                addFromDocument(row);
+        }
+    }
+    return [...seen];
+}
+/**
+ * Per-udfPath documentId extraction (ADR-131 §D3.1b). Returns a
+ * de-duplicated, declared-order list (Set semantics with stable
+ * insertion order — JS Map/Set preserve insertion order).
+ *
+ * Shape rules (mirrors the gateway's response envelopes):
+ *   - `queries:getRouteByPathname`→ `{ document: { documentId, ... } }`
+ *     on hit; miss envelopes do not contain a document
+ *   - `queries:queryV2`           → document(s) in the exact result `.data`
+ *
+ * Unknown udfPath OR a response missing the expected `documentId` shape
+ * returns the empty list — the tap is silently inert rather than
+ * surfacing a contract violation. The orchestrator's second-preview
+ * bundle composition will reconverge via the schema marker path
+ * (§D3.1a 3-source union — chrome:true ∪ page-closure ∪ observed).
+ */
+function extractAccessedDocumentIds(udfPath, data) {
+    const seen = new Set();
+    const add = (value) => {
+        if (typeof value === 'string' && value.length > 0)
+            seen.add(value);
+    };
+    switch (udfPath) {
+        case 'queries:getRouteByPathname': {
+            if (data && typeof data === 'object') {
+                const doc = data.document;
+                if (doc && typeof doc === 'object') {
+                    add(doc.documentId);
+                }
+            }
+            break;
+        }
+        case 'queries:queryV2': {
+            if (data && typeof data === 'object') {
+                const result = data.data;
+                for (const row of Array.isArray(result) ? result : [result]) {
+                    if (row && typeof row === 'object')
+                        add(row.documentId);
+                }
+            }
+            break;
+        }
+        default:
+            break;
+    }
+    return Array.from(seen);
+}