canopycms 0.0.68-int.98 → 0.1.0

package/dist/utils/markdown-body-splice.js

@@ -0,0 +1,421 @@
+/**
+ * Source-preserving save for md/mdx bodies.
+ *
+ * The editor sends a body re-serialised from its own document model, so every block comes back
+ * in the serialiser's style (bullet and emphasis markers, rule style, escapes, no blank line
+ * after the frontmatter) whether or not the user touched it. This writes the on-disk text of
+ * every block whose MEANING the edit left alone, and the editor's text only where it changed:
+ *
+ * - Top-level blocks are aligned by a position-free canonical form of their mdast, so a block
+ *   matches only when it parses to the same tree. A matched block is written from disk.
+ * - A changed block paired with an original of the same kind is spliced by its children when it
+ *   is a list (by item) or a list item (by child block), at any depth, so editing one item leaves
+ *   its siblings alone. New items take the original list's marker and numbering.
+ * - Whitespace between two output blocks that stand for adjacent on-disk blocks (an edited block
+ *   stands for the original it is paired with) is the disk's; elsewhere it is the editor's,
+ *   re-indented into the original's nesting and written in its line endings.
+ *
+ * The result is kept only if it parses to exactly the tree the editor's body parses to. A splice
+ * that fails that check is retried without descending into lists, and failing that the editor's
+ * body is written as sent: the worst case is the editor's own serialisation, never different
+ * content.
+ */
+import { fromMarkdown } from 'mdast-util-from-markdown';
+import { gfmFromMarkdown } from 'mdast-util-gfm';
+import { mdxFromMarkdown } from 'mdast-util-mdx';
+import { gfm } from 'micromark-extension-gfm';
+import { mdxjs } from 'micromark-extension-mdxjs';
+import { createDebugLogger } from './debug.js';
+import { getErrorMessage } from './error.js';
+import { withSourceLineEndings } from './yaml-source-splice.js';
+const log = createDebugLogger({ prefix: 'MarkdownBodySplice' });
+/** Above this many LCS cells the middle of a sequence is treated as one changed run. */
+const MAX_LCS_CELLS = 4_000_000;
+function parse(text, format) {
+    try {
+        return format === 'mdx'
+            ? fromMarkdown(text, {
+                extensions: [gfm(), mdxjs()],
+                mdastExtensions: [gfmFromMarkdown(), mdxFromMarkdown()],
+            })
+            : fromMarkdown(text, { extensions: [gfm()], mdastExtensions: [gfmFromMarkdown()] });
+    }
+    catch (err) {
+        log.debug('markdown-body-splice', 'body does not parse', { error: getErrorMessage(err) });
+        return undefined;
+    }
+}
+/**
+ * A node's meaning as a string: its tree without source positions. `data` goes too, because
+ * the parser fills it only with derived information (an MDX expression's estree, which carries
+ * its own offsets) and never with content. Line endings inside values are normalised, so a CRLF
+ * file's blocks match the editor's LF ones. A bare URL and `[url](url)` share a tree, which keeps
+ * a bare URL on disk when the editor (whose `linkPlugin()` autolinks, in `MarkdownField.tsx`) sends it back as a link.
+ */
+function canonical(node) {
+    return JSON.stringify(node, (key, value) => {
+        if (key === 'position' || key === 'data')
+            return undefined;
+        if (typeof value === 'string')
+            return value.replace(/\r\n?/g, '\n');
+        return value;
+    });
+}
+/**
+ * `text`'s top-level blocks, each as its source text and its `canonical` form, or undefined when
+ * `text` does not parse: two bodies mean the same to the splice exactly when their `meaning`
+ * lists are equal.
+ *
+ * @internal Exported for the round-trip corpus test.
+ */
+export function markdownBlocks(text, format) {
+    return parse(text, format)?.children?.map((node) => ({
+        text: sliceOf(text, node) ?? '',
+        meaning: canonical(node),
+    }));
+}
+/** What a changed block must share with an original to be paired with it. */
+function kindOf(node) {
+    return `${node.type}:${String(node.ordered ?? '')}:${String(node.checked ?? '')}`;
+}
+function startOf(node) {
+    return node?.position?.start.offset;
+}
+function endOf(node) {
+    return node?.position?.end.offset;
+}
+function sliceOf(text, node) {
+    const start = startOf(node);
+    const end = endOf(node);
+    return start === undefined || end === undefined ? undefined : text.slice(start, end);
+}
+/**
+ * Move continuation lines from one nesting to another: a line starting with `from` gets `to`
+ * instead. The first line is never touched (it continues whatever precedes it), and neither is
+ * an empty line, which would otherwise gain trailing spaces.
+ */
+function reindent(text, from, to) {
+    if (from === to)
+        return text;
+    return text
+        .split('\n')
+        .map((line, i) => i > 0 && line !== '' && line.startsWith(from) ? to + line.slice(from.length) : line)
+        .join('\n');
+}
+/**
+ * Index pairs of a longest common subsequence of `a` and `b`, in order. Common prefix and suffix
+ * are matched first, which is the whole answer for the usual one-region edit.
+ */
+function matchSequences(keysA, keysB) {
+    // Compared as small integers: the DP compares O(n * m) pairs, and keys are whole serialised trees.
+    const ids = new Map();
+    const intern = (key) => {
+        const id = ids.get(key) ?? ids.size;
+        ids.set(key, id);
+        return id;
+    };
+    const a = keysA.map(intern);
+    const b = keysB.map(intern);
+    const pairs = [];
+    let head = 0;
+    while (head < a.length && head < b.length && a[head] === b[head]) {
+        pairs.push([head, head]);
+        head++;
+    }
+    let endA = a.length;
+    let endB = b.length;
+    while (endA > head && endB > head && a[endA - 1] === b[endB - 1]) {
+        endA--;
+        endB--;
+    }
+    const n = endA - head;
+    const m = endB - head;
+    if (n > 0 && m > 0 && n * m <= MAX_LCS_CELLS) {
+        const width = m + 1;
+        // lengths[i * width + j]: LCS length of a[head + i, endA) and b[head + j, endB).
+        const lengths = new Uint32Array((n + 1) * width);
+        const at = (i, j) => lengths[i * width + j] ?? 0;
+        for (let i = n - 1; i >= 0; i--) {
+            for (let j = m - 1; j >= 0; j--) {
+                lengths[i * width + j] =
+                    a[head + i] === b[head + j] ? at(i + 1, j + 1) + 1 : Math.max(at(i + 1, j), at(i, j + 1));
+            }
+        }
+        let i = 0;
+        let j = 0;
+        while (i < n && j < m) {
+            if (a[head + i] === b[head + j]) {
+                pairs.push([head + i, head + j]);
+                i++;
+                j++;
+            }
+            else if (at(i + 1, j) >= at(i, j + 1)) {
+                i++;
+            }
+            else {
+                j++;
+            }
+        }
+    }
+    for (let k = 0; k < a.length - endA; k++)
+        pairs.push([endA + k, endB + k]);
+    return pairs;
+}
+/**
+ * The text a line has before `offset`, provided it is pure indentation plus list markers: the
+ * width continuation lines of a block starting at `offset` are indented by. Undefined for a tab
+ * or any other character, whose width this module does not reason about.
+ */
+function leadWidth(text, offset) {
+    const lineStart = text.lastIndexOf('\n', offset - 1) + 1;
+    const lead = text.slice(lineStart, offset);
+    return /^(?: |[-*+](?= )|\d{1,9}[.)](?= )|\[[ xX]\](?= ))*$/.test(lead) ? lead.length : undefined;
+}
+class Splicer {
+    constructor(original, updated, 
+    /** Whether a changed list or list item may be spliced by its children. */
+    deep) {
+        this.original = original;
+        this.updated = updated;
+        this.deep = deep;
+        this.eol = withSourceLineEndings('\n', original);
+    }
+    /** The whole body, or undefined when either side has nothing to align. */
+    body(before, after) {
+        const oNodes = before.children ?? [];
+        const nNodes = after.children ?? [];
+        const first = startOf(oNodes[0]);
+        const last = endOf(oNodes[oNodes.length - 1]);
+        if (first === undefined || last === undefined || nNodes.length === 0)
+            return undefined;
+        const o = { text: this.original, indent: '' };
+        const n = { text: this.updated, indent: '' };
+        const pieces = this.siblings(o, oNodes, n, nNodes);
+        if (pieces === undefined)
+            return undefined;
+        const run = this.join(pieces, o, oNodes, n, nNodes);
+        return run === undefined
+            ? undefined
+            : this.original.slice(0, first) + run + this.original.slice(last);
+    }
+    /** Output blocks for one sibling sequence, in the editor's order. */
+    siblings(o, oNodes, n, nNodes) {
+        const oKeys = oNodes.map(canonical);
+        const nKeys = nNodes.map(canonical);
+        const pairs = matchSequences(oKeys, nKeys);
+        // Originals the alignment left unmatched, by meaning: an in-order alignment cannot match a
+        // block that MOVED, so a new block equal to one of these is written from its source here.
+        const unmatched = new Map();
+        const matched = new Set(pairs.map(([oi]) => oi));
+        oKeys.forEach((key, index) => {
+            if (matched.has(index))
+                return;
+            const bucket = unmatched.get(key);
+            if (bucket)
+                bucket.push(index);
+            else
+                unmatched.set(key, [index]);
+        });
+        const pieces = [];
+        let oNext = 0;
+        let nNext = 0;
+        for (const [oi, ni] of [...pairs, [oNodes.length, nNodes.length]]) {
+            // The changed run between two matches. Its blocks pair by kind, in order: an in-place
+            // edit, possibly beside insertions and deletions. A paired block stands in its original's
+            // place for whitespace, and may be spliced by its children.
+            const kinds = matchSequences(oNodes.slice(oNext, oi).map(kindOf), nNodes.slice(nNext, ni).map(kindOf));
+            const partner = new Map(kinds.map(([a, b]) => [nNext + b, oNext + a]));
+            for (let k = nNext; k < ni; k++) {
+                const nNode = nNodes[k];
+                if (nNode === undefined)
+                    return undefined;
+                const moved = unmatched.get(nKeys[k] ?? '')?.shift();
+                const movedNode = moved === undefined ? undefined : oNodes[moved];
+                if (movedNode !== undefined) {
+                    const text = sliceOf(o.text, movedNode);
+                    if (text === undefined)
+                        return undefined;
+                    pieces.push({ text, orig: moved });
+                    continue;
+                }
+                const oIndex = partner.get(k);
+                const oNode = oIndex === undefined ? undefined : oNodes[oIndex];
+                const text = (oNode && this.deep ? this.changed(o, oNode, n, nNode) : undefined) ??
+                    this.fresh(n, nNode, o);
+                if (text === undefined)
+                    return undefined;
+                pieces.push({ text, orig: oIndex });
+            }
+            const oNode = oNodes[oi];
+            if (oNode !== undefined && ni < nNodes.length) {
+                const text = sliceOf(o.text, oNode);
+                if (text === undefined)
+                    return undefined;
+                pieces.push({ text, orig: oi });
+            }
+            oNext = oi + 1;
+            nNext = ni + 1;
+        }
+        return pieces;
+    }
+    /** The editor's text for a node, moved into the original's nesting and line endings. */
+    fresh(n, node, o) {
+        const text = sliceOf(n.text, node);
+        return text === undefined ? undefined : this.ownEndings(reindent(text, n.indent, o.indent));
+    }
+    /** Whitespace from the editor's body, moved into the original's nesting and line endings. */
+    editorGap(gap, n, o) {
+        return gap === undefined ? undefined : this.ownEndings(reindent(gap, n.indent, o.indent));
+    }
+    ownEndings(text) {
+        const lf = text.replace(/\r\n?/g, '\n');
+        return this.eol === '\n' ? lf : lf.replace(/\n/g, this.eol);
+    }
+    /** A changed node spliced by its children, or undefined to write the editor's text. */
+    changed(o, oNode, n, nNode) {
+        if (oNode.type === 'list' && nNode.type === 'list' && oNode.ordered === nNode.ordered) {
+            return this.list(o, oNode, n, nNode);
+        }
+        if (oNode.type === 'listItem' &&
+            nNode.type === 'listItem' &&
+            (oNode.checked ?? null) === (nNode.checked ?? null)) {
+            return this.item(o, oNode, n, nNode);
+        }
+        return undefined;
+    }
+    list(o, oList, n, nList) {
+        const oItems = oList.children ?? [];
+        const nItems = nList.children ?? [];
+        const markers = listMarkers(o.text, oItems, Boolean(oList.ordered));
+        if (markers === undefined)
+            return undefined;
+        const pieces = this.siblings(o, oItems, n, nItems);
+        if (pieces === undefined)
+            return undefined;
+        for (const [index, piece] of pieces.entries()) {
+            const text = markers(piece.text, index);
+            if (text === undefined)
+                return undefined;
+            piece.text = text;
+        }
+        return this.join(pieces, o, oItems, n, nItems);
+    }
+    item(o, oItem, n, nItem) {
+        const oChildren = oItem.children ?? [];
+        const nChildren = nItem.children ?? [];
+        const oStart = startOf(oItem);
+        const oContent = startOf(oChildren[0]);
+        const nContent = startOf(nChildren[0]);
+        if (oStart === undefined || oContent === undefined || nContent === undefined)
+            return undefined;
+        const prefix = o.text.slice(oStart, oContent);
+        if (prefix.includes('\n'))
+            return undefined;
+        const oWidth = leadWidth(o.text, oContent);
+        const nWidth = leadWidth(n.text, nContent);
+        if (oWidth === undefined || nWidth === undefined)
+            return undefined;
+        const oInner = { text: o.text, indent: ' '.repeat(oWidth) };
+        const nInner = { text: n.text, indent: ' '.repeat(nWidth) };
+        const pieces = this.siblings(oInner, oChildren, nInner, nChildren);
+        if (pieces === undefined)
+            return undefined;
+        const run = this.join(pieces, oInner, oChildren, nInner, nChildren);
+        return run === undefined ? undefined : prefix + run;
+    }
+    /**
+     * Join output blocks. Between two blocks that were adjacent on disk the disk's whitespace is
+     * kept; otherwise the editor's (every output block pair is adjacent in the editor's body).
+     */
+    join(pieces, o, oNodes, n, nNodes) {
+        let out = '';
+        for (const [k, piece] of pieces.entries()) {
+            if (k > 0) {
+                const prev = pieces[k - 1]?.orig;
+                const gap = prev !== undefined && piece.orig === prev + 1
+                    ? gapBetween(o.text, oNodes[prev], oNodes[piece.orig])
+                    : this.editorGap(gapBetween(n.text, nNodes[k - 1], nNodes[k]), n, o);
+                if (gap === undefined)
+                    return undefined;
+                out += gap;
+            }
+            out += piece.text;
+        }
+        return out;
+    }
+}
+function gapBetween(text, a, b) {
+    const end = endOf(a);
+    const start = startOf(b);
+    return end === undefined || start === undefined ? undefined : text.slice(end, start);
+}
+/**
+ * Rewrites an output item's marker to the original list's: its bullet character, or for an
+ * ordered list its delimiter and numbering scheme (all one number when the original's first two
+ * items share one, else counting up from its start). Undefined when the original's markers
+ * cannot be read, or when renumbering would change the width of a multi-line item, whose
+ * continuation lines are aligned to the old width.
+ */
+function listMarkers(text, items, ordered) {
+    const firstStart = startOf(items[0]);
+    if (firstStart === undefined)
+        return undefined;
+    if (!ordered) {
+        const bullet = text[firstStart];
+        if (bullet !== '-' && bullet !== '*' && bullet !== '+')
+            return undefined;
+        return (itemText) => (/^[-*+]/.test(itemText) ? bullet + itemText.slice(1) : undefined);
+    }
+    const numberAt = (offset) => offset === undefined ? null : /^(\d{1,9})([.)])/.exec(text.slice(offset, offset + 10));
+    const first = numberAt(firstStart);
+    if (first === null)
+        return undefined;
+    const start = Number(first[1]);
+    const delimiter = first[2] ?? '.';
+    // `01.`, `02.`: zero-padded to the first marker's width.
+    const padTo = first[1]?.startsWith('0') ? first[1].length : 0;
+    const second = items.length > 1 ? numberAt(startOf(items[1])) : null;
+    const step = second !== null && Number(second[1]) === start ? 0 : 1;
+    return (itemText, index) => {
+        const current = /^\d{1,9}[.)]/.exec(itemText);
+        if (current === null)
+            return undefined;
+        const marker = `${String(start + step * index).padStart(padTo, '0')}${delimiter}`;
+        if (marker.length !== current[0].length && itemText.includes('\n'))
+            return undefined;
+        return marker + itemText.slice(current[0].length);
+    };
+}
+/**
+ * The body to write for an edit from `original` (on disk) to `updated` (the editor's body):
+ * `updated`'s content, in `original`'s text wherever the two agree. See the module header.
+ */
+export function preserveMarkdownSource(original, updated, format) {
+    if (original === updated)
+        return original;
+    try {
+        return splice(original, updated, format) ?? updated;
+    }
+    catch (err) {
+        // A deep enough body overflows the stack in parsing or serialising; a save must not fail.
+        log.debug('markdown-body-splice', 'splice failed', { error: getErrorMessage(err) });
+        return updated;
+    }
+}
+function splice(original, updated, format) {
+    const before = parse(original, format);
+    const after = parse(updated, format);
+    if (before === undefined || after === undefined)
+        return undefined;
+    const target = canonical(after);
+    for (const deep of [true, false]) {
+        const candidate = new Splicer(original, updated, deep).body(before, after);
+        if (candidate === undefined)
+            continue;
+        const reparsed = parse(candidate, format);
+        if (reparsed !== undefined && canonical(reparsed) === target)
+            return candidate;
+        log.debug('markdown-body-splice', 'splice does not read back as the edit', { deep });
+    }
+    return undefined;
+}

