@rathnasgala2/template 2.0.0 → 2.2.0

package/src/core/internal/theme-assets.js

@@ -1,5 +1,5 @@
 /**
- * Theme package asset integration (task packet S2-T12): copy the selected
+ * Theme package asset integration: copy the selected
  * theme package's stylesheets (and any declared passive assets) into the
  * candidate output directory's `<basePath>/assets/theme/`, produce their
  * `manifestAsset` rows, and render the ordered `<link>` elements every
@@ -9,22 +9,25 @@
  * `internal/print-stylesheet.js`'s own module documentation): this module
  * trusts the theme package's own `theme.json` file-set/`cssLayers`/
  * `stylesheets` declarations to the extent needed to *consume* them —
- * closed stylesheet-list shape, `cssLayers` projection matching the
- * published `contracts/theme-styling-contract.jcs`'s `orderedLayers`, and
- * the declared files actually existing. It does **not** re-implement
- * DEC-097's full CSS Syntax Module admission grammar (selector/property/
- * at-rule closed catalogs, byte/token/rule ceilings, etc.) — that is the
- * shared `theme-release.yml` conformance runner's job (S2-T11), run once
- * per theme package release, not per publication build. Authoring real
- * theme CSS is S2-T13's task, forbidden here; this module only moves bytes
- * an already-conformant theme package supplies.
+ * closed stylesheet-list shape and the declared files actually existing.
+ * The `cssLayers`/`stylesheets` pairing itself is fully closed by
+ * `urn:gala:schema:theme-contract:2.0.0`'s own `oneOf` (exactly the two
+ * admitted stylesheet lists, each with its own `const` `cssLayers`
+ * projection), which `assertThemeContractIntegrity` validates before any
+ * file is read, so this module does not re-check that projection itself.
+ * It does **not** re-implement a full CSS Syntax Module admission grammar
+ * (selector/property/at-rule closed catalogs, byte/token/rule ceilings,
+ * etc.) — that is the shared `theme-release.yml` conformance runner's job,
+ * run once per theme package release, not per publication build. Authoring
+ * real theme CSS is out of scope and forbidden here; this module only moves
+ * bytes an already-conformant theme package supplies.
  *
  * The theme package directory this module reads from (`options.themeDirectory`
  * on `renderPublication`) is optional: a caller that does not yet resolve a
- * theme package (e.g. most of this repository's own S2-T02 through S2-T11
- * tests) gets the S2-T08 default — a `<link>` at the fixed conventional
- * `assets/theme/print.css` path, matching `internal/print-stylesheet.js`'s
- * pre-existing convention — so this task's addition is purely additive.
+ * theme package (e.g. most of this repository's own test suite) gets the
+ * default — a `<link>` at the fixed conventional `assets/theme/print.css`
+ * path, matching `internal/print-stylesheet.js`'s pre-existing convention —
+ * so this addition is purely additive.
  *
  * Path-containment hardening (independent-review finding B1): every
  * declared `theme.json` path this module reads — a `stylesheets` entry or a
@@ -50,17 +53,49 @@
  * `<basePath>/assets/theme/<name>` matches the `<link href>` this module
  * also emits. `<link href>` and the physical/manifest path are derived from
  * the exact same joined value, so they cannot drift apart.
+ *
+ * Passive-asset admission (TPL-C2 fix): a declared `theme.json.assets[]` row
+ * is a lower-trust supply-chain input than the repository owner's own
+ * authored content, so it is held to at least the same bar as author media:
+ * its bytes are sniffed with `internal/media/sniff.js` (never trusted from
+ * the declared `mediaType` string), classified against a closed allowlist
+ * (raster formats, or SVG only after {@link sanitizeThemeSvg}'s closed
+ * admission grammar — see that module and TPL-H6's iconography decision),
+ * checked against `theme.json.budgets`'s per-file/total/count ceilings, and
+ * verified byte-for-byte against its own declared `byteLength`/`sha256`
+ * before it is ever copied into a published artifact. The manifest
+ * `mediaType` this module records is always the *sniffed* type, never the
+ * theme's own declaration.
  */
 
+import { createHash } from 'node:crypto';
 import { lstat, readFile } from 'node:fs/promises';
 import path from 'node:path';
 
