canopycms 0.0.67 → 0.0.68-int.100

package/dist/utils/debug.js

@@ -55,6 +55,10 @@ export class DebugLogger {
             throw new Error(errorMsg);
         }
     }
+    /**
+     * Keyed by label alone, so two overlapping timers with one label overwrite each other;
+     * anything that can run concurrently uses {@link timed}.
+     */
     time(label) {
         this.timers.set(label, Date.now());
     }
@@ -69,13 +73,17 @@ export class DebugLogger {
         this.debug(category, `${label} completed`, { durationMs: duration });
         return duration;
     }
+    /**
+     * Log `<label> completed {durationMs}` once `fn` settles. The start time is local to the
+     * call, so concurrent spans with the same label on one logger never overwrite each other.
+     */
     async timed(category, label, fn) {
-        this.time(label);
+        const start = Date.now();
         try {
             return await fn();
         }
         finally {
-            this.timeEnd(category, label);
+            this.debug(category, `${label} completed`, { durationMs: Date.now() - start });
         }
     }
 }

package/dist/utils/git.d.ts

@@ -1,3 +1,4 @@
+import { type SimpleGit } from 'simple-git';
 import type { OperatingMode } from '../operating-mode/index.js';
 /**
  * Whether a git remote URL points at a network location rather than a local filesystem path. Only
@@ -39,6 +40,15 @@ export declare function isNonFastForwardRejection(message: string): boolean;
  * surfacing as the permanent, human-actionable state it is. Same locale caveat as above.
  */
 export declare function isStaleLeaseRejection(message: string): boolean;
+/**
+ * The workflow file named by GitHub's refusal of a push that would add workflow content the
+ * credential lacks the workflows permission for, or null if the message is not that refusal.
+ *
+ * GitHub refuses only content it does not already hold: carrying a base-branch workflow change by
+ * rebase, merge or fast-forward is accepted. Retrying the identical push can never succeed, so the
+ * worker fails it fast. The text is GitHub's own, not git's, so no locale pinning is needed.
+ */
+export declare function workflowPushRefusalFile(message: string): string | null;
 /**
  * Whether a `git fetch <remote> <branch>` failure is specifically "that ref doesn't exist on the
  * remote" -- the ONLY benign fetch outcome, meaning the branch has never been pushed.
@@ -50,6 +60,28 @@ export declare function isStaleLeaseRejection(message: string): boolean;
  * caveat as the predicates above.
  */
 export declare function isMissingRemoteRefFailure(message: string): boolean;
+/**
+ * The directory, at every workspace root, holding canopycms's own per-workspace state: branch
+ * metadata, comments, generation markers and lock markers. None of it is content, so it never
+ * belongs in a commit.
+ */
+export declare const CANOPY_META_DIR = ".canopy-meta";
+/**
+ * Whether a repo-relative path from `git status` / `git ls-files` is {@link CANOPY_META_DIR}
+ * or lies under it.
+ */
+export declare function isCanopyInternalPath(repoRelativePath: string): boolean;
+/**
+ * Stage every working-tree change (additions, edits, deletions) except anything under
+ * {@link CANOPY_META_DIR}, including files an adopter committed there by mistake. Stage-all then
+ * unstage, because git rejects `:(exclude)` pathspecs (six spellings tried) with "paths are ignored" when
+ * the excluded directory is itself ignored, which `.git/info/exclude` makes it in every clone.
+ *
+ * `--sparse`: in a sparse clone a plain `add -A` fails on any file present outside the cone.
+ * With it, such a file is staged like any other, and a tracked file absent only because it is
+ * outside the cone is still not staged as a deletion. A no-op in a full clone.
+ */
+export declare function stageAllExceptCanopyState(git: SimpleGit): Promise<void>;
 /**
  * Whether a repository has an INTERRUPTED rebase on disk — the `rebase-merge` (interactive/merge
  * backend) or `rebase-apply` (am backend) state directory git leaves when a rebase stops for

package/dist/utils/git.js

@@ -88,6 +88,21 @@ const STALE_LEASE_REASON = 'stale info';
 export function isStaleLeaseRejection(message) {
     return message.includes(REJECTED_MARKER) && message.includes(STALE_LEASE_REASON);
 }
+// GitHub's reason text when a push would introduce workflow content the credential may not write.
+// It names the credential kind ("a GitHub App", "an OAuth App", ...) and then the file.
+// Both classes stop at a newline, so the match stays on the one status line that carries it.
+const WORKFLOW_REFUSAL_PATTERN = /refusing to allow an? [^`\n]+? to create or update workflow `([^`\n]+)`/;
+/**
+ * The workflow file named by GitHub's refusal of a push that would add workflow content the
+ * credential lacks the workflows permission for, or null if the message is not that refusal.
+ *
+ * GitHub refuses only content it does not already hold: carrying a base-branch workflow change by
+ * rebase, merge or fast-forward is accepted. Retrying the identical push can never succeed, so the
+ * worker fails it fast. The text is GitHub's own, not git's, so no locale pinning is needed.
+ */
+export function workflowPushRefusalFile(message) {
+    return WORKFLOW_REFUSAL_PATTERN.exec(message)?.[1] ?? null;
+}
 // git's message when `git fetch <remote> <branch>` names a ref the remote does not have. Both
 // spellings occur: modern git prints the lowercase form, older versions and some transports
 // capitalize it.