package/dist/utils/occ-json-write.js

@@ -4,6 +4,8 @@ import { randomUUID } from 'node:crypto';
 import lockfile from 'proper-lockfile';
 import { getErrorMessage, isFileExistsError, isNodeError } from './error.js';
 import { createDebugLogger } from './debug.js';
+import { canopyLogWarn } from './logger.js';
+import { guardOnCompromised } from './provisioning-lock.js';
 const log = createDebugLogger({ prefix: 'OccJsonWrite' });
 /**
  * Shared optimistic-concurrency-control (OCC) JSON write machinery, extracted
@@ -158,8 +160,16 @@ export async function withOccRetry(operation, options) {
  * legitimately take many seconds.
  */
 export async function withOccFileLock(filePath, fn) {
-    const dir = path.dirname(filePath);
-    await fs.mkdir(dir, { recursive: true });
+    // The lock's own directory only, never its ancestors: a waiter must not recreate a branch root
+    // that a delete removed under it (the same rule as the ENOENT case in the loop below).
+    try {
+        await fs.mkdir(path.dirname(filePath));
+    }
+    catch (err) {
+        if (!isNodeError(err) || err.code !== 'EEXIST') {
+            throw new OccWriteConflictError(`Could not acquire file lock: ${getErrorMessage(err)}`);
+        }
+    }
     // Acquisition retries are OUR loop, not proper-lockfile's built-in
     // `retries`: the built-in loop retries blindly on ANY error, so a waiter
     // whose target directory was deleted mid-poll (deleteBranch's rm removing
@@ -191,16 +201,12 @@ export async function withOccFileLock(filePath, fn) {
                 realpath: false,
                 stale: 10_000,
                 retries: 0,
-                // A compromised lock (the lock dir vanished or refresh failed
-                // mid-hold, e.g. the branch directory containing it was deleted)
-                // must not crash the process, which is proper-lockfile's default.
-                // Our critical sections are short and idempotent-on-conflict (OCC
-                // verify inside); log and let the section finish.
-                onCompromised: (err) => {
-                    log.warn('lock', `Lock compromised mid-hold for ${filePath}`, {
-                        error: getErrorMessage(err),
-                    });
-                },
+                // A compromised lock (the lock dir vanished or refresh failed mid-hold, e.g. the branch
+                // directory containing it was deleted, or an EFS waiter misread a cached mtime and took
+                // it over) must not crash the process, which is proper-lockfile's default. Our critical
+                // sections are short and idempotent-on-conflict (OCC verify inside); log and let the
+                // section finish.
+                onCompromised: guardOnCompromised((err) => canopyLogWarn(`[canopy] OCC file lock compromised mid-hold for ${filePath}:`, getErrorMessage(err)), filePath),
             });
         }
         catch (err) {

package/dist/utils/provision-log.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Replace where step lines go; no argument restores `canopyLog`. The test
+ * setup silences them, since nearly every suite provisions a workspace.
+ * @internal Exported for tests.
+ */
+export declare function setProvisionLogSink(next?: (line: string) => void): void;
+/**
+ * Per-step timing for one workspace provisioning, printed unconditionally
+ * (never behind `CANOPYCMS_DEBUG`). A request killed mid-step, such as a Lambda
+ * at its timeout, never reaches its own error handling, so each step prints a
+ * `start` line and a `done` line: the last line in the log names the step that
+ * was running.
+ *
+ * Lines read `[canopy] provision id=<id> dir=<dir> step=<step> start|done ms=<n>|failed ms=<n>`,
+ * then one `outcome=<outcome> total=<ms> <step>=<ms> …` summary.
+ */
+export declare class ProvisionLog {
+    readonly id: string;
+    private readonly startedAt;
+    private readonly durations;
+    private readonly prefix;
+    constructor(dir: string);
+    step<T>(name: string, run: () => Promise<T>): Promise<T>;
+    finish(outcome: string): void;
+}

package/dist/utils/provision-log.js

@@ -0,0 +1,49 @@
+import { randomBytes } from 'node:crypto';
+import { canopyLog } from './logger.js';
+const defaultSink = (line) => canopyLog(line);
+let sink = defaultSink;
+/**
+ * Replace where step lines go; no argument restores `canopyLog`. The test
+ * setup silences them, since nearly every suite provisions a workspace.
+ * @internal Exported for tests.
+ */
+export function setProvisionLogSink(next) {
+    sink = next ?? defaultSink;
+}
+/**
+ * Per-step timing for one workspace provisioning, printed unconditionally
+ * (never behind `CANOPYCMS_DEBUG`). A request killed mid-step, such as a Lambda
+ * at its timeout, never reaches its own error handling, so each step prints a
+ * `start` line and a `done` line: the last line in the log names the step that
+ * was running.
+ *
+ * Lines read `[canopy] provision id=<id> dir=<dir> step=<step> start|done ms=<n>|failed ms=<n>`,
+ * then one `outcome=<outcome> total=<ms> <step>=<ms> …` summary.
+ */
+export class ProvisionLog {
+    constructor(dir) {
+        this.id = randomBytes(3).toString('hex');
+        this.startedAt = Date.now();
+        this.durations = [];
+        this.prefix = `[canopy] provision id=${this.id} dir=${dir}`;
+    }
+    async step(name, run) {
+        sink(`${this.prefix} step=${name} start`);
+        const stepStartedAt = Date.now();
+        let state = 'failed';
+        try {
+            const result = await run();
+            state = 'done';
+            return result;
+        }
+        finally {
+            const ms = Date.now() - stepStartedAt;
+            this.durations.push(`${name}=${ms}`);
+            sink(`${this.prefix} step=${name} ${state} ms=${ms}`);
+        }
+    }
+    finish(outcome) {
+        const total = Date.now() - this.startedAt;
+        sink(`${this.prefix} outcome=${outcome} total=${total} ${this.durations.join(' ')}`.trim());
+    }
+}

package/dist/utils/provisioning-lock.d.ts

@@ -9,6 +9,23 @@
  * inside the refresh timer, so a throw is an uncaught exception that kills the process.
  */
 export type OnLockCompromised = (err: Error) => void;
+/**
+ * Wrap a compromise handler for proper-lockfile's `onCompromised`, which it invokes from inside
+ * its refresh timer: ANY throw escaping there is an uncaught exception that kills the process.
+ * Call sites are told not to throw (see {@link OnLockCompromised}); this makes it structural
+ * rather than a convention, and also covers the LOGGER throwing -- under `CI=true`, vitest's
+ * `onConsoleLog` turns a console write into a throw.
+ *
+ * Handlers report through an always-on logger (`canopyLogWarn`), never the debug logger: "two
+ * holders may now be live" must be visible without CANOPYCMS_DEBUG.
+ */
+export declare function guardOnCompromised(handler: OnLockCompromised, lockPath: string): OnLockCompromised;
+/**
+ * When an acquirer may take a provisioning marker over. Staleness is read from the marker's mtime,
+ * which EFS serves from the NFS attribute cache for up to 60s, so a live holder's 15s refreshes
+ * can look 60s late; one threshold above that for every acquirer means none reaps a live hold.
+ */
+export declare const PROVISIONING_LOCK_STALE_MS = 90000;
 /**
  * The provisioning lock's name for the branch workspace directory `dirName`, held in that
  * directory's parent. Every party to a branch workspace's provisioning names it through this:
@@ -44,5 +61,19 @@ export declare function acquireProvisioningLock(lockTargetDir: string, lockName:
  *
  * @param staleMs how old the marker must look before this caller takes it over; defaults to
  *   {@link PROVISIONING_LOCK_STALE_MS}
+ * @param createParents whether a missing parent of `lockTargetDir` is created. A lock inside a
+ *   branch passes false: a waiter must never recreate a branch root a delete removed, so a missing
+ *   parent fails with ENOENT instead.
+ */
+export declare function tryAcquireProvisioningLock(lockTargetDir: string, lockName: string, onCompromised?: OnLockCompromised, staleMs?: number, createParents?: boolean): Promise<() => Promise<void>>;
+/**
+ * {@link tryAcquireProvisioningLock} retried for at most `waitMs`, for a caller whose own hold is
+ * milliseconds long (publishing a staged branch workspace). A dead holder's marker stays live for
+ * {@link PROVISIONING_LOCK_STALE_MS}, so waiting it out from a request would spend the request's
+ * whole timeout; this gives up instead.
+ *
+ * Retries only on `ELOCKED`, like the content-write lock's bounded wait.
+ *
+ * @throws the last `ELOCKED` error once the budget is spent
  */
-export declare function tryAcquireProvisioningLock(lockTargetDir: string, lockName: string, onCompromised?: OnLockCompromised, staleMs?: number): Promise<() => Promise<void>>;
+export declare function acquireProvisioningLockWithin(lockTargetDir: string, lockName: string, waitMs: number, onCompromised?: OnLockCompromised): Promise<() => Promise<void>>;