canopycms 0.0.68-int.106 → 0.0.68-int.107

package/dist/ai/generate.js

@@ -177,7 +177,7 @@ async function collectEntries(read, collection, cleanPath) {
         if (config?.exclude?.entryTypes?.includes(entryTypeName))
             continue;
         const entryTypeConfig = findEntryType(collection, entryTypeName);
-        if (!entryTypeConfig)
+        if (!entryTypeConfig || entryTypeConfig.unavailable)
             continue;
         try {
             const doc = await store.read(listEntry.collection, listEntry.slug, {

package/dist/api/admin.d.ts

@@ -10,6 +10,7 @@ import type { ApiResponse } from './types.js';
 import type { Task, QueueStats, CorruptTaskFile } from '../task-queue/cms-task-queue.js';
 import type { BuildIdentity, WorkerStatusReport } from '../types.js';
 import type { OperatingMode } from '../operating-mode/index.js';
+import type { SchemaIssue } from '../schema/types.js';
 export type { BranchHealthResponse, PurgeBranchDirResponse, RepairBranchDirResponse, RepairContentDuplicatesResponse, } from './admin-branch-health.js';
 type WorkerLivenessState = 'alive' | 'stale' | 'absent';
 export interface WorkerLiveness {
@@ -37,6 +38,8 @@ export interface AdminStatusData {
      * /admin.
      */
     settingsWorkspaceError?: string;
+    /** What the base branch's schema leaves out under this process's code; absent when nothing. */
+    schemaIssues?: SchemaIssue[];
     /** Build of the API process answering this request. */
     build: BuildIdentity;
     /** Whether `media` is configured; without it every upload returns 501. */

package/dist/api/admin.js

@@ -83,6 +83,24 @@ async function readSettingsWorkspaceError(ctx) {
         return redactCredentials(getErrorMessage(err));
     }
 }
+/**
+ * What the base branch's schema leaves out under this process's registry (see
+ * `BranchSchemaCache`). Empty when the probe cannot resolve it: that failure reaches the
+ * editor through every schema-guarded route anyway.
+ */
+async function readBaseSchemaIssues(ctx) {
+    try {
+        const { config, branchSchemaCache, entrySchemaRegistry } = ctx.services;
+        const base = await ctx.getBranchContext(config.defaultBaseBranch ?? 'main');
+        if (!base)
+            return [];
+        const { issues } = await branchSchemaCache.getSchema(base.branchRoot, entrySchemaRegistry, config.contentRoot || 'content');
+        return issues;
+    }
+    catch {
+        return [];
+    }
+}
 /** Age (ms) of the oldest file in pending/, or undefined if empty/missing. */
 async function getOldestPendingAgeMs(taskDir) {
     const pendingDir = path.join(taskDir, 'pending');
@@ -147,13 +165,14 @@ async function probeImageProcessing() {
 const getAdminStatusHandler = async (_gc, ctx, _req) => {
     const taskDir = getTaskQueueDir(ctx.services.config);
     try {
-        const [queueStats, oldestPendingAgeMs, worker, { workerStatus, statusReadError }, settingsWorkspaceError, imageProcessing,] = await Promise.all([
+        const [queueStats, oldestPendingAgeMs, worker, { workerStatus, statusReadError }, settingsWorkspaceError, imageProcessing, schemaIssues,] = await Promise.all([
             getQueueStats(taskDir),
             getOldestPendingAgeMs(taskDir),
             classifyWorkerLiveness(taskDir),
             readWorkerStatus(taskDir),
             readSettingsWorkspaceError(ctx),
             probeImageProcessing(),
+            readBaseSchemaIssues(ctx),
         ]);
         return {
             ok: true,
@@ -169,6 +188,7 @@ const getAdminStatusHandler = async (_gc, ctx, _req) => {
                 workerStatus,
                 ...(statusReadError ? { statusReadError } : {}),
                 ...(settingsWorkspaceError ? { settingsWorkspaceError } : {}),
+                ...(schemaIssues.length > 0 ? { schemaIssues } : {}),
                 build: getBuildIdentity(),
                 assetStore: { configured: !!ctx.assetStore },
                 imageProcessing,

package/dist/api/content.js

@@ -1,6 +1,7 @@
 import { z } from 'zod';
 import { BranchSyncingError, ContentStore, ContentStoreError, ContentConflictError, DuplicateContentIdError, UrlPathConflictError, getDefaultEntryType, } from '../content-store.js';
 import { defineEndpoint } from './route-builder.js';
+import { SchemaUnavailableError } from '../schema/schema-unavailable-error.js';
 import { ReferenceValidator } from '../validation/reference-validator.js';
 import { findUnknownKeys, mergeBodyIntoData, normalizeReferenceValues, validateEntryData, } from '../validation/entry-validator.js';
 import { validateEntryLinks } from '../validation/entry-link-validator.js';
@@ -210,6 +211,11 @@ const writeContentHandler = async (gc, ctx, req, params, body) => {
         fields = entryTypeConfig?.schema ?? [];
         maxItems = entryTypeConfig?.maxItems;
     }
+    // Refused before validation, which an empty `fields` would wave through; mapped to a 503.
+    const resolvedEntryType = schemaItem.type === 'entry-type' ? schemaItem : entryTypeConfig;
+    if (resolvedEntryType?.unavailable) {
+        throw new SchemaUnavailableError(resolvedEntryType.name, resolvedEntryType.unavailable);
+    }
     const data = body.data ?? {};
     const isDataOnly = isDataOnlyFormat(body.format);
     // The store's own `undefined` (blind write) is never reachable from here: an omitted token is

package/dist/api/entries.js

@@ -202,6 +202,16 @@ const deleteEntryParamsSchema = z.object({
     /** Delete even though other entries reference this one (query param). */
     confirmReferenced: queryBooleanSchema.optional(),
 });
+/** Every entry of an `unavailable` entry type on the branch. */
+const listUnavailableEntries = async (branchRoot, flatSchema) => {
+    const collections = flatSchema.filter((item) => item.type === 'collection' && item.entries?.some((e) => e.unavailable));
+    const listed = await Promise.all(collections.map((collection) => listCollectionEntriesShared(branchRoot, collection)));
+    return listed.flat().filter((item) => {
+        const collection = collections.find((c) => c.logicalPath === item.collectionPath);
+        return (collection?.type === 'collection' &&
+            collection.entries?.some((e) => e.name === item.entryType && e.unavailable));
+    });
+};
 /**
  * Every entry on the branch that references `contentId`, split by whether `user` may read it.
  * A full raw scan of the branch's content: references are stored only on the referencing
@@ -209,7 +219,21 @@ const deleteEntryParamsSchema = z.object({
  */
 const findReferencedBy = async (branchContext, ctx, req, contentId) => {
     const { branchRoot, flatSchema } = branchContext;
-    const entries = await listContentEntries(branchRoot, flatSchema, ctx.services.config.contentRoot || 'content');
+    const listed = await listContentEntries(branchRoot, flatSchema, ctx.services.config.contentRoot || 'content');
+    // listEntries leaves out entries of an unavailable type; scanned raw, they still count.
+    const unavailable = await listUnavailableEntries(branchRoot, flatSchema);
+    const entries = [
+        ...listed,
+        ...unavailable.map((item) => ({
+            entryPath: item.logicalPath,
+            entryId: item.contentId,
+            slug: item.slug,
+            collectionPath: item.collectionPath,
+            entryType: item.entryType,
+            data: item.data,
+            schemaUnavailable: true,
+        })),
+    ];
     const referencing = findReferencingEntries(entries, contentId);
     if (referencing.length === 0)
         return null;
@@ -312,6 +336,8 @@ const deleteEntryHandler = async (gc, ctx, req, params) => {
             error: 'Edit permission required to delete entry',
         };
     }
+    // Before the reference scan, whose 409 would otherwise answer first; mapped to a 503.
+    await contentStore.assertEntryAvailable(collectionLogicalPath, entrySlug);
     let orderCleanupWarning;
     try {
         // Get the entry's content ID before deleting (for order update)

package/dist/api/schema.d.ts

@@ -6,7 +6,7 @@
  */
 import { z } from 'zod';
 import type { ApiResponse } from './types.js';
-import type { ContentFormat, EntrySchema } from '../config/index.js';
+import type { EntryTypeUnavailable, ContentFormat, EntrySchema } from '../config/index.js';
 import { type LogicalPath, type ContentId } from '../paths/index.js';
 /** Entry type in wire format: schemaRef instead of resolved schema */
 interface WireEntryType {
@@ -16,6 +16,7 @@ interface WireEntryType {
     readonly label?: string;
     readonly default?: boolean;
     readonly maxItems?: number;
+    readonly unavailable?: EntryTypeUnavailable;
 }
 /** Collection in wire format (entry types carry schemaRef, not resolved schema) */
 interface WireCollectionConfig {
@@ -52,6 +53,7 @@ type WireFlatSchemaItem = {
     schemaRef: string;
     default?: boolean;
     maxItems?: number;
+    unavailable?: EntryTypeUnavailable;
 };
 interface SchemaResponse {
     flatSchema: WireFlatSchemaItem[];
@@ -339,18 +341,18 @@ export declare const updateEntryType: import("./route-builder.js").RouteDefiniti
     branch: string & {
         readonly __brand: "BranchName";
     };
-    entryTypeName: string;
     collectionPath: string & {
         readonly __brand: "LogicalPath";
     };
+    entryTypeName: string;
 }, {
     branch: string & {
         readonly __brand: "BranchName";
     };
-    entryTypeName: string;
     collectionPath: string & {
         readonly __brand: "LogicalPath";
     };
+    entryTypeName: string;
 }>, z.ZodObject<{
     label: z.ZodOptional<z.ZodString>;
     format: z.ZodOptional<z.ZodEnum<["md", "mdx", "json", "yaml"]>>;
@@ -383,18 +385,18 @@ export declare const removeEntryType: import("./route-builder.js").RouteDefiniti
     branch: string & {
         readonly __brand: "BranchName";
     };
-    entryTypeName: string;
     collectionPath: string & {
         readonly __brand: "LogicalPath";
     };
+    entryTypeName: string;
 }, {
     branch: string & {
         readonly __brand: "BranchName";
     };
-    entryTypeName: string;
     collectionPath: string & {
         readonly __brand: "LogicalPath";
     };
+    entryTypeName: string;
 }>, undefined, RemoveEntryTypeApiResponse>;
 /**
  * PATCH /:branch/schema/order/...collectionPath - Update item order
@@ -616,18 +618,18 @@ export declare const SCHEMA_ROUTES: {
         branch: string & {
             readonly __brand: "BranchName";
         };
-        entryTypeName: string;
         collectionPath: string & {
             readonly __brand: "LogicalPath";
         };
+        entryTypeName: string;
     }, {
         branch: string & {
             readonly __brand: "BranchName";
         };
-        entryTypeName: string;
         collectionPath: string & {
             readonly __brand: "LogicalPath";
         };
+        entryTypeName: string;
     }>, z.ZodObject<{
         label: z.ZodOptional<z.ZodString>;
         format: z.ZodOptional<z.ZodEnum<["md", "mdx", "json", "yaml"]>>;
@@ -655,18 +657,18 @@ export declare const SCHEMA_ROUTES: {
         branch: string & {
             readonly __brand: "BranchName";
         };
-        entryTypeName: string;
         collectionPath: string & {
             readonly __brand: "LogicalPath";
         };
+        entryTypeName: string;
     }, {
         branch: string & {
             readonly __brand: "BranchName";
         };
-        entryTypeName: string;
         collectionPath: string & {
             readonly __brand: "LogicalPath";
         };
+        entryTypeName: string;
     }>, undefined, RemoveEntryTypeApiResponse>;
     readonly updateOrder: import("./route-builder.js").RouteDefinition<z.ZodObject<{
         branch: z.ZodType<import("../paths/index.js").BranchName, z.ZodTypeDef, import("../paths/index.js").BranchName>;

package/dist/api/schema.js

@@ -57,6 +57,7 @@ function toWireEntryType(et, registry) {
         ...(et.label !== undefined && { label: et.label }),
         ...(et.default !== undefined && { default: et.default }),
         ...(et.maxItems !== undefined && { maxItems: et.maxItems }),
+        ...(et.unavailable && { unavailable: et.unavailable }),
     };
 }
 function toWireCollection(col, registry) {
@@ -99,6 +100,7 @@ function toWireFlatSchema(items, registry) {
             schemaRef: resolveSchemaRef(item, registry),
             ...(item.default !== undefined && { default: item.default }),
             ...(item.maxItems !== undefined && { maxItems: item.maxItems }),
+            ...(item.unavailable && { unavailable: item.unavailable }),
         };
     });
 }

package/dist/api/types.d.ts

@@ -48,4 +48,11 @@ export interface ApiResponse<TData = unknown> {
         fieldPath: string;
         message: string;
     }>;
+    /** A machine-readable reason for some failures; see {@link ApiErrorCode}. */
+    code?: ApiErrorCode;
 }
+/**
+ * `SCHEMA_UNAVAILABLE`: the entry's type names an entry schema the running code lacks (a 503,
+ * see `SchemaUnavailableError`).
+ */
+export type ApiErrorCode = 'SCHEMA_UNAVAILABLE';

package/dist/branch-schema-cache.d.ts

@@ -1,7 +1,7 @@
 import type { RootCollectionConfig } from './config/index.js';
 import type { FlatSchemaItem } from './config/types.js';
 import type { OperatingMode } from './operating-mode/index.js';
-import type { EntrySchemaRegistry, SchemaResolutionResult } from './schema/types.js';
+import type { EntrySchemaRegistry, SchemaIssue, SchemaResolutionResult, UnknownSchemaPolicy } from './schema/types.js';
 /** File name of the schema cache inside {@link schemaCacheDir}. */
 export declare const SCHEMA_CACHE_FILE = "schema-cache.json";
 /** resource-generation.ts resource key for the schema cache's marker. */
@@ -18,6 +18,19 @@ export interface BranchSchemaCacheEntry {
      * isGenerationCurrent) to decide freshness.
      */
     generation: string | null;
+    /**
+     * {@link registryFingerprint} of the registry this snapshot was resolved
+     * against. A deploy bumps no marker, so without it a new image would keep
+     * serving schemas resolved by the old image's registry.
+     */
+    registryFingerprint: string;
+    issues: SchemaIssue[];
+}
+/** A branch's resolved schema, plus what a degraded resolve left out of it. */
+export interface ResolvedBranchSchema {
+    schema: RootCollectionConfig;
+    flatSchema: FlatSchemaItem[];
+    issues: SchemaIssue[];
 }
 /**
  * Per-branch schema cache: one file in {@link schemaCacheDir} with no in-memory
@@ -32,6 +45,15 @@ export interface BranchSchemaCacheEntry {
  * Callers that bypass SchemaOps (api/schema.ts's invalidate endpoint, and the
  * bulk git-op bump in invalidateBranchContentCaches) accept the lazy
  * next-read regen instead.
+ *
+ * The owner of the strict/degrade split. Content read from the checkout (a
+ * build, a static deployment) shares a commit with the code, so a schema
+ * reference the registry lacks is a real bug and resolution throws. A branch
+ * workspace's content arrives by sync, which can land before the image whose
+ * registry it needs, or after an image that needs content it lacks; there an
+ * unknown schema marks only its entry type `unavailable`, an unknown reference
+ * `entryTypes` value only empties that field's options, and both are returned
+ * as `issues`.
  */
 export declare class BranchSchemaCache {
     /** Tracks when we last checked mtimes per contentRoot, to debounce rapid requests */
@@ -39,25 +61,23 @@ export declare class BranchSchemaCache {
     private readonly devMode;
     constructor(mode?: OperatingMode);
     /**
-     * Whether to skip the on-disk cache for this branchRoot.
+     * Whether this branchRoot is the checkout rather than a branch workspace,
+     * which skips the on-disk cache and resolves strictly (see the class doc).
      *
      * Never write a schema cache at the project root, whichever entrypoint
      * produced the cwd branchRoot. branchRoot equals process.cwd() only in the
      * synthetic contexts static deployments and build phases use; a real branch
      * root is always nested under the workspace.
      */
-    private skipDiskCache;
+    private readsCheckout;
     /** Get schema for a branch, from the cache when fresh, else resolved fresh. */
-    getSchema(branchRoot: string, entrySchemaRegistry: EntrySchemaRegistry, contentRootName?: string): Promise<{
-        schema: RootCollectionConfig;
-        flatSchema: FlatSchemaItem[];
-    }>;
+    getSchema(branchRoot: string, entrySchemaRegistry: EntrySchemaRegistry, contentRootName?: string): Promise<ResolvedBranchSchema>;
     /**
      * Resolve the schema from disk. Protected rather than a direct resolveSchema
      * call so tests can subclass and block it to simulate cross-process
      * interleavings — mirrors BranchRegistry's scanBranchDirectories() hook.
      */
-    protected resolveFresh(contentRoot: string, entrySchemaRegistry: EntrySchemaRegistry): Promise<SchemaResolutionResult>;
+    protected resolveFresh(contentRoot: string, entrySchemaRegistry: EntrySchemaRegistry, unknownSchema: UnknownSchemaPolicy): Promise<SchemaResolutionResult>;
     private loadFromCacheOrResolve;
     /**
      * Resolve the schema fresh from disk and persist it (subject to the
@@ -75,10 +95,7 @@ export declare class BranchSchemaCache {
      * instead return a snapshot a concurrent host wrote — possibly one embedding
      * the now-current token over ITS own stale-NFS scan — skipping that scan.
      */
-    resolveAndPersist(branchRoot: string, entrySchemaRegistry: EntrySchemaRegistry, contentRootName?: string): Promise<{
-        schema: RootCollectionConfig;
-        flatSchema: FlatSchemaItem[];
-    }>;
+    resolveAndPersist(branchRoot: string, entrySchemaRegistry: EntrySchemaRegistry, contentRootName?: string): Promise<ResolvedBranchSchema>;
     /**
      * Invalidate a branch's cache by bumping the marker; every process sharing
      * this branchRoot re-resolves at its next read. The bump must succeed —

package/dist/branch-schema-cache.js

@@ -1,20 +1,39 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import { resolveSchema, isValidSchema } from './schema/resolver.js';
+import { registryFingerprint } from './schema/registry-fingerprint.js';
 import { flattenSchema } from './config/flatten.js';
 import { validateReferenceEntryTypes } from './validation/entry-type-reference-validator.js';
 import { isBuildMode } from './build-mode.js';
 import { bumpResourceGeneration, readResourceGeneration, isGenerationCurrent, } from './resource-generation.js';
 import { timeRequestPhase } from './utils/request-timing.js';
 import { CANOPY_META_DIR } from './utils/git.js';
+import { canopyLogWarn } from './utils/logger.js';
 /** Bump when BranchSchemaCacheEntry shape changes to auto-invalidate stale caches */
-const SCHEMA_CACHE_VERSION = 3;
+const SCHEMA_CACHE_VERSION = 4;
 /** Minimum interval between mtime staleness checks (ms) */
 const MTIME_CHECK_DEBOUNCE_MS = 1000;
 /** File name of the schema cache inside {@link schemaCacheDir}. */
 export const SCHEMA_CACHE_FILE = 'schema-cache.json';
 /** resource-generation.ts resource key for the schema cache's marker. */
 export const SCHEMA_GENERATION_RESOURCE = 'schema';
+const reportedIssues = new Set();
+/** Log each schema issue once per process, whether it was resolved here or read from a snapshot. */
+function reportSchemaIssues(issues) {
+    for (const issue of issues) {
+        const line = issue.kind === 'unknown-schema'
+            ? `CanopyCMS: ${issue.metaFile} names entry schema "${issue.schemaRef}", which this ` +
+                `deployment's entry schema registry does not define, so entry type ` +
+                `"${issue.entryType}" is unavailable until code defining it is deployed or the ` +
+                `content stops naming it.`
+            : `CanopyCMS: ${issue.message} That reference field offers no options until the ` +
+                `content declares the entry type.`;
+        if (reportedIssues.has(line))
+            continue;
+        reportedIssues.add(line);
+        canopyLogWarn(line);
+    }
+}
 /**
  * True when a .collection.json under `dir` is newer than `cachedAt`.
  *
@@ -73,6 +92,15 @@ async function schemaCacheDir(branchRoot) {
  * Callers that bypass SchemaOps (api/schema.ts's invalidate endpoint, and the
  * bulk git-op bump in invalidateBranchContentCaches) accept the lazy
  * next-read regen instead.
+ *
+ * The owner of the strict/degrade split. Content read from the checkout (a
+ * build, a static deployment) shares a commit with the code, so a schema
+ * reference the registry lacks is a real bug and resolution throws. A branch
+ * workspace's content arrives by sync, which can land before the image whose
+ * registry it needs, or after an image that needs content it lacks; there an
+ * unknown schema marks only its entry type `unavailable`, an unknown reference
+ * `entryTypes` value only empties that field's options, and both are returned
+ * as `issues`.
  */
 export class BranchSchemaCache {
     constructor(mode = 'prod') {
@@ -81,14 +109,15 @@ export class BranchSchemaCache {
         this.devMode = mode === 'dev';
     }
     /**
-     * Whether to skip the on-disk cache for this branchRoot.
+     * Whether this branchRoot is the checkout rather than a branch workspace,
+     * which skips the on-disk cache and resolves strictly (see the class doc).
      *
      * Never write a schema cache at the project root, whichever entrypoint
      * produced the cwd branchRoot. branchRoot equals process.cwd() only in the
      * synthetic contexts static deployments and build phases use; a real branch
      * root is always nested under the workspace.
      */
-    skipDiskCache(branchRoot) {
+    readsCheckout(branchRoot) {
         return isBuildMode() || path.resolve(branchRoot) === path.resolve(process.cwd());
     }
     /** Get schema for a branch, from the cache when fresh, else resolved fresh. */
@@ -100,13 +129,13 @@ export class BranchSchemaCache {
      * call so tests can subclass and block it to simulate cross-process
      * interleavings — mirrors BranchRegistry's scanBranchDirectories() hook.
      */
-    async resolveFresh(contentRoot, entrySchemaRegistry) {
-        return resolveSchema(contentRoot, entrySchemaRegistry);
+    async resolveFresh(contentRoot, entrySchemaRegistry, unknownSchema) {
+        return resolveSchema(contentRoot, entrySchemaRegistry, { unknownSchema });
     }
     async loadFromCacheOrResolve(branchRoot, entrySchemaRegistry, contentRootName) {
         const contentRoot = path.join(branchRoot, contentRootName);
-        const skipDiskCache = this.skipDiskCache(branchRoot);
-        if (!skipDiskCache) {
+        const fromCheckout = this.readsCheckout(branchRoot);
+        if (!fromCheckout) {
             const cachePath = path.join(await schemaCacheDir(branchRoot), SCHEMA_CACHE_FILE);
             let cacheData = null;
             try {
@@ -120,7 +149,9 @@ export class BranchSchemaCache {
             // Strict version check, not truthiness: a snapshot from an older version
             // left on EFS by a rolling deploy has no `generation` field, and an
             // `undefined` token breaks the freshness comparison below.
-            if (cacheData && cacheData.version === SCHEMA_CACHE_VERSION) {
+            if (cacheData &&
+                cacheData.version === SCHEMA_CACHE_VERSION &&
+                cacheData.registryFingerprint === registryFingerprint(entrySchemaRegistry)) {
                 const read = await readResourceGeneration(branchRoot, SCHEMA_GENERATION_RESOURCE);
                 if (isGenerationCurrent(cacheData.generation, read)) {
                     // Dev also walks mtimes, debounced, to catch edits made outside the CMS.
@@ -135,7 +166,12 @@ export class BranchSchemaCache {
                     else {
                         if (this.devMode)
                             this.lastMtimeCheck.set(contentRoot, now);
-                        return { schema: cacheData.schema, flatSchema: cacheData.flatSchema };
+                        reportSchemaIssues(cacheData.issues);
+                        return {
+                            schema: cacheData.schema,
+                            flatSchema: cacheData.flatSchema,
+                            issues: cacheData.issues,
+                        };
                     }
                 }
                 else {
@@ -148,7 +184,7 @@ export class BranchSchemaCache {
             }
         }
         return this.resolveFreshAndPersist(branchRoot, entrySchemaRegistry, contentRootName, {
-            skipDiskCache,
+            fromCheckout,
         });
     }
     /**
@@ -158,32 +194,36 @@ export class BranchSchemaCache {
      * cache-miss fallback and by {@link resolveAndPersist}.
      */
     async resolveFreshAndPersist(branchRoot, entrySchemaRegistry, contentRootName, options) {
-        const { skipDiskCache } = options;
+        const { fromCheckout } = options;
         const contentRoot = path.join(branchRoot, contentRootName);
         // Capture the marker strictly BEFORE resolving, so a bump landing
         // mid-resolve differs from the token persisted below and forces a
         // re-resolve on the next read.
-        const read = skipDiskCache
+        const read = fromCheckout
             ? null
             : await readResourceGeneration(branchRoot, SCHEMA_GENERATION_RESOURCE);
         // Nested under `schema`, so a request summary names a cache miss (`…schema>resolve`).
-        const result = await timeRequestPhase('resolve', () => this.resolveFresh(contentRoot, entrySchemaRegistry));
+        const result = await timeRequestPhase('resolve', () => this.resolveFresh(contentRoot, entrySchemaRegistry, fromCheckout ? 'throw' : 'degrade'));
         // Validate schema has content
         if (!isValidSchema(result.schema)) {
             throw new Error(`No schema found in ${contentRoot}. Create .collection.json files ` +
                 'with references to field schemas defined in your entry schema registry.');
         }
         // Reference fields may only scope themselves to entry types that exist.
-        // Checked here, before anything is cached, so a typo fails loudly and
-        // consistently instead of silently resolving to zero reference options.
+        // Checked here, before anything is cached, so a typo fails a build loudly
+        // instead of silently resolving to zero reference options.
         const entryTypeIssues = validateReferenceEntryTypes(result.schema);
-        if (entryTypeIssues.length > 0) {
+        if (entryTypeIssues.length > 0 && fromCheckout) {
             throw new Error(`Invalid reference field entryTypes in ${contentRoot}:\n` +
                 entryTypeIssues.map((issue) => `  - ${issue}`).join('\n'));
         }
+        const issues = [
+            ...result.issues,
+            ...entryTypeIssues.map((message) => ({ kind: 'reference-entry-type', message })),
+        ];
         // Use configured contentRoot name as base path for logical paths
         const flatSchema = flattenSchema(result.schema, contentRootName);
-        if (!skipDiskCache) {
+        if (!fromCheckout) {
             const cacheDir = await schemaCacheDir(branchRoot);
             const cachePath = path.join(cacheDir, SCHEMA_CACHE_FILE);
             // Opportunistic cleanup of the retired .stale marker file, which a
@@ -196,6 +236,8 @@ export class BranchSchemaCache {
                     flatSchema,
                     cachedAt: new Date().toISOString(),
                     generation: read.token,
+                    registryFingerprint: registryFingerprint(entrySchemaRegistry),
+                    issues,
                 };
                 // Temp file then rename, with the temp file unlinked on a failed
                 // rename so a transient error leaves no stray `.tmp` beside the cache.
@@ -215,7 +257,8 @@ export class BranchSchemaCache {
             // with an unattributable one would look correctly attributed to every
             // future reader. Serve the fresh result without persisting it.
         }
-        return { schema: result.schema, flatSchema };
+        reportSchemaIssues(issues);
+        return { schema: result.schema, flatSchema, issues };
     }
     /**
      * Resolve fresh from disk and persist, SKIPPING the cache read entirely.
@@ -227,9 +270,9 @@ export class BranchSchemaCache {
      * the now-current token over ITS own stale-NFS scan — skipping that scan.
      */
     async resolveAndPersist(branchRoot, entrySchemaRegistry, contentRootName = 'content') {
-        const skipDiskCache = this.skipDiskCache(branchRoot);
+        const fromCheckout = this.readsCheckout(branchRoot);
         return this.resolveFreshAndPersist(branchRoot, entrySchemaRegistry, contentRootName, {
-            skipDiskCache,
+            fromCheckout,
         });
     }
     /**
@@ -241,7 +284,7 @@ export class BranchSchemaCache {
      * No eager re-resolve here; it lives in SchemaOps (see the class doc).
      */
     async invalidate(branchRoot) {
-        if (this.skipDiskCache(branchRoot))
+        if (this.readsCheckout(branchRoot))
             return;
         await bumpResourceGeneration(branchRoot, SCHEMA_GENERATION_RESOURCE, { mustSucceed: true });
     }

package/dist/build/generate-ai-content.js

@@ -181,6 +181,11 @@ export async function generateAIContentFiles(options) {
     else {
         const schemaCache = new BranchSchemaCache(config.mode);
         const cached = await schemaCache.getSchema(branchRoot, entrySchemaRegistry, contentRootName);
+        // A branch workspace resolves degraded (see BranchSchemaCache); a build command fails instead.
+        if (cached.issues.length > 0) {
+            throw new Error(`AI content generation: the schema in ${branchRoot} does not match this code's entry ` +
+                `schema registry:\n${cached.issues.map((issue) => `  - ${issue.message}`).join('\n')}`);
+        }
         flatSchema = cached.flatSchema;
     }
     // Fail the build on abandoned create-scaffolds (schema-invalid entries) rather than baking them