@@ -135,6 +150,33 @@ async function resolveGitDir(repoPath) {
         return null;
     }
 }
+/**
+ * The directory, at every workspace root, holding canopycms's own per-workspace state: branch
+ * metadata, comments, generation markers and lock markers. None of it is content, so it never
+ * belongs in a commit.
+ */
+export const CANOPY_META_DIR = '.canopy-meta';
+/**
+ * Whether a repo-relative path from `git status` / `git ls-files` is {@link CANOPY_META_DIR}
+ * or lies under it.
+ */
+export function isCanopyInternalPath(repoRelativePath) {
+    return repoRelativePath === CANOPY_META_DIR || repoRelativePath.startsWith(`${CANOPY_META_DIR}/`);
+}
+/**
+ * Stage every working-tree change (additions, edits, deletions) except anything under
+ * {@link CANOPY_META_DIR}, including files an adopter committed there by mistake. Stage-all then
+ * unstage, because git rejects `:(exclude)` pathspecs (six spellings tried) with "paths are ignored" when
+ * the excluded directory is itself ignored, which `.git/info/exclude` makes it in every clone.
+ *
+ * `--sparse`: in a sparse clone a plain `add -A` fails on any file present outside the cone.
+ * With it, such a file is staged like any other, and a tracked file absent only because it is
+ * outside the cone is still not staged as a deletion. A no-op in a full clone.
+ */
+export async function stageAllExceptCanopyState(git) {
+    await git.raw(['add', '-A', '--sparse']);
+    await git.raw(['reset', '-q', '--', CANOPY_META_DIR]);
+}
 /**
  * Whether a repository has an INTERRUPTED rebase on disk — the `rebase-merge` (interactive/merge
  * backend) or `rebase-apply` (am backend) state directory git leaves when a rebase stops for

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

@@ -158,8 +158,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

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,19 @@
  * inside the refresh timer, so a throw is an uncaught exception that kills the process.
  */
 export type OnLockCompromised = (err: Error) => void;
