canopycms 0.0.68-int.98 → 0.1.0

package/dist/branch-health.d.ts

@@ -6,13 +6,33 @@ import { type DuplicateContentId } from './content-id-index.js';
  * Without it two stuck states have no in-product recovery, and prod admins have
  * no filesystem access to see them: a branch dir whose `.canopy-meta/branch.json`
  * is corrupt (the registry drops it silently) and an orphan dir with no
- * `branch.json` at all (a partial delete crash — see `api/branch.ts`).
+ * `branch.json` at all (a clone or delete killed in place, until the worker
+ * quarantines it — see branch-provisioning.ts).
  *
  * `scanBranchHealth` mirrors the registry's own directory-listing rules (skip
  * non-directories and dot-prefixed names) so the two never disagree about what
  * counts as missing.
  */
 type BranchHealthKind = 'healthy' | 'corrupt-metadata' | 'orphan';
+/**
+ * An orphan younger than this may still be a clone in progress: admin purge refuses it and the
+ * worker does not quarantine it. Corrupt-metadata dirs are exempt.
+ */
+export declare const ORPHAN_YOUTH_THRESHOLD_MS: number;
+/**
+ * One healthy branch's duplicate-content-ID scan (see content-id-index.ts).
+ * `unknown` means the scan did not finish — it failed, or the request's time
+ * budget ran out first — and must never be read as `none`.
+ */
+export type DuplicateIdScan = {
+    state: 'none';
+} | {
+    state: 'found';
+    duplicates: DuplicateContentId[];
+} | {
+    state: 'unknown';
+    reason: 'failed' | 'out-of-time';
+};
 export interface BranchHealthEntry {
     dirName: string;
     kind: BranchHealthKind;
@@ -21,19 +41,19 @@ export interface BranchHealthEntry {
     /** healthy only */
     branch?: BranchMetadata;
     /**
-     * healthy only, non-empty only: duplicate content IDs in this branch's
-     * content tree (see content-id-index.ts). The branch stays usable — only the
-     * quarantined IDs degrade, dropping out of ID-based lookups and refusing
-     * saves (`DuplicateContentIdError`, a 409 naming the repair action) rather
-     * than mutating an ambiguous target.
+     * healthy only, and only when the caller asked for the duplicate-ID scan: see
+     * {@link DuplicateIdScan}. The branch stays usable while IDs are duplicated —
+     * only the quarantined IDs degrade, dropping out of ID-based lookups and
+     * refusing saves (`DuplicateContentIdError`) rather than mutating an
+     * ambiguous target.
      */
-    duplicateContentIds?: DuplicateContentId[];
+    duplicateIdScan?: DuplicateIdScan;
     /**
      * healthy only, true only: this clone has an interrupted rebase on disk
      * (`.git/rebase-merge` / `.git/rebase-apply`).
      *
      * Advisory on `healthy` rather than its own `BranchHealthKind`, like
-     * `duplicateContentIds`: the metadata is intact and the state is usually
+     * `duplicateIdScan`: the metadata is intact and the state is usually
      * transient, since the worker's sync loop aborts an interrupted rebase at the
      * top of its next per-branch pass. The flag buys visibility in the window
      * before that, where the branch otherwise scans as plain `healthy` while
@@ -74,9 +94,16 @@ export interface BranchHealthEntry {
  * metadata must not take down the whole scan, as in the registry's quarantine.
  * A missing `baseRoot` returns `[]`, so the admin endpoint can call this
  * without a pre-existence check.
+ *
+ * `duplicateIdScan` opts in to the per-branch duplicate-ID scan, which shares
+ * one `budgetMs` across every healthy branch, scanned in turn; a branch
+ * reached after the budget is spent reports `unknown`/`out-of-time`.
  */
 export declare function scanBranchHealth(baseRoot: string, opts: {
     baseBranchName: string;
     contentRootName?: string;
+    duplicateIdScan?: {
+        budgetMs: number;
+    };
 }): Promise<BranchHealthEntry[]>;
 export {};

package/dist/branch-health.js

@@ -6,6 +6,11 @@ import { sanitizeBranchName } from './paths/branch-name.js';
 import { getErrorMessage, isNodeError, isNotFoundError } from './utils/error.js';
 import { isRebaseInProgress } from './utils/git.js';
 import { branchProvisioningLockName } from './utils/provisioning-lock.js';
+/**
+ * An orphan younger than this may still be a clone in progress: admin purge refuses it and the
+ * worker does not quarantine it. Corrupt-metadata dirs are exempt.
+ */
+export const ORPHAN_YOUTH_THRESHOLD_MS = 15 * 60_000;
 /**
  * The provisioning lock marker's path for a branch directory.
  *
@@ -39,20 +44,41 @@ async function readMetaMtime(branchRoot) {
     }
 }
 /**
- * Scan a healthy branch's content tree for duplicate embedded IDs (see
- * content-id-index.ts). Never throws: one branch's unreadable content tree must
- * not take down the whole health scan. Costs a full recursive readdir — the
- * same class of cost as a ContentStore's first-access warm-up, fine for an
- * admin-triggered scan and not for a hot path.
+ * Scan a healthy branch's content tree for duplicate embedded IDs, giving up
+ * when `budget` runs out. Never throws: one branch's unreadable content tree
+ * must not take down the whole health scan. Costs a full recursive readdir, so
+ * it runs only on request and under a budget. A readdir cannot be cancelled: a
+ * scan that misses the deadline keeps running unobserved until it settles.
  */
-async function scanDuplicateContentIds(branchRoot, contentRootName) {
+async function scanDuplicateContentIds(branchRoot, contentRootName, budget) {
+    const remainingMs = budget.deadline - Date.now();
+    if (budget.spent || remainingMs <= 0) {
+        budget.spent = true;
+        return { state: 'unknown', reason: 'out-of-time' };
+    }
+    const scan = (async () => {
+        try {
+            const idIndex = new ContentIdIndex(branchRoot);
+            await idIndex.buildFromFilenames(contentRootName);
+            const duplicates = idIndex.getDuplicateIds();
+            return duplicates.length ? { state: 'found', duplicates } : { state: 'none' };
+        }
+        catch {
+            return { state: 'unknown', reason: 'failed' };
+        }
+    })();
+    let timer;
+    const outOfTime = new Promise((resolve) => {
+        timer = setTimeout(() => {
+            budget.spent = true;
+            resolve({ state: 'unknown', reason: 'out-of-time' });
+        }, remainingMs);
+    });
     try {
-        const idIndex = new ContentIdIndex(branchRoot);
-        await idIndex.buildFromFilenames(contentRootName);
-        return idIndex.getDuplicateIds();
+        return await Promise.race([scan, outOfTime]);
     }
-    catch {
-        return [];
+    finally {
+        clearTimeout(timer);
     }
 }
 /**
@@ -61,8 +87,15 @@ async function scanDuplicateContentIds(branchRoot, contentRootName) {
  * metadata must not take down the whole scan, as in the registry's quarantine.
  * A missing `baseRoot` returns `[]`, so the admin endpoint can call this
  * without a pre-existence check.
+ *
+ * `duplicateIdScan` opts in to the per-branch duplicate-ID scan, which shares
+ * one `budgetMs` across every healthy branch, scanned in turn; a branch
+ * reached after the budget is spent reports `unknown`/`out-of-time`.
  */
 export async function scanBranchHealth(baseRoot, opts) {
+    const duplicateScanBudget = opts.duplicateIdScan
+        ? { deadline: Date.now() + opts.duplicateIdScan.budgetMs, spent: false }
+        : undefined;
     const resolvedRoot = path.resolve(baseRoot);
     const sanitizedBaseBranchName = sanitizeBranchName(opts.baseBranchName);
     const contentRootName = opts.contentRootName ?? 'content';
@@ -95,13 +128,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
@@ -124,8 +158,10 @@ export async function scanBranchHealth(baseRoot, opts) {
             continue;
         }
         if (meta) {
-            const [duplicateContentIds, rebaseInProgress] = await Promise.all([
-                scanDuplicateContentIds(branchRoot, contentRootName),
+            const [duplicateIdScan, rebaseInProgress] = await Promise.all([
+                duplicateScanBudget === undefined
+                    ? undefined
+                    : scanDuplicateContentIds(branchRoot, contentRootName, duplicateScanBudget),
                 isRebaseInProgress(branchRoot),
             ]);
             entries.push({
@@ -133,7 +169,7 @@ export async function scanBranchHealth(baseRoot, opts) {
                 kind: 'healthy',
                 ...(isBaseBranch ? { isBaseBranch } : {}),
                 branch: meta.branch,
-                ...(duplicateContentIds.length ? { duplicateContentIds } : {}),
+                ...(duplicateIdScan ? { duplicateIdScan } : {}),
                 ...(rebaseInProgress ? { rebaseInProgress } : {}),
             });
             continue;

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,205 @@ 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>;
+    editors: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    uncommittedEditors: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+}, "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>;
+    editors: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    uncommittedEditors: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+}, 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>;
+    editors: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    uncommittedEditors: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+}, 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>;