canopycms 0.0.68-int.98 → 0.1.0

package/dist/schema/registry-fingerprint.d.ts

@@ -0,0 +1,14 @@
+import type { EntrySchemaRegistry } from './types.js';
+/**
+ * A sha256 digest of an entry schema registry: equal for registries with equal content, so it
+ * is stable across cold starts of one image, and different when any definition differs.
+ *
+ * Object keys are sorted, so declaration order cannot change it. Every value is tagged with
+ * its type and every string carries its length, so distinct JSON-shaped values never write the
+ * same bytes. A custom field may hold anything, so a function contributes its source text rather
+ * than being dropped the way JSON drops it; any other object is walked by its own enumerable
+ * keys (a Date, Map or Set writes like `{}`), and a value already on the walk's path is written
+ * as a cycle marker rather than recursed into. Memoized per registry object, which the code
+ * builds once.
+ */
+export declare function registryFingerprint(registry: EntrySchemaRegistry): string;

package/dist/schema/registry-fingerprint.js

@@ -0,0 +1,63 @@
+import { createHash } from 'node:crypto';
+const fingerprints = new WeakMap();
+/**
+ * A sha256 digest of an entry schema registry: equal for registries with equal content, so it
+ * is stable across cold starts of one image, and different when any definition differs.
+ *
+ * Object keys are sorted, so declaration order cannot change it. Every value is tagged with
+ * its type and every string carries its length, so distinct JSON-shaped values never write the
+ * same bytes. A custom field may hold anything, so a function contributes its source text rather
+ * than being dropped the way JSON drops it; any other object is walked by its own enumerable
+ * keys (a Date, Map or Set writes like `{}`), and a value already on the walk's path is written
+ * as a cycle marker rather than recursed into. Memoized per registry object, which the code
+ * builds once.
+ */
+export function registryFingerprint(registry) {
+    const memo = fingerprints.get(registry);
+    if (memo)
+        return memo;
+    const hash = createHash('sha256');
+    const ancestors = new Set();
+    const text = (tag, value) => hash.update(`${tag}${value.length}:${value}`);
+    const write = (value) => {
+        switch (typeof value) {
+            case 'string':
+                return void text('s', value);
+            case 'number':
+            case 'bigint':
+            case 'boolean':
+                return void text(typeof value, String(value));
+            case 'undefined':
+                return void hash.update('u');
+            case 'symbol':
+                return void text('y', value.toString());
+            case 'function':
+                return void text('f', Function.prototype.toString.call(value));
+        }
+        if (value === null)
+            return void hash.update('n');
+        const object = value;
+        if (ancestors.has(object))
+            return void hash.update('c');
+        ancestors.add(object);
+        if (Array.isArray(object)) {
+            hash.update(`[${object.length}`);
+            for (const item of object)
+                write(item);
+        }
+        else {
+            const record = object;
+            const keys = Object.keys(record).sort();
+            hash.update(`{${keys.length}`);
+            for (const key of keys) {
+                text('k', key);
+                write(record[key]);
+            }
+        }
+        ancestors.delete(object);
+    };
+    write(registry);
+    const digest = hash.digest('hex');
+    fingerprints.set(registry, digest);
+    return digest;
+}

package/dist/schema/resolver.d.ts

@@ -8,22 +8,25 @@
  * in .collection.json files for reusability and type safety.
  */
 import type { RootCollectionConfig } from '../config/index.js';
-import type { EntrySchemaRegistry, SchemaResolutionResult } from './types.js';
+import type { EntrySchemaRegistry, SchemaResolutionResult, UnknownSchemaPolicy } from './types.js';
 /**
  * Resolve schema from .collection.json files.
  *
  * @param contentRoot - Path to the content directory
  * @param entrySchemaRegistry - Map of entry schema names to field definitions
+ * @param options.unknownSchema - 'throw' (the default) or 'degrade'; see `resolveCollectionMetaFiles`
  * @returns Resolved schema configuration
- * @throws Error if schema references cannot be resolved
+ * @throws Error if schema references cannot be resolved under the 'throw' policy
  */
