@shoalrun/cli 0.1.0-alpha.11 → 0.1.0-alpha.13

package/dist/content-rest-client.js

@@ -0,0 +1,162 @@
+import { ContentDeliveryError, contentRefKey } from './content-delivery-contract.js';
+import { contentResourceKey } from './content-rest-contract.js';
+import { validContentPublication, validContentRef, validateContentResources, safeContentPath } from './content-delivery-validation.js';
+import { freeze, sha256, readBounded } from './content-delivery-transport.js';
+const digestPattern = /^[a-f0-9]{64}$/;
+const record = (value) => !!value && typeof value === 'object' && !Array.isArray(value);
+const exactKeys = (value, keys) => record(value) && Object.keys(value).length === keys.length && Object.keys(value).every(key => keys.includes(key));
+const samePublication = (left, right) => left.channel === right.channel && left.version === right.version && left.language === right.language;
+const invalid = (message) => { throw new ContentDeliveryError('invalid_manifest', message); };
+/** Preloads a REST inventory and pins all subsequent reads to that revision. */
+export async function openRestContentSource(options) {
+    let baseUrl;
+    try {
+        baseUrl = new URL(options.baseUrl, typeof location === 'undefined' ? undefined : location.href);
+    }
+    catch {
+        return invalid('REST base URL must be a valid HTTP(S) URL.');
+    }
+    if (!['http:', 'https:'].includes(baseUrl.protocol) || baseUrl.username || baseUrl.password || baseUrl.search || baseUrl.hash || !/^\/(?:[A-Za-z0-9_-]+\/?)*$/.test(baseUrl.pathname))
+        invalid('Invalid REST base URL.');
+    if (typeof location !== 'undefined' && baseUrl.origin !== location.origin)
+        invalid('Browser content must be served from the application origin.');
+    if (!validContentPublication(options.publication) || options.revision !== undefined && !digestPattern.test(options.revision))
+        invalid('Invalid REST publication or revision.');
+    const publication = { ...options.publication };
+    const requestedRevision = options.revision;
+    const fetcher = options.fetch ?? globalThis.fetch;
+    const manifestBytes = options.limits?.manifestBytes ?? 5_000_000;
+    const resourceBytes = options.limits?.resourceBytes ?? 8_000_000;
+    const maxResources = options.limits?.resources ?? 10_000;
+    for (const limit of [manifestBytes, resourceBytes, maxResources])
+        if (!Number.isSafeInteger(limit) || limit <= 0)
+            invalid('Limits must be positive safe integers.');
+    const lifetime = new AbortController();
+    let disposed = false;
+    const openSignal = options.signal ? AbortSignal.any([options.signal, lifetime.signal]) : lifetime.signal;
+    const urlFor = (suffix, revision) => {
+        const url = new URL(baseUrl.href);
+        url.pathname = baseUrl.pathname.replace(/\/$/, '') + '/resources' + suffix;
+        for (const key of ['channel', 'version', 'language'])
+            url.searchParams.set(key, publication[key]);
+        if (revision !== undefined)
+            url.searchParams.set('revision', revision);
+        return url;
+    };
+    async function request(url, mediaType, limit, signal) {
+        signal.throwIfAborted();
+        let response;
+        try {
+            response = await fetcher(url.href, { signal, redirect: 'error', credentials: 'same-origin', cache: 'no-store', headers: { Accept: mediaType } });
+        }
+        catch {
+            signal.throwIfAborted();
+            throw new ContentDeliveryError('network_error', 'Cannot fetch REST content.');
+        }
+        const reject = async (code, message) => {
+            // Cancelling releases the body without consuming an arbitrary host error.
+            // A custom stream's cancellation promise must not delay the failure.
+            void response.body?.cancel().catch(() => { });
+            signal.throwIfAborted();
+            throw new ContentDeliveryError(code, message);
+        };
+        if (response.redirected || response.url && response.url !== url.href)
+            return reject('invalid_content', 'Redirected content is not accepted.');
+        const actualType = response.headers.get('content-type')?.split(';', 1)[0].trim().toLowerCase();
+        try {
+            if (!response.ok) {
+                const codes = { 400: 'invalid_request', 404: 'not_found', 406: 'unsupported_format', 409: 'stale_revision', 405: 'method_not_allowed', 500: 'internal_error' };
+                if (!(response.status in codes))
+                    return reject('network_error', `Content request failed (${response.status}).`);
+                if (actualType !== 'application/json')
+                    return reject('invalid_content', 'REST error must be JSON.');
+                const bytes = await readBounded(response, Math.min(manifestBytes, 65_536), signal);
+                let envelope;
+                try {
+                    envelope = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(bytes));
+                }
+                catch {
+                    throw new ContentDeliveryError('invalid_content', 'Malformed REST error.');
+                }
+                if (!exactKeys(envelope, ['error']) || !exactKeys(envelope.error, ['code', 'message']) || codes[response.status] !== envelope.error.code || typeof envelope.error.message !== 'string')
+                    throw new ContentDeliveryError('invalid_content', 'Malformed REST error.');
+                const code = response.status === 404 ? 'not_found' : response.status === 406 ? 'unsupported_format' : response.status === 409 ? 'stale_revision' : 'network_error';
+                throw new ContentDeliveryError(code, envelope.error.message);
+            }
+            if (actualType !== mediaType)
+                return reject('invalid_content', 'Unexpected content type.');
+            return await readBounded(response, limit, signal);
+        }
+        catch (error) {
+            signal.throwIfAborted();
+            if (error instanceof ContentDeliveryError)
+                throw error;
+            throw new ContentDeliveryError('network_error', 'Content response was interrupted.');
+        }
+    }
+    let envelope;
+    try {
+        envelope = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(await request(urlFor('', requestedRevision), 'application/json', manifestBytes, openSignal)));
+    }
+    catch (error) {
+        if (error instanceof ContentDeliveryError || openSignal.aborted)
+            throw error;
+        return invalid('REST inventory is not valid UTF-8 JSON.');
+    }
+    if (!exactKeys(envelope, ['schemaVersion', 'revision', 'publication', 'resources']) || envelope.schemaVersion !== 1 || !digestPattern.test(envelope.revision ?? '') || !validContentPublication(envelope.publication) || !samePublication(envelope.publication, publication))
+        invalid('Invalid REST inventory identity.');
+    if (requestedRevision !== undefined && requestedRevision !== envelope.revision)
+        throw new ContentDeliveryError('stale_revision', 'REST inventory differs from the requested revision.');
+    if (!Array.isArray(envelope.resources) || envelope.resources.length > maxResources)
+        invalid('Invalid REST resource inventory.');
+    const resources = [];
+    const assets = new Set();
+    for (const item of envelope.resources) {
+        if (!exactKeys(item, ['key', 'resource']) || !record(item.resource) || !validContentRef(item.resource.ref) || item.key !== contentResourceKey(item.resource.ref))
+            invalid('Invalid REST resource key.');
+        if (!Array.isArray(item.resource.assets) || item.resource.assets.some((asset) => !safeContentPath(asset) || !asset.startsWith('assets/')))
+            invalid('Invalid REST resource assets.');
+        item.resource.assets.forEach((asset) => assets.add(asset));
+        resources.push(item.resource);
+    }
+    validateContentResources(resources, publication, assets, rep => record(rep) && safeContentPath(rep.path) && Number.isSafeInteger(rep.bytes) && rep.bytes >= 0 && rep.bytes <= resourceBytes && digestPattern.test(rep.digest ?? ''));
+    const revision = envelope.revision;
+    freeze(resources);
+    freeze(publication);
+    const byRef = new Map(resources.map(resource => [contentRefKey(resource.ref), resource]));
+    openSignal.throwIfAborted();
+    const active = () => { if (disposed)
+        throw new ContentDeliveryError('disposed', 'Content snapshot has been disposed.'); };
+    return Object.freeze({ revision, publication,
+        list() { active(); return resources; },
+        async get(ref, getOptions) {
+            active();
+            if (!validContentRef(ref))
+                throw new ContentDeliveryError('not_found', 'Invalid content reference.');
+            const resource = byRef.get(contentRefKey(ref));
+            if (!resource)
+                throw new ContentDeliveryError('not_found', 'No matching content in this publication.');
+            const format = getOptions?.format;
+            if (!['html', 'markdown'].includes(format) || !resource.representations[format])
+                throw new ContentDeliveryError('unsupported_format', 'The requested representation is unavailable.');
+            const representation = resource.representations[format];
+            const signal = getOptions.signal ? AbortSignal.any([lifetime.signal, getOptions.signal]) : lifetime.signal;
+            const bytes = await request(urlFor('/' + contentResourceKey(resource.ref) + '/representations/' + format, revision), representation.mediaType, resourceBytes, signal);
+            if (bytes.byteLength !== representation.bytes || await sha256(bytes) !== representation.digest)
+                throw new ContentDeliveryError('stale_revision', 'Representation differs from the opened revision.');
+            signal.throwIfAborted();
+            active();
+            let content;
+            try {
+                content = new TextDecoder('utf-8', { fatal: true }).decode(bytes);
+            }
+            catch {
+                throw new ContentDeliveryError('invalid_content', 'Content is not valid UTF-8.');
+            }
+            return Object.freeze({ resource, representation, format, content, revision });
+        },
+        dispose() { if (!disposed) {
+            disposed = true;
+            lifetime.abort(new ContentDeliveryError('disposed', 'Content snapshot has been disposed.'));
+        } }, });
+}

