canopycms 0.0.68-int.108 → 0.0.68-int.109

package/README.md

@@ -442,7 +442,7 @@ export function PostView({ data }: { data: PostContent }) {
 - `data`: The current content data (initial data on first render, then live updates from editor)
 - `isLoading`: Object mirroring your data structure with boolean loading states for reference fields
 - `highlightEnabled`: Boolean indicating if field highlighting is active in the editor
-- `fieldProps`: Helper function to add `data-canopy-path` attributes for editor integration
+- `fieldProps`: marks the element rendering a field (`data-canopy-path`), with the path typed against your content; `fieldAttrs` and `scopeFieldProps` from `canopycms` thread it through section components (see the root README's Live Preview)
 
 **Reference fields and loading states:**
 

package/dist/api/branch-status.js

@@ -39,9 +39,8 @@ const submitBranchForMergeHandler = async (gc, ctx, req, _params) => {
     // (merged) branch could be re-submitted by its creator, re-stamping it
     // 'submitted' and overwriting the merged PR's title/body.
     //
-    // Fails closed on a missing status (branch.json is read with a bare
-    // JSON.parse, no schema validation, so a damaged file can yield
-    // `undefined`) -- same as runWritableBranchGuard's unreadable-status arm.
+    // Fails closed on a missing status, same as runWritableBranchGuard's
+    // unreadable-status arm.
     const status = branchContext.branch.status;
     if (status !== 'editing') {
         return {

package/dist/api/content.d.ts

@@ -104,14 +104,14 @@ export declare const CONTENT_ROUTES: {
         expectedVersion: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
     }, "strip", z.ZodTypeAny, {
         format: "mdx" | "md" | "json" | "yaml";
+        data?: Record<string, unknown> | undefined;
         expectedVersion?: number | null | undefined;
         body?: string | undefined;
-        data?: Record<string, unknown> | undefined;
     }, {
         format: "mdx" | "md" | "json" | "yaml";
+        data?: Record<string, unknown> | undefined;
         expectedVersion?: number | null | undefined;
         body?: string | undefined;
-        data?: Record<string, unknown> | undefined;
     }>, ContentWriteResponse>;
     readonly validateReferences: 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/content.js

@@ -132,7 +132,7 @@ function withoutKey(record, key) {
     return rest;
 }
 /** The policy's issues in the stored entry, which a save may keep. */
-const storedMarkdownSafetyIssues = async (store, collectionPath, slug, fields) => {
+const storedMarkdownSafetyIssues = async (store, collectionPath, slug, fields, siteAllow) => {
     // 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 })
@@ -140,7 +140,7 @@ const storedMarkdownSafetyIssues = async (store, collectionPath, slug, fields) =
     if (doc === undefined)
         return [];
     const data = 'body' in doc ? mergeBodyIntoData(fields, doc.data, doc.body) : doc.data;
-    return findMarkdownSafetyIssues(fields, doc.format, data);
+    return findMarkdownSafetyIssues(fields, doc.format, data, siteAllow);
 };
 const writeContentHandler = async (gc, ctx, req, params, body) => {
     const { branchContext } = gc;
@@ -302,10 +302,11 @@ const writeContentHandler = async (gc, ctx, req, params, 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);
+            const { mdxAllow } = ctx.services.config;
+            const unsafe = findMarkdownSafetyIssues(fields, body.format, dataForValidation, mdxAllow);
             if (unsafe.length > 0) {
                 const stored = exists
-                    ? await storedMarkdownSafetyIssues(store, schemaItem.logicalPath, slug, fields)
+                    ? await storedMarkdownSafetyIssues(store, schemaItem.logicalPath, slug, fields, mdxAllow)
                     : [];
                 const { refused, kept } = splitByStored(unsafe, stored);
                 fieldErrors.push(...refused);
@@ -313,7 +314,7 @@ const writeContentHandler = async (gc, ctx, req, params, body) => {
                     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.`,
+                        message: `holds content this field refuses, kept because the saved entry already had it: ${e.message}. Ask a developer to move it into a component, or to allow it.`,
                     });
                 }
             }

package/dist/api/guards.js

@@ -3,6 +3,8 @@
  * error response (404/403/500) to short-circuit, or produce a guard context (e.g. branch context
  * with schema) for the handler. See api/AGENTS.md for the full guard reference.
  */
+import { BRANCH_METADATA_CORRUPT_MESSAGE, BranchMetadataCorruptError, } from '../branch-metadata-error.js';
+import { canopyLogError } from '../utils/logger.js';
 import { isAdmin, isReviewer, isPrivileged } from '../authorization/helpers.js';
 import { getBranchProtection, getBranchWriteProtection } from '../authorization/protected-branch.js';
 function extractBranchName(params) {
@@ -117,8 +119,8 @@ const runWritableBranchGuard = async (ctx, _req, params, accumulated) => {
         const branchStatus = context.branch.status;
         const error = branchStatus === 'submitted'
             ? `Branch "${context.branch.name}" is submitted for review and cannot be edited. Withdraw it or request changes to resume editing.`
-            : // Unreadable status: branch.json parses without schema validation, so a
-                // damaged file reaches here with no status. Refuse rather than guess.
+            : // A branch.json without a status is refused as corrupt before this
+                // point; a context built elsewhere can still lack one. Refuse rather than guess.
                 branchStatus === undefined
                     ? `Branch "${context.branch.name}" has no readable workflow status and cannot be edited until its metadata is repaired.`
                     : `Branch "${context.branch.name}" is ${branchStatus} and cannot be edited.`;
@@ -196,7 +198,21 @@ export async function executeGuards(guards, ctx, req, params) {
     const accumulated = {};
     for (const guardId of guards) {
         const runner = GUARD_RUNNERS[guardId];
-        const result = await runner(ctx, req, params, accumulated);
+        let result;
+        try {
+            result = await runner(ctx, req, params, accumulated);
+        }
+        catch (err) {
+            // Every branch guard resolves the branch from its branch.json, and a
+            // corrupt one has no status or ACL anyone can trust: deny, whatever the guard.
+            if (!(err instanceof BranchMetadataCorruptError))
+                throw err;
+            canopyLogError(`CanopyCMS: ${err.message}`);
+            return {
+                ok: false,
+                response: { ok: false, status: 500, error: BRANCH_METADATA_CORRUPT_MESSAGE },
+            };
+        }
         if (!result.ok) {
             return { ok: false, response: result.response };
         }

package/dist/api/types.d.ts

@@ -53,6 +53,7 @@ export interface ApiResponse<TData = unknown> {
 }
 /**
  * `SCHEMA_UNAVAILABLE`: the entry's type names an entry schema the running code lacks (a 503,
- * see `SchemaUnavailableError`).
+ * see `SchemaUnavailableError`). `WORKER_FAILED`: the CMS worker recorded that its latest start
+ * failed, so a retry will not help until an admin fixes it (a 503 with no `Retry-After`).
  */
-export type ApiErrorCode = 'SCHEMA_UNAVAILABLE';
+export type ApiErrorCode = 'SCHEMA_UNAVAILABLE' | 'WORKER_FAILED';

package/dist/authorization/protected-branch.d.ts

@@ -76,9 +76,10 @@ export declare function getBranchProtection(config: Pick<CanopyConfig, 'mode' |
  * branches-list wire flag and the editor.
  *
  * `status` is REQUIRED and admits `undefined` because a missing status must
- * FAIL CLOSED: `branch.json` is read with a bare `JSON.parse(...) as
- * BranchMetadataFile` (branch-metadata.ts), so it can be absent at runtime.
- * Required, not optional, so "argument omitted" and "file had no status" stay
- * distinguishable -- the safe answer differs.
+ * FAIL CLOSED. A branch.json without one never gets this far (its read
+ * boundary, branch-metadata-file.ts, rejects it as corrupt), but a status can
+ * still arrive unset from a context built anywhere else. Required, not
+ * optional, so "argument omitted" and "status unknown" stay distinguishable --
+ * the safe answer differs.
  */
 export declare function getBranchWriteProtection(config: Pick<CanopyConfig, 'mode' | 'defaultBaseBranch'>, branchName: string, recordedBaseBranch: string | undefined, status: BranchStatus | undefined): BranchWriteProtection;

package/dist/authorization/protected-branch.js

@@ -47,10 +47,11 @@ export function getBranchProtection(config, branchName, recordedBaseBranch) {
  * branches-list wire flag and the editor.
  *
  * `status` is REQUIRED and admits `undefined` because a missing status must
- * FAIL CLOSED: `branch.json` is read with a bare `JSON.parse(...) as
- * BranchMetadataFile` (branch-metadata.ts), so it can be absent at runtime.
- * Required, not optional, so "argument omitted" and "file had no status" stay
- * distinguishable -- the safe answer differs.
+ * FAIL CLOSED. A branch.json without one never gets this far (its read
+ * boundary, branch-metadata-file.ts, rejects it as corrupt), but a status can
+ * still arrive unset from a context built anywhere else. Required, not
+ * optional, so "argument omitted" and "status unknown" stay distinguishable --
+ * the safe answer differs.
  */
 export function getBranchWriteProtection(config, branchName, recordedBaseBranch, status) {
     const protection = getBranchProtection(config, branchName, recordedBaseBranch);

package/dist/branch-health.js

@@ -100,13 +100,14 @@ export async function scanBranchHealth(baseRoot, opts) {
         }
         if (loadErr) {
             // Every loadOnly failure lands here — BranchMetadataCorruptError for bad
-            // JSON, EACCES/EISDIR and the rest for everything else — since all of
-            // them need admin attention and none may throw out of the scan.
+            // JSON or a failed schema check, EACCES/EISDIR and the rest for
+            // everything else — since all of them need admin attention and none may
+            // throw out of the scan.
             //
             // [REDACT] parseError reaches the browser through the admin branch-health
             // endpoint, so it must never carry the absolute workspace path.
-            // BranchMetadataCorruptError's `parseCause` is the path-free JSON.parse
-            // message for exactly this, while its `message` embeds branchRoot and is
+            // BranchMetadataCorruptError's `parseCause` is the path-free cause
+            // for exactly this, while its `message` embeds branchRoot and is
             // for server logs only. Node errors embed the path in `message` too, so
             // only their `code` is safe to surface.
             const parseError = loadErr instanceof BranchMetadataCorruptError

package/dist/branch-metadata-error.d.ts

@@ -0,0 +1,27 @@
+/**
+ * The corrupt-`branch.json` error and what the API says about it. Free of
+ * node built-ins, so the API guards, which the client bundle reaches, can
+ * recognize the error without pulling in the reader (branch-metadata-file.ts).
+ */
+/** What the editor API answers for a branch whose branch.json is corrupt. */
+export declare const BRANCH_METADATA_CORRUPT_MESSAGE = "This branch's metadata file is damaged, so the branch can't be opened or edited. An admin can repair it in System health.";
+/**
+ * branch.json exists but is not valid JSON, or fails the schema in branch-metadata-file.ts.
+ * Distinguished from provisioning and IO failures so callers can degrade instead
+ * of failing hard: the registry scan quarantines the branch, the API answers
+ * {@link BRANCH_METADATA_CORRUPT_MESSAGE}, and the request handler keeps serving
+ * (with empty internal groups) when the BASE branch is the corrupt one —
+ * otherwise the admin recovery surface is unreachable exactly when it is needed.
+ */
+export declare class BranchMetadataCorruptError extends Error {
+    readonly branchRoot: string;
+    /**
+     * [REDACT] What is wrong with the file, with no embedded path: the JSON.parse
+     * failure, or the fields that failed the schema.
+     * `message` above keeps the `branchRoot`-qualified text for server logs;
+     * `parseCause` is the one callers surface to clients (branch-health.ts's
+     * `parseError`), so no scan leaks the absolute workspace path.
+     */
+    readonly parseCause: string;
+    constructor(branchRoot: string, cause: string);
+}

package/dist/branch-metadata-error.js

@@ -0,0 +1,23 @@
+/**
+ * The corrupt-`branch.json` error and what the API says about it. Free of
+ * node built-ins, so the API guards, which the client bundle reaches, can
+ * recognize the error without pulling in the reader (branch-metadata-file.ts).
+ */
+/** What the editor API answers for a branch whose branch.json is corrupt. */
+export const BRANCH_METADATA_CORRUPT_MESSAGE = "This branch's metadata file is damaged, so the branch can't be opened or edited. An admin can repair it in System health.";
+/**
+ * branch.json exists but is not valid JSON, or fails the schema in branch-metadata-file.ts.
+ * Distinguished from provisioning and IO failures so callers can degrade instead
+ * of failing hard: the registry scan quarantines the branch, the API answers
+ * {@link BRANCH_METADATA_CORRUPT_MESSAGE}, and the request handler keeps serving
+ * (with empty internal groups) when the BASE branch is the corrupt one —
+ * otherwise the admin recovery surface is unreachable exactly when it is needed.
+ */
+export class BranchMetadataCorruptError extends Error {
+    constructor(branchRoot, cause) {
+        super(`Corrupt branch metadata in '${branchRoot}': ${cause}`);
+        this.name = 'BranchMetadataCorruptError';
+        this.branchRoot = branchRoot;
+        this.parseCause = cause;
+    }
+}

package/dist/branch-metadata-file.d.ts

@@ -1,12 +1,16 @@
 /**
  * Reading `branch.json` — the file format, nothing else.
  *
- * Deliberately a LEAF, importing only node built-ins, a type, and the error
- * helper. That is what keeps `branch-registry.ts` (which reads every branch's
+ * Deliberately a LEAF, importing only node built-ins, zod, types, and the error
+ * modules. That is what keeps `branch-registry.ts` (which reads every branch's
  * `branch.json`) out of a runtime import cycle with `branch-metadata.ts` (which
  * writes it and then invalidates the registry cache).
  */
+import { z } from 'zod';
+import type { ContentId } from './paths/types.js';
 import type { BranchMetadata } from './types.js';
+import { BranchMetadataCorruptError } from './branch-metadata-error.js';
+export { BranchMetadataCorruptError };
 export declare const BRANCH_META_DIR = ".canopy-meta";
 export declare const BRANCH_META_FILE = "branch.json";
 export interface BranchMetadataFile {
@@ -15,28 +19,199 @@ export interface BranchMetadataFile {
     writeId?: string;
     branch: BranchMetadata;
 }
+/** The `branch` object, also embedded in the registry snapshot (branch-registry.ts). */
+export declare const branchMetadataSchema: z.ZodObject<{
+    name: z.ZodString;
+    title: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+    status: z.ZodNativeEnum<{
+        editing: "editing";
+        submitted: "submitted";
+        approved: "approved";
+        archived: "archived";
+    }>;
+    access: z.ZodObject<{
+        allowedUsers: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        allowedGroups: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        managerOrAdminAllowed: z.ZodOptional<z.ZodBoolean>;
+    }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+        allowedUsers: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        allowedGroups: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        managerOrAdminAllowed: z.ZodOptional<z.ZodBoolean>;
+    }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+        allowedUsers: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        allowedGroups: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        managerOrAdminAllowed: z.ZodOptional<z.ZodBoolean>;
+    }, z.ZodTypeAny, "passthrough">>;
+    createdBy: z.ZodDefault<z.ZodString>;
+    createdAt: z.ZodDefault<z.ZodString>;
+    updatedAt: z.ZodDefault<z.ZodString>;
+    baseBranch: z.ZodOptional<z.ZodString>;
+    pullRequestUrl: z.ZodOptional<z.ZodString>;
+    pullRequestNumber: z.ZodOptional<z.ZodNumber>;
+    submittedAt: z.ZodOptional<z.ZodString>;
+    pushedToGitHubAt: z.ZodOptional<z.ZodString>;
+    syncStatus: z.ZodOptional<z.ZodNativeEnum<{
+        synced: "synced";
+        "pending-sync": "pending-sync";
+        "sync-failed": "sync-failed";
+    }>>;
+    conflictStatus: z.ZodOptional<z.ZodNativeEnum<{
+        clean: "clean";
+        "conflicts-detected": "conflicts-detected";
+    }>>;
+    conflictFiles: z.ZodOptional<z.ZodArray<z.ZodType<ContentId, z.ZodTypeDef, ContentId>, "many">>;
+    pullRequestState: z.ZodOptional<z.ZodNativeEnum<{
+        open: "open";
+        closed: "closed";
+        merged: "merged";
+    }>>;
+    mergedAt: z.ZodOptional<z.ZodString>;
+    rebaseFailure: z.ZodOptional<z.ZodObject<{
+        message: z.ZodString;
+        firstAt: z.ZodString;
+        lastAt: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        message: string;
+        firstAt: string;
+        lastAt: string;
+    }, {
+        message: string;
+        firstAt: string;
+        lastAt: string;
+    }>>;
+    historyRewrittenFrom: z.ZodOptional<z.ZodString>;
+    syncFailureReason: z.ZodOptional<z.ZodString>;
+}, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+    name: z.ZodString;
+    title: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+    status: z.ZodNativeEnum<{
+        editing: "editing";
+        submitted: "submitted";
+        approved: "approved";
+        archived: "archived";
+    }>;
+    access: z.ZodObject<{
+        allowedUsers: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        allowedGroups: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        managerOrAdminAllowed: z.ZodOptional<z.ZodBoolean>;
+    }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+        allowedUsers: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        allowedGroups: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        managerOrAdminAllowed: z.ZodOptional<z.ZodBoolean>;
+    }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+        allowedUsers: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        allowedGroups: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        managerOrAdminAllowed: z.ZodOptional<z.ZodBoolean>;
+    }, z.ZodTypeAny, "passthrough">>;
+    createdBy: z.ZodDefault<z.ZodString>;
+    createdAt: z.ZodDefault<z.ZodString>;
+    updatedAt: z.ZodDefault<z.ZodString>;
+    baseBranch: z.ZodOptional<z.ZodString>;
+    pullRequestUrl: z.ZodOptional<z.ZodString>;
+    pullRequestNumber: z.ZodOptional<z.ZodNumber>;
+    submittedAt: z.ZodOptional<z.ZodString>;
+    pushedToGitHubAt: z.ZodOptional<z.ZodString>;
+    syncStatus: z.ZodOptional<z.ZodNativeEnum<{
+        synced: "synced";
+        "pending-sync": "pending-sync";
+        "sync-failed": "sync-failed";
+    }>>;
+    conflictStatus: z.ZodOptional<z.ZodNativeEnum<{
+        clean: "clean";
+        "conflicts-detected": "conflicts-detected";
+    }>>;
+    conflictFiles: z.ZodOptional<z.ZodArray<z.ZodType<ContentId, z.ZodTypeDef, ContentId>, "many">>;
+    pullRequestState: z.ZodOptional<z.ZodNativeEnum<{
+        open: "open";
+        closed: "closed";
+        merged: "merged";
+    }>>;
+    mergedAt: z.ZodOptional<z.ZodString>;
+    rebaseFailure: z.ZodOptional<z.ZodObject<{
+        message: z.ZodString;
+        firstAt: z.ZodString;
+        lastAt: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        message: string;
+        firstAt: string;
+        lastAt: string;
+    }, {
+        message: string;
+        firstAt: string;
+        lastAt: string;
+    }>>;
+    historyRewrittenFrom: z.ZodOptional<z.ZodString>;
+    syncFailureReason: z.ZodOptional<z.ZodString>;
+}, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+    name: z.ZodString;
+    title: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+    status: z.ZodNativeEnum<{
+        editing: "editing";
+        submitted: "submitted";
+        approved: "approved";
+        archived: "archived";
+    }>;
+    access: z.ZodObject<{
+        allowedUsers: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        allowedGroups: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        managerOrAdminAllowed: z.ZodOptional<z.ZodBoolean>;
+    }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+        allowedUsers: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        allowedGroups: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        managerOrAdminAllowed: z.ZodOptional<z.ZodBoolean>;
+    }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+        allowedUsers: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        allowedGroups: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        managerOrAdminAllowed: z.ZodOptional<z.ZodBoolean>;
+    }, z.ZodTypeAny, "passthrough">>;
+    createdBy: z.ZodDefault<z.ZodString>;
+    createdAt: z.ZodDefault<z.ZodString>;
+    updatedAt: z.ZodDefault<z.ZodString>;
+    baseBranch: z.ZodOptional<z.ZodString>;
+    pullRequestUrl: z.ZodOptional<z.ZodString>;
+    pullRequestNumber: z.ZodOptional<z.ZodNumber>;
+    submittedAt: z.ZodOptional<z.ZodString>;
+    pushedToGitHubAt: z.ZodOptional<z.ZodString>;
+    syncStatus: z.ZodOptional<z.ZodNativeEnum<{
+        synced: "synced";
+        "pending-sync": "pending-sync";
+        "sync-failed": "sync-failed";
+    }>>;
+    conflictStatus: z.ZodOptional<z.ZodNativeEnum<{
+        clean: "clean";
+        "conflicts-detected": "conflicts-detected";
+    }>>;
+    conflictFiles: z.ZodOptional<z.ZodArray<z.ZodType<ContentId, z.ZodTypeDef, ContentId>, "many">>;
+    pullRequestState: z.ZodOptional<z.ZodNativeEnum<{
+        open: "open";
+        closed: "closed";
+        merged: "merged";
+    }>>;
+    mergedAt: z.ZodOptional<z.ZodString>;
+    rebaseFailure: z.ZodOptional<z.ZodObject<{
+        message: z.ZodString;
+        firstAt: z.ZodString;
+        lastAt: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        message: string;
+        firstAt: string;
+        lastAt: string;
+    }, {
+        message: string;
+        firstAt: string;
+        lastAt: string;
+    }>>;
+    historyRewrittenFrom: z.ZodOptional<z.ZodString>;
+    syncFailureReason: z.ZodOptional<z.ZodString>;
+}, z.ZodTypeAny, "passthrough">>;
 /**
- * branch.json exists but is not valid JSON. Distinguished from provisioning and
- * IO failures so callers can degrade instead of failing hard: the registry scan
- * quarantines the branch, and the request handler keeps serving (with empty
- * internal groups) when the BASE branch is the corrupt one — otherwise the
- * admin recovery surface is unreachable exactly when it is needed.
- */
-export declare class BranchMetadataCorruptError extends Error {
-    readonly branchRoot: string;
-    /**
-     * [REDACT] The raw JSON.parse failure message, with no embedded path.
-     * `message` above keeps the `branchRoot`-qualified text for server logs;
-     * `parseCause` is the one callers surface to clients (branch-health.ts's
-     * `parseError`), so no scan leaks the absolute workspace path.
-     */
-    readonly parseCause: string;
-    constructor(branchRoot: string, cause: string);
-}
-/**
- * Read and parse `branch.json`, with no locking, no OCC and no side effects.
- * Callers distinguish three outcomes: `null` when the file does not exist (an
- * un-provisioned or non-branch directory), `BranchMetadataCorruptError` on
- * malformed JSON, and every other IO failure rethrown unchanged.
+ * Read, parse and validate `branch.json`, with no locking, no OCC and no side
+ * effects. Callers distinguish three outcomes: `null` when the file does not
+ * exist (an un-provisioned or non-branch directory),
+ * `BranchMetadataCorruptError` on malformed JSON or a failed schema check, and
+ * every other IO failure rethrown unchanged.
  */
 export declare function readBranchMetadataFile(branchRoot: string): Promise<BranchMetadataFile | null>;