-export declare function resolveSchema(contentRoot: string, entrySchemaRegistry: EntrySchemaRegistry): Promise<SchemaResolutionResult>;
+export declare function resolveSchema(contentRoot: string, entrySchemaRegistry: EntrySchemaRegistry, options?: {
+    unknownSchema?: UnknownSchemaPolicy;
+}): Promise<SchemaResolutionResult>;
 /**
  * Check if content root has any .collection.json files.
  *
  * @param contentRoot - Path to the content directory
  * @returns true if at least one .collection.json file exists
- * @internal No importer; deletion candidate in knip-no-importer-deletion-candidates.md.
+ * @internal No importer; deletion candidate in safeinsights/canopycms#725.
  */
 export declare function hasSchemaFiles(contentRoot: string): Promise<boolean>;
 /**

package/dist/schema/resolver.js

@@ -7,16 +7,17 @@
  * Field schemas are defined in the entry schema registry and referenced by name
  * in .collection.json files for reusability and type safety.
  */
-import { loadCollectionMetaFiles, resolveCollectionReferences } from './meta-loader.js';
+import { loadCollectionMetaFiles, resolveCollectionMetaFiles } from './meta-loader.js';
 /**
  * Resolve schema from .collection.json files.
  *
  * @param contentRoot - Path to the content directory
  * @param entrySchemaRegistry - Map of entry schema names to field definitions
+ * @param options.unknownSchema - 'throw' (the default) or 'degrade'; see `resolveCollectionMetaFiles`
  * @returns Resolved schema configuration
- * @throws Error if schema references cannot be resolved
+ * @throws Error if schema references cannot be resolved under the 'throw' policy
  */
-export async function resolveSchema(contentRoot, entrySchemaRegistry) {
+export async function resolveSchema(contentRoot, entrySchemaRegistry, options = {}) {
     const metaFiles = await loadCollectionMetaFiles(contentRoot);
     // Build source info for debugging
     const sources = [];
@@ -34,15 +35,15 @@ export async function resolveSchema(contentRoot, entrySchemaRegistry) {
             collections: [collection.name],
         });
     }
