canopycms 0.0.68-int.106 → 0.0.68-int.108

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/branch-status.js

@@ -11,6 +11,7 @@ import { getErrorMessage, redactCredentials, sanitizeErrorMessage } from '../uti
 import { isNonFastForwardRejection } from '../utils/git.js';
 import { ContentWriteLockBusyError } from '../utils/content-write-lock.js';
 import { submissionEditorFromUser } from '../submission-attribution.js';
+import { NothingToSubmitError } from '../services.js';
 const getBranchStatusHandler = async (gc, _ctx, _req, _params) => {
     const { branchContext } = gc;
     return { ok: true, status: 200, data: { branch: branchContext.branch } };
@@ -59,6 +60,9 @@ const submitBranchForMergeHandler = async (gc, ctx, req, _params) => {
         ({ changedPaths } = await ctx.services.submitBranch({ context: branchContext, submitter }));
     }
     catch (err) {
+        if (err instanceof NothingToSubmitError) {
+            return { ok: false, status: 400, error: err.message };
+        }
         // Retriable either way: a resubmit commits nothing new and pushes only
         // what has not reached the remote.
         if (err instanceof ContentWriteLockBusyError) {
@@ -107,13 +111,33 @@ const submitBranchForMergeHandler = async (gc, ctx, req, _params) => {
         };
     }
     // Create or update PR (sync via githubService, or async via task queue)
-    const prResult = await syncSubmitPr(ctx, branchContext, { submitter, changedPaths });
-    // Update metadata with status and PR info
+    const submittedAt = new Date().toISOString();
+    const prResult = await syncSubmitPr(ctx, branchContext, {
+        submitter,
+        changedPaths,
+        submittedAt,
+    });
     const meta = getBranchMetadataFileManager(branchContext.branchRoot, branchContext.baseRoot);
+    const pushed = prResult.pushedToGitHub ? { pushedToGitHubAt: submittedAt } : {};
+    // GitHub found nothing between the pushed branch and its base, though the diff above found
+    // changes: GitHub's base can already hold them, or the diff could not be computed. The branch
+    // stays editable; the stamp records that it is now on GitHub, for delete.
+    if (prResult.nothingToSubmit) {
+        await meta.save({ branch: { name: branchContext.branch.name, ...pushed } });
+        const base = branchContext.branch.baseBranch ?? ctx.services.config.defaultBaseBranch ?? 'main';
+        return {
+            ok: false,
+            status: 400,
+            error: new NothingToSubmitError(branchContext.branch.name, base).message,
+        };
+    }
     const updated = await meta.save({
         branch: {
             name: branchContext.branch.name,
             status: 'submitted',
+            submittedAt,
+            ...pushed,
+            syncFailureReason: prResult.syncFailureReason,
             pullRequestUrl: prResult.prUrl ?? branchContext.branch.pullRequestUrl,
             pullRequestNumber: prResult.prNumber ?? branchContext.branch.pullRequestNumber,
             ...(prResult.syncStatus !== undefined ? { syncStatus: prResult.syncStatus } : {}),

package/dist/api/content.js

@@ -1,14 +1,17 @@
 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';
+import { findMarkdownSafetyIssues, splitByStored } from '../validation/markdown-safety.js';
 import { collectReferenceIds } from '../validation/field-traversal.js';
 import { branchNameSchema, logicalPathSchema, slugSchema } from './validators.js';
 import { entryLogicalPath, parseSlug } from '../paths/index.js';
 import { getErrorMessage, isNotFoundError, sanitizeErrorMessage } from '../utils/error.js';
 import { isDataOnlyFormat } from '../utils/format.js';
+import { findBodyFieldName } from '../utils/body-field.js';
 /**
  * Parse an API path into logical path segments, prepending the content root if needed.
  * Shared by all content API handlers.
@@ -122,6 +125,23 @@ const storedReferenceSites = async (store, collectionPath, slug, fields) => {
     const doc = await store.read(collectionPath, slug, { resolveReferences: false });
     return new Set(collectReferenceIds(fields, doc.data).map((ref) => referenceSite(ref.path, ref.id)));
 };
+function withoutKey(record, key) {
+    if (!(key in record))
+        return record;
+    const { [key]: _dropped, ...rest } = record;
+    return rest;
+}
+/** The policy's issues in the stored entry, which a save may keep. */
+const storedMarkdownSafetyIssues = async (store, collectionPath, slug, fields) => {
+    // A stored file that does not read keeps nothing, so the save's code is refused, not a 500.
+    const doc = await store
+        .read(collectionPath, slug, { resolveReferences: false })
+        .catch(() => undefined);
+    if (doc === undefined)
+        return [];
+    const data = 'body' in doc ? mergeBodyIntoData(fields, doc.data, doc.body) : doc.data;
+    return findMarkdownSafetyIssues(fields, doc.format, data);
+};
 const writeContentHandler = async (gc, ctx, req, params, body) => {
     const { branchContext } = gc;
     const flatSchema = branchContext.flatSchema;
@@ -210,15 +230,25 @@ const writeContentHandler = async (gc, ctx, req, params, body) => {
         fields = entryTypeConfig?.schema ?? [];
         maxItems = entryTypeConfig?.maxItems;
     }
-    const data = body.data ?? {};
+    // 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 isDataOnly = isDataOnlyFormat(body.format);
+    // An md/mdx file's body field is its body, so a frontmatter key of that name is dropped: no
+    // check would see it, and a read or a resolved reference would serve it as the body.
+    const requestData = isDataOnly || body.data === undefined
+        ? body.data
+        : withoutKey(body.data, findBodyFieldName(fields));
+    const data = requestData ?? {};
     // The store's own `undefined` (blind write) is never reachable from here: an omitted token is
     // a create, so an update that lost its token 409s instead of overwriting unchecked.
     const expectedVersion = body.expectedVersion ?? null;
     const createConflictError = body.expectedVersion === null
         ? `An entry with slug "${slug}" already exists`
         : `An entry with slug "${slug}" already exists; an update must send the expectedVersion from its last read`;
-    const danglingWarnings = [];
+    const keptWarnings = [];
     try {
         const exists = await store.documentExists(schemaItem.logicalPath, slug);
         // Create guard: a create against a slug that already has content must never silently
@@ -270,6 +300,23 @@ const writeContentHandler = async (gc, ctx, req, params, body) => {
             // as the schema's isBody field.
             const dataForValidation = isDataOnly ? data : mergeBodyIntoData(fields, data, body.body ?? '');
             const fieldErrors = validateEntryData(fields, dataForValidation);
+            // Code in markdown or MDX (validation/markdown-safety.ts). A field the stored entry held
+            // with code is kept, with a warning, when saved unchanged; any other code is refused.
+            const unsafe = findMarkdownSafetyIssues(fields, body.format, dataForValidation);
+            if (unsafe.length > 0) {
+                const stored = exists
+                    ? await storedMarkdownSafetyIssues(store, schemaItem.logicalPath, slug, fields)
+                    : [];
+                const { refused, kept } = splitByStored(unsafe, stored);
+                fieldErrors.push(...refused);
+                for (const e of kept) {
+                    keptWarnings.push({
+                        level: 'warning',
+                        fieldPath: e.fieldPath,
+                        message: `holds code that runs when the page renders, kept because the saved entry already had it: ${e.message}. Ask a developer to move it into a component.`,
+                    });
+                }
+            }
             // Reference existence (server-only: reads the content ID index). Editor
             // payloads may still carry resolved `{ id, ... }` objects from a prior
             // read, so collapse them to id strings before checking.
@@ -286,7 +333,7 @@ const writeContentHandler = async (gc, ctx, req, params, body) => {
                     : new Set();
                 for (const e of refResult.errors) {
                     if (e.dangling && storedSites.has(referenceSite(e.fieldPath, e.id))) {
-                        danglingWarnings.push({
+                        keptWarnings.push({
                             level: 'warning',
                             fieldPath: e.fieldPath,
                             message: `references a missing entry (${e.id}). It is kept as it was; repoint or clear it.`,
@@ -317,7 +364,7 @@ const writeContentHandler = async (gc, ctx, req, params, body) => {
     // Adopter save-time validation, run BEFORE the file is written: 'error' issues
     // refuse the save (e.g. a body that would break the site's production build),
     // 'warning' issues are returned alongside the successful write.
-    let validationWarnings = danglingWarnings.length > 0 ? danglingWarnings : undefined;
+    let validationWarnings = keptWarnings.length > 0 ? keptWarnings : undefined;
     const validateEntry = ctx.services.config.validateEntry;
     // Collapse resolved reference objects back to bare ID strings before persisting (the reference
     // validator above gets its own copy). The editor's GET resolves references by default, so form
@@ -325,7 +372,7 @@ const writeContentHandler = async (gc, ctx, req, params, body) => {
     // left unnormalized, a save would freeze that snapshot into the file (resolution only
     // re-resolves plain ID strings), permanently severing the reference from its target. Idempotent:
     // a payload that already holds ID strings is unchanged.
-    const normalizedData = body.data === undefined ? undefined : normalizeReferenceValues(fields, body.data);
+    const normalizedData = requestData === undefined ? undefined : normalizeReferenceValues(fields, requestData);
     // Computed before the validateEntry hook and the entry-link scan too, not just the write, so
     // every consumer agrees on the same bytes — otherwise an adopter's hook could see a resolved
     // object while the file got an ID string, depending on whether the post came from the editor.
@@ -360,7 +407,9 @@ const writeContentHandler = async (gc, ctx, req, params, body) => {
             issues = await validateEntry({
                 entryPath: logicalPathSegments.join('/'),
                 branch: params.branch,
-                ...(params.entryType ? { entryType: params.entryType } : {}),
+                // The type the store writes with, so a request that omits `entryType` can't skip a
+                // type-gated rule.
+                ...(entryTypeName ? { entryType: entryTypeName } : {}),
                 format: body.format,
                 data: normalizedData ?? {},
                 body: body.body,

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/github-sync.d.ts

@@ -8,11 +8,19 @@ export interface GitHubSyncResult {
     prUrl?: string;
     prNumber?: number;
     syncStatus?: SyncStatus;
+    /** Client-safe reason a direct GitHub call failed, recorded as the branch's syncFailureReason. */
+    syncFailureReason?: string;
+    /** GitHub refused the PR because the pushed branch has no commits its base lacks. */
+    nothingToSubmit?: boolean;
+    /** The direct path, whose submit pushes to GitHub itself: the branch is there whatever the PR call did. */
+    pushedToGitHub?: boolean;
 }
 /** What the PR body records about a submit. */
 export interface SubmissionRecord {
     submitter?: SubmissionEditor;
     changedPaths: readonly string[];
+    /** The submit's `submittedAt`, carried to the worker so its failure handling targets this submit. */
+    submittedAt?: string;
 }
 /**
  * Uses githubService directly if available, otherwise queues a task for the worker.
@@ -28,9 +36,9 @@ export declare function syncSubmitPr(ctx: ApiContext, context: BranchContext, su
 export declare function syncConvertToDraft(ctx: ApiContext, context: BranchContext): Promise<void>;
 /**
  * Used by delete, after the local delete succeeded. Deletes the branch on GitHub when the CMS
- * put it there: a content branch reaches GitHub only through submit, which always opens a PR,
- * so a recorded PR number is the proof. Without one, a same-named GitHub branch is someone
- * else's (the create-time collision check is best-effort) and is never touched.
+ * put it there: a recorded PR number or `pushedToGitHubAt` stamp is the proof (a submit whose PR
+ * GitHub refused pushed the branch but has no PR number). Without either, a same-named GitHub
+ * branch is someone else's (the create-time collision check is best-effort) and is never touched.
  *
  * Returns a client-facing warning when the delete could not be done or queued; never throws.
  */

package/dist/api/github-sync.js

@@ -1,10 +1,10 @@
 import { enqueueTask } from '../task-queue/cms-task-queue.js';
 import { getTaskQueueDir } from '../task-queue/task-queue-config.js';
 import { clientOperatingStrategy } from '../operating-mode/index.js';
-import { getErrorMessage } from '../utils/error.js';
+import { getErrorMessage, sanitizeErrorMessage } from '../utils/error.js';
 import { sanitizeBranchName } from '../paths/branch-name.js';
 import { buildPrSection, mergePrSection } from '../submission-attribution.js';
-import { isRefAlreadyGoneError } from '../github-service.js';
+import { isNoCommitsBetweenError, isRefAlreadyGoneError } from '../github-service.js';
 /**
  * Uses githubService directly if available, otherwise queues a task for the worker.
  *
@@ -65,6 +65,7 @@ export async function syncSubmitPr(ctx, context, submission) {
                     prUrl: context.branch.pullRequestUrl,
                     prNumber: context.branch.pullRequestNumber,
                     syncStatus: 'synced',
+                    pushedToGitHub: true,
                 };
             }
             else {
@@ -92,16 +93,21 @@ export async function syncSubmitPr(ctx, context, submission) {
                     prUrl: result.url,
                     prNumber: result.number,
                     syncStatus: 'synced',
+                    pushedToGitHub: true,
                 };
             }
         }
         catch (err) {
-            const message = err instanceof Error ? err.message : 'Unknown error';
+            const message = getErrorMessage(err);
             console.error(`CanopyCMS: Failed to create/update PR for ${context.branch.name}:`, message);
+            if (isNoCommitsBetweenError(err))
+                return { nothingToSubmit: true, pushedToGitHub: true };
             return {
                 prUrl: context.branch.pullRequestUrl,
                 prNumber: context.branch.pullRequestNumber,
                 syncStatus: 'sync-failed',
+                syncFailureReason: sanitizeErrorMessage(message),
+                pushedToGitHub: true,
             };
         }
     }
@@ -124,6 +130,7 @@ export async function syncSubmitPr(ctx, context, submission) {
             // A content submit is an explicit "ready for review" action: convert a
             // pre-existing draft PR to ready.
             markReadyIfDraft: true,
+            submittedAt: submission.submittedAt,
         },
     });
 }
@@ -159,14 +166,15 @@ export async function syncConvertToDraft(ctx, context) {
 }
 /**
  * Used by delete, after the local delete succeeded. Deletes the branch on GitHub when the CMS
- * put it there: a content branch reaches GitHub only through submit, which always opens a PR,
- * so a recorded PR number is the proof. Without one, a same-named GitHub branch is someone
- * else's (the create-time collision check is best-effort) and is never touched.
+ * put it there: a recorded PR number or `pushedToGitHubAt` stamp is the proof (a submit whose PR
+ * GitHub refused pushed the branch but has no PR number). Without either, a same-named GitHub
+ * branch is someone else's (the create-time collision check is best-effort) and is never touched.
  *
  * Returns a client-facing warning when the delete could not be done or queued; never throws.
  */
 export async function syncDeleteRemoteBranch(ctx, context) {
-    if (!context.branch.pullRequestNumber)
+    const { pullRequestNumber, pushedToGitHubAt } = context.branch;
+    if (!pullRequestNumber && !pushedToGitHubAt)
         return undefined;
     const { githubService } = ctx.services;
     const branch = context.branch.name;
@@ -187,7 +195,7 @@ export async function syncDeleteRemoteBranch(ctx, context) {
         return undefined;
     const result = await enqueueGitHubTask(ctx, context, {
         action: 'delete-remote-branch',
-        payload: { branch, pullRequestNumber: context.branch.pullRequestNumber },
+        payload: { branch, pullRequestNumber, pushedToGitHubAt },
     });
     return result.syncStatus === 'sync-failed'
         ? 'Deleting the branch on GitHub could not be queued; delete it there by hand'

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-metadata.d.ts

@@ -68,6 +68,12 @@ export declare class BranchMetadataFileManager {
      * creates only its own directory (`withOccFileLock`), so the save fails there.
      */
     save(incoming: BranchMetadataUpdate): Promise<BranchMetadataFile>;
+    /**
+     * {@link save}, applied only when `onlyIf` accepts the metadata on disk; resolves null when it
+     * does not, having written nothing. `onlyIf` runs inside the lock stack against the version
+     * the write is checked against, so the decision and the write are one compare-and-set.
+     */
+    saveIf(incoming: BranchMetadataUpdate, onlyIf: (existing: BranchMetadataFile | null) => boolean): Promise<BranchMetadataFile | null>;
     /** Invalidate the registry cache so the next list() regenerates. */
     private invalidateRegistry;
 }

package/dist/branch-metadata.js

@@ -106,6 +106,17 @@ export class BranchMetadataFileManager {
      * creates only its own directory (`withOccFileLock`), so the save fails there.
      */
     async save(incoming) {
+        const saved = await this.saveIf(incoming, () => true);
+        if (saved === null)
+            throw new Error('unreachable: an unconditional save was skipped');
+        return saved;
+    }
+    /**
+     * {@link save}, applied only when `onlyIf` accepts the metadata on disk; resolves null when it
+     * does not, having written nothing. `onlyIf` runs inside the lock stack against the version
+     * the write is checked against, so the decision and the write are one compare-and-set.
+     */
+    async saveIf(incoming, onlyIf) {
         try {
             await fs.stat(this.branchRoot);
         }
@@ -119,6 +130,8 @@ export class BranchMetadataFileManager {
         try {
             saved = await withLock(this.filePath, () => withOccFileLock(this.filePath, () => withOccRetry(async () => {
                 const { meta: existing, version } = await this.load();
+                if (!onlyIf(existing))
+                    return null;
                 const merged = mergeBranchMetadata(existing, version, incoming);
                 const written = await this.write(merged, version);
                 merged.version = written.version;
@@ -137,7 +150,8 @@ export class BranchMetadataFileManager {
         // does, and the registry's eager regeneration is O(branch count) fs reads
         // on EFS — holding the lock through it would stretch every save's critical
         // section for no correctness gain.
-        await this.invalidateRegistry();
+        if (saved !== null)
+            await this.invalidateRegistry();
         return saved;
     }
     /** Invalidate the registry cache so the next list() regenerates. */