package/dist/content-rest-contract.d.ts

@@ -0,0 +1,27 @@
+import type { ContentPublication, ContentRef, ContentResource } from './content-delivery-contract.js';
+/** Public identity only: independent of publication, revision, and export filenames. */
+export declare function contentResourceKey(ref: ContentRef): string;
+export type ContentRestEntry = {
+    key: string;
+    resource: ContentResource;
+};
+export type ContentRestList = {
+    schemaVersion: 1;
+    revision: string;
+    publication: ContentPublication;
+    resources: ContentRestEntry[];
+};
+export type ContentRestResource = {
+    schemaVersion: 1;
+    revision: string;
+    publication: ContentPublication;
+    key: string;
+    resource: ContentResource;
+};
+export type ContentRestErrorCode = 'invalid_request' | 'not_found' | 'unsupported_format' | 'stale_revision' | 'method_not_allowed' | 'internal_error';
+export type ContentRestError = {
+    error: {
+        code: ContentRestErrorCode;
+        message: string;
+    };
+};

package/dist/content-rest-contract.js

@@ -0,0 +1,9 @@
+import { contentRefKey } from './content-delivery-contract.js';
+/** Public identity only: independent of publication, revision, and export filenames. */
+export function contentResourceKey(ref) {
+    const bytes = new TextEncoder().encode(contentRefKey(ref));
+    let binary = '';
+    for (const byte of bytes)
+        binary += String.fromCharCode(byte);
+    return 'k_' + btoa(binary).replaceAll('+', '-').replaceAll('/', '_').replace(/=+$/, '');
+}

package/dist/content-rest-server.d.ts

