canopycms 0.0.68-int.98 → 0.1.0

package/dist/branch-metadata-file.js

@@ -1,52 +1,153 @@
 /**
  * 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 fs from 'node:fs/promises';
 import path from 'node:path';
-import { isNotFoundError } from './utils/error.js';
+import { z } from 'zod';
+import { getErrorMessage, isNotFoundError } from './utils/error.js';
+import { BranchMetadataCorruptError } from './branch-metadata-error.js';
+export { BranchMetadataCorruptError };
 export const BRANCH_META_DIR = '.canopy-meta';
 export const BRANCH_META_FILE = 'branch.json';
+/** Absolute path to a branch workspace's `branch.json`. */
+const branchMetadataFilePath = (branchRoot) => path.join(path.resolve(branchRoot), BRANCH_META_DIR, BRANCH_META_FILE);
+/** The value a timestamp missing from a hand-written file reads as: honestly unknown, and stable. */
+const UNKNOWN_TIME = new Date(0).toISOString();
+/** A zod enum of every member of `T`: the mapped type refuses to compile if one is left out. */
+const enumOf = (values) => z.nativeEnum(values);
 /**
- * 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.
+ * `branch.json`'s shape, checked on every read.
+ *
+ * Strict where a guard or an access check reads the field: `status` (writes and
+ * submits are gated on it), `name` (the protected-base-branch test compares it)
+ * and `access` (defaulted to `{}`, a missing one would read as "no ACL" and
+ * widen access). Lenient,
+ * with defaults, where a hand-written file can omit bookkeeping: the envelope's
+ * `version` (0, as occ-json-write reads it) and `schemaVersion`, and
+ * `createdBy` ('unknown', which matches no user, so the creator grant fails
+ * closed) and the timestamps. Every optional field is type-checked.
+ *
+ * Unknown keys pass through, so a field a newer deployment writes survives an
+ * older one's save. Code reads only the typed {@link BranchMetadataFile}.
  */
