canopycms 0.0.67 → 0.0.68-int.101

package/dist/reference-resolver.js

@@ -1,46 +1,15 @@
 import nodePath from 'node:path';
 import { extractSlugFromFilename, extractEntryTypeFromFilename } from './content-id-index.js';
+import { entryLogicalPath } from './paths/index.js';
 /**
- * ReferenceResolver resolves content IDs to display values for reference fields.
+ * Loads the options a reference field's picker offers. Resolving a stored reference to its
+ * target is `ContentStore`'s job (`read()`, `resolveReferenceTarget`).
  */
 export class ReferenceResolver {
     constructor(store, idIndex) {
         this.store = store;
         this.idIndex = idIndex;
     }
-    /**
-     * Resolve a content ID to a display value.
-     * Returns null if the ID doesn't exist or points to a collection.
-     */
-    async resolve(id, displayField = 'title') {
-        const location = this.idIndex.findById(id);
-        if (!location || location.type !== 'entry') {
-            return {
-                id,
-                exists: false,
-                displayValue: id, // Fallback to showing the ID itself
-            };
-        }
-        try {
-            const doc = await this.store.read(location.collection, location.slug);
-            const displayValue = String(doc.data[displayField] || doc.data.title || location.slug);
-            return {
-                id,
-                exists: true,
-                displayValue,
-                collection: location.collection,
-                slug: location.slug,
-            };
-        }
-        catch (error) {
-            console.error('Failed to resolve reference:', { id, error });
-            return {
-                id,
-                exists: false,
-                displayValue: id,
-            };
-        }
-    }
     /**
      * Load all available reference options for a reference field.
      *
@@ -48,7 +17,7 @@ export class ReferenceResolver {
      * At least one of `collections` or `entryTypes` should be provided.
      *
      * @param canAccess - Optional permission predicate, called with each candidate's
-     *   relative path before it is read. Returning false skips the entry entirely --
+     *   logical path (`entryLogicalPath`) before it is read. Returning false skips the entry entirely --
      *   no file I/O, no label, no option -- so a caller who can't read a path never
      *   triggers a read for content they won't be allowed to see anyway.
      */
@@ -74,7 +43,7 @@ export class ReferenceResolver {
             if (!location.collection || !location.slug)
                 continue;
             // Skip denied paths before any file I/O.
-            if (canAccess && !canAccess(location.relativePath))
+            if (canAccess && !canAccess(entryLogicalPath(location.collection, location.slug)))
                 continue;
             const id = this.idIndex.findByPath(location.relativePath);
             if (!id)
@@ -82,7 +51,10 @@ export class ReferenceResolver {
             try {
                 const filename = nodePath.basename(location.relativePath);
                 const normalizedSlug = extractSlugFromFilename(filename);
-                const doc = await this.store.read(location.collection, normalizedSlug);
+                // Only the label is read, so the candidate's own references stay unresolved.
+                const doc = await this.store.read(location.collection, normalizedSlug, {
+                    resolveReferences: false,
+                });
                 const label = String(doc.data[displayField] || doc.data.title || normalizedSlug);
                 if (search && !label.toLowerCase().includes(search.toLowerCase())) {
                     continue;
@@ -104,11 +76,4 @@ export class ReferenceResolver {
         }
         return options.sort((a, b) => a.label.localeCompare(b.label));
     }
-    /**
-     * Resolve multiple IDs at once.
-     * Useful for displaying lists of referenced items.
-     */
-    async resolveMany(ids, displayField = 'title') {
-        return Promise.all(ids.map((id) => this.resolve(id, displayField)));
-    }
 }

package/dist/resolve-canopy-user.js

@@ -12,6 +12,7 @@
 import { canopyLogWarn } from './utils/logger.js';
 import { authResultToCanopyUser } from './user.js';
 import { loadInternalGroups, RESERVED_GROUPS } from './authorization/index.js';
+import { timeRequestPhase } from './utils/request-timing.js';
 /** Module-level: warn at most once per process. */
 let warnedNoAdmins = false;
 /**
@@ -39,7 +40,7 @@ function warnIfNoAdmins(internalGroups, bootstrapAdminIds) {
  */
 export async function resolveCanopyUser(authResult, deps) {
     const settingsRoot = await deps.getSettingsBranchRoot();
-    const internalGroups = await loadInternalGroups(settingsRoot, deps.mode, deps.bootstrapAdminIds);
+    const internalGroups = await timeRequestPhase('groups', () => loadInternalGroups(settingsRoot, deps.mode, deps.bootstrapAdminIds));
     warnIfNoAdmins(internalGroups, deps.bootstrapAdminIds);
     return authResultToCanopyUser(authResult, deps.bootstrapAdminIds, internalGroups);
 }

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

@@ -1,6 +1,5 @@
 /**
- * Schema Store - handles reading and writing .collection.json files.
- * All mutations are branch-specific (like content edits).
+ * Schema Store - reads and writes .collection.json files, per branch.
  *
  * ## Concurrency
  *
@@ -16,11 +15,11 @@
  *
  * Protection is instead layer 1 ({@link withLock}) + layer 3
  * ({@link withOccFileLock}) on one COARSE per-branch SURROGATE lock path
- * OUTSIDE the content tree (`{branchRoot}/.canopy-meta/schema`, see
- * `withSchemaLock`), covering every schema mutation on the branch including
- * multi-file ones. Layer 2 (OCC read-back) is skipped, since there's no
- * version field to check; layer 4 (generation marker) guards the schema
- * CACHE separately, not this write path.
+ * OUTSIDE the content tree (`{branchRoot}/.canopy-meta/schema`), covering
+ * every schema mutation including multi-file ones, inside the [SYNC-C1]
+ * content-write lock the worker's rebase also takes (`withBranchSchemaLock`).
+ * Layer 2 (OCC read-back) is skipped, since there's no version field to
+ * check; layer 4 (generation marker) guards the schema CACHE separately.
  *
  * Accepted residual: `deleteBranch` does not take this lock before its
  * recursive `rm`, so an in-flight write can race a concurrent branch
@@ -182,7 +181,30 @@ declare const updateEntryTypeInputSchema: z.ZodObject<{
  * into a 409 so the editor can retry rather than surfacing a raw 400.
  */
 export declare class SchemaStoreBusyError extends Error {
-    constructor(message?: string);
+    /** As on `ContentWriteLockBusyError`: `'unknown'` means the mutation ran and may have landed. */
+    readonly outcome: 'not-run' | 'unknown';
+    constructor(message?: string, 
+    /** As on `ContentWriteLockBusyError`: `'unknown'` means the mutation ran and may have landed. */
+    outcome?: 'not-run' | 'unknown');
+}
+/**
+ * Run `fn` holding every lock a schema mutation needs on `branchRoot`, in the
+ * global order (docs/concurrency.md, "Lock acquisition order"): the branch's
+ * content-write lock, then the `.canopy-meta/schema` surrogate's in-process
+ * mutex, then its lockfile. Shared with `cli/migrate.ts` so the two cannot
+ * drift.
+ *
+ * NOT re-entrant, and nothing inside `fn` may take the content-write lock
+ * (no `ContentStore` writes): proper-lockfile refuses a second acquisition in
+ * the same process, so a nested one burns its wait and fails busy.
+ *
+ * Errors propagate untranslated: `ContentWriteLockBusyError` (contention, or
+ * a compromise reported after `fn` completed) and `OccWriteConflictError`.
+ */
+export declare function withBranchSchemaLock<T>(branchRoot: string, fn: () => Promise<T>, contentWriteLockWaitMs?: number): Promise<T>;
+export interface SchemaOpsOptions {
+    /** Bounded wait for the branch's content-write lock; defaults to `DEFAULT_CONTENT_WRITE_LOCK_WAIT_MS`. */
+    contentWriteLockWaitMs?: number;
 }
 export declare class SchemaOps {
     private readonly contentRoot;
@@ -199,34 +221,35 @@ export declare class SchemaOps {
      * and never match the root collection's logical path).
      */
     private readonly contentRootName;
-    /** Coarse per-branch surrogate lock path — see the module doc comment. */
-    private readonly schemaLockPath;
-    constructor(contentRoot: string, entrySchemaRegistry: EntrySchemaRegistry, services?: CanopyServices | undefined, branchRoot?: string);
+    /** See SchemaOpsOptions.contentWriteLockWaitMs. */
+    private readonly contentWriteLockWaitMs;
+    constructor(contentRoot: string, entrySchemaRegistry: EntrySchemaRegistry, services?: CanopyServices | undefined, branchRoot?: string, options?: SchemaOpsOptions);
     /**
-     * Serialize an entire read-modify-write schema mutation behind the coarse
-     * per-branch surrogate lock described in the module doc comment: layer 1
-     * ({@link withLock}, in-process FIFO mutex) wraps layer 3
-     * ({@link withOccFileLock}, cross-process/cross-host mkdir-based mutual
-     * exclusion, immune to NFS attribute caching), same structure as
-     * `BranchMetadataFileManager.save()` in branch-metadata.ts.
+     * Serialize an entire read-modify-write schema mutation behind
+     * {@link withBranchSchemaLock}: the content-write lock, then the surrogate
+     * ({@link withLock} wrapping {@link withOccFileLock}, as in
+     * `BranchMetadataFileManager.save()`).
      *
      * NOT re-entrant — callers must never invoke this from inside a callback
-     * already running under it, or `withLock` deadlocks waiting on itself;
-     * that's why `updateOrderInner` calls `updateCollectionInner` directly
-     * instead of the public `updateCollection`.
+     * already running under it, or the nested acquisition fails busy; that's
+     * 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.
+     * raw {@link OccWriteConflictError} bubble up here untranslated, and a
+     * {@link ContentWriteLockBusyError} becomes a `SchemaStoreBusyError` with
+     * its message, so every caller's 409 mapping covers both.
+     *
+     * A content-lock compromise is reported after `fn` completed, so the
+     * mutation is on disk while the caller's post-lock `invalidateSchemaCache()`
+     * never runs; this runs it before throwing.
      */
     private withSchemaLock;
     /**
@@ -322,7 +345,7 @@ export declare class SchemaOps {
      * Body of updateCollection, holding the schema lock for its full
      * read-modify-write. Called directly (not via the public `updateCollection`)
      * by `updateOrderInner` for non-root collections — `withSchemaLock` is NOT
-     * re-entrant, so going through the public method there would deadlock.
+     * re-entrant, so going through the public method there would fail busy.
      *
      * `collectionPath` here is always already normalized (content-root prefix
      * stripped, if it had one) by whichever public method reached this — either

package/dist/schema/schema-store.js

@@ -1,6 +1,5 @@
 /**
- * Schema Store - handles reading and writing .collection.json files.
- * All mutations are branch-specific (like content edits).
+ * Schema Store - reads and writes .collection.json files, per branch.
  *
  * ## Concurrency
  *
@@ -16,11 +15,11 @@
  *
  * Protection is instead layer 1 ({@link withLock}) + layer 3
  * ({@link withOccFileLock}) on one COARSE per-branch SURROGATE lock path
- * OUTSIDE the content tree (`{branchRoot}/.canopy-meta/schema`, see
- * `withSchemaLock`), covering every schema mutation on the branch including
- * multi-file ones. Layer 2 (OCC read-back) is skipped, since there's no
- * version field to check; layer 4 (generation marker) guards the schema
- * CACHE separately, not this write path.
+ * OUTSIDE the content tree (`{branchRoot}/.canopy-meta/schema`), covering
+ * every schema mutation including multi-file ones, inside the [SYNC-C1]
+ * content-write lock the worker's rebase also takes (`withBranchSchemaLock`).
+ * Layer 2 (OCC read-back) is skipped, since there's no version field to
+ * check; layer 4 (generation marker) guards the schema CACHE separately.
  *
  * Accepted residual: `deleteBranch` does not take this lock before its
  * recursive `rm`, so an in-flight write can race a concurrent branch
@@ -34,6 +33,7 @@ import { z } from 'zod';
 import { atomicWriteFile } from '../utils/atomic-write.js';
 import { withLock } from '../utils/async-mutex.js';
 import { createDebugLogger } from '../utils/debug.js';
+import { ContentWriteLockBusyError, DEFAULT_CONTENT_WRITE_LOCK_WAIT_MS, withContentWriteLock, } from '../utils/content-write-lock.js';
 import { getErrorMessage, isNotFoundError } from '../utils/error.js';
 import { withOccFileLock, OccWriteConflictError } from '../utils/occ-json-write.js';
 import { resolveCollectionPath } from '../content-id-index.js';
@@ -107,13 +107,34 @@ const log = createDebugLogger({ prefix: 'SchemaOps' });
  * into a 409 so the editor can retry rather than surfacing a raw 400.
  */
 export class SchemaStoreBusyError extends Error {
-    constructor(message = 'Schema is being modified by another operation, try again') {
+    constructor(message = 'Schema is being modified by another operation, try again', 
+    /** As on `ContentWriteLockBusyError`: `'unknown'` means the mutation ran and may have landed. */
+    outcome = 'not-run') {
         super(message);
+        this.outcome = outcome;
         this.name = 'SchemaStoreBusyError';
     }
 }
+/**
+ * Run `fn` holding every lock a schema mutation needs on `branchRoot`, in the
+ * global order (docs/concurrency.md, "Lock acquisition order"): the branch's
+ * content-write lock, then the `.canopy-meta/schema` surrogate's in-process
+ * mutex, then its lockfile. Shared with `cli/migrate.ts` so the two cannot
+ * drift.
+ *
+ * NOT re-entrant, and nothing inside `fn` may take the content-write lock
+ * (no `ContentStore` writes): proper-lockfile refuses a second acquisition in
+ * the same process, so a nested one burns its wait and fails busy.
+ *
+ * Errors propagate untranslated: `ContentWriteLockBusyError` (contention, or
+ * a compromise reported after `fn` completed) and `OccWriteConflictError`.
+ */
+export async function withBranchSchemaLock(branchRoot, fn, contentWriteLockWaitMs = DEFAULT_CONTENT_WRITE_LOCK_WAIT_MS) {
+    const schemaLockPath = path.join(path.resolve(branchRoot), '.canopy-meta', 'schema');
+    return withContentWriteLock(branchRoot, () => withLock(schemaLockPath, () => withOccFileLock(schemaLockPath, fn)), contentWriteLockWaitMs);
+}
 export class SchemaOps {
-    constructor(contentRoot, entrySchemaRegistry, services, branchRoot) {
+    constructor(contentRoot, entrySchemaRegistry, services, branchRoot, options = {}) {
         this.contentRoot = contentRoot;
         this.entrySchemaRegistry = entrySchemaRegistry;
         this.services = services;
@@ -130,33 +151,35 @@ export class SchemaOps {
             .relative(this.branchRoot, resolvedContentRoot)
             .split(path.sep)
             .join('/');
-        this.schemaLockPath = path.join(this.branchRoot, '.canopy-meta', 'schema');
+        this.contentWriteLockWaitMs =
+            options.contentWriteLockWaitMs ?? DEFAULT_CONTENT_WRITE_LOCK_WAIT_MS;
     }
     /**
-     * Serialize an entire read-modify-write schema mutation behind the coarse
-     * per-branch surrogate lock described in the module doc comment: layer 1
-     * ({@link withLock}, in-process FIFO mutex) wraps layer 3
-     * ({@link withOccFileLock}, cross-process/cross-host mkdir-based mutual
-     * exclusion, immune to NFS attribute caching), same structure as
-     * `BranchMetadataFileManager.save()` in branch-metadata.ts.
+     * Serialize an entire read-modify-write schema mutation behind
+     * {@link withBranchSchemaLock}: the content-write lock, then the surrogate
+     * ({@link withLock} wrapping {@link withOccFileLock}, as in
+     * `BranchMetadataFileManager.save()`).
      *
      * NOT re-entrant — callers must never invoke this from inside a callback
-     * already running under it, or `withLock` deadlocks waiting on itself;
-     * that's why `updateOrderInner` calls `updateCollectionInner` directly
-     * instead of the public `updateCollection`.
+     * already running under it, or the nested acquisition fails busy; that's
+     * 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.
+     * raw {@link OccWriteConflictError} bubble up here untranslated, and a
+     * {@link ContentWriteLockBusyError} becomes a `SchemaStoreBusyError` with
+     * its message, so every caller's 409 mapping covers both.
+     *
+     * A content-lock compromise is reported after `fn` completed, so the
+     * mutation is on disk while the caller's post-lock `invalidateSchemaCache()`
+     * never runs; this runs it before throwing.
      */
     async withSchemaLock(fn) {
         try {
@@ -168,13 +191,36 @@ export class SchemaOps {
             }
             throw err;
         }
+        let landed = false;
         try {
-            return await withLock(this.schemaLockPath, () => withOccFileLock(this.schemaLockPath, fn));
+            return await withBranchSchemaLock(this.branchRoot, async () => {
+                const result = await fn();
+                landed = true;
+                return result;
+            }, this.contentWriteLockWaitMs);
         }
         catch (err) {
             if (err instanceof OccWriteConflictError) {
                 throw new SchemaStoreBusyError();
             }
+            if (err instanceof ContentWriteLockBusyError) {
+                if (landed) {
+                    await this.invalidateSchemaCache().catch((invalidateErr) => {
+                        log.warn('schema-cache', 'Invalidation after a lost content-write lock failed', {
+                            branchRoot: this.branchRoot,
+                            error: getErrorMessage(invalidateErr),
+                        });
+                    });
+                }
+                throw new SchemaStoreBusyError(err.outcome === 'unknown'
+                    ? '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;
         }
     }
@@ -461,7 +507,7 @@ export class SchemaOps {
      * Body of updateCollection, holding the schema lock for its full
      * read-modify-write. Called directly (not via the public `updateCollection`)
      * by `updateOrderInner` for non-root collections — `withSchemaLock` is NOT
-     * re-entrant, so going through the public method there would deadlock.
+     * re-entrant, so going through the public method there would fail busy.
      *
      * `collectionPath` here is always already normalized (content-root prefix
      * stripped, if it had one) by whichever public method reached this — either

package/dist/server.d.ts

@@ -126,32 +126,87 @@ 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 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';

package/dist/server.js

@@ -115,28 +115,68 @@ 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 } from './assets/keys.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';
 /**
  * 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';
 /**
  * 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';
+/**
+ * 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 } 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';
+/** 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';
+/**
+ * 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 } 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';

package/dist/services.d.ts

@@ -24,11 +24,16 @@ import { GitManager } from './git-manager.js';
 import { BranchRegistry } from './branch-registry.js';
 import { type GitHubService } from './github-service.js';
 import { BranchSchemaCache } from './branch-schema-cache.js';
+import { type SubmissionEditor } from './submission-attribution.js';
 /**
  * Bootstrap admin IDs from the environment. These users are treated as Admins
  * whatever their group membership.
  */
 export declare const getBootstrapAdminIds: () => Set<string>;
+export interface SubmitBranchResult {
+    /** Repo-relative paths the branch changes, excluding canopycms runtime metadata. */
+    changedPaths: string[];
+}
 export interface CanopyServices {
     config: CanopyConfig;
     /**
@@ -58,27 +63,34 @@ export interface CanopyServices {
     githubService?: GitHubService;
     /** Bootstrap admin user IDs that are always treated as Admins */
     bootstrapAdminIds: Set<string>;
-    /** Commit files to git with automatic author handling */
+    /**
+     * Commit files to git with automatic author handling. Holds the branch's
+     * content-write lock; rejects with `ContentWriteLockBusyError` when busy.
+     */
     commitFiles: (options: {
         context: BranchContext;
         files: string | string[];
         message: string;
     }) => Promise<void>;
-    /** Submit branch: commit all changes and push to remote */
+    /**
+     * Submit branch: commit all changes (with the submitter's trailers) and push
+     * to remote. Resolves with every path the branch changes against its base.
+     * Holds the branch's content-write lock; rejects with
+     * `ContentWriteLockBusyError` when busy.
+     */
     submitBranch: (options: {
         context: BranchContext;
+        submitter?: SubmissionEditor;
         message?: string;
-    }) => Promise<void>;
-    /** Commit to settings branch (for permissions/groups), with optional PR creation */
+    }) => Promise<SubmitBranchResult>;
+    /** Commit to the settings branch (for permissions/groups) and push it; never opens a PR */
     commitToSettingsBranch: (options: {
         branchRoot: string;
         files: string | string[];
         message: string;
-        createPR?: boolean;
     }) => Promise<{
         committed: boolean;
         pushed: boolean;
-        prUrl?: string;
         error?: string;
         syncStatus?: 'pending-sync' | 'synced' | 'sync-failed';
     }>;