@@ -0,0 +1,7 @@
+import type { ContentSnapshot } from './content-delivery-contract.js';
+export type ContentRestHandlerOptions = {
+    sources: readonly ContentSnapshot[];
+    basePath?: string;
+};
+/** Serve already-approved, pinned snapshots. The caller retains source ownership. */
+export declare function createContentRestHandler(options: ContentRestHandlerOptions): (request: Request) => Promise<Response>;

package/dist/content-rest-server.js

@@ -0,0 +1,99 @@
+import { ContentDeliveryError, contentRefKey } from './content-delivery-contract.js';
+import { contentResourceKey } from './content-rest-contract.js';
+const publicationKey = (publication) => JSON.stringify([publication.channel, publication.version, publication.language]);
+const digest = async (bytes) => [...new Uint8Array(await crypto.subtle.digest('SHA-256', bytes))].map(value => value.toString(16).padStart(2, '0')).join('');
+const encoder = new TextEncoder();
+const validPublication = (value) => value && Object.keys(value).sort().join(',') === 'channel,language,version' && Object.values(value).every(part => typeof part === 'string' && part.length > 0 && part.length <= 2048);
+const canonical = (value) => Array.isArray(value) ? value.map(canonical) : value && typeof value === 'object' ? Object.fromEntries(Object.keys(value).sort().map(key => [key, canonical(value[key])])) : value;
+const same = (left, right) => JSON.stringify(canonical(left)) === JSON.stringify(canonical(right));
+/** Serve already-approved, pinned snapshots. The caller retains source ownership. */
+export function createContentRestHandler(options) {
+    const basePath = options.basePath ?? '/content/v1';
+    if (!/^\/(?:[A-Za-z0-9_-]+\/)*[A-Za-z0-9_-]+$/.test(basePath))
+        throw new Error('Content REST basePath must be an absolute path without a trailing slash.');
+    const publications = new Map();
+    for (const source of options.sources) {
+        if (!/^[a-f0-9]{64}$/.test(source.revision) || !validPublication(source.publication))
+            throw new Error('Content REST source requires a valid revision and publication.');
+        const publication = structuredClone(source.publication);
+        const key = publicationKey(publication);
+        if (publications.has(key))
+            throw new Error('Content REST sources must have distinct publications.');
+        const resources = source.list().map(resource => ({ key: contentResourceKey(resource.ref), resource: structuredClone(resource) }));
+        if (resources.some(item => !validPublication(item.resource.publication) || publicationKey(item.resource.publication) !== key) || new Set(resources.map(item => item.key)).size !== resources.length)
+            throw new Error('Content REST source contains inconsistent publication or duplicate references.');
+        resources.sort((left, right) => left.key < right.key ? -1 : left.key > right.key ? 1 : 0);
+        publications.set(key, { source, publication, revision: source.revision, resources });
+    }
+    return async (request) => {
+        request.signal.throwIfAborted();
+        const head = request.method === 'HEAD';
+        const error = (status, code, message, headers = {}) => new Response(head ? null : JSON.stringify({ error: { code, message } }), { status, headers: { 'Content-Type': 'application/json; charset=utf-8', 'Cache-Control': 'no-store', ...headers } });
+        if (!['GET', 'HEAD'].includes(request.method))
+            return error(405, 'method_not_allowed', 'Use GET or HEAD.', { Allow: 'GET, HEAD' });
+        const url = new URL(request.url);
+        const prefix = `${basePath}/resources`;
+        if (url.pathname !== prefix && !url.pathname.startsWith(`${prefix}/`))
+            return error(404, 'not_found', 'Unknown content route.');
+        const parts = url.pathname.slice(prefix.length).split('/').slice(1);
+        if (parts.length !== 0 && parts.length !== 1 && !(parts.length === 3 && parts[1] === 'representations'))
+            return error(404, 'not_found', 'Unknown content route.');
+        const allowed = new Set(['channel', 'version', 'language', 'revision']);
+        if ([...url.searchParams.keys()].some(key => !allowed.has(key) || url.searchParams.getAll(key).length !== 1))
+            return error(400, 'invalid_request', 'Unknown or repeated query parameter.');
+        const publication = Object.fromEntries(['channel', 'version', 'language'].map(key => [key, url.searchParams.get(key)]));
+        if (Object.values(publication).some(value => !value || value.length > 2048))
+            return error(400, 'invalid_request', 'channel, version, and language are required.');
+        const revision = url.searchParams.get('revision');
+        if (revision !== null && !/^[a-f0-9]{64}$/.test(revision) || parts.length > 0 && revision === null)
+            return error(400, 'invalid_request', 'A valid revision is required for resource requests.');
+        const selected = publications.get(publicationKey(publication));
+        if (!selected)
+            return error(404, 'not_found', 'Publication not found.');
+        if (revision !== null && revision !== selected.revision)
+            return error(409, 'stale_revision', 'The requested revision is not available.');
+        const resource = parts.length ? selected.resources.find(item => item.key === parts[0]) : undefined;
+        if (parts.length && !resource)
+            return error(404, 'not_found', 'Resource not found.');
+        try {
+            let body;
+            let mediaType = 'application/json';
+            if (!parts.length)
+                body = JSON.stringify({ schemaVersion: 1, revision: selected.revision, publication: selected.publication, resources: selected.resources });
+            else if (parts.length === 1)
+                body = JSON.stringify({ schemaVersion: 1, revision: selected.revision, publication: selected.publication, ...resource });
+            else {
+                const format = parts[2];
+                if (!['html', 'markdown'].includes(format) || !resource.resource.representations[format])
+                    return error(406, 'unsupported_format', 'Representation not available.');
+                const descriptor = resource.resource.representations[format];
+                const result = await selected.source.get(resource.resource.ref, { format, signal: request.signal });
+                request.signal.throwIfAborted();
+                if (result.revision !== selected.revision)
+                    return error(409, 'stale_revision', 'The requested revision is no longer available.');
+                if (typeof result.content !== 'string' || contentRefKey(result.resource.ref) !== contentRefKey(resource.resource.ref) || result.format !== format || !same(result.resource, resource.resource) || !same(result.representation, descriptor))
+                    return error(500, 'internal_error', 'Content source returned inconsistent metadata.');
+                const bytes = encoder.encode(result.content);
+                if (bytes.byteLength !== descriptor.bytes || await digest(bytes) !== descriptor.digest)
+                    return error(409, 'stale_revision', 'The requested revision bytes are no longer available.');
+                body = result.content;
+                mediaType = descriptor.mediaType;
+            }
+            const bytes = encoder.encode(body);
+            const etag = `"sha256-${await digest(bytes)}"`;
+            request.signal.throwIfAborted();
+            const headers = { 'Content-Type': `${mediaType}; charset=utf-8`, 'Content-Length': String(bytes.byteLength), ETag: etag, 'Cache-Control': revision === null ? 'no-cache' : 'public, max-age=31536000, immutable' };
+            const condition = request.headers.get('if-none-match');
+            const matches = condition?.trim() === '*' || condition?.split(',').some(value => value.trim().replace(/^W\//, '') === etag);
+            if (matches)
+                return new Response(null, { status: 304, headers });
+            return new Response(head ? null : body, { status: 200, headers });
+        }
+        catch (cause) {
+            request.signal.throwIfAborted();
+            if (cause instanceof ContentDeliveryError && ['stale_revision', 'not_found'].includes(cause.code))
+                return error(409, 'stale_revision', 'The requested revision is no longer available.');
+            return error(500, 'internal_error', 'Content source could not serve the request.');
+        }
+    };
+}

package/dist/content-source.d.ts

@@ -1,6 +1,7 @@
 import type { AuthoredChange, ResolvedChange } from './authored-change.js';
 import type { SubjectDeprecation, ResolvedSubjectDeprecation } from './subject-deprecation.js';
 import type { ReaderSelection } from './reader-filters.js';
+import type { StandaloneSectionDeclaration } from './section-identity.js';
 export type Variant = {
     channel: string;
     version: string;
@@ -32,7 +33,7 @@ export type Frontmatter = {
     product?: string;
     area?: string | string[];
     subarea?: string | string[];
-    standaloneSections?: string[];
+    standaloneSections?: StandaloneSectionDeclaration[];
     access?: {
         policy: string;
     };
@@ -45,6 +46,7 @@ export type Frontmatter = {
     layout?: 'docs' | 'wide' | 'landing' | 'splash';
     image?: string;
     showNavigationTabs?: boolean;
+    showVerified?: boolean;
     [key: string]: unknown;
 };
 export type Document = {

package/dist/frontmatter.js

@@ -2,8 +2,9 @@ import { validateAuthoredChange, changeKinds } from './authored-change.js';
 import { validateSubjectDeprecation } from './subject-deprecation.js';
 import { validateCardMetadata } from './cards.js';
 import { resolveTaxonomy, validateTaxonomy, taxonomySchema } from './taxonomy.js';
+import { validateStandaloneSectionDeclarations } from './section-identity.js';
 export const nativePublicFields = new Set(['id', 'title', 'type', 'summary', 'description', 'language', 'locale', 'date', 'updated', 'verified', 'releaseVersion', 'product', 'area', 'subarea', 'operations', 'relatedApiReferences', 'audiences', 'readerFilters', 'tags', 'subjectLifecycle', 'subjectDeprecation', 'change', 'lifecycle']);
-export const protectedMetadataRoots = new Set(['standaloneSections', 'access', 'seo', 'markdownMetadata', 'variables', 'tocDepth', 'layout', 'showNavigationTabs', 'image', 'private', 'internal', 'card', 'displayText', 'publications']);
+export const protectedMetadataRoots = new Set(['standaloneSections', 'access', 'seo', 'markdownMetadata', 'variables', 'tocDepth', 'layout', 'showNavigationTabs', 'showVerified', 'image', 'private', 'internal', 'card', 'displayText', 'publications']);
 const fieldTypes = new Set(['string', 'number', 'integer', 'boolean', 'object', 'array']);
 const safePath = (value) => /^[A-Za-z_][A-Za-z0-9_-]*(?:\.[A-Za-z_][A-Za-z0-9_-]*)*$/.test(value);
 const object = (value) => !!value && typeof value === 'object' && !Array.isArray(value);
@@ -116,10 +117,7 @@ export function validateFrontmatter(frontmatter, config, file, source) {
     validateCardMetadata(frontmatter.card, file);
     validateSubjectDeprecation(frontmatter.subjectDeprecation, file);
     validateAuthoredChange(frontmatter, file);
-    const standalone = frontmatter.standaloneSections;
-    if (standalone !== undefined && (!Array.isArray(standalone) || standalone.some(title => typeof title !== 'string' || !title.trim() || title !== title.trim()) || new Set(standalone).size !== standalone.length)) {
-        throw new Error(`${file}: standaloneSections must be a unique list of nonempty, trimmed heading titles`);
-    }
+    validateStandaloneSectionDeclarations(frontmatter.standaloneSections, file);
     const mode = config?.changelogIdentifier ?? 'either';
     if (frontmatter.type === 'changelog-entry' &&
         (mode === 'date' && frontmatter.date === undefined || mode === 'version' && frontmatter.releaseVersion === undefined || mode === 'either' && frontmatter.date === undefined && frontmatter.releaseVersion === undefined))
@@ -180,6 +178,8 @@ export function validateFrontmatter(frontmatter, config, file, source) {
         throw new Error(`${file}: tocDepth must be 0 or an integer from 2 through 6`);
     if (frontmatter.layout !== undefined && !['docs', 'wide', 'landing', 'splash'].includes(frontmatter.layout))
         throw new Error(`${file}: layout must be docs, wide, landing, or splash`);
+    if (frontmatter.showVerified !== undefined && typeof frontmatter.showVerified !== 'boolean')
+        throw new Error(`${file}: showVerified must be true or false`);
     if (frontmatter.showNavigationTabs !== undefined && typeof frontmatter.showNavigationTabs !== 'boolean')
         throw new Error(`${file}: showNavigationTabs must be true or false`);
     if (frontmatter.image !== undefined && (typeof frontmatter.image !== 'string' || !/\.(?:png|jpe?g)$/i.test(frontmatter.image) || /^[a-z][a-z0-9+.-]*:/i.test(frontmatter.image)))
@@ -245,8 +245,9 @@ export function frontmatterSchema(config) {
         subjectDeprecation: { type: 'object', minProperties: 1, additionalProperties: false, description: 'Page-specific subject retirement dates and stable document IDs; requires deprecated subjectLifecycle, including OpenAPI inference. Dates do not change status automatically.', properties: { deprecatedOn: { type: 'string', format: 'date' }, sunsetOn: { type: 'string', format: 'date' }, replacement: { type: 'string', minLength: 1 }, migration: { type: 'string', minLength: 1 } } },
         subjectLifecycle: { type: 'string', enum: ['deprecated', 'in-development', 'beta', 'experimental'], description: 'Displays a content status badge in the page and navigation.' },
         lifecycle: { type: 'string', minLength: 1, description: 'Editorial lifecycle of the document; validated by an opted-in external vocabulary.' },
-        standaloneSections: { type: 'array', items: { type: 'string' }, uniqueItems: true, description: 'Page-specific exact level-two heading titles reviewed by the author as self-contained with the page introduction. Allows eligible sections to be recommended alone; omitted means full-page reads.' },
+        standaloneSections: { type: 'array', items: { oneOf: [{ type: 'string', minLength: 1 }, { type: 'object', additionalProperties: false, required: ['id', 'context'], properties: { id: { type: 'string', pattern: '^[a-z0-9][a-z0-9-]{0,511}$' }, context: { const: 'section' } } }] }, uniqueItems: true, description: 'Page-specific standalone approval: a heading title approves contextual discovery with the page introduction; {id, context: section} approves the root level-two section slice for content export. IDs may be derived or explicitly anchored. Omitted means full-page reads.' },
         tocDepth: { type: 'integer', enum: [0, 2, 3, 4, 5, 6], description: 'Deepest heading shown in the page table of contents; 0 hides it. Defaults to 3.' },
+        showVerified: { type: 'boolean', description: 'Show an authored verified date in the HTML page header. Defaults to true. False hides it only in HTML; Markdown and manifest dates remain unchanged. Does not assign a verification date.' },
         showNavigationTabs: { type: 'boolean', description: 'Show the HTML navigation section bar when tabs are configured. Defaults to true for docs and wide layouts, false for landing and splash. Does not change agent discovery or section membership.' },
         image: { type: 'string', pattern: '\\.(?:png|jpe?g)$', description: 'Local .png or .jpg shown in link previews for this page, relative to the page file; replaces the generated share image. Best at 1200×630.' },
         layout: { type: 'string', enum: ['docs', 'wide', 'landing', 'splash'], description: 'HTML page layout: docs (default), wide (no page outline, full content width), landing (no sidebar or outline; a Hero replaces the page header), or splash (full-bleed marketing page built from Hero and Section blocks).' },
@@ -319,7 +320,7 @@ export function frontmatterReference(config, sectionsOnly = false) {
         'Language is the content language and selects a publication. Locale describes formatting conventions in the content and does not select a publication. `frontmatter.locales` can set a project locale for each language; pages may override it.', '',
         '## Categorize, connect, and present the page', '',
         'By default, `product`, `area`, and `subarea` are optional, nonempty string categories. They can come from project defaults and appear in the document manifest and search index. A matching configured reader facet makes each category a page filter; without that facet it remains taxonomy only. `operations` links a guide or reference to stable API operation IDs. On a guide or how-to page, `relatedApiReferences` names API reference page IDs to add cross links in both directions within the same publication. Tags help document collections find the page. Card settings change its preview when another page links to it; they do not change the destination. `subjectLifecycle` displays the status of the documented API or feature; `lifecycle` is available for the document\'s editorial state. `tocDepth` limits the HTML page table of contents; use 0 to hide it. `layout` picks the HTML page layout: `docs`, `wide`, `landing`, or `splash`. `showNavigationTabs` overrides the navigation tab bar for this page; landing and splash pages hide it by default. `image` replaces the generated link-preview image. `date` and `releaseVersion` can identify a changelog entry under the project\'s `frontmatter.changelogIdentifier` rule.', '',
-        ...table, ...nativeRows(['product', 'area', 'subarea', 'operations', 'relatedApiReferences', 'tags', 'date', 'releaseVersion', 'subjectLifecycle', 'subjectDeprecation', 'change', 'lifecycle', 'card', 'standaloneSections', 'tocDepth', 'layout', 'showNavigationTabs', 'image']), '',
+        ...table, ...nativeRows(['product', 'area', 'subarea', 'operations', 'relatedApiReferences', 'tags', 'date', 'releaseVersion', 'subjectLifecycle', 'subjectDeprecation', 'change', 'lifecycle', 'card', 'standaloneSections', 'tocDepth', 'layout', 'showNavigationTabs', 'showVerified', 'image']), '',
         'Projects can opt into built-in category enforcement with `frontmatter.taxonomy`. It declares areas and their allowed subareas, optional required fields, and optional explicit-field requirements for authored pages. Its `multiple` list permits arrays for selected category fields; otherwise each field allows one value. Defaults and enforced values still apply; generated API references use resolved categories. Definitions appear in the document manifest and constrain the generated frontmatter schema. Omit taxonomy or set it to false to preserve optional category behavior.', '',
         '## Control output details', '',
         '`seo` changes the browser title or HTML meta description. `displayText` overrides the text chosen for one output surface on this page. `variables` supplies values to registered snippets before they expand into the page body. `markdownMetadata` selects or overrides the YAML preamble of the generated Markdown twin—the machine-readable copy of this page. That generated preamble is separate from the source frontmatter shown above.', '',

package/dist/html-renderer.js

@@ -15,6 +15,7 @@ export function renderHtmlWithHeadings(tree, highlighter, reservedIds = []) {
     const hast = html.runSync(tree);
     const used = new Set(reservedIds);
     const headings = [];
+    const aliases = new Map();
     const textOf = (node) => node.type === 'text' ? node.value : (node.children ?? []).map(textOf).join('');
     const checkUrl = (value) => {
         if (typeof value !== 'string')
@@ -34,6 +35,11 @@ export function renderHtmlWithHeadings(tree, highlighter, reservedIds = []) {
     };
     collectIds(hast);
     const visit = (node) => {
+        const sectionId = node.properties?.['data-shoalrun-section-id'] ?? node.properties?.dataShoalrunSectionId;
+        if (node.properties) {
+            delete node.properties['data-shoalrun-section-id'];
+            delete node.properties.dataShoalrunSectionId;
+        }
         const match = /^h([2-6])$/.exec(node.tagName ?? '');
         if (match && !node.properties?.className?.some((name) => ['tab-fallback-heading', 'walkthrough-step-title'].includes(name))) {
             const title = textOf(node).trim();
@@ -50,11 +56,30 @@ export function renderHtmlWithHeadings(tree, highlighter, reservedIds = []) {
                 }
                 if (!node.properties?.className?.includes('doc-step-heading-toc-ignore'))
                     headings.push({ depth, id, title });
+                if (typeof sectionId === 'string' && sectionId !== id)
+                    aliases.set(node, sectionId);
             }
         }
         node.children?.forEach(visit);
     };
     visit(hast);
+    // Preserve existing heading-derived URLs. Explicit identities add aliases,
+    // rather than reserving names early and renumbering unrelated headings.
+    for (const id of aliases.values()) {
+        if (used.has(id))
+            throw new Error(`Explicit section ID ${id} conflicts with an existing HTML anchor`);
+        used.add(id);
+    }
+    const addAliases = (node) => {
+        if (!node.children)
+            return;
+        node.children = node.children.flatMap((child) => {
+            addAliases(child);
+            const id = aliases.get(child);
+            return id ? [{ type: 'element', tagName: 'span', properties: { id, ariaHidden: 'true' }, children: [] }, child] : [child];
+        });
+    };
+    addAliases(hast);
     let rendered = String(html.stringify(hast));
     for (const [marker, markup] of math)
         rendered = rendered.replaceAll(marker, markup);

package/dist/markdown-sections.d.ts

@@ -1,3 +1,4 @@
+import { type StandaloneSectionDeclaration } from './section-identity.js';
 export type MarkdownSection = {
     id: string;
     title: string;
@@ -12,4 +13,4 @@ export type MarkdownSection = {
     markdownTokenEncoding: string;
     content: string;
 };
-export declare function markdownSections(tree: any, markdownUrl: string, parent: string, prefix: string, render: (tree: any) => string, standaloneTitles?: string[]): MarkdownSection[];
+export declare function markdownSections(tree: any, markdownUrl: string, parent: string, prefix: string, render: (tree: any) => string, declarations?: StandaloneSectionDeclaration[]): MarkdownSection[];

package/dist/markdown-sections.js

@@ -1,6 +1,7 @@
 import { createHash } from 'node:crypto';
 import { markdownSize } from './markdown-size.js';
 import { link, list, paragraph, renderMarkdown, root, text } from './semantic-markdown.js';
+import { validateStandaloneSections } from './section-identity.js';
 const digest = (value) => createHash('sha256').update(value).digest('hex');
 const pathKey = (item) => `${item.type}:${item.id}`;
 // Only direct page children qualify: hoisting a view from a ReaderSection, tab,
@@ -27,34 +28,23 @@ function missingReadingPath(all, included) {
 const textOf = (node) => typeof node.value === 'string' ? node.value : (node.children ?? []).map(textOf).join('');
 // Split the semantic root, never the flattened Markdown: a reader section or tab
 // remains intact even when it contains headings. Nested headings are not resources.
-export function markdownSections(tree, markdownUrl, parent, prefix, render, standaloneTitles = []) {
+export function markdownSections(tree, markdownUrl, parent, prefix, render, declarations = []) {
     const parentSize = markdownSize(parent);
     const children = tree.children ?? [];
-    const starts = children.flatMap((node, index) => node.type === 'heading' && node.depth === 2 ? [index] : []);
+    const identities = validateStandaloneSections(tree, declarations, markdownUrl);
+    const starts = identities.map(section => section.start);
     // Check declarations even on short pages: a renamed or ambiguous heading must
     // never silently retain an author's approval. Titles refer to normalized text.
-    for (const title of standaloneTitles) {
-        if (starts.filter(start => textOf(children[start]).trim() === title).length !== 1) {
-            throw new Error(`${markdownUrl}: standaloneSections title "${title}" must match exactly one top-level level-two heading`);
-        }
-    }
     if (parentSize.markdownTokens < 2000)
         return [];
     const preamble = children.slice(0, starts[0] ?? 0);
-    const used = new Set();
-    return starts.map(start => {
-        const title = textOf(children[start]).trim();
-        const stem = title.normalize('NFKD').toLowerCase().replace(/[\u0300-\u036f]/g, '').replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '').slice(0, 80).replace(/-$/, '') || 'section';
-        let id = stem;
-        for (let suffix = 2; used.has(id); suffix++)
-            id = `${stem}-${suffix}`;
-        used.add(id);
-        const end = children.findIndex((node, position) => position > start && node.type === 'heading' && node.depth <= 2);
-        const nodes = [...preamble, ...children.slice(start, end === -1 ? children.length : end)].filter(node => !['definition', 'footnoteDefinition'].includes(node.type));
+    return identities.map(({ start, end, id, title }) => {
+        const nodes = [...preamble, ...children.slice(start, end)].filter(node => !['definition', 'footnoteDefinition'].includes(node.type));
         const definitions = children.filter(node => ['definition', 'footnoteDefinition'].includes(node.type));
         const content = prefix + renderMarkdown(root([paragraph(text('Parent page: '), link(markdownUrl, 'Full Markdown page'))])) + '\n'
             + render(root([...missingReadingPath(children, nodes), ...nodes, ...definitions]));
-        return { id, title, depth: 2, ...(standaloneTitles.includes(title) ? { standalone: true } : {}), markdownUrl: `${markdownUrl.slice(0, -3)}.sections/${id}.md`, parentMarkdownUrl: markdownUrl,
+        const standalone = declarations.some(item => typeof item === 'string' ? item === title : item.id === id);
+        return { id, title, depth: 2, ...(standalone ? { standalone: true } : {}), markdownUrl: `${markdownUrl.slice(0, -3)}.sections/${id}.md`, parentMarkdownUrl: markdownUrl,
             parentDigest: digest(parent), digest: digest(content), ...markdownSize(content), content };
     }).filter(section => section.markdownTokens <= parentSize.markdownTokens / 2 && section.markdownBytes <= parentSize.markdownBytes / 2);
 }

package/dist/page-renderer.js

@@ -1,5 +1,5 @@
 import { resolveAgentDiscovery } from './agent-discovery.js';
-import { navigationCounts } from './compiler-config.js';
+import { navigationCounts, navigationHeading } from './compiler-config.js';
 import { navigationTab } from './project-navigation.js';
 import { highlightedExample } from './highlight.js';
 import { readerFilterAttribute } from './reader-filters.js';
@@ -81,8 +81,9 @@ export function buildHtmlPage(doc, tree, markdownUrl, siteTitle, navigation, exa
     const date = doc.frontmatter.date ? `<time class="page-date" datetime="${esc(doc.frontmatter.date)}">${esc(doc.frontmatter.date)}</time>` : '';
     const changelogEntry = doc.frontmatter.type === 'changelog-entry';
     const updated = doc.frontmatter.updated && !(changelogEntry && doc.frontmatter.date) ? `<span class="page-date">Updated <time datetime="${esc(doc.frontmatter.updated)}">${esc(doc.frontmatter.updated.slice(0, 10))}</time></span>` : '';
+    const verified = doc.frontmatter.verified && doc.frontmatter.showVerified !== false ? `<span class="page-date">Verified <time datetime="${esc(doc.frontmatter.verified)}">${esc(doc.frontmatter.verified)}</time></span>` : '';
     const releaseVersion = doc.frontmatter.releaseVersion ? `<span class="page-version">Version ${esc(doc.frontmatter.releaseVersion)}</span>` : '';
-    const pageDates = changelogEntry ? `<div class="page-meta">${date}${updated}${releaseVersion}</div>` : `${date}${updated}${releaseVersion}`;
+    const pageDates = changelogEntry ? `<div class="page-meta">${date}${updated}${verified}${releaseVersion}</div>` : `${date}${updated}${verified}${releaseVersion}`;
     const containsCurrent = (item) => item.route === doc.route || !!item.items?.some(containsCurrent);
     const activeTab = navigationTab(navigation, doc.route);
     const analyticsBootstrap = config.analytics ? `<script type="application/json" id="analytics-config">${JSON.stringify({ pageId: doc.frontmatter.id, pageUrl: doc.route, documentType: doc.frontmatter.type, channel: doc.variant.channel, version: doc.variant.version, language: doc.variant.language, ...(activeTab ? { navigationSectionId: activeTab.id } : {}) }).replaceAll('<', '\\u003c')}</script><script type="module" src="/assets/analytics.js"></script>` : '';
@@ -107,7 +108,8 @@ export function buildHtmlPage(doc, tree, markdownUrl, siteTitle, navigation, exa
         return `<li class="nav-entry${deprecated ? ' nav-deprecated' : ''}" data-search="${esc(search)}"${config.readerFilters ? ` data-reader-filters="${esc(readerFilterAttribute(item.readerFilters ?? {}))}"` : ''}><a href="${esc(item.route)}"${item.route === doc.route ? ' aria-current="page"' : ''}>${method}${label}${status}</a></li>`;
     }).join('');
     const readerControls = readerConfig?.controls.sidebar ? readerFilterSlot({ display: 'checks', label: 'Reader view' }, esc) : '';
-    const nav = `<details class="nav-disclosure" open><summary>Menu</summary><div class="nav-body"><a class="region-return" href="#main" data-region-return>Back to article</a><div class="nav-tools"><h2>Explore</h2>${readerControls}<div class="nav-search" hidden><label for="nav-filter">Filter navigation</label><input id="nav-filter" type="search" autocomplete="off"><p class="nav-filter-status" role="status" aria-live="polite"></p></div></div><ul class="nav-tree">${renderNav(sidebarNavigation)}</ul></div></details>`;
+    const heading = navigationHeading(config.outputs);
+    const nav = `<details class="nav-disclosure" open><summary>Menu</summary><div class="nav-body"><a class="region-return" href="#main" data-region-return>Back to article</a><div class="nav-tools">${heading === false ? '' : `<h2>${esc(heading)}</h2>`}${readerControls}<div class="nav-search" hidden><label for="nav-filter">Filter navigation</label><input id="nav-filter" type="search" autocomplete="off"><p class="nav-filter-status" role="status" aria-live="polite"></p></div></div><ul class="nav-tree">${renderNav(sidebarNavigation)}</ul></div></details>`;
     const readerBanner = readerConfig ? '<aside class="reader-outside-view" role="status" hidden></aside>' : '';
     const readerBootstrap = readerConfig ? `<script type="application/json" id="reader-filter-config">${JSON.stringify({ facets: readerConfig.facets, storageKey: `shoalrun-reader-view:${basePath || '/'}`, moduleUrl: readerConfig.module ? sitePath(basePath, '/assets/reader-view-custom.js') : null }).replaceAll('<', '\\u003c')}</script><script type="module" src="/assets/reader-filters.js"></script>` : '';
     const groups = new Map();

package/dist/publication-plan.js

@@ -1,3 +1,4 @@
+import { hasScaffoldPlaceholders } from './scaffold-placeholders.js';
 import { matchesContentFilter } from './content-filter.js';
 import { readdir } from 'node:fs/promises';
 import path from 'node:path';
@@ -60,7 +61,7 @@ export async function planAuthoredDocuments({ base, basePath, config, variants,
         const marks = pageReaderFilters(frontmatter, readerFilters, file);
         if (!matchesContentFilter(marks, contentFilter))
             continue;
-        if (/\[\[TODO:[\s\S]*?\]\]/.test(body) || /\[\[TODO:[\s\S]*?\]\]/.test(JSON.stringify(frontmatter)) || frontmatter.summary?.startsWith('Draft guide for '))
+        if (hasScaffoldPlaceholders(body) || /\[\[TODO:[\s\S]*?\]\]/.test(JSON.stringify(frontmatter)) || frontmatter.summary?.startsWith('Draft guide for '))
             throw new Error(`${file}: unresolved scaffold placeholders cannot be published`);
         for (const variant of variants) {
             if (pagePublications ? !pagePublications.some(item => item.channel === variant.channel && item.version === variant.version) : (frontmatter.channel && frontmatter.channel !== variant.channel || frontmatter.version && frontmatter.version !== variant.version))

package/dist/scaffold-placeholders.d.ts

@@ -0,0 +1,2 @@
+/** Fenced code are teaching examples, not scaffold prose. */
+export declare function hasScaffoldPlaceholders(body: string): boolean;

package/dist/scaffold-placeholders.js

@@ -0,0 +1,19 @@
+import { parse } from './semantic-markdown.js';
+/** Fenced code are teaching examples, not scaffold prose. */
+export function hasScaffoldPlaceholders(body) {
+    const placeholder = /\[\[TODO:[\s\S]*?\]\]/;
+    if (!placeholder.test(body))
+        return false;
+    const ranges = [];
+    const visit = (node) => {
+        if (node.type === 'code' && node.position)
+            ranges.push([node.position.start.offset, node.position.end.offset]);
+        else
+            for (const child of node.children ?? [])
+                visit(child);
+    };
+    visit(parse.parse(body));
+    for (const [start, end] of ranges.sort((a, b) => b[0] - a[0]))
+        body = body.slice(0, start) + ' '.repeat(end - start) + body.slice(end);
+    return placeholder.test(body);
+}

package/dist/section-identity.d.ts

@@ -0,0 +1,24 @@
+/** Section identities are independent of a representation's DOM anchors. */
+export type StandaloneSectionDeclaration = string | {
+    id: string;
+    context: 'section';
+};
+export type SectionIdentity = {
+    id: string;
+    title: string;
+    depth: 2;
+    start: number;
+    end: number;
+    explicit: boolean;
+};
+export declare const validSectionId: (value: unknown) => value is string;
+/** Consume only a direct trailing marker on an authored root H2. Code stays inert. */
+export declare function lowerSectionMarkers(tree: any, label?: string): any;
+export declare function sectionIdentities(tree: any, label?: string): SectionIdentity[];
+export declare function validateStandaloneSectionDeclarations(value: unknown, label?: string): asserts value is StandaloneSectionDeclaration[] | undefined;
+export declare function validateStandaloneSections(tree: any, declarations?: StandaloneSectionDeclaration[], label?: string): SectionIdentity[];
+/** Slice-only delivery is a distinct author approval from contextual discovery. */
+export declare function selectSection(tree: any, id: string, declarations?: StandaloneSectionDeclaration[], label?: string): {
+    section: SectionIdentity;
+    tree: any;
+};