-export class BranchMetadataCorruptError extends Error {
-    constructor(branchRoot, cause) {
-        super(`Corrupt branch metadata in '${branchRoot}': ${cause}`);
-        this.name = 'BranchMetadataCorruptError';
-        this.branchRoot = branchRoot;
-        this.parseCause = cause;
+const branchMetadataShape = {
+    name: z.string().min(1),
+    title: z.string().optional(),
+    description: z.string().optional(),
+    status: enumOf({
+        editing: 'editing',
+        submitted: 'submitted',
+        approved: 'approved',
+        archived: 'archived',
+    }),
+    access: z
+        .object({
+        allowedUsers: z.array(z.string()).optional(),
+        allowedGroups: z.array(z.string()).optional(),
+        managerOrAdminAllowed: z.boolean().optional(),
+    })
+        .passthrough(),
+    createdBy: z.string().default('unknown'),
+    createdAt: z.string().default(UNKNOWN_TIME),
+    updatedAt: z.string().default(UNKNOWN_TIME),
+    baseBranch: z.string().optional(),
+    pullRequestUrl: z.string().optional(),
+    pullRequestNumber: z.number().int().optional(),
+    submittedAt: z.string().optional(),
+    pushedToGitHubAt: z.string().optional(),
+    syncStatus: enumOf({
+        synced: 'synced',
+        'pending-sync': 'pending-sync',
+        'sync-failed': 'sync-failed',
+    }).optional(),
+    conflictStatus: enumOf({
+        clean: 'clean',
+        'conflicts-detected': 'conflicts-detected',
+    }).optional(),
+    conflictFiles: z.array(z.custom((v) => typeof v === 'string')).optional(),
+    pullRequestState: enumOf({
+        open: 'open',
+        closed: 'closed',
+        merged: 'merged',
+    }).optional(),
+    mergedAt: z.string().optional(),
+    rebaseFailure: z
+        .object({ message: z.string(), firstAt: z.string(), lastAt: z.string() })
+        .optional(),
+    historyRewrittenFrom: z.string().optional(),
+    syncFailureReason: z.string().optional(),
+    editors: z.array(z.string()).optional(),
+    uncommittedEditors: z.array(z.string()).optional(),
+};
+/** The `branch` object, also embedded in the registry snapshot (branch-registry.ts). */
+export const branchMetadataSchema = z.object(branchMetadataShape).passthrough();
+const branchMetadataFileSchema = z
+    .object({
+    schemaVersion: z.number().int().default(1),
+    version: z.number().int().nonnegative().default(0),
+    writeId: z.string().optional(),
+    branch: branchMetadataSchema,
+})
+    .passthrough();
+/** The schema failures, by field and without values, so no file content reaches a client. */
+function describeSchemaIssues(issues) {
+    const missing = new Set();
+    const invalid = new Set();
+    for (const issue of issues) {
+        const field = issue.path.length > 0 ? issue.path.join('.') : 'the file';
+        const isMissing = issue.code === z.ZodIssueCode.invalid_type && issue.received === z.ZodParsedType.undefined;
+        (isMissing ? missing : invalid).add(field);
     }
+    const parts = [];
+    if (missing.size > 0)
+        parts.push(`Missing: ${[...missing].join(', ')}`);
+    if (invalid.size > 0)
+        parts.push(`Invalid: ${[...invalid].join(', ')}`);
+    return `Not branch metadata. ${parts.join('. ')}`;
 }
-/** Absolute path to a branch workspace's `branch.json`. */
-const branchMetadataFilePath = (branchRoot) => path.join(path.resolve(branchRoot), BRANCH_META_DIR, BRANCH_META_FILE);
 /**
- * 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 async function readBranchMetadataFile(branchRoot) {
     const resolvedRoot = path.resolve(branchRoot);
+    let raw;
     try {
-        const raw = await fs.readFile(branchMetadataFilePath(resolvedRoot), 'utf8');
-        return JSON.parse(raw);
+        raw = await fs.readFile(branchMetadataFilePath(resolvedRoot), 'utf8');
     }
     catch (err) {
         if (isNotFoundError(err)) {
             return null;
         }
-        if (err instanceof SyntaxError) {
-            throw new BranchMetadataCorruptError(resolvedRoot, err.message);
-        }
         throw err;
     }
+    return parseBranchMetadataFile(resolvedRoot, raw);
+}
+/**
+ * Parse and validate `branch.json` text already read from `branchRoot`.
+ *
+ * @throws BranchMetadataCorruptError when it is not JSON or fails the schema
+ */
+function parseBranchMetadataFile(branchRoot, raw) {
+    let json;
+    try {
+        json = JSON.parse(raw);
+    }
+    catch (err) {
+        throw new BranchMetadataCorruptError(branchRoot, `Not valid JSON: ${getErrorMessage(err)}`);
+    }
+    const result = branchMetadataFileSchema.safeParse(json);
+    if (!result.success) {
+        throw new BranchMetadataCorruptError(branchRoot, describeSchemaIssues(result.error.issues));
+    }
+    const file = result.data;
+    return file;
 }

package/dist/branch-metadata.d.ts

@@ -1,4 +1,5 @@
-import type { BranchContext, BranchMetadata } from './types.js';
+import type { BranchContext, BranchMetadata, BranchPaths, CanopyUserId } from './types.js';
+import type { CanopyUser } from './user.js';
 import { BranchMetadataCorruptError, type BranchMetadataFile } from './branch-metadata-file.js';
 import { type OperatingMode } from './operating-mode/index.js';
 export { BranchMetadataCorruptError, type BranchMetadataFile };
@@ -37,6 +38,12 @@ export declare class BranchMetadataFileManager {
     static get(branchRoot: string, baseRoot: string, options?: {
         settleMs?: number;
     }): BranchMetadataFileManager;
+    /**
+     * The file the save cycle merges over. A corrupt one throws
+     * {@link BranchMetadataCorruptError} rather than reading as absent, so a save
+     * never lays defaults (status 'editing', no ACL) over a branch whose real
+     * state is unknown; repair-metadata archives the file before it saves.
+     */
     private load;
     /**
      * Write branch.json via the shared OCC helper, applying the schemaVersion
@@ -63,16 +70,48 @@ export declare class BranchMetadataFileManager {
      * entry with no clone behind it. It runs BEFORE the lock stack so a doomed
      * save fails fast instead of paying for a lock.
      *
-     * Accepted residual window: a save that passes the check can still race a
-     * `rm` that starts moments later and is mid-flight when the write lands.
-     * Closing that needs a tombstone OUTSIDE the tree being removed, and the
-     * lockfile taken next lives INSIDE `branchRoot`, so it can promise no more
-     * than "the directory existed a moment ago".
+     * A save that passes the check just before a delete still cannot write: the
+     * delete renames the tree away under the same lockfile, and that lockfile
+     * 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>;
+    /**
+     * A save whose update `compute` derives from the metadata on disk, inside the lock stack, so
+     * an update built from the existing value (adding to a list) cannot lose a concurrent one.
+     * `compute` returning null writes nothing and resolves null. `keepUpdatedAt` leaves
+     * `updatedAt` as it was, for bookkeeping writes that are not a change to the branch.
+     */
+    update(compute: (existing: BranchMetadataFile | null) => BranchMetadataUpdate | null, options?: {
+        keepUpdatedAt?: boolean;
+    }): Promise<BranchMetadataFile | null>;
+    /**
+     * Adds `userId` to `editors` and `uncommittedEditors`. A lock-free read skips the write when
+     * both already hold it, so only a user's first save since the last submit commit pays for the lock.
+     * Never creates branch.json.
+     */
+    recordEditor(userId: CanopyUserId): Promise<void>;
+    /**
+     * Removes `userIds` from `uncommittedEditors` once a submit commit's trailers name them. Ids
+     * recorded after the commit read them stay, so the next commit names them.
+     */
+    markEditorsCommitted(userIds: readonly CanopyUserId[]): Promise<void>;
     /** Invalidate the registry cache so the next list() regenerates. */
     private invalidateRegistry;
 }
+/**
+ * Records `user` as an editor of the branch, for the submit's trailers and PR body. Called once a
+ * change to the branch's working tree has succeeded, so a failure here is logged and never fails
+ * that change. Anonymous users are not recorded.
+ */
+export declare function recordBranchEditor(context: BranchPaths, user: CanopyUser): Promise<void>;
+/** The branch.json a brand-new branch starts with: {@link mergeBranchMetadata} over nothing. */
+export declare function buildInitialBranchMetadata(incoming: BranchMetadataUpdate, now?: string): BranchMetadataFile;
 /**
  * Fields save() accepts. `createdBy` applies on creation only and is ignored
  * once metadata exists; createdAt/updatedAt are managed here, not by callers.

package/dist/branch-metadata.js

@@ -3,7 +3,8 @@ import path from 'node:path';
 import { BranchRegistry } from './branch-registry.js';
 import { BRANCH_META_DIR, BRANCH_META_FILE, BranchMetadataCorruptError, readBranchMetadataFile, } from './branch-metadata-file.js';
 import { resolveBranchPath } from './paths/index.js';
-import { isNotFoundError } from './utils/error.js';
+import { getErrorMessage, isNotFoundError } from './utils/error.js';
+import { canopyLogWarn } from './utils/logger.js';
 import { withLock } from './utils/async-mutex.js';
 import { writeOccJsonFile, withOccRetry, withOccFileLock, OccWriteConflictError, } from './utils/occ-json-write.js';
 // The file format lives in the leaf so branch-registry.ts can read branch.json
@@ -52,19 +53,15 @@ export class BranchMetadataFileManager {
     static get(branchRoot, baseRoot, options) {
         return new BranchMetadataFileManager(branchRoot, baseRoot, options);
     }
+    /**
+     * The file the save cycle merges over. A corrupt one throws
+     * {@link BranchMetadataCorruptError} rather than reading as absent, so a save
+     * never lays defaults (status 'editing', no ACL) over a branch whose real
+     * state is unknown; repair-metadata archives the file before it saves.
+     */
     async load() {
-        try {
-            const raw = await fs.readFile(this.filePath, 'utf8');
-            const parsed = JSON.parse(raw);
-            const version = parsed.version ?? 0;
-            return { meta: parsed, version };
-        }
-        catch (err) {
-            if (isNotFoundError(err)) {
-                return { meta: null, version: null };
-            }
-            throw err;
-        }
+        const meta = await readBranchMetadataFile(this.branchRoot);
+        return { meta, version: meta?.version ?? null };
     }
     /**
      * Write branch.json via the shared OCC helper, applying the schemaVersion
@@ -101,13 +98,31 @@ export class BranchMetadataFileManager {
      * entry with no clone behind it. It runs BEFORE the lock stack so a doomed
      * save fails fast instead of paying for a lock.
      *
-     * Accepted residual window: a save that passes the check can still race a
-     * `rm` that starts moments later and is mid-flight when the write lands.
-     * Closing that needs a tombstone OUTSIDE the tree being removed, and the
-     * lockfile taken next lives INSIDE `branchRoot`, so it can promise no more
-     * than "the directory existed a moment ago".
+     * A save that passes the check just before a delete still cannot write: the
+     * delete renames the tree away under the same lockfile, and that lockfile
+     * 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) {
+        return this.update((existing) => (onlyIf(existing) ? incoming : null));
+    }
+    /**
+     * A save whose update `compute` derives from the metadata on disk, inside the lock stack, so
+     * an update built from the existing value (adding to a list) cannot lose a concurrent one.
+     * `compute` returning null writes nothing and resolves null. `keepUpdatedAt` leaves
+     * `updatedAt` as it was, for bookkeeping writes that are not a change to the branch.
+     */
+    async update(compute, options = {}) {
         try {
             await fs.stat(this.branchRoot);
         }
@@ -121,37 +136,12 @@ export class BranchMetadataFileManager {
         try {
             saved = await withLock(this.filePath, () => withOccFileLock(this.filePath, () => withOccRetry(async () => {
                 const { meta: existing, version } = await this.load();
-                const now = new Date().toISOString();
-                const defaults = {
-                    name: 'unknown',
-                    status: 'editing',
-                    access: {},
-                    createdBy: 'unknown',
-                    createdAt: now,
-                    updatedAt: now,
-                };
-                const merged = {
-                    schemaVersion: CURRENT_SCHEMA_VERSION,
-                    version: version ?? 0,
-                    branch: {
-                        ...defaults,
-                        ...existing?.branch,
-                        ...incoming.branch,
-                        access: {
-                            ...existing?.branch?.access,
-                            ...incoming.branch?.access,
-                        },
-                        // Immutable after creation
-                        createdBy: existing?.branch.createdBy ?? incoming.branch?.createdBy ?? defaults.createdBy,
-                        createdAt: existing?.branch.createdAt ?? defaults.createdAt,
-                        // Fork point is recorded once at creation; later saves must not move it
-                        baseBranch: existing?.branch.baseBranch ?? incoming.branch?.baseBranch,
-                        // Always stamped fresh; the spreads above would otherwise let
-                        // the creation-time value win forever, freezing the timestamp
-                        // the editor's Branches panel sorts and displays by
-                        updatedAt: now,
-                    },
-                };
+                const incoming = compute(existing);
+                if (incoming === null)
+                    return null;
+                const merged = mergeBranchMetadata(existing, version, incoming);
+                if (options.keepUpdatedAt && existing)
+                    merged.branch.updatedAt = existing.branch.updatedAt;
                 const written = await this.write(merged, version);
                 merged.version = written.version;
                 merged.writeId = written.writeId;
@@ -169,15 +159,114 @@ 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;
     }
+    /**
+     * Adds `userId` to `editors` and `uncommittedEditors`. A lock-free read skips the write when
+     * both already hold it, so only a user's first save since the last submit commit pays for the lock.
+     * Never creates branch.json.
+     */
+    async recordEditor(userId) {
+        const current = await readBranchMetadataFile(this.branchRoot);
+        if (!current || isRecordedEditor(current.branch, userId))
+            return;
+        await this.update((existing) => existing && !isRecordedEditor(existing.branch, userId)
+            ? {
+                branch: {
+                    editors: withMember(existing.branch.editors, userId),
+                    uncommittedEditors: withMember(existing.branch.uncommittedEditors, userId),
+                },
+            }
+            : null, { keepUpdatedAt: true });
+    }
+    /**
+     * Removes `userIds` from `uncommittedEditors` once a submit commit's trailers name them. Ids
+     * recorded after the commit read them stay, so the next commit names them.
+     */
+    async markEditorsCommitted(userIds) {
+        const committed = new Set(userIds);
+        if (committed.size === 0)
+            return;
+        await this.update((existing) => {
+            const pending = existing?.branch.uncommittedEditors ?? [];
+            const remaining = pending.filter((id) => !committed.has(id));
+            if (remaining.length === pending.length)
+                return null;
+            return { branch: { uncommittedEditors: remaining.length > 0 ? remaining : undefined } };
+        }, { keepUpdatedAt: true });
+    }
     /** Invalidate the registry cache so the next list() regenerates. */
     async invalidateRegistry() {
         const registry = new BranchRegistry(this.baseRoot);
         await registry.invalidate();
     }
 }
+function isRecordedEditor(branch, userId) {
+    return ((branch.editors?.includes(userId) ?? false) &&
+        (branch.uncommittedEditors?.includes(userId) ?? false));
+}
+function withMember(list, id) {
+    return list?.includes(id) ? [...list] : [...(list ?? []), id];
+}
+/**
+ * Records `user` as an editor of the branch, for the submit's trailers and PR body. Called once a
+ * change to the branch's working tree has succeeded, so a failure here is logged and never fails
+ * that change. Anonymous users are not recorded.
+ */
+export async function recordBranchEditor(context, user) {
+    if (user.type !== 'authenticated')
+        return;
+    try {
+        await getBranchMetadataFileManager(context.branchRoot, context.baseRoot).recordEditor(user.userId);
+    }
+    catch (err) {
+        canopyLogWarn(`CanopyCMS: Could not record an editor of ${path.basename(context.branchRoot)}; the next submit will not credit them:`, getErrorMessage(err));
+    }
+}
+/**
+ * The branch.json that {@link BranchMetadataFileManager.save} writes for `incoming` over
+ * `existing`. Pure, so a staged workspace's first branch.json (branch-provisioning.ts) is built by
+ * the same rules as a save and the two cannot drift.
+ */
+function mergeBranchMetadata(existing, version, incoming, now = new Date().toISOString()) {
+    const defaults = {
+        name: 'unknown',
+        status: 'editing',
+        access: {},
+        createdBy: 'unknown',
+        createdAt: now,
+        updatedAt: now,
+    };
+    return {
+        // Envelope keys this code does not know survive, as unknown branch keys do below.
+        ...existing,
+        schemaVersion: CURRENT_SCHEMA_VERSION,
+        version: version ?? 0,
+        branch: {
+            ...defaults,
+            ...existing?.branch,
+            ...incoming.branch,
+            access: {
+                ...existing?.branch?.access,
+                ...incoming.branch?.access,
+            },
+            // Immutable after creation
+            createdBy: existing?.branch.createdBy ?? incoming.branch?.createdBy ?? defaults.createdBy,
+            createdAt: existing?.branch.createdAt ?? defaults.createdAt,
+            // Fork point is recorded once at creation; later saves must not move it
+            baseBranch: existing?.branch.baseBranch ?? incoming.branch?.baseBranch,
+            // Always stamped fresh; the spreads above would otherwise let the creation-time value win
+            // forever, freezing the timestamp the editor's Branches panel sorts and displays by
+            updatedAt: now,
+        },
+    };
+}
+/** The branch.json a brand-new branch starts with: {@link mergeBranchMetadata} over nothing. */
+export function buildInitialBranchMetadata(incoming, now) {
+    return mergeBranchMetadata(null, null, incoming, now);
+}
 /**
  * The metadata update for archiving a branch whose PR merged. Shared by the
  * worker's merge-poll (CmsWorker.pollMergeState) and the manual markAsMerged
@@ -193,6 +282,9 @@ export function buildMergedBranchUpdate(branchName, now = new Date()) {
         status: 'archived',
         pullRequestState: 'merged',
         mergedAt: now.toISOString(),
+        // The merge settled every conflict the record named.
+        conflictStatus: 'clean',
+        conflictFiles: [],
     };
 }
 /** {@link BranchMetadataFileManager.get} as a function. */

package/dist/branch-provisioning.d.ts

@@ -0,0 +1,167 @@
+import { type BranchMetadataFile } from './branch-metadata-file.js';
+import { type CloneRepoOptions } from './git-manager.js';
+import type { ProvisionLog } from './utils/provision-log.js';
+/** How long residue must have been untouched before a create request moves it aside. */
+export declare const CREATE_RESIDUE_MIN_QUIET_MS = 60000;
+/**
+ * Retriable: another process is setting this branch up, or what is at its path is too recently
+ * touched (or under an admin repair) to judge. Callers answer 503.
+ */
+export declare class BranchProvisioningBusyError extends Error {
+    readonly dirName: string;
+    constructor(dirName: string, message?: string);
+}
+/** The branch's path holds a git repository this deployment did not create (prod only). */
+export declare class BranchDirOccupiedError extends Error {
+    readonly dirName: string;
+    constructor(dirName: string);
+}
+/** `YYYYMMDDTHHMMSSZ` in UTC, with no colons. */
+export declare function formatDirStamp(date: Date): string;
+/**
+ * The date in a name ending `-{STAMP}`, or null. Leftovers are aged by this alone, never by
+ * mtime: `rename()` keeps a directory's mtime, so a months-old residue would look old the
+ * moment it was moved.
+ */
+export declare function parseDirStamp(name: string): Date | null;
+/**
+ * A branch directory name cut to a bounded, still-unique form: branch names run to 250 chars.
+ * @internal Exported for tests.
+ */
+export declare function shortDirName(dirName: string): string;
+/** Where a branch directory goes the moment it is deleted, before its `rm`. */
+export declare const deletingDirName: (dirName: string, now?: Date) => string;
+/** The settings workspace's staging and trash siblings, under the workspace root. */
+export declare const settingsStagingDirName: (now?: Date) => string;
+export declare const settingsTrashDirName: (now?: Date) => string;
+interface ResidueSignature {
+    hasGitDir: boolean;
+    configLock: boolean;
+    hasIndex: boolean;
+}
+/**
+ * What occupies a branch's final path.
+ *
+ * - `live` / `corrupt`: branch.json is there. Never touched by provisioning.
+ * - `protected`: an admin repair-metadata is mid-way (`branch.json.corrupt-*` with no
+ *   branch.json), or branch.json vanished between the listing and the read. Left alone.
+ * - `residue`: nothing this deployment could still be using — no `.git`, or a `.git` whose config
+ *   is missing or unreadable (an interrupted clone), or one whose remote is this deployment's own
+ *   (an interrupted clone or delete).
+ * - `foreign`: any other repository, such as a dev CLI-sync workspace, which has no remote.
+ */
+export type FinalDirState = {
+    kind: 'vacant';
+} | {
+    kind: 'live';
+} | {
+    kind: 'corrupt';
+} | {
+    kind: 'protected';
+} | {
+    kind: 'foreign';
+} | {
+    kind: 'residue';
+    signature: ResidueSignature;
+};
+/** Classify what is at `dirPath`; see {@link FinalDirState}. */
+export declare function classifyFinalDir(dirPath: string, expectedRemoteUrl: string): Promise<FinalDirState>;
+/**
+ * Milliseconds since anything was last created or removed in the directory, its `.git` or its
+ * `.canopy-meta`. A clone killed inside `git config` touched `.git` when it made `config.lock`.
+ */
+export declare function quietAgeMs(dirPath: string, now?: number): Promise<number>;
+type KeptReason = 'live' | 'corrupt' | 'protected' | 'foreign' | 'too-young' | 'replaced';
+export type QuarantineResult = {
+    kind: 'quarantined';
+    trashName: string;
+} | {
+    kind: 'vacant';
+} | {
+    kind: 'kept';
+    reason: KeptReason;
+};
+export interface QuarantineOptions {
+    minQuietMs: number;
+    expectedRemoteUrl: string;
+    now?: number;
+}
+/**
+ * Move residue at `baseRoot/dirName` to `.trash-*`. The caller MUST hold the branch's
+ * provisioning lock: admin repair-metadata holds it while it legitimately leaves a directory
+ * with real edits and no branch.json.
+ *
+ * Move-then-verify: the name is renamed aside first and only what arrived at the new name is
+ * judged — the same inode the old name showed, still residue, quiet for `minQuietMs` — because
+ * a look through the old name can come from a stale NFS dentry for a directory another host has
+ * since replaced with a live clone. Anything that fails a check, or cannot be checked, is
+ * renamed straight back: the sweep would trash a `.repair-*` without branch.json.
+ */
+export declare function quarantineResidueAt(baseRoot: string, dirName: string, options: QuarantineOptions): Promise<QuarantineResult>;
+export interface StageBranchOptions {
+    baseRoot: string;
+    dirName: string;
+    branchName: string;
+    baseBranch: string;
+    remoteUrl: string;
+    clone: Pick<CloneRepoOptions, 'remoteName' | 'config'>;
+    gitExcludePattern: string;
+    metadata: BranchMetadataFile;
+    provisionLog: ProvisionLog;
+    /** The sparse-checkout cone (branch-sparse.ts), set before the checkout; none for a full clone. */
+    sparseCone?: readonly string[] | null;
+}
+export type StageResult = {
+    kind: 'staged';
+    stagingPath: string;
+    meta: BranchMetadataFile;
+} | {
+    kind: 'exists';
+};
+/** Remove a staging or deleted directory, leaving it to the worker's sweep on failure. */
+export declare function removeLeftoverDir(dirPath: string): Promise<void>;
+/**
+ * Build a complete branch workspace, branch.json included, in a staging sibling of the final
+ * path. Takes no lock. Returns `exists` without checking out when a competitor published first.
+ * A failure removes the staging directory; a kill leaves it for the worker.
+ */
+export declare function stageBranchWorkspace(options: StageBranchOptions): Promise<StageResult>;
+/**
+ * The branch's provisioning lock with a bounded wait; contention is
+ * {@link BranchProvisioningBusyError}.
+ */
+export declare function lockBranchName(baseRoot: string, dirName: string): Promise<() => Promise<void>>;
+/** What blocks a refused publish rename, as {@link publishStaging} sees it. */
+export type BlockingKind = 'live' | 'protected' | 'residue';
+export interface PublishOptions {
+    baseRoot: string;
+    dirName: string;
+    stagingPath: string;
+    /** branch.json's `writeId` in the staged workspace: proof the rename was ours. */
+    writeId: string | undefined;
+    expectedRemoteUrl: string;
+    /** Test seam replacing the look at what blocks a refused rename. */
+    inspectBlocked?: (finalPath: string) => Promise<BlockingKind>;
+}
+/**
+ * Publish a staged workspace at its final path, under the branch's provisioning lock.
+ *
+ * A refused rename is inspected: branch.json there means another request won (`exists`);
+ * residue is quarantined and the rename retried once. ENOENT can be an NFS retransmission of a
+ * rename that already landed, so it counts as published when the final branch.json carries our
+ * `writeId`. The caller removes the staging directory on any outcome but `published`.
+ */
+export declare function publishStaging(options: PublishOptions): Promise<'published' | 'exists'>;
+export interface LeftoverAction {
+    name: string;
+    action: 'removed' | 'restored' | 'trashed' | 'failed';
+    detail?: string;
+}
+/**
+ * Clear what killed processes left beside the branch directories (`baseRoot`) and the settings
+ * workspace (`workspaceRoot`): stale `.prov-*` builds, `.deleting-*` directories whose `rm` never
+ * finished, `.repair-*` from an interrupted quarantine, and expired settings trash. Ages come
+ * from the stamp in each name.
+ */
+export declare function sweepProvisioningLeftovers(baseRoot: string, workspaceRoot: string, now?: number): Promise<LeftoverAction[]>;
+export {};