-    const schema = resolveCollectionReferences(metaFiles, entrySchemaRegistry);
-    return { schema, sources };
+    const { schema, issues } = resolveCollectionMetaFiles(metaFiles, entrySchemaRegistry, options.unknownSchema ?? 'throw');
+    return { schema, sources, issues };
 }
 /**
  * Check if content root has any .collection.json files.
  *
  * @param contentRoot - Path to the content directory
  * @returns true if at least one .collection.json file exists
- * @internal No importer; deletion candidate in knip-no-importer-deletion-candidates.md.
+ * @internal No importer; deletion candidate in safeinsights/canopycms#725.
  */
 export async function hasSchemaFiles(contentRoot) {
     const metaFiles = await loadCollectionMetaFiles(contentRoot);

package/dist/schema/schema-store.d.ts

@@ -235,15 +235,12 @@ export declare class SchemaOps {
      * why `updateOrderInner` calls `updateCollectionInner` directly instead of
      * the public `updateCollection`.
      *
-     * Phantom-resurrection guard: `branchRoot` can be removed by a concurrent
-     * `deleteBranch` between the caller resolving its BranchContext and this
-     * call's own lock acquisition, which would otherwise let
-     * `withOccFileLock`'s `mkdir({recursive:true})` silently recreate
-     * `.canopy-meta/` in an otherwise-deleted tree. Checking BEFORE the lock
-     * fails fast instead. Residual (accepted, same shape as
-     * branch-metadata.ts's): a call that passes this check can still race a
-     * `deleteBranch` `rm` starting moments later — not closed here either,
-     * since `deleteBranch` never takes this lock (see the module doc comment).
+     * `branchRoot` can be removed by a concurrent `deleteBranch` between the
+     * caller resolving its BranchContext and this call's lock acquisition. The
+     * stat below fails fast before any lock; past it, neither lock recreates a
+     * missing root (each creates only its own directory), so a later removal
+     * fails the acquisition, and any failure on a vanished root is reported as
+     * `SchemaStoreBusyError` below.
      *
      * Translation happens ONLY at this boundary: inner code always sees the
      * raw {@link OccWriteConflictError} bubble up here untranslated, and a
@@ -320,7 +317,7 @@ export declare class SchemaOps {
      * root can re-normalise to the ROOT collection on a second call, mutating
      * the wrong one instead of reporting not-found. Every entry point calls
      * this exactly once today, so the ambiguity is unreachable; see
-     * .claude/future-tasks/collection-path-content-root-ambiguity.md. A future
+     * safeinsights/canopycms#623. A future
      * method that accepts a logical collection path must do the same.
      */
     private normalizeCollectionPath;

package/dist/schema/schema-store.js

@@ -165,15 +165,12 @@ export class SchemaOps {
      * why `updateOrderInner` calls `updateCollectionInner` directly instead of
      * the public `updateCollection`.
      *
-     * Phantom-resurrection guard: `branchRoot` can be removed by a concurrent
-     * `deleteBranch` between the caller resolving its BranchContext and this
-     * call's own lock acquisition, which would otherwise let
-     * `withOccFileLock`'s `mkdir({recursive:true})` silently recreate
-     * `.canopy-meta/` in an otherwise-deleted tree. Checking BEFORE the lock
-     * fails fast instead. Residual (accepted, same shape as
-     * branch-metadata.ts's): a call that passes this check can still race a
-     * `deleteBranch` `rm` starting moments later — not closed here either,
-     * since `deleteBranch` never takes this lock (see the module doc comment).
+     * `branchRoot` can be removed by a concurrent `deleteBranch` between the
+     * caller resolving its BranchContext and this call's lock acquisition. The
+     * stat below fails fast before any lock; past it, neither lock recreates a
+     * missing root (each creates only its own directory), so a later removal
+     * fails the acquisition, and any failure on a vanished root is reported as
+     * `SchemaStoreBusyError` below.
      *
      * Translation happens ONLY at this boundary: inner code always sees the
      * raw {@link OccWriteConflictError} bubble up here untranslated, and a
@@ -219,6 +216,11 @@ export class SchemaOps {
                     ? 'This branch was being synced while the schema change was written, so it may or may not have been recorded. Reload before changing the schema again.'
                     : err.message, err.outcome);
             }
+            // A delete that removes the branch root mid-operation fails it wherever it is (a lock's
+            // mkdir ENOENT, a vanished collection meta); the deletion is the cause, whatever the symptom.
+            const rootGone = await fs.stat(this.branchRoot).then(() => false, (statErr) => isNotFoundError(statErr));
+            if (rootGone)
+                throw new SchemaStoreBusyError('Branch no longer exists');
             throw err;
         }
     }
@@ -302,7 +304,7 @@ export class SchemaOps {
      * root can re-normalise to the ROOT collection on a second call, mutating
      * the wrong one instead of reporting not-found. Every entry point calls
      * this exactly once today, so the ambiguity is unreachable; see
-     * .claude/future-tasks/collection-path-content-root-ambiguity.md. A future
+     * safeinsights/canopycms#623. A future
      * method that accepts a logical collection path must do the same.
      */
     normalizeCollectionPath(collectionPath) {
@@ -578,7 +580,7 @@ export class SchemaOps {
                 // already rules out a `{slug}.{id}` directory at the destination — but that check is
                 // case-SENSITIVE and lets an ID-less `docs/`-style directory through, so a case or
                 // ID-less collision can still slip past it for entries deeper than the index; see
-                // .claude/future-tasks/collection-sibling-name-uniqueness.md.
+                // safeinsights/canopycms#624.
                 if (await findIndexEntryIn(physicalPath)) {
                     // Renaming TO "index" collapses this collection onto its OWN new path, not the
                     // parent's — see url-collision.ts's findUrlPathClaimant for the equivalent create-time

package/dist/schema/schema-unavailable-error.d.ts

@@ -0,0 +1,11 @@
+import type { EntryTypeUnavailable } from '../config/index.js';
+/**
+ * Thrown for an entry whose entry type is `unavailable` (see `EntryTypeConfig.unavailable`):
+ * nothing may be written against a schema the running code does not have. The API answers it
+ * with a retriable 503 (`http/worker-not-ready.ts`), since a deploy usually clears it.
+ */
+export declare class SchemaUnavailableError extends Error {
+    readonly entryType: string;
+    readonly unavailable: EntryTypeUnavailable;
+    constructor(entryType: string, unavailable: EntryTypeUnavailable);
+}

package/dist/schema/schema-unavailable-error.js

@@ -0,0 +1,15 @@
+/**
+ * Thrown for an entry whose entry type is `unavailable` (see `EntryTypeConfig.unavailable`):
+ * nothing may be written against a schema the running code does not have. The API answers it
+ * with a retriable 503 (`http/worker-not-ready.ts`), since a deploy usually clears it.
+ */
+export class SchemaUnavailableError extends Error {
+    constructor(entryType, unavailable) {
+        super(`Entry type "${entryType}" uses a content type this editor version doesn't know yet ` +
+            `("${unavailable.schemaRef}", named in ${unavailable.metaFile}). It usually appears ` +
+            'after the editor finishes updating; reload in a few minutes.');
+        this.name = 'SchemaUnavailableError';
+        this.entryType = entryType;
+        this.unavailable = unavailable;
+    }
+}

package/dist/schema/types.d.ts

@@ -22,4 +22,26 @@ export interface SchemaResolutionResult {
     schema: RootCollectionConfig;
     /** Information about schema sources for debugging */
     sources: SchemaSourceInfo[];
+    /** What a degraded resolve left out; always empty for a strict one. */
+    issues: SchemaIssue[];
 }
+/**
+ * A part of a branch's schema the running code could not resolve, contained rather than thrown
+ * (see `BranchSchemaCache` for where that applies). `unknown-schema` marks one entry type
+ * unavailable; `reference-entry-type` leaves a reference field scoped to a type the content does
+ * not declare, which offers no options until it does.
+ */
+export type SchemaIssue = {
+    kind: 'unknown-schema';
+    /** The collection's path relative to the content root; '' for the root collection. */
+    collectionPath: string;
+    entryType: string;
+    schemaRef: string;
+    metaFile: string;
+    message: string;
+} | {
+    kind: 'reference-entry-type';
+    message: string;
+};
+/** How resolution treats a `.collection.json` naming an entry schema the registry lacks. */
+export type UnknownSchemaPolicy = 'throw' | 'degrade';

package/dist/schema-registry-record.d.ts

@@ -0,0 +1,35 @@
+import { type BuildIdentity } from './build-identity.js';
+import type { CanopyConfig } from './config/index.js';
+import type { EntrySchemaRegistry } from './schema/types.js';
+/** @internal Exported for tests. */
+export declare const SCHEMA_REGISTRY_RECORD = ".schema-registry.json";
+export interface SchemaRegistryRecord {
+    version: 1;
+    /** The registry's keys, sorted: the names a `.collection.json` entry type may reference. */
+    schemas: string[];
+    /** `registryFingerprint` of the registry, which the branch schema cache is also stamped with. */
+    fingerprint: string;
+    /** Content root relative to the repository root, as the editor resolves it. */
+    contentRoot: string;
+    build: BuildIdentity;
+    recordedAt: string;
+}
+/** The record, or undefined when none is recorded or it does not parse. */
+export declare function readSchemaRegistryRecord(contentBranchesRoot: string): Promise<SchemaRegistryRecord | undefined>;
+/**
+ * Record `schemas` unless the record already says the same, by temp file and rename. Does not
+ * create the branches root: a deployment without one has no worker syncing into it.
+ * @internal Exported for tests; `recordServedSchemaRegistry` is the caller.
+ */
+export declare function recordSchemaRegistry(contentBranchesRoot: string, entry: {
+    schemas: readonly string[];
+    fingerprint: string;
+    contentRoot: string;
+    build: BuildIdentity;
+}): Promise<void>;
+/**
+ * Record the registry this process serves, once per process start. A process with an empty
+ * registry speaks for no editor (a config-only handler resolves no schema at all), so it records
+ * nothing rather than make the worker hold every new reference. Best-effort: a failure is logged.
+ */
+export declare function recordServedSchemaRegistry(config: CanopyConfig, registry: EntrySchemaRegistry): Promise<void>;

package/dist/schema-registry-record.js

@@ -0,0 +1,134 @@
+/**
+ * The entry schema registry the serving editor was built with, recorded beside the branch
+ * directories for the worker, which has no adopter config. The worker's git sync holds the base
+ * branch while incoming content names a schema this record lacks (worker/schema-gate.ts), so a
+ * merge that adds a schema and content using it waits for the image carrying the schema.
+ *
+ * Last write wins. Each API process records once, at its first API request, so with one API
+ * deployment per workspace the newest process start names the serving image. An old image
+ * starting during a rollout leaves the record behind, and the gate then holds until the next
+ * new-image start, the safe direction.
+ */
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { readsFromCheckout } from './build-mode.js';
+import { getBuildIdentity } from './build-identity.js';
+import { operatingStrategy } from './operating-mode/index.js';
+import { registryFingerprint } from './schema/registry-fingerprint.js';
+import { getErrorMessage, isNodeError } from './utils/error.js';
+import { canopyLogWarn } from './utils/logger.js';
+/** @internal Exported for tests. */
+export const SCHEMA_REGISTRY_RECORD = '.schema-registry.json';
+function isStringArray(value) {
+    return Array.isArray(value) && value.every((item) => typeof item === 'string');
+}
+function isBuildIdentity(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    if (!('canopycmsVersion' in value) || typeof value.canopycmsVersion !== 'string')
+        return false;
+    return !('sourceRevision' in value) || typeof value.sourceRevision === 'string';
+}
+/** The record, or undefined when none is recorded or it does not parse. */
+export async function readSchemaRegistryRecord(contentBranchesRoot) {
+    let raw;
+    try {
+        raw = await fs.readFile(path.join(contentBranchesRoot, SCHEMA_REGISTRY_RECORD), 'utf8');
+    }
+    catch (err) {
+        if (isNodeError(err) && err.code === 'ENOENT')
+            return undefined;
+        throw err;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return undefined;
+    }
+    if (typeof parsed !== 'object' || parsed === null)
+        return undefined;
+    if (!('version' in parsed) || parsed.version !== 1)
+        return undefined;
+    if (!('schemas' in parsed) || !isStringArray(parsed.schemas))
+        return undefined;
+    if (!('fingerprint' in parsed) || typeof parsed.fingerprint !== 'string')
+        return undefined;
+    if (!('contentRoot' in parsed) || typeof parsed.contentRoot !== 'string')
+        return undefined;
+    if (!('build' in parsed) || !isBuildIdentity(parsed.build))
+        return undefined;
+    if (!('recordedAt' in parsed) || typeof parsed.recordedAt !== 'string')
+        return undefined;
+    return {
+        version: 1,
+        schemas: parsed.schemas,
+        fingerprint: parsed.fingerprint,
+        contentRoot: parsed.contentRoot,
+        build: parsed.build,
+        recordedAt: parsed.recordedAt,
+    };
+}
+function sameRecord(a, b) {
+    return (a.fingerprint === b.fingerprint &&
+        a.contentRoot === b.contentRoot &&
+        a.build.canopycmsVersion === b.build.canopycmsVersion &&
+        a.build.sourceRevision === b.build.sourceRevision);
+}
+/**
+ * Record `schemas` unless the record already says the same, by temp file and rename. Does not
+ * create the branches root: a deployment without one has no worker syncing into it.
+ * @internal Exported for tests; `recordServedSchemaRegistry` is the caller.
+ */
+export async function recordSchemaRegistry(contentBranchesRoot, entry) {
+    const next = { ...entry, schemas: [...entry.schemas].sort() };
+    const current = await readSchemaRegistryRecord(contentBranchesRoot);
+    if (current && sameRecord(current, next))
+        return;
+    const record = {
+        version: 1,
+        ...next,
+        recordedAt: new Date().toISOString(),
+    };
+    const target = path.join(contentBranchesRoot, SCHEMA_REGISTRY_RECORD);
+    const temp = `${target}.${process.pid}.${Math.random().toString(36).slice(2)}.tmp`;
+    try {
+        await fs.writeFile(temp, `${JSON.stringify(record)}\n`, 'utf8');
+    }
+    catch (err) {
+        if (isNodeError(err) && err.code === 'ENOENT')
+            return;
+        throw err;
+    }
+    try {
+        await fs.rename(temp, target);
+    }
+    catch (err) {
+        await fs.unlink(temp).catch(() => { });
+        throw err;
+    }
+}
+/**
+ * Record the registry this process serves, once per process start. A process with an empty
+ * registry speaks for no editor (a config-only handler resolves no schema at all), so it records
+ * nothing rather than make the worker hold every new reference. Best-effort: a failure is logged.
+ */
+export async function recordServedSchemaRegistry(config, registry) {
+    try {
+        if (readsFromCheckout(config))
+            return;
+        const schemas = Object.keys(registry);
+        if (schemas.length === 0)
+            return;
+        await recordSchemaRegistry(operatingStrategy(config.mode).getContentBranchesRoot(config.sourceRoot), {
+            schemas,
+            fingerprint: registryFingerprint(registry),
+            contentRoot: config.contentRoot || 'content',
+            build: getBuildIdentity(),
+        });
+    }
+    catch (err) {
+        canopyLogWarn(`[canopy] Could not record the entry schema registry: ${getErrorMessage(err)}`);
+    }
+}

package/dist/server.d.ts

@@ -105,6 +105,12 @@ export type { RoutableEntry, CollectRoutableEntriesOptions } from './static/inde
  */
 export { findDuplicateUrlPaths } from './static/index.js';
 export type { DuplicateUrlPath } from './static/index.js';
+/**
+ * Find every reference naming no entry — the check a production build runs and fails on unless
+ * `danglingReferences: 'warn'`. Pass an unscoped `listEntries()`.
+ */
+export { findDanglingReferences } from './static/index.js';
+export type { DanglingReference } from './static/index.js';
 /**
  * SEO field extraction and URL shaping, framework-agnostic. `isNoindexEntry` is the single
  * predicate behind both `robots: noindex` and sitemap exclusion.
@@ -126,32 +132,96 @@ export { createAssetStore } from './assets/factory.js';
 /**
  * The five S3/local bucket-prefix strings (`asset-originals/`, `asset-staging/`, `asset-meta/`,
  * `assets/`, `assets/t/`). Exported so server-only consumers outside this package — notably the
- * prod transform Lambda (`packages/canopycms-cdk/lambda/asset-transform`) — build and parse
+ * lazy transform Lambda (`packages/canopycms-cdk/lambda/asset-transform`) — build and parse
  * asset keys through the same constants `S3AssetStore` uses rather than duplicating the strings.
  */
 export { ASSET_PREFIXES, type AssetPrefixes } from './assets/keys.js';
-/** Asset metadata sidecar shape (`asset-meta/{hash32}.json`), written by the finalize pipeline and read by the transform layer (dev-mode emulation and the prod transform Lambda). */
+/** Asset metadata sidecar shape (`asset-meta/{hash32}.json`), written by the finalize pipeline and read by `storeTransform`. */
 export type { AssetMeta } from './assets/types.js';
 /**
  * Parse the three path segments after `assets/t/` (`{directives}/{hash32}/{slug}.{ext}`) into a
- * validated `TransformDirectives` set, or a structured parse error. Reused unchanged by the
- * dev-mode lazy `/assets/t/*` emulation (`api/assets.ts`) and the prod transform Lambda, so the
- * URL grammar is defined in exactly one place.
+ * validated `TransformDirectives` set, or a structured parse error, so the URL grammar is
+ * defined in exactly one place.
  */
 export { parseTransformPath } from './assets/transform-directives.js';
 export type { ParsedTransformPath, ParseTransformPathResult } from './assets/transform-directives.js';
 /**
  * Canonical string form of a `TransformDirectives` set — the cache key every transform output is
  * stored under (`assets/t/{formatDirectives(...)}/{hash32}/{slug}.{ext}`). Equivalent directive
- * sets (different key order or float formatting) always format to the same string. Reused by the
- * prod transform Lambda so its writes agree with the dev-mode emulation and `assetUrl()`.
+ * sets (different key order or float formatting) always format to the same string.
  */
 export { formatDirectives } from './assets/transform-directives.js';
+/**
+ * Parse `assets/t/` path segments and resolve them to the canonical spelling their output is
+ * stored under, with directives re-parsed from that spelling. The lazy transform Lambda 301s a
+ * non-canonical request to it; the authenticated raw route serves the canonical bytes.
+ */
+export { canonicalizeTransformPath } from './assets/transform-directives.js';
+export type { CanonicalTransformPathResult, TransformWidthPolicy, } from './assets/transform-directives.js';
 /**
  * Apply a parsed `TransformDirectives` set to source image bytes with sharp:
  * resize/format/quality/crop, EXIF stripped on every re-encode, identity included. Server-only
- * (sharp); reused unchanged by the dev-mode lazy `/assets/t/*` emulation and the prod transform
- * Lambda.
+ * (sharp); `storeTransform` below wraps it for every caller that stores the output.
  */
 export { applyTransform } from './assets/transform.js';
 export type { ApplyTransformInput, TransformResult } from './assets/transform.js';
+/**
+ * Compute the transform a canonical `assets/t/` path names and store it under that key: meta
+ * lookup, raster-only, slug and ext checks, then `applyTransform`. Shared by the authenticated raw
+ * route, `materialize-assets` and the lazy transform Lambda. A 404's `error` names hashes and
+ * slugs, so a caller answering a browser replaces it.
+ */
+export { storeTransform, type StoreTransformResult } from './assets/materialize.js';
+/** The `Cache-Control` every stored transform output carries: content-addressed, so immutable. */
+export { TRANSFORM_CACHE_CONTROL } from './assets/materialize.js';
+/** The object tag the lazy transform Lambda's outputs carry, which its `assets/t/` expiry filters on. */
+export { LAZY_TRANSFORM_TAG } from './assets/materialize.js';
+/**
+ * Make every `assets/t/` key a build references exist in `store` (transforming only the missing
+ * ones from the stored originals) and check every referenced svg/pdf key exists. Under an
+ * `outputPrefix`, keys are written beneath it, and those production already stores are copied. A
+ * release job that bundles its own tool calls this with a store from `createAssetStore` and gates
+ * on the returned report; no site config is involved. Needs sharp only when something is missing.
+ */
+export { materializeAssets } from './assets/materialize.js';
+/**
+ * The live preview's asset prefix on the server: the signed-in raw route under a `basePath`, the
+ * same-origin check every preview prefix passes, and the hook registering the request-scoped getter
+ * `assetUrl` reads.
+ * @internal `canopycms-next`'s preview page is their consumer.
+ */
+export { authenticatedAssetBase, readAssetBase } from './editor/raw-asset-base.js';
+/** @internal */
+export { setServerPreviewAssetBaseGetter } from './editor/preview-asset-base.js';
+/** The asset store `createAssetStore` returns and `materializeAssets` takes. */
+export type { AssetStore } from './assets/types.js';
+/** What a create-only store write did: `created`, or `already-exists` (the stored object was kept). */
+export type { CreateOnlyResult } from './assets/types.js';
+/** Thrown by `materializeAssets` when sharp cannot load and keys are missing, so none can be produced. */
+export { SharpUnavailableError } from './assets/materialize.js';
+/**
+ * Thrown by `materializeAssets` before any store request when `outputPrefix` is not a relative,
+ * `/`-terminated run of `[A-Za-z0-9._-]` segments outside every canopy prefix.
+ */
+export { InvalidOutputPrefixError } from './assets/materialize.js';
+/** The `schemaVersion` carried by every `MaterializeReport`. */
+export { MATERIALIZE_REPORT_SCHEMA_VERSION } from './assets/materialize.js';
+/** Options for `materializeAssets`: the store, the referenced keys, an output prefix, and concurrency/retry limits. */
+export type { MaterializeOptions } from './assets/materialize.js';
+/** What `materializeAssets` returns: a versioned summary and one result per key, sorted by key. */
+export type { MaterializeReport } from './assets/materialize.js';
+/** One key's outcome in a `MaterializeReport`: `existed`, `created`, `copied` or `failed` (`content` or `store`). */
+export type { MaterializeResult } from './assets/materialize.js';
+/** One key a build references, with the pages and output files that reference it. */
+export type { MaterializeTarget } from './assets/materialize.js';
+/**
+ * Scan a static build's output for `/assets/…` URLs and write `canopy-asset-refs.json` into it.
+ * Throws `AssetRefsError` for a URL no stored object can answer (non-canonical or malformed).
+ */
+export { collectAssetRefs, type CollectAssetRefsResult } from './build/asset-refs.js';
+/** Read and validate a `canopy-asset-refs.json`; throws when it is unreadable or malformed. */
+export { readAssetRefsFile } from './build/asset-refs.js';
+/** Thrown by `collectAssetRefs`; `problems` lists each offending file and URL. */
+export { AssetRefsError } from './build/asset-refs.js';
+/** The shape of `canopy-asset-refs.json`: the transform and static keys a build references. */
+export type { AssetRefsFile } from './build/asset-refs.js';