+import { validateGalaDocument } from '@rathnasgala2/schemas';
+
 import { ThemeAssetError } from '../errors.js';
 import { digestBytes } from './canonical-jcs.js';
-import { ORDERED_LAYERS } from './appearance/styling-contract.js';
+import {
+  buildTemplateStylingContract,
+  TEMPLATE_STYLING_CONTRACT_TEMPLATE_VERSION,
+} from './appearance/styling-contract.js';
+import { MEDIA_TYPE_BY_FORMAT, sniffMediaFormat } from './media/sniff.js';
+import { sanitizeThemeSvg } from './media/theme-svg-sanitizer.js';
 import { projectFixedAssetPath } from './route.js';
+import { satisfiesTemplateRange } from './semver-range.js';
 import { escapeHtml } from './skeleton.js';
 
+/** @type {string} the `urn:gala:schema:theme-contract:2.0.0` schema id
+ * every consumed `theme.json` is validated against (TPL-H1). */
+const THEME_CONTRACT_SCHEMA_ID = 'urn:gala:schema:theme-contract:2.0.0';
+
+/** @type {number} the hard byte ceiling for one passive asset when a
+ * theme's own `theme.json.budgets.maximumFileBytes` is absent or larger
+ * (belt-and-suspenders; every real theme package declares a tighter budget
+ * of its own, enforced below). */
+const DEFAULT_MAXIMUM_PASSIVE_ASSET_BYTES = 262144;
+
 /** @type {string} the fixed, non-content-addressed output directory every
  * theme asset (stylesheet or passive file) is copied under, relative to
  * `basePath`. */
@@ -81,15 +116,6 @@ const STYLESHEETS_WITH_UTILITIES = Object.freeze([
   'print.css',
 ]);
 
-/** @type {Readonly<Record<string, string>>} theme stylesheet filename to its
- * fixed `@layer` name (DEC-097 section 4). */
-const LAYER_BY_STYLESHEET = Object.freeze({
-  'tokens.css': 'gala-tokens',
-  'components.css': 'gala-components',
-  'utilities.css': 'gala-utilities',
-  'print.css': 'gala-print',
-});
-
 /**
  * @param {readonly unknown[]} candidate
  * @returns {void}
@@ -108,38 +134,6 @@ function assertStylesheetListShape(candidate) {
   }
 }
 
-/**
- * @param {readonly unknown[]} stylesheets the already-shape-validated
- *   stylesheet list
- * @param {unknown} cssLayers the candidate `theme.json.cssLayers`
- * @returns {void}
- */
-function assertCssLayersProjection(stylesheets, cssLayers) {
-  const expected = /** @type {readonly string[]} */ (stylesheets).map(
-    (filename) => LAYER_BY_STYLESHEET[/** @type {string} */ (filename)],
-  );
-  if (JSON.stringify(cssLayers) !== JSON.stringify(expected)) {
-    throw new ThemeAssetError(
-      'THEME_CSS_LAYERS_INVALID',
-      'theme.json cssLayers must byte-equal the exact ordered layer ' +
-        'projection of its own stylesheets list',
-    );
-  }
-  if (
-    !expected.every(
-      (layer, index) =>
-        layer === ORDERED_LAYERS[index] ||
-        (layer === 'gala-print' && index === expected.length - 1),
-    )
-  ) {
-    throw new ThemeAssetError(
-      'THEME_CSS_LAYERS_INVALID',
-      'theme.json cssLayers must be a subsequence of the published ' +
-        'templateStylingContract.orderedLayers, in that exact relative order',
-    );
-  }
-}
-
 /** @type {string} the reason code every path-containment rejection below
  * carries. */
 const PATH_CONTAINMENT_CODE = 'THEME_ASSET_PATH_UNSAFE';
@@ -154,7 +148,7 @@ const PATH_CONTAINMENT_CODE = 'THEME_ASSET_PATH_UNSAFE';
  * @returns {string} the same value, once it is known to be a syntactically
  *   safe relative path
  */