+/**
+ * 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:
+ * the Lambda while it clones, the admin purge, branch-health's freshness rail, and the worker
+ * while it refreshes or rebases.
+ */
+export declare function branchProvisioningLockName(dirName: string): string;
 /**
  * Acquire a cross-process filesystem lock for content provisioning. Returns a release function —
  * always call it in a `finally`.
@@ -27,12 +40,29 @@ export declare function acquireProvisioningLock(lockTargetDir: string, lockName:
  * request/response cycle (a Lambda-backed API handler). `acquireProvisioningLock`'s ~600-retry
  * budget waits minutes for a live provisioner; an admin request must fail fast instead.
  *
- * `stale: 30_000` is unchanged from the patient variant: a genuinely stale lock (holder crashed
- * more than 30s ago) is still taken over normally. Only the RETRY loop for live contention is
- * removed, not the staleness recovery a caller depends on -- see branch-health.ts's [H1]
- * freshness rail, which reads this lock's mtime before an admin purge/repair proceeds.
+ * Staleness recovery is unchanged from the patient variant: a genuinely stale lock is still taken
+ * over normally. Only the RETRY loop for live contention is removed, not the staleness recovery a
+ * caller depends on -- see branch-health.ts's [H1] freshness rail, which reads this lock's mtime
+ * before an admin purge/repair proceeds.
  *
  * Throws with `err.code === 'ELOCKED'` on contention (a live, non-stale holder) -- callers
  * translate that into a 409.
+ *
+ * @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): Promise<() => Promise<void>>;
+export declare function acquireProvisioningLockWithin(lockTargetDir: string, lockName: string, waitMs: number, onCompromised?: OnLockCompromised): Promise<() => Promise<void>>;

package/dist/utils/provisioning-lock.js

@@ -3,6 +3,12 @@ import path from 'node:path';
 import lockfile from 'proper-lockfile';
 import { getErrorMessage, isNodeError } from './error.js';
 import { canopyLogWarn } from './logger.js';
+/**
+ * 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 const PROVISIONING_LOCK_STALE_MS = 90_000;
 /**
  * Shared option set for both provisioning-lock variants.
  *
@@ -16,12 +22,14 @@ import { canopyLogWarn } from './logger.js';
  * share one. `realpath: false` because that anchor path does not exist before we create it
  * (realpath would ENOENT). See docs/concurrency.md ("Anchor path matters").
  */
