canopycms 0.0.67 → 0.0.68-int.101

package/dist/branch-provisioning.js

@@ -0,0 +1,501 @@
+/**
+ * Crash-safe provisioning of content-branch workspaces.
+ *
+ * [PROV-1] A final branch directory only ever appears by `rename()`, with
+ * `.canopy-meta/branch.json` already inside it. A Lambda can be killed at its
+ * timeout inside any git step, and anything it was building at the final path
+ * would wedge that branch name for every later request. So a workspace is built
+ * in a dot-prefixed staging sibling without any lock (the registry,
+ * branch-health, the rebase loop and admin all skip dot-prefixed names), then
+ * published by one rename under the branch's provisioning lock, held for
+ * milliseconds. A kill at any point leaves nothing at the final name or a
+ * complete workspace; the worker sweeps the leftovers.
+ *
+ * The rename alone does not settle a race: it silently replaces an EMPTY
+ * directory, and a refused rename may be blocked by a live branch or by
+ * residue. Hence the lock, and the inspection of whatever blocks the rename.
+ * docs/concurrency.md has the cross-host picture.
+ */
+import { createHash, randomBytes } from 'node:crypto';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { BRANCH_META_DIR, BRANCH_META_FILE, BranchMetadataCorruptError, readBranchMetadataFile, } from './branch-metadata-file.js';
+import { GitManager } from './git-manager.js';
+import { sanitizeBranchName } from './paths/branch-name.js';
+import { getErrorMessage, isNodeError, isNotFoundError } from './utils/error.js';
+import { isNetworkRemoteUrl } from './utils/git.js';
+import { canopyLogError, canopyLogWarn } from './utils/logger.js';
+import { writeOccJsonFile } from './utils/occ-json-write.js';
+import { acquireProvisioningLockWithin, branchProvisioningLockName, tryAcquireProvisioningLock, } from './utils/provisioning-lock.js';
+/**
+ * How long a publish waits for the branch's provisioning lock. Holds on a name being published
+ * are brief; a dead holder's marker stays live for 90 s, and waiting that out would spend the
+ * request's timeout.
+ */
+const PUBLISH_LOCK_WAIT_MS = 8_000;
+/** How long residue must have been untouched before a create request moves it aside. */
+export const CREATE_RESIDUE_MIN_QUIET_MS = 60_000;
+/**
+ * Stamped leftovers older than these are swept by the worker. A `.prov-*` may belong to a live
+ * builder for as long as a Lambda can run (900 s at most, whatever timeout an adopter sets).
+ */
+const STAGING_MAX_AGE_MS = 20 * 60_000;
+const REPAIR_MAX_AGE_MS = 20 * 60_000;
+const DELETING_MAX_AGE_MS = 10 * 60_000;
+const SETTINGS_TRASH_MAX_AGE_MS = 30 * 24 * 60 * 60_000;
+/**
+ * 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 class BranchProvisioningBusyError extends Error {
+    constructor(dirName, message = `Branch '${dirName}' is still being set up. Try again in a minute.`) {
+        super(message);
+        this.dirName = dirName;
+        this.name = 'BranchProvisioningBusyError';
+    }
+}
+/** The branch's path holds a git repository this deployment did not create (prod only). */
+export class BranchDirOccupiedError extends Error {
+    constructor(dirName) {
+        super(`A directory named '${dirName}' already exists in the branch workspace and holds a git ` +
+            `repository this deployment did not create. It was left untouched; an admin can purge ` +
+            `it from System Health, or choose another branch name.`);
+        this.dirName = dirName;
+        this.name = 'BranchDirOccupiedError';
+    }
+}
+// --- Names -----------------------------------------------------------------------------------
+const DIR_STAMP_RE = /-(\d{8}T\d{6}Z)$/;
+/** `YYYYMMDDTHHMMSSZ` in UTC, with no colons. */
+export function formatDirStamp(date) {
+    return date
+        .toISOString()
+        .replace(/[-:]/g, '')
+        .replace(/\.\d{3}Z$/, 'Z');
+}
+/**
+ * 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 function parseDirStamp(name) {
+    const match = DIR_STAMP_RE.exec(name);
+    if (!match)
+        return null;
+    const [, year, month, day, hour, minute, second] = /^(\d{4})(\d{2})(\d{2})T(\d{2})(\d{2})(\d{2})Z$/.exec(match[1]) ?? [];
+    const date = new Date(`${year}-${month}-${day}T${hour}:${minute}:${second}.000Z`);
+    return Number.isNaN(date.getTime()) ? null : date;
+}
+/**
+ * A branch directory name cut to a bounded, still-unique form: branch names run to 250 chars.
+ * @internal Exported for tests.
+ */
+export function shortDirName(dirName) {
+    const digest = createHash('sha1').update(dirName).digest('hex').slice(0, 10);
+    return `${dirName.slice(0, 40)}-${digest}`;
+}
+function stampedName(prefix, dirName, now) {
+    return `${prefix}${shortDirName(dirName)}-${randomBytes(3).toString('hex')}-${formatDirStamp(now)}`;
+}
+const STAGING_PREFIX = '.prov-';
+const REPAIR_PREFIX = '.repair-';
+const TRASH_PREFIX = '.trash-';
+const DELETING_PREFIX = '.deleting-';
+/** Where a branch is built before it is published. */
+const stagingDirName = (dirName, now = new Date()) => stampedName(STAGING_PREFIX, dirName, now);
+/** Where a branch directory goes the moment it is deleted, before its `rm`. */
+export const deletingDirName = (dirName, now = new Date()) => stampedName(DELETING_PREFIX, dirName, now);
+/** The settings workspace's staging and trash siblings, under the workspace root. */
+export const settingsStagingDirName = (now = new Date()) => `${STAGING_PREFIX}settings-${randomBytes(3).toString('hex')}-${formatDirStamp(now)}`;
+export const settingsTrashDirName = (now = new Date()) => `${TRASH_PREFIX}settings-${randomBytes(3).toString('hex')}-${formatDirStamp(now)}`;
+const NO_GIT = { hasGitDir: false, configLock: false, hasIndex: false };
+async function listDir(dirPath) {
+    try {
+        return await fs.readdir(dirPath);
+    }
+    catch (err) {
+        if (isNodeError(err) && (err.code === 'ENOENT' || err.code === 'ENOTDIR'))
+            return null;
+        throw err;
+    }
+}
+/** Remote URLs in a git config file's text. Read as a file: git does not treat a `.git` that a
+ * kill left without `HEAD` as a repository, and a stale `config.lock` blocks only config writes. */
+function gitConfigRemoteUrls(text) {
+    const urls = [];
+    let inRemote = false;
+    for (const raw of text.split('\n')) {
+        const line = raw.trim();
+        if (line.startsWith('[')) {
+            inRemote = /^\[\s*remote\s+"[^"]*"\s*\]/i.test(line);
+            continue;
+        }
+        const match = inRemote ? /^url\s*=\s*(.*)$/i.exec(line) : null;
+        if (match)
+            urls.push(match[1].trim().replace(/^"(.*)"$/, '$1'));
+    }
+    return urls;
+}
+function sameRemote(url, expected) {
+    if (isNetworkRemoteUrl(url) || isNetworkRemoteUrl(expected))
+        return url === expected;
+    const local = (value) => path.resolve(value.replace(/^file:\/\//i, ''));
+    return local(url) === local(expected);
+}
+/** Classify what is at `dirPath`; see {@link FinalDirState}. */
+export async function classifyFinalDir(dirPath, expectedRemoteUrl) {
+    let stat;
+    try {
+        stat = await fs.lstat(dirPath);
+    }
+    catch (err) {
+        if (isNotFoundError(err))
+            return { kind: 'vacant' };
+        throw err;
+    }
+    if (!stat.isDirectory())
+        return { kind: 'residue', signature: NO_GIT };
+    const metaEntries = (await listDir(path.join(dirPath, BRANCH_META_DIR))) ?? [];
+    if (metaEntries.includes(BRANCH_META_FILE)) {
+        try {
+            return (await readBranchMetadataFile(dirPath)) ? { kind: 'live' } : { kind: 'protected' };
+        }
+        catch (err) {
+            if (err instanceof BranchMetadataCorruptError)
+                return { kind: 'corrupt' };
+            throw err;
+        }
+    }
+    if (metaEntries.some((name) => name.startsWith(`${BRANCH_META_FILE}.corrupt-`))) {
+        return { kind: 'protected' };
+    }
+    const gitPath = path.join(dirPath, '.git');
+    let gitStat;
+    try {
+        gitStat = await fs.lstat(gitPath);
+    }
+    catch (err) {
+        if (isNotFoundError(err))
+            return { kind: 'residue', signature: NO_GIT };
+        throw err;
+    }
+    if (!gitStat.isDirectory())
+        return { kind: 'foreign' };
+    const gitEntries = (await listDir(gitPath)) ?? [];
+    const signature = {
+        hasGitDir: true,
+        configLock: gitEntries.includes('config.lock'),
+        hasIndex: gitEntries.includes('index'),
+    };
+    let config;
+    try {
+        config = await fs.readFile(path.join(gitPath, 'config'), 'utf8');
+    }
+    catch {
+        return { kind: 'residue', signature };
+    }
+    return gitConfigRemoteUrls(config).some((url) => sameRemote(url, expectedRemoteUrl))
+        ? { kind: 'residue', signature }
+        : { kind: 'foreign' };
+}
+/**
+ * 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 async function quietAgeMs(dirPath, now = Date.now()) {
+    const mtimes = await Promise.all(['', '.git', BRANCH_META_DIR].map((sub) => fs.lstat(path.join(dirPath, sub)).then((stat) => stat.mtimeMs, () => 0)));
+    return now - Math.max(...mtimes);
+}
+/**
+ * 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 async function quarantineResidueAt(baseRoot, dirName, options) {
+    const finalPath = path.join(baseRoot, dirName);
+    let inode;
+    try {
+        inode = (await fs.lstat(finalPath)).ino;
+    }
+    catch (err) {
+        if (isNotFoundError(err))
+            return { kind: 'vacant' };
+        throw err;
+    }
+    const candidateName = stampedName(REPAIR_PREFIX, dirName, new Date());
+    const candidate = path.join(baseRoot, candidateName);
+    try {
+        await fs.rename(finalPath, candidate);
+    }
+    catch (err) {
+        if (isNotFoundError(err))
+            return { kind: 'vacant' };
+        throw err;
+    }
+    const moveBack = async (why) => {
+        try {
+            await fs.rename(candidate, finalPath);
+        }
+        catch (err) {
+            canopyLogError(`[canopy] Could not move '${dirName}' back from ${candidateName} after ${why}: ` +
+                `${getErrorMessage(err)}. The worker's sweep restores or trashes it.`);
+        }
+    };
+    const { state, quiet, reason } = await judgeQuarantineCandidate(candidate, inode, options).catch(async (err) => {
+        await moveBack(`failing to judge it (${getErrorMessage(err)})`);
+        throw err;
+    });
+    if (reason === undefined && state.kind === 'residue') {
+        const trashName = stampedName(TRASH_PREFIX, dirName, new Date());
+        await fs.rename(candidate, path.join(baseRoot, trashName));
+        const { hasGitDir, configLock, hasIndex } = state.signature;
+        canopyLogWarn(`[canopy] Quarantined unfinished branch directory '${dirName}' as ${trashName} ` +
+            `(git=${hasGitDir} config.lock=${configLock} index=${hasIndex} quiet=${Math.round(quiet / 1000)}s)`);
+        return { kind: 'quarantined', trashName };
+    }
+    await moveBack(`declining to quarantine it (${reason})`);
+    return { kind: 'kept', reason: reason ?? 'replaced' };
+}
+/** Judge what arrived at the quarantine candidate name; `reason` is set when it must be kept. */
+async function judgeQuarantineCandidate(candidate, inode, options) {
+    const state = await classifyFinalDir(candidate, options.expectedRemoteUrl);
+    const moved = await fs.lstat(candidate).catch(() => null);
+    const quiet = await quietAgeMs(candidate, options.now);
+    let reason;
+    if (!moved || moved.ino !== inode)
+        reason = 'replaced';
+    else if (state.kind === 'vacant')
+        reason = 'replaced';
+    else if (state.kind !== 'residue')
+        reason = state.kind;
+    else if (quiet < options.minQuietMs)
+        reason = 'too-young';
+    return { state, quiet, reason };
+}
+/** Remove a staging or deleted directory, leaving it to the worker's sweep on failure. */
+export async function removeLeftoverDir(dirPath) {
+    try {
+        await fs.rm(dirPath, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 });
+    }
+    catch (err) {
+        canopyLogWarn(`[canopy] Could not remove ${dirPath}; the worker sweeps it: ${getErrorMessage(err)}`);
+    }
+}
+async function hasBranchMetadata(branchRoot) {
+    return fs.access(path.join(branchRoot, BRANCH_META_DIR, BRANCH_META_FILE)).then(() => true, () => false);
+}
+/**
+ * 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 async function stageBranchWorkspace(options) {
+    const { provisionLog: log } = options;
+    const stagingPath = path.join(options.baseRoot, stagingDirName(options.dirName));
+    try {
+        await log.step('clone', () => GitManager.cloneWorkspace(options.remoteUrl, stagingPath, options.baseBranch, {
+            ...options.clone,
+            noCheckout: true,
+        }));
+        const git = new GitManager({
+            repoPath: stagingPath,
+            baseBranch: options.baseBranch,
+            remote: options.clone.remoteName,
+        });
+        const cone = options.sparseCone;
+        if (cone)
+            await log.step('sparse', () => git.setSparseCone(cone));
+        // The checkout is the expensive half; skip it when a competitor has already won.
+        if (await hasBranchMetadata(path.join(options.baseRoot, options.dirName))) {
+            await removeLeftoverDir(stagingPath);
+            return { kind: 'exists' };
+        }
+        await log.step('checkout', () => git.checkoutFreshClone(options.branchName));
+        await log.step('exclude', () => git.ensureGitExclude(options.gitExcludePattern));
+        const written = await log.step('metadata', () => writeOccJsonFile(path.join(stagingPath, BRANCH_META_DIR, BRANCH_META_FILE), { ...options.metadata }, { expectedVersion: null, trailingNewline: true }));
+        return {
+            kind: 'staged',
+            stagingPath,
+            meta: { ...options.metadata, version: written.version, writeId: written.writeId },
+        };
+    }
+    catch (err) {
+        await removeLeftoverDir(stagingPath);
+        throw err;
+    }
+}
+/**
+ * The branch's provisioning lock with a bounded wait; contention is
+ * {@link BranchProvisioningBusyError}.
+ */
+export async function lockBranchName(baseRoot, dirName) {
+    try {
+        return await acquireProvisioningLockWithin(baseRoot, branchProvisioningLockName(dirName), PUBLISH_LOCK_WAIT_MS);
+    }
+    catch (err) {
+        if (isNodeError(err) && err.code === 'ELOCKED')
+            throw new BranchProvisioningBusyError(dirName);
+        throw err;
+    }
+}
+/** Listing `.canopy-meta` opens the directory, which makes NFS revalidate it. */
+async function inspectBlocking(finalPath) {
+    const entries = (await listDir(path.join(finalPath, BRANCH_META_DIR))) ?? [];
+    if (entries.includes(BRANCH_META_FILE))
+        return 'live';
+    if (entries.some((name) => name.startsWith(`${BRANCH_META_FILE}.corrupt-`)))
+        return 'protected';
+    return 'residue';
+}
+const RENAME_BLOCKED = new Set(['EEXIST', 'ENOTEMPTY', 'ENOTDIR']);
+/**
+ * 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 async function publishStaging(options) {
+    const { baseRoot, dirName, stagingPath } = options;
+    const finalPath = path.join(baseRoot, dirName);
+    const release = await lockBranchName(baseRoot, dirName);
+    try {
+        for (let attempt = 0; attempt < 2; attempt++) {
+            try {
+                await fs.rename(stagingPath, finalPath);
+                return 'published';
+            }
+            catch (err) {
+                if (!isNodeError(err))
+                    throw err;
+                if (err.code === 'ENOENT') {
+                    const meta = await readBranchMetadataFile(finalPath).catch(() => null);
+                    if (meta?.writeId !== undefined && meta.writeId === options.writeId)
+                        return 'published';
+                    throw err;
+                }
+                if (!RENAME_BLOCKED.has(err.code ?? ''))
+                    throw err;
+            }
+            const blocking = await (options.inspectBlocked ?? inspectBlocking)(finalPath);
+            if (blocking === 'live')
+                return 'exists';
+            if (blocking === 'protected')
+                throw new BranchProvisioningBusyError(dirName);
+            const result = await quarantineResidueAt(baseRoot, dirName, {
+                minQuietMs: CREATE_RESIDUE_MIN_QUIET_MS,
+                expectedRemoteUrl: options.expectedRemoteUrl,
+            });
+            if (result.kind !== 'kept')
+                continue;
+            if (result.reason === 'live')
+                return 'exists';
+            if (result.reason === 'corrupt') {
+                await readBranchMetadataFile(finalPath);
+                return 'exists';
+            }
+            if (result.reason === 'foreign')
+                throw new BranchDirOccupiedError(dirName);
+            throw new BranchProvisioningBusyError(dirName);
+        }
+        throw new BranchProvisioningBusyError(dirName);
+    }
+    finally {
+        await release().catch((err) => {
+            canopyLogWarn(`[canopy] Failed to release the provisioning lock for ${dirName}:`, err);
+        });
+    }
+}
+async function sweepByAge(root, rules, now) {
+    const entries = (await listDir(root)) ?? [];
+    const actions = [];
+    for (const name of entries) {
+        const rule = rules.find((candidate) => name.startsWith(candidate.prefix));
+        const stamp = rule ? parseDirStamp(name) : null;
+        if (!rule || !stamp || now - stamp.getTime() < rule.maxAgeMs)
+            continue;
+        try {
+            await fs.rm(path.join(root, name), {
+                recursive: true,
+                force: true,
+                maxRetries: 3,
+                retryDelay: 100,
+            });
+            actions.push({ name, action: 'removed' });
+        }
+        catch (err) {
+            actions.push({ name, action: 'failed', detail: getErrorMessage(err) });
+        }
+    }
+    return actions;
+}
+/**
+ * A `.repair-*` left by a process killed mid-quarantine goes back to its branch name when it
+ * holds branch.json and the name is free; anything else is trashed. The branch name comes from
+ * its branch.json, checked against the name's bounded prefix.
+ */
+async function recoverRepairDir(baseRoot, name) {
+    const repairPath = path.join(baseRoot, name);
+    const meta = await readBranchMetadataFile(repairPath).catch(() => null);
+    const dirName = meta ? sanitizeBranchName(meta.branch.name) : undefined;
+    if (dirName && name.startsWith(`${REPAIR_PREFIX}${shortDirName(dirName)}-`)) {
+        let release;
+        try {
+            release = await tryAcquireProvisioningLock(baseRoot, branchProvisioningLockName(dirName));
+        }
+        catch (err) {
+            if (isNodeError(err) && err.code === 'ELOCKED') {
+                return { name, action: 'failed', detail: 'provisioning lock held; retrying next cycle' };
+            }
+            throw err;
+        }
+        try {
+            const finalPath = path.join(baseRoot, dirName);
+            if ((await fs.lstat(finalPath).catch(() => null)) === null) {
+                await fs.rename(repairPath, finalPath);
+                return { name, action: 'restored', detail: dirName };
+            }
+        }
+        finally {
+            await release().catch(() => { });
+        }
+    }
+    const trashName = `${TRASH_PREFIX}${name.slice(REPAIR_PREFIX.length)}`;
+    await fs.rename(repairPath, path.join(baseRoot, trashName));
+    return { name, action: 'trashed', detail: trashName };
+}
+/**
+ * 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 async function sweepProvisioningLeftovers(baseRoot, workspaceRoot, now = Date.now()) {
+    const actions = await sweepByAge(baseRoot, [
+        { prefix: STAGING_PREFIX, maxAgeMs: STAGING_MAX_AGE_MS },
+        { prefix: DELETING_PREFIX, maxAgeMs: DELETING_MAX_AGE_MS },
+    ], now);
+    for (const name of (await listDir(baseRoot)) ?? []) {
+        const stamp = name.startsWith(REPAIR_PREFIX) ? parseDirStamp(name) : null;
+        if (!stamp || now - stamp.getTime() < REPAIR_MAX_AGE_MS)
+            continue;
+        try {
+            actions.push(await recoverRepairDir(baseRoot, name));
+        }
+        catch (err) {
+            actions.push({ name, action: 'failed', detail: getErrorMessage(err) });
+        }
+    }
+    actions.push(...(await sweepByAge(workspaceRoot, [
+        { prefix: `${STAGING_PREFIX}settings-`, maxAgeMs: STAGING_MAX_AGE_MS },
+        { prefix: `${TRASH_PREFIX}settings-`, maxAgeMs: SETTINGS_TRASH_MAX_AGE_MS },
+    ], now)));
+    return actions;
+}

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

@@ -2,6 +2,8 @@ import type { RootCollectionConfig } from './config/index.js';
 import type { FlatSchemaItem } from './config/types.js';
 import type { OperatingMode } from './operating-mode/index.js';
 import type { EntrySchemaRegistry, SchemaResolutionResult } from './schema/types.js';
+/** File name of the schema cache inside {@link schemaCacheDir}. */
+export declare const SCHEMA_CACHE_FILE = "schema-cache.json";
 /** resource-generation.ts resource key for the schema cache's marker. */
 export declare const SCHEMA_GENERATION_RESOURCE = "schema";
 /** @internal Exported for tests. */
@@ -18,8 +20,8 @@ export interface BranchSchemaCacheEntry {
     generation: string | null;
 }
 /**
- * Per-branch schema cache: a file at {branchRoot}/.canopy-meta/schema-cache.json
- * with no in-memory layer, so it stays coherent across Lambda invocations.
+ * Per-branch schema cache: one file in {@link schemaCacheDir} with no in-memory
+ * layer, so it stays coherent across Lambda invocations.
  *
  * Freshness follows the generation-marker protocol owned by
  * resource-generation.ts, and this is one of that protocol's durable-snapshot
@@ -39,7 +41,7 @@ export declare class BranchSchemaCache {
     /**
      * Whether to skip the on-disk cache for this branchRoot.
      *
-     * Never write `.canopy-meta/` at the project root, whichever entrypoint
+     * Never write a schema cache at the project root, whichever entrypoint
      * produced the cwd branchRoot. branchRoot equals process.cwd() only in the
      * synthetic contexts static deployments and build phases use; a real branch
      * root is always nested under the workspace.

package/dist/branch-schema-cache.js

@@ -5,10 +5,14 @@ import { flattenSchema } from './config/flatten.js';
 import { validateReferenceEntryTypes } from './validation/entry-type-reference-validator.js';
 import { isBuildMode } from './build-mode.js';
 import { bumpResourceGeneration, readResourceGeneration, isGenerationCurrent, } from './resource-generation.js';
+import { timeRequestPhase } from './utils/request-timing.js';
+import { CANOPY_META_DIR } from './utils/git.js';
 /** Bump when BranchSchemaCacheEntry shape changes to auto-invalidate stale caches */
 const SCHEMA_CACHE_VERSION = 3;
 /** Minimum interval between mtime staleness checks (ms) */
 const MTIME_CHECK_DEBOUNCE_MS = 1000;
+/** File name of the schema cache inside {@link schemaCacheDir}. */
+export const SCHEMA_CACHE_FILE = 'schema-cache.json';
 /** resource-generation.ts resource key for the schema cache's marker. */
 export const SCHEMA_GENERATION_RESOURCE = 'schema';
 /**
@@ -43,8 +47,22 @@ async function isStaleByMtime(dir, cachedAt) {
     return false;
 }
 /**
- * Per-branch schema cache: a file at {branchRoot}/.canopy-meta/schema-cache.json
- * with no in-memory layer, so it stays coherent across Lambda invocations.
+ * Directory holding a branch's schema cache: `{branchRoot}/.git/canopycms` when
+ * the branch root is a full clone (every canopycms branch workspace is), else
+ * `{branchRoot}/.canopy-meta`. Under `.git/` because nothing there is ever
+ * tracked or reported by `git status`, so the cache can neither dirty the
+ * workspace nor enter a commit, even where an adopter has committed
+ * `.canopy-meta/`. It also lives and dies with the clone, so a re-clone never
+ * reads its predecessor's snapshot.
+ */
+async function schemaCacheDir(branchRoot) {
+    const gitDir = path.join(branchRoot, '.git');
+    const isClone = await fs.stat(gitDir).then((stat) => stat.isDirectory(), () => false);
+    return isClone ? path.join(gitDir, 'canopycms') : path.join(branchRoot, CANOPY_META_DIR);
+}
+/**
+ * Per-branch schema cache: one file in {@link schemaCacheDir} with no in-memory
+ * layer, so it stays coherent across Lambda invocations.
  *
  * Freshness follows the generation-marker protocol owned by
  * resource-generation.ts, and this is one of that protocol's durable-snapshot
@@ -65,7 +83,7 @@ export class BranchSchemaCache {
     /**
      * Whether to skip the on-disk cache for this branchRoot.
      *
-     * Never write `.canopy-meta/` at the project root, whichever entrypoint
+     * Never write a schema cache at the project root, whichever entrypoint
      * produced the cwd branchRoot. branchRoot equals process.cwd() only in the
      * synthetic contexts static deployments and build phases use; a real branch
      * root is always nested under the workspace.
@@ -75,7 +93,7 @@ export class BranchSchemaCache {
     }
     /** Get schema for a branch, from the cache when fresh, else resolved fresh. */
     async getSchema(branchRoot, entrySchemaRegistry, contentRootName = 'content') {
-        return this.loadFromCacheOrResolve(branchRoot, entrySchemaRegistry, contentRootName);
+        return timeRequestPhase('schema', () => this.loadFromCacheOrResolve(branchRoot, entrySchemaRegistry, contentRootName));
     }
     /**
      * Resolve the schema from disk. Protected rather than a direct resolveSchema
@@ -89,8 +107,7 @@ export class BranchSchemaCache {
         const contentRoot = path.join(branchRoot, contentRootName);
         const skipDiskCache = this.skipDiskCache(branchRoot);
         if (!skipDiskCache) {
-            const cacheDir = path.join(branchRoot, '.canopy-meta');
-            const cachePath = path.join(cacheDir, 'schema-cache.json');
+            const cachePath = path.join(await schemaCacheDir(branchRoot), SCHEMA_CACHE_FILE);
             let cacheData = null;
             try {
                 const cacheContent = await fs.readFile(cachePath, 'utf-8');
@@ -149,7 +166,8 @@ export class BranchSchemaCache {
         const read = skipDiskCache
             ? null
             : await readResourceGeneration(branchRoot, SCHEMA_GENERATION_RESOURCE);
-        const result = await this.resolveFresh(contentRoot, entrySchemaRegistry);
+        // Nested under `schema`, so a request summary names a cache miss (`…schema>resolve`).
+        const result = await timeRequestPhase('resolve', () => this.resolveFresh(contentRoot, entrySchemaRegistry));
         // Validate schema has content
         if (!isValidSchema(result.schema)) {
             throw new Error(`No schema found in ${contentRoot}. Create .collection.json files ` +
@@ -166,11 +184,11 @@ export class BranchSchemaCache {
         // Use configured contentRoot name as base path for logical paths
         const flatSchema = flattenSchema(result.schema, contentRootName);
         if (!skipDiskCache) {
-            const cacheDir = path.join(branchRoot, '.canopy-meta');
-            const cachePath = path.join(cacheDir, 'schema-cache.json');
+            const cacheDir = await schemaCacheDir(branchRoot);
+            const cachePath = path.join(cacheDir, SCHEMA_CACHE_FILE);
             // Opportunistic cleanup of the retired .stale marker file, which a
             // mid-flight deploy can leave behind. Not load-bearing.
-            await fs.unlink(path.join(cacheDir, 'schema-cache.stale')).catch(() => { });
+            await fs.unlink(path.join(branchRoot, CANOPY_META_DIR, 'schema-cache.stale')).catch(() => { });
             if (read && read.ok) {
                 const newCache = {
                     version: SCHEMA_CACHE_VERSION,
@@ -180,7 +198,7 @@ export class BranchSchemaCache {
                     generation: read.token,
                 };
                 // Temp file then rename, with the temp file unlinked on a failed
-                // rename so a transient error leaves no stray `.tmp` in `.canopy-meta/`.
+                // rename so a transient error leaves no stray `.tmp` beside the cache.
                 await fs.mkdir(cacheDir, { recursive: true });
                 const tmpPath = path.join(cacheDir, `schema-cache.tmp.${Date.now()}.${Math.random()}.json`);
                 await fs.writeFile(tmpPath, JSON.stringify(newCache, null, 2), 'utf-8');

package/dist/branch-sparse.d.ts

@@ -0,0 +1,23 @@
+import type { CanopyConfig } from './config/index.js';
+/**
+ * The cone a content branch's clone checks out for `contentRoot`, sorted as
+ * `git sparse-checkout list` prints it, or null for a full clone when the content root is the
+ * repository root.
+ */
+export declare function sparseConeFor(contentRoot: string | undefined): string[] | null;
+export declare function sameCone(a: readonly string[] | null, b: readonly string[] | null): boolean;
+export interface RecordedSparseCone {
+    cone: string[] | null;
+}
+/** The recorded cone, or undefined when none is recorded or the record does not parse. */
+export declare function readRecordedSparseCone(contentBranchesRoot: string): Promise<RecordedSparseCone | undefined>;
+/**
+ * Record `cone` unless it already is, by temp file and rename. Does not create the branches
+ * root: a deployment without one has no clones to re-apply a cone to.
+ */
+export declare function recordSparseCone(contentBranchesRoot: string, cone: string[] | null): Promise<void>;
+/**
+ * Record the cone `config` asks for, once per process start, so a changed content root reaches
+ * existing clones without waiting for a new branch. Best-effort: a failure is logged.
+ */
+export declare function recordConfiguredSparseCone(config: CanopyConfig): Promise<void>;