-function assertSafeThemeRelativePath(candidate) {
+export function assertSafeThemeRelativePath(candidate) {
   if (typeof candidate !== 'string' || candidate.length === 0) {
     throw new ThemeAssetError(
       PATH_CONTAINMENT_CODE,
@@ -210,7 +204,7 @@ function assertSafeThemeRelativePath(candidate) {
  *   (see {@link assertSafeThemeRelativePath})
  * @returns {Promise<string>} the absolute, verified-contained path
  */
-async function assertContainedThemePath(themeDirectory, relativePath) {
+export async function assertContainedThemePath(themeDirectory, relativePath) {
   const resolvedRoot = path.resolve(themeDirectory);
   let current = resolvedRoot;
   for (const segment of relativePath.split('/')) {
@@ -283,6 +277,201 @@ function joinedThemeOutputPath(basePath, themeRelativePath) {
   );
 }
 
+/**
+ * The public `<link href>` for one theme file: the same joined path as
+ * {@link joinedThemeOutputPath}, but under the public base path.
+ *
+ * @param {string} publicBasePath the public base path
+ * @param {string} themeRelativePath the file's path relative to
+ *   `THEME_ASSET_DIRECTORY`
+ * @returns {string} the root-absolute href
+ */
+function themeHref(publicBasePath, themeRelativePath) {
+  return `/${joinedThemeOutputPath(publicBasePath, themeRelativePath)}`;
+}
+
+/** @type {{maximumFileBytes: number, maximumTotalBytes: number, maximumFiles: number}} */
+const FALLBACK_BUDGETS = Object.freeze({
+  maximumFileBytes: DEFAULT_MAXIMUM_PASSIVE_ASSET_BYTES,
+  maximumTotalBytes: DEFAULT_MAXIMUM_PASSIVE_ASSET_BYTES,
+  maximumFiles: 8,
+});
+
+/**
+ * Parse and validate `theme.json.budgets` (TPL-C2/THD-M3: the declared
+ * ceilings are load-bearing, not decorative). An absent or malformed
+ * `budgets` object falls back to {@link FALLBACK_BUDGETS} rather than
+ * failing closed outright, since a missing budgets object is a shape defect
+ * TPL-H1's schema validation already rejects for a real theme package; this
+ * fallback only matters for this repository's own minimal test fixtures.
+ *
+ * @param {unknown} candidate the parsed `theme.json.budgets` value
+ * @returns {{maximumFileBytes: number, maximumTotalBytes: number, maximumFiles: number}}
+ *   the effective numeric budgets
+ */
+function assertThemeBudgetsShape(candidate) {
+  if (!candidate || typeof candidate !== 'object') {
+    return FALLBACK_BUDGETS;
+  }
+  const row = /** @type {Record<string, unknown>} */ (candidate);
+  const maximumFileBytes = Number(row.maximumFileBytes);
+  const maximumTotalBytes = Number(row.maximumTotalBytes);
+  const maximumFiles = Number(row.maximumFiles);
+  if (
+    !Number.isInteger(maximumFileBytes) ||
+    maximumFileBytes <= 0 ||
+    !Number.isInteger(maximumTotalBytes) ||
+    maximumTotalBytes <= 0 ||
+    !Number.isInteger(maximumFiles) ||
+    maximumFiles <= 0
+  ) {
+    throw new ThemeAssetError(
+      'THEME_ASSET_BUDGET_EXCEEDED',
+      'theme.json.budgets must declare positive integer maximumFileBytes, maximumTotalBytes and maximumFiles',
+    );
+  }
+  return { maximumFileBytes, maximumTotalBytes, maximumFiles };
+}
+
+/**
+ * Verify a declared passive-asset row's own `byteLength`/`sha256` against
+ * the bytes actually read (TPL-C2: the digest chain becomes load-bearing at
+ * consume time, not merely computed and republished).
+ *
+ * @param {{path: string, byteLength?: unknown, sha256?: unknown}} asset the
+ *   declared `theme.json.assets[]` row
+ * @param {Buffer} bytes the bytes actually read from disk
+ * @returns {void}
+ */
+function assertPassiveAssetIntegrity(asset, bytes) {
+  if (
+    asset.byteLength !== undefined &&
+    String(asset.byteLength) !== String(bytes.byteLength)
+  ) {
+    throw new ThemeAssetError(
+      'THEME_ASSET_DIGEST_MISMATCH',
+      `${asset.path}: declared byteLength ${asset.byteLength} does not match ${bytes.byteLength} actual bytes`,
+    );
+  }
+  const actualDigest = digestBytes(bytes);
+  if (asset.sha256 !== undefined && asset.sha256 !== actualDigest) {
+    throw new ThemeAssetError(
+      'THEME_ASSET_DIGEST_MISMATCH',
+      `${asset.path}: declared sha256 does not match its actual bytes (expected ${actualDigest}, got ${asset.sha256})`,
+    );
+  }
+}
+
+/**
+ * Sniff, allowlist and (for SVG) sanitize one passive asset's bytes,
+ * deriving its published `mediaType` from the sniffed format, never from the
+ * theme's own declaration (TPL-C2).
+ *
+ * @param {string} relativePath the declared, already-validated theme-relative
+ *   path (for error messages only)
+ * @param {Buffer} bytes the bytes actually read from disk
+ * @returns {{mediaType: string, publishedBytes: Buffer}} the manifest media
+ *   type and the exact bytes to publish (sanitized, for SVG)
+ */
+function admitPassiveAssetBytes(relativePath, bytes) {
+  const format = sniffMediaFormat(bytes);
+  if (format === 'svg') {
+    // Author SVG is unconditionally rejected (media/sniff.js's own module
+    // documentation); a theme-declared SVG is admitted only after it
+    // survives the closed sanitization grammar below (TPL-H6's iconography
+    // decision: this is the mechanism that makes icon assets safe to ship).
+    return {
+      mediaType: 'image/svg+xml',
+      publishedBytes: sanitizeThemeSvg(bytes),
+    };
+  }
+  const mediaType =
+    format === 'unknown' ? undefined : MEDIA_TYPE_BY_FORMAT[format];
+  if (!mediaType) {
+    throw new ThemeAssetError(
+      'THEME_ASSET_FORMAT_INVALID',
+      `${relativePath}: bytes do not sniff as an admitted passive-asset format (png, jpeg, webp, avif, or sanitizable svg)`,
+    );
+  }
+  return { mediaType, publishedBytes: bytes };
+}
+
+/**
+ * The full TPL-H1 fix: schema-validate the parsed `theme.json` against
+ * `urn:gala:schema:theme-contract:2.0.0` (the same validator this
+ * repository's own tests already use), then make the digest chain and
+ * version negotiation load-bearing rather than parsed-and-ignored:
+ * `contractVersion` must byte-equal this renderer's own published styling
+ * contract version, `stylingContractDigest` must byte-equal that contract's
+ * own `catalogDigest`, and `templateRange` must admit this renderer's own
+ * published version. Fails closed with a {@link ThemeAssetError} on the
+ * first violation.
+ *
+ * @param {Record<string, unknown>} themeJson the parsed `theme.json` document
+ * @returns {void}
+ */
+function assertThemeContractIntegrity(themeJson) {
+  const validation = validateGalaDocument(THEME_CONTRACT_SCHEMA_ID, themeJson);
+  if (!validation.valid) {
+    throw new ThemeAssetError(
+      'THEME_CONTRACT_SCHEMA_INVALID',
+      `theme.json failed urn:gala:schema:theme-contract:2.0.0 validation ` +
+        `(${validation.diagnostics.length} diagnostic(s)): ` +
+        JSON.stringify(validation.diagnostics),
+    );
+  }
+
+  const publishedContract = buildTemplateStylingContract();
+  if (themeJson.contractVersion !== publishedContract.contractVersion) {
+    throw new ThemeAssetError(
+      'THEME_CONTRACT_VERSION_MISMATCH',
+      `theme.json.contractVersion (${themeJson.contractVersion}) does not ` +
+        `byte-equal the published styling contract version ` +
+        `(${publishedContract.contractVersion})`,
+    );
+  }
+  if (themeJson.stylingContractDigest !== publishedContract.catalogDigest) {
+    throw new ThemeAssetError(
+      'THEME_CONTRACT_VERSION_MISMATCH',
+      `theme.json.stylingContractDigest does not byte-equal the published ` +
+        `styling contract's own catalogDigest (this theme was built ` +
+        `against a different template styling contract)`,
+    );
+  }
+  let templateRangeSatisfied;
+  try {
+    templateRangeSatisfied = satisfiesTemplateRange(
+      TEMPLATE_STYLING_CONTRACT_TEMPLATE_VERSION,
+      /** @type {string} */ (themeJson.templateRange),
+    );
+  } catch (error) {
+    throw new ThemeAssetError(
+      'THEME_CONTRACT_VERSION_MISMATCH',
+      `theme.json.templateRange is not admitted: ${/** @type {Error} */ (error).message}`,
+    );
+  }
+  if (!templateRangeSatisfied) {
+    throw new ThemeAssetError(
+      'THEME_CONTRACT_VERSION_MISMATCH',
+      `theme.json.templateRange (${themeJson.templateRange}) does not admit ` +
+        `this renderer's own published version ` +
+        `(${TEMPLATE_STYLING_CONTRACT_TEMPLATE_VERSION})`,
+    );
+  }
+}
+
+/**
+ * TPL-M1 fix: compute a Subresource Integrity attribute value
+ * (`sha256-<base64>`) from exact file bytes, so a theme stylesheet `<link>`
+ * can be verified by the browser itself.
+ *
+ * @param {Buffer} bytes exact file bytes
+ * @returns {string} an `integrity` attribute value, e.g. `sha256-AAAA...`
+ */
+function subresourceIntegrityAttribute(bytes) {
+  return `sha256-${createHash('sha256').update(bytes).digest('base64')}`;
+}
+
 /**
  * Load and validate a selected theme package's `theme.json`, copy its
  * stylesheets (and any declared non-CSS passive assets) into
@@ -295,6 +484,8 @@ function joinedThemeOutputPath(basePath, themeRelativePath) {
  *   file set `theme.json.stylesheets`/`assets` and `package.json.files`
  *   name)
  * @param {string} options.basePath the build input's `basePath`
+ * @param {string} [options.publicBasePath] the base path emitted `<link href>`
+ *   values use (`route.js#derivePublicBasePath`); defaults to `basePath`
  * @returns {Promise<{
  *   files: {path: string, bytes: Buffer}[],
  *   assets: import('../../../types/index.d.ts').ManifestAssetEntry[],
@@ -302,14 +493,20 @@ function joinedThemeOutputPath(basePath, themeRelativePath) {
  * }>} the files to write (already `basePath`-joined), their manifest rows
  *   (same joined paths), and the ready-to-insert `<link>` markup
  */
-export async function loadThemeAssets({ themeDirectory, basePath }) {
+export async function loadThemeAssets({
+  themeDirectory,
+  basePath,
+  publicBasePath = basePath,
+}) {
   const { bytes: themeJsonBytes } = await readDeclaredThemeFile(
     themeDirectory,
     'theme.json',
   );
-  /** @type {{stylesheets: unknown, cssLayers: unknown, assets?: {path: string, mediaType: string}[]}} */
+  /** @type {Record<string, unknown> & {stylesheets: unknown, cssLayers: unknown, assets?: {path: string, mediaType: string, byteLength?: string, sha256?: string}[]}} */
   const themeJson = JSON.parse(themeJsonBytes.toString('utf8'));
 
+  assertThemeContractIntegrity(themeJson);
+
   if (!Array.isArray(themeJson.stylesheets)) {
     throw new ThemeAssetError(
       'THEME_STYLESHEETS_INVALID',
@@ -317,7 +514,6 @@ export async function loadThemeAssets({ themeDirectory, basePath }) {
     );
   }
   assertStylesheetListShape(themeJson.stylesheets);
-  assertCssLayersProjection(themeJson.stylesheets, themeJson.cssLayers);
 
   /** @type {{path: string, bytes: Buffer}[]} */
   const files = [];
@@ -326,11 +522,19 @@ export async function loadThemeAssets({ themeDirectory, basePath }) {
   /** @type {string[]} */
   const linkTags = [];
 
+  const declaredAssetsByPath = new Map(
+    (themeJson.assets ?? []).map((asset) => [asset.path, asset]),
+  );
   for (const filename of /** @type {string[]} */ (themeJson.stylesheets)) {
     const { relativePath, bytes } = await readDeclaredThemeFile(
       themeDirectory,
       filename,
     );
+    // TPL-H1: the schema requires every stylesheet to also carry its own
+    // `assets[]` digest row; verify it here rather than parsing and
+    // ignoring it.
+    const declaredRow = declaredAssetsByPath.get(relativePath);
+    if (declaredRow) assertPassiveAssetIntegrity(declaredRow, bytes);
     const outputPath = joinedThemeOutputPath(basePath, relativePath);
     files.push({ path: outputPath, bytes });
     assets.push({
@@ -341,26 +545,68 @@ export async function loadThemeAssets({ themeDirectory, basePath }) {
       immutable: false,
     });
     const mediaAttribute = filename === 'print.css' ? ' media="print"' : '';
+    // TPL-M1 fix: emit Subresource Integrity so a mutated stylesheet in a
+    // published artifact is detectable by the browser itself, not only by
+    // re-running manifest verification. `digestBytes` returns a hex-prefixed
+    // `sha256:` tag for the manifest; SRI needs the same digest re-encoded as
+    // base64, computed fresh from these exact bytes.
+    const integrity = subresourceIntegrityAttribute(bytes);
     linkTags.push(
-      `<link rel="stylesheet" href="${escapeHtml(`/${outputPath}`)}"${mediaAttribute}>`,
+      `<link rel="stylesheet" href="${escapeHtml(themeHref(publicBasePath, relativePath))}" integrity="${integrity}" crossorigin="anonymous"${mediaAttribute}>`,
     );
   }
 
+  // TPL-M2 fix: partition by the already-shape-validated `stylesheets` list
+  // itself, not by comparing `asset.mediaType` against the literal string
+  // `'text/css'` — a theme declaring its own stylesheet rows with the same
+  // `'text/css; charset=utf-8'` spelling this function's own manifest rows
+  // above use would otherwise be classified as a passive asset and copied a
+  // second time under the same output path.
+  const declaredStylesheetPaths = new Set(themeJson.stylesheets);
   const passiveAssets = (themeJson.assets ?? []).filter(
-    (asset) => asset.mediaType !== 'text/css',
+    (asset) => !declaredStylesheetPaths.has(asset.path),
   );
+
+  const budgets = assertThemeBudgetsShape(themeJson.budgets);
+  let totalPassiveBytes = 0;
+  if (passiveAssets.length > budgets.maximumFiles) {
+    throw new ThemeAssetError(
+      'THEME_ASSET_BUDGET_EXCEEDED',
+      `theme declares ${passiveAssets.length} passive assets, exceeding budgets.maximumFiles (${budgets.maximumFiles})`,
+    );
+  }
+
   for (const asset of passiveAssets) {
     const { relativePath, bytes } = await readDeclaredThemeFile(
       themeDirectory,
       asset.path,
     );
+    assertPassiveAssetIntegrity(asset, bytes);
+    if (bytes.byteLength > budgets.maximumFileBytes) {
+      throw new ThemeAssetError(
+        'THEME_ASSET_BUDGET_EXCEEDED',
+        `${relativePath} is ${bytes.byteLength} bytes, exceeding budgets.maximumFileBytes (${budgets.maximumFileBytes})`,
+      );
+    }
+    totalPassiveBytes += bytes.byteLength;
+    if (totalPassiveBytes > budgets.maximumTotalBytes) {
+      throw new ThemeAssetError(
+        'THEME_ASSET_BUDGET_EXCEEDED',
+        `passive assets total ${totalPassiveBytes} bytes, exceeding budgets.maximumTotalBytes (${budgets.maximumTotalBytes})`,
+      );
+    }
+
+    const { mediaType, publishedBytes } = admitPassiveAssetBytes(
+      relativePath,
+      bytes,
+    );
     const outputPath = joinedThemeOutputPath(basePath, relativePath);
-    files.push({ path: outputPath, bytes });
+    files.push({ path: outputPath, bytes: publishedBytes });
     assets.push({
       path: outputPath,
-      mediaType: asset.mediaType,
-      byteLength: String(bytes.byteLength),
-      sha256: digestBytes(bytes),
+      mediaType,
+      byteLength: String(publishedBytes.byteLength),
+      sha256: digestBytes(publishedBytes),
       immutable: false,
     });
   }
@@ -369,7 +615,7 @@ export async function loadThemeAssets({ themeDirectory, basePath }) {
 }
 
 /**
- * The S2-T08 default theme stylesheet markup, used only when
+ * The default theme stylesheet markup, used only when
  * `renderPublication` is not given a resolved `options.themeDirectory`
  * (this repository's own tests, and any caller that has not yet resolved a
  * theme package): one `media="print"` `<link>` at the fixed conventional

package/src/core/internal/uuid.js

@@ -1,9 +1,8 @@
 /**
- * A minimal RFC 9562 UUIDv7 generator for `artifactId`. DEC-097's
- * `stableId` pattern requires the version nibble `7` and an `8`/`9`/`a`/`b`
- * variant nibble; `node:crypto`'s `randomUUID()` only produces v4. The
- * decision text is explicit that "equal artifact bytes may have distinct
- * artifact IDs" (DEC-097 section 6), so this value is intentionally not
+ * A minimal RFC 9562 UUIDv7 generator for `artifactId`. The `stableId`
+ * pattern requires the version nibble `7` and an `8`/`9`/`a`/`b` variant
+ * nibble; `node:crypto`'s `randomUUID()` only produces v4. Equal artifact
+ * bytes may have distinct artifact IDs, so this value is intentionally not
  * required to be deterministic across two otherwise byte-identical builds.
  */
 

package/types/index.d.ts

@@ -1,9 +1,9 @@
 /**
- * Hand-maintained declaration surface for `@rathnasgala2/template`
- * (DEC-094: JSDoc-typed JavaScript ESM, no TypeScript sources).
+ * Hand-maintained declaration surface for `@rathnasgala2/template`: this
+ * package is JSDoc-typed JavaScript ESM, with no TypeScript sources.
  *
  * Every `build-input:2.0.0` / `artifact-manifest:2.0.0` shape below is a
- * pragmatic subset of DEC-097 section 5/6's exact schemas: it types every
+ * pragmatic subset of the published schemas' exact shapes: it types every
  * field this renderer actually reads or writes, and widens everything else
  * to `unknown`/index signatures rather than re-authoring the full published
  * schema as TypeScript. The `@rathnasgala2/schemas` package (JSON Schema
@@ -222,7 +222,7 @@ export interface ManifestRouteEntry {
   interactionBearing: false;
 }
 
-/** A `manifestAsset`-shaped entry (S2-T05's media pipeline emits one per generated file). */
+/** A `manifestAsset`-shaped entry (the media pipeline emits one per generated file). */
 export interface ManifestAssetEntry {
   path: string;
   mediaType: string;
@@ -269,7 +269,7 @@ export interface ManifestExcludedInputEntry {
 /**
  * Provenance facts the renderer cannot derive from `build-input` alone (see
  * `src/core/manifest.js` module documentation). Supplied by the caller
- * (eventually `publish-kernel`/`publish-action`, S2-T15 through S2-T20).
+ * (eventually `publish-kernel`/`publish-action`).
  */
 export interface RenderProvenance {
   builder: PackageIdentity;
@@ -285,13 +285,13 @@ export interface RenderOptions {
   workDirectory: string;
   /**
    * The caller-mounted, read-only repository source tree that
-   * `build-input`'s `resolvedFile` references (images, fonts) point into
-   * (S2-T05). Must be distinct from `outputDirectory` and `workDirectory`.
+   * `build-input`'s `resolvedFile` references (images, fonts) point into.
+   * Must be distinct from `outputDirectory` and `workDirectory`.
    */
   sourceDirectory: string;
   /**
    * An optional caller-mounted, read-only extracted theme package directory
-   * (S2-T12: `internal/theme-assets.js`). When supplied, its `theme.json`
+   * (`internal/theme-assets.js`). When supplied, its `theme.json`
    * declared stylesheets (and any declared passive assets) are copied into
    * `assets/theme/` and linked from every generated page. Must be distinct
    * from `outputDirectory`, `workDirectory` and `sourceDirectory`.
@@ -345,3 +345,17 @@ export declare function normalizeAuthoredMarkdown(markdownSource: string): {
 
 /** A plain (not domain-separated) tagged SHA-256 digest of a body's exact UTF-8 bytes. */
 export declare function computeBodyDigest(html: string): string;
+
+/**
+ * The current published `renderPolicyIdentity`
+ * (`{name, version, digest}`) every `renderableBody.renderPolicy` must
+ * byte-equal, computed from the published `contracts/render-policy.jcs`
+ * file. A consumer that needs to construct or verify a `renderableBody`
+ * ahead of calling `renderPublication` can compute this identity without
+ * reaching into `src/core/internal/`.
+ */
+export declare function computeRenderPolicyIdentity(): Promise<{
+  name: string;
+  version: string;
+  digest: string;
+}>;