-function provisioningLockOptions(lockPath, retries, onCompromised) {
+function provisioningLockOptions(lockPath, retries, onCompromised, staleMs) {
     return {
         lockfilePath: lockPath,
         realpath: false,
         retries,
-        stale: 30_000,
+        stale: staleMs,
+        // Fixed, not stale/2: every holder refreshes at 15s whatever threshold it judges others by.
+        update: 15_000,
         // proper-lockfile invokes this from inside its refresh timer, so ANY throw escaping here is
         // an uncaught exception that kills the process. Call sites are told not to throw (see
         // OnLockCompromised); this makes it structural rather than a convention, and also covers the
@@ -76,6 +84,15 @@ function releaseIgnoringAlreadyReleased(release, lockPath) {
         }
     };
 }
+/**
+ * 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:
+ * the Lambda while it clones, the admin purge, branch-health's freshness rail, and the worker
+ * while it refreshes or rebases.
+ */
+export function branchProvisioningLockName(dirName) {
+    return `.${dirName}.init.lock`;
+}
 /**
  * Acquire a cross-process filesystem lock for content provisioning. Returns a release function —
  * always call it in a `finally`.
@@ -94,9 +111,9 @@ export async function acquireProvisioningLock(lockTargetDir, lockName, onComprom
     // Generous, jittered retries: several processes may contend for one workspace (Lambda
     // containers cold-starting together against one EFS root), and the holder can take seconds to
     // init plus clone/push. `randomize` de-syncs the herd so a waiter is not perpetually colliding
-    // on the same tick. `stale` stays modest because proper-lockfile auto-refreshes a live holder's
-    // lock, so it expires only when a process actually dies.
-    const release = await lockfile.lock(lockPath, provisioningLockOptions(lockPath, { retries: 600, factor: 1, minTimeout: 300, maxTimeout: 800, randomize: true }, onCompromised));
+    // on the same tick. A live holder's lock never goes stale, because proper-lockfile refreshes it;
+    // it expires only when a process actually dies.
+    const release = await lockfile.lock(lockPath, provisioningLockOptions(lockPath, { retries: 600, factor: 1, minTimeout: 300, maxTimeout: 800, randomize: true }, onCompromised, PROVISIONING_LOCK_STALE_MS));
     return releaseIgnoringAlreadyReleased(release, lockPath);
 }
 /**
@@ -104,17 +121,61 @@ export async function acquireProvisioningLock(lockTargetDir, lockName, onComprom
  * request/response cycle (a Lambda-backed API handler). `acquireProvisioningLock`'s ~600-retry
  * budget waits minutes for a live provisioner; an admin request must fail fast instead.
  *
- * `stale: 30_000` is unchanged from the patient variant: a genuinely stale lock (holder crashed
- * more than 30s ago) is still taken over normally. Only the RETRY loop for live contention is
- * removed, not the staleness recovery a caller depends on -- see branch-health.ts's [H1]
- * freshness rail, which reads this lock's mtime before an admin purge/repair proceeds.
+ * Staleness recovery is unchanged from the patient variant: a genuinely stale lock is still taken
+ * over normally. Only the RETRY loop for live contention is removed, not the staleness recovery a
+ * caller depends on -- see branch-health.ts's [H1] freshness rail, which reads this lock's mtime
+ * before an admin purge/repair proceeds.
  *
  * Throws with `err.code === 'ELOCKED'` on contention (a live, non-stale holder) -- callers
  * translate that into a 409.
+ *
+ * @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 async function tryAcquireProvisioningLock(lockTargetDir, lockName, onCompromised) {
-    await fs.mkdir(lockTargetDir, { recursive: true });
+export async function tryAcquireProvisioningLock(lockTargetDir, lockName, onCompromised, staleMs = PROVISIONING_LOCK_STALE_MS, createParents = true) {
+    if (createParents) {
+        await fs.mkdir(lockTargetDir, { recursive: true });
+    }
+    else {
+        await fs.mkdir(lockTargetDir).catch((err) => {
+            if (!isNodeError(err) || err.code !== 'EEXIST')
+                throw err;
+        });
+    }
     const lockPath = path.join(lockTargetDir, lockName);
-    const release = await lockfile.lock(lockPath, provisioningLockOptions(lockPath, 0, onCompromised));
+    const release = await lockfile.lock(lockPath, provisioningLockOptions(lockPath, 0, onCompromised, staleMs));
     return releaseIgnoringAlreadyReleased(release, lockPath);
 }
+const sleep = (ms) => new Promise((resolve) => {
+    setTimeout(resolve, ms);
+});
+/**
+ * {@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 async function acquireProvisioningLockWithin(lockTargetDir, lockName, waitMs, onCompromised) {
+    const startedAt = Date.now();
+    for (let attempt = 0;; attempt++) {
+        try {
+            return await tryAcquireProvisioningLock(lockTargetDir, lockName, onCompromised);
+        }
+        catch (err) {
+            if (!isNodeError(err) || err.code !== 'ELOCKED')
+                throw err;
+            const remaining = waitMs - (Date.now() - startedAt);
+            if (remaining <= 0)
+                throw err;
+            const base = Math.min(50 * 2 ** attempt, 500);
+            await sleep(Math.min(base * (0.5 + Math.random()), remaining));
+        }
+    }
+}

package/dist/utils/request-timing.d.ts

@@ -0,0 +1,25 @@
+interface PhaseTotal {
+    count: number;
+    ms: number;
+}
+/** Record `fn` as `phase` in the active request scope; outside one, just run it. */
+export declare function timeRequestPhase<T>(phase: string, fn: () => Promise<T>): Promise<T>;
+/**
+ * Whether a request scope is open here.
+ * @internal Exported for tests.
+ */
+export declare function isRequestTimingScopeActive(): boolean;
+/** Name the matched route (a pattern, never raw path segments) for the summary line. */
+export declare function setRequestTimingRoute(route: string): void;
+/**
+ * The summary line's message, after the logger's timestamp/category prefix:
+ * `GET :branch/entries 200 1172ms | context=0 auth=12 route=1110 route>settingsRoot=1080(x2) untimed=50`.
+ * @internal Exported for tests.
+ */
+export declare function formatRequestTimingSummary(method: string, route: string, status: number | 'error', totalMs: number, phases: ReadonlyMap<string, PhaseTotal>): string;
+/**
+ * Run one API request inside a timing scope and log its summary line when it settles,
+ * thrown or not. `statusOf` reads the status from the result.
+ */
+export declare function runWithRequestTiming<T>(method: string, fn: () => Promise<T>, statusOf: (result: T) => number): Promise<T>;
+export {};

package/dist/utils/request-timing.js

@@ -0,0 +1,101 @@
+/**
+ * Per-request phase timing for the API handler, enabled by `CANOPYCMS_DEBUG=true`.
+ *
+ * `runWithRequestTiming` opens a request scope in AsyncLocalStorage and, when the request
+ * finishes, emits ONE summary line: method, route pattern, status, total, and every phase
+ * recorded inside the scope. `timeRequestPhase` records a phase into whichever scope is
+ * active. Scopes are per async context, so concurrent requests in one process never share
+ * or overwrite a span, and a phase reached outside any request (the worker, a build, a
+ * page render) just runs its function.
+ *
+ * Disabled, `runWithRequestTiming` calls straight through without opening a scope, so each
+ * `timeRequestPhase` costs one `getStore()` that returns undefined.
+ *
+ * A phase started inside another records under the joined name (`route>settingsRoot`), so
+ * nesting stays visible and nested time is never added to its parent's siblings. A phase
+ * run several times in one request accumulates, and the line shows the count. `untimed` is
+ * the total minus the top-level phases, which run sequentially in the handler.
+ *
+ * Server-only: `node:async_hooks`.
+ */
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { createDebugLogger } from './debug.js';
+const storage = new AsyncLocalStorage();
+const log = createDebugLogger({ prefix: 'CanopyCMS' });
+/** Read per call, like DebugLogger, so toggling the env var needs no restart. */
+function isRequestTimingEnabled() {
+    return process.env.CANOPYCMS_DEBUG === 'true';
+}
+/** Record `fn` as `phase` in the active request scope; outside one, just run it. */
+export async function timeRequestPhase(phase, fn) {
+    const parent = storage.getStore();
+    if (!parent)
+        return fn();
+    const key = parent.path ? `${parent.path}>${phase}` : phase;
+    // Created at START so the summary lists phases in the order they began.
+    let total = parent.phases.get(key);
+    if (!total) {
+        total = { count: 0, ms: 0 };
+        parent.phases.set(key, total);
+    }
+    const start = performance.now();
+    try {
+        return await storage.run({ ...parent, path: key }, fn);
+    }
+    finally {
+        total.count += 1;
+        total.ms += performance.now() - start;
+    }
+}
+/**
+ * Whether a request scope is open here.
+ * @internal Exported for tests.
+ */
+export function isRequestTimingScopeActive() {
+    return storage.getStore() !== undefined;
+}
+/** Name the matched route (a pattern, never raw path segments) for the summary line. */
+export function setRequestTimingRoute(route) {
+    const scope = storage.getStore();
+    if (scope)
+        scope.request.route = route;
+}
+/**
+ * The summary line's message, after the logger's timestamp/category prefix:
+ * `GET :branch/entries 200 1172ms | context=0 auth=12 route=1110 route>settingsRoot=1080(x2) untimed=50`.
+ * @internal Exported for tests.
+ */
+export function formatRequestTimingSummary(method, route, status, totalMs, phases) {
+    let topLevelMs = 0;
+    const parts = [];
+    for (const [name, { count, ms }] of phases) {
+        if (!name.includes('>'))
+            topLevelMs += ms;
+        parts.push(`${name}=${Math.round(ms)}${count > 1 ? `(x${count})` : ''}`);
+    }
+    parts.push(`untimed=${Math.max(0, Math.round(totalMs - topLevelMs))}`);
+    return `${method} ${route} ${status} ${Math.round(totalMs)}ms | ${parts.join(' ')}`;
+}
+/**
+ * Run one API request inside a timing scope and log its summary line when it settles,
+ * thrown or not. `statusOf` reads the status from the result.
+ */
+export async function runWithRequestTiming(method, fn, statusOf) {
+    if (!isRequestTimingEnabled())
+        return fn();
+    const scope = {
+        phases: new Map(),
+        path: '',
+        request: { route: '(unmatched)' },
+    };
+    const start = performance.now();
+    let status = 'error';
+    try {
+        const result = await storage.run(scope, fn);
+        status = statusOf(result);
+        return result;
+    }
+    finally {
+        log.debug('timing', formatRequestTimingSummary(method, scope.request.route, status, performance.now() - start, scope.phases));
+    }
+}

package/dist/utils/sanitize-href.d.ts

@@ -55,36 +55,22 @@ export declare function neutralizeImplicitOffOrigin(url: string): string;
  * this file either way, so the two surfaces cannot drift into disagreeing about which schemes
  * are acceptable (that drift is exactly why `utils/url-prefix.ts` exists — see its header).
  *
- * `allowProtocolRelative` exists because the two callers genuinely differ, and the difference
- * is blast radius rather than taste:
- *
- * - A READ-side prefix (`media.publicBaseUrl`, joined onto `/assets/…`) may legitimately be
- *   `//cdn.example.com`. `utils/url-prefix.ts`'s `isAbsoluteUrl` documents that literal
- *   spelling as an intentionally-supported off-site pointer, so rejecting it here would break
- *   a working configuration. A bad value costs a broken `<img>`.
- * - A WRITE-side endpoint (`media.uploadUrl`, where the browser POSTs a presigned upload) must
- *   not be protocol-relative even when spelled literally, because such a URL is AMBIGUOUS: it
- *   resolves to http or https depending on the scheme of whichever editor page happens to
- *   issue the upload, so the stored config does not determine where a live presigned credential
- *   and the user's file bytes are sent. That is the same principle every other rule here
- *   enforces — a config value must describe what actually happens.
- *
- *   Note this is NOT an argument that http is forbidden on the write side; bare `http://` is
- *   accepted, because a loopback or in-cluster S3-compatible endpoint is a real need and a
- *   browser on an https editor blocks the mixed-content request anyway, so it fails closed. The
- *   objection to `//host` is that it is undetermined, not that it might be insecure.
+ * A protocol-relative `//host` is refused even when spelled literally, because it is AMBIGUOUS:
+ * it resolves to http or https depending on the page issuing the request, so the stored config
+ * does not determine where, for `media.uploadUrl`, a live presigned credential and the user's
+ * file bytes are sent. Bare `http://` is accepted: a loopback or in-cluster S3-compatible
+ * endpoint is a real need, and a browser on an https editor blocks the mixed-content request
+ * anyway, so it fails closed.
  *
  * Every spelling that READS as site-relative while redefining the authority — `/\host`,
- * `\\host`, `\/host`, `///host` — is rejected for both, in both modes. Those look site-relative
+ * `\\host`, `\/host`, `///host` — is rejected too. Those look site-relative
  * to a human and to a naive `startsWith('/')` check, but WHATWG URL resolves each to a
  * different authority (measured: `///x` resolves to host `x`, not to pathname `/x`), so they
  * are never what an adopter meant. A scheme-qualified absolute URL is a separate case and is
  * accepted — `https:///cdn.example.com/` is unusual but unambiguous, resolving identically
  * standalone and against any base.
  */
-export declare function isHttpUrlOrSameOriginPath(value: string, opts?: {
-    allowProtocolRelative?: boolean;
-}): boolean;
+export declare function isHttpUrlOrSameOriginPath(value: string): boolean;
 /**
  * Sanitize an untrusted URL for use in `href` attributes.
  *