@bevel-software/platform-core-backend 0.14.0 → 0.15.1

package/dist/shared/domain-errors.js

@@ -157,6 +157,35 @@ export class PullRebaseConflictError extends WorkflowDomainError {
         this.name = 'PullRebaseConflictError';
     }
 }
+/**
+ * The clone's branch no longer exists on origin: the fetch that refreshes
+ * `refs/remotes/origin/<branch>` found no such ref. Distinct from an
+ * unreachable remote — the host answered, and the answer was "gone" — so a
+ * caller can treat the clone as stale rather than the sync as failed. 410.
+ */
+export class RemoteBranchGoneError extends WorkflowDomainError {
+    branch;
+    kind = 'remote-branch-gone';
+    constructor(branch) {
+        super(`Branch "${branch}" no longer exists on the remote.`, 410, {
+            kind: 'remote-branch-gone',
+            branch,
+        });
+        this.branch = branch;
+        this.name = 'RemoteBranchGoneError';
+    }
+}
+/**
+ * Whether a failed clone or fetch failed because origin has no such branch, as
+ * opposed to being unreachable or refusing the credential. Git's wording for
+ * the two shapes: `Remote branch <x> not found in upstream origin` (clone) and
+ * `couldn't find remote ref refs/heads/<x>` (fetch). The ONE classifier for
+ * this fact — the workspace bootstrap and the git layer both consult it, so
+ * a wording learned by one is learned by both.
+ */
+export function isMissingRemoteBranchFailure(message) {
+    return /Remote branch .* not found in upstream|couldn't find remote ref/i.test(message);
+}
 /**
  * Generic 400 for workflow-input validation (malformed branch names, missing
  * fields, etc.). Carries an optional payload so callers can attach typed

package/dist/shared/domain-errors.js.map

@@ -1 +1 @@
-{"version":3,"file":"domain-errors.js","sourceRoot":"","sources":["../../src/shared/domain-errors.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"domain-errors.js","sourceRoot":"","sources":["../../src/shared/domain-errors.ts"],"names":[],"mappings":"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"}

package/dist/shared/fs-errors.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Whether a filesystem error means "there is no such path" — the one failure
+ * a reader may treat as an ordinary answer. Everything else (permissions,
+ * I/O, a loop) is a failure to READ what is there, and a caller that folds
+ * it into absence turns an outage into a wrong answer.
+ */
+export declare function isAbsence(err: unknown): boolean;
+//# sourceMappingURL=fs-errors.d.ts.map

package/dist/shared/fs-errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fs-errors.d.ts","sourceRoot":"","sources":["../../src/shared/fs-errors.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAG/C"}

package/dist/shared/fs-errors.js

@@ -0,0 +1,11 @@
+/**
+ * Whether a filesystem error means "there is no such path" — the one failure
+ * a reader may treat as an ordinary answer. Everything else (permissions,
+ * I/O, a loop) is a failure to READ what is there, and a caller that folds
+ * it into absence turns an outage into a wrong answer.
+ */
+export function isAbsence(err) {
+    const code = err?.code;
+    return code === 'ENOENT' || code === 'ENOTDIR';
+}
+//# sourceMappingURL=fs-errors.js.map

package/dist/shared/fs-errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fs-errors.js","sourceRoot":"","sources":["../../src/shared/fs-errors.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,UAAU,SAAS,CAAC,GAAY;IACpC,MAAM,IAAI,GAAI,GAAiC,EAAE,IAAI,CAAC;IACtD,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,SAAS,CAAC;AACjD,CAAC"}

package/dist/shared/fs-walk.d.ts

@@ -1,9 +1,23 @@
+import { isSkippedEntry } from './kb-walk.js';
+export { isSkippedEntry };
 /**
- * The ONE recursive file walk for catalog scanners: relative (`/`-separated,
- * sorted) paths of files under `root` whose basename matches. A missing root
- * yields `[]`; dot-entries (incl. `.git`) are skipped. Scanners with different
- * semantics (the skills scanner's stop-at-skill-folder walk, the access
- * resolver's dir chains) deliberately keep their own walks.
+ * The file listing catalog scanners want, on top of {@link walkKb}: relative
+ * (`/`-separated, sorted) paths of files under `root` whose basename matches.
+ * A missing root yields `[]`; skipped entries are never entered.
+ *
+ * A directory that cannot be listed is SKIPPED by default — right for a
+ * catalog, which shows what it can. A caller that must see EVERYTHING or
+ * nothing passes `strict`, and the listing throws a {@link WalkError} naming
+ * the directory instead: a list with a hole in it is not a list of every
+ * file, and the caller can say WHICH hole rather than pass a raw errno up.
  */
-export declare function walkFiles(root: string, match: (basename: string) => boolean): Promise<string[]>;
+export declare function walkFiles(root: string, match: (basename: string) => boolean, opts?: {
+    strict?: boolean;
+}): Promise<string[]>;
+/** A strict listing's refusal: the directory (relative to the root, `''` for the root itself) it could not list. */
+export declare class WalkError extends Error {
+    readonly relDir: string;
+    readonly cause: unknown;
+    constructor(relDir: string, cause: unknown);
+}
 //# sourceMappingURL=fs-walk.d.ts.map

package/dist/shared/fs-walk.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"fs-walk.d.ts","sourceRoot":"","sources":["../../src/shared/fs-walk.ts"],"names":[],"mappings":"AAGA;;;;;;GAMG;AACH,wBAAsB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAmBrG"}
+{"version":3,"file":"fs-walk.d.ts","sourceRoot":"","sources":["../../src/shared/fs-walk.ts"],"names":[],"mappings":"AAAA,OAAO,EAAU,cAAc,EAAE,MAAM,cAAc,CAAC;AAEtD,OAAO,EAAE,cAAc,EAAE,CAAC;AAE1B;;;;;;;;;;GAUG;AACH,wBAAsB,SAAS,CAC7B,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,EACpC,IAAI,GAAE;IAAE,MAAM,CAAC,EAAE,OAAO,CAAA;CAAO,GAC9B,OAAO,CAAC,MAAM,EAAE,CAAC,CAcnB;AAED,oHAAoH;AACpH,qBAAa,SAAU,SAAQ,KAAK;IAEhC,QAAQ,CAAC,MAAM,EAAE,MAAM;IACvB,QAAQ,CAAC,KAAK,EAAE,OAAO;gBADd,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,OAAO;CAK1B"}

package/dist/shared/fs-walk.js

@@ -1,34 +1,42 @@
-import path from 'node:path';
-import fs from 'node:fs/promises';
+import { walkKb, isSkippedEntry } from './kb-walk.js';
+export { isSkippedEntry };
 /**
- * The ONE recursive file walk for catalog scanners: relative (`/`-separated,
- * sorted) paths of files under `root` whose basename matches. A missing root
- * yields `[]`; dot-entries (incl. `.git`) are skipped. Scanners with different
- * semantics (the skills scanner's stop-at-skill-folder walk, the access
- * resolver's dir chains) deliberately keep their own walks.
+ * The file listing catalog scanners want, on top of {@link walkKb}: relative
+ * (`/`-separated, sorted) paths of files under `root` whose basename matches.
+ * A missing root yields `[]`; skipped entries are never entered.
+ *
+ * A directory that cannot be listed is SKIPPED by default — right for a
+ * catalog, which shows what it can. A caller that must see EVERYTHING or
+ * nothing passes `strict`, and the listing throws a {@link WalkError} naming
+ * the directory instead: a list with a hole in it is not a list of every
+ * file, and the caller can say WHICH hole rather than pass a raw errno up.
  */
-export async function walkFiles(root, match) {
+export async function walkFiles(root, match, opts = {}) {
     const out = [];
-    const walk = async (dir, rel) => {
-        let entries;
-        try {
-            entries = await fs.readdir(dir, { withFileTypes: true });
-        }
-        catch {
-            return;
-        }
-        for (const entry of entries) {
-            if (entry.name.startsWith('.'))
-                continue;
-            const childRel = rel ? `${rel}/${entry.name}` : entry.name;
-            if (entry.isDirectory())
-                await walk(path.join(dir, entry.name), childRel);
-            else if (entry.isFile() && match(entry.name))
-                out.push(childRel);
-        }
-    };
-    await walk(root, '');
+    await walkKb(root, [
+        {
+            onFile(dir, name) {
+                if (match(name))
+                    out.push(dir ? `${dir}/${name}` : name);
+            },
+            onHole(rel, err) {
+                if (opts.strict)
+                    throw new WalkError(rel, err);
+            },
+        },
+    ]);
     out.sort();
     return out;
 }
+/** A strict listing's refusal: the directory (relative to the root, `''` for the root itself) it could not list. */
+export class WalkError extends Error {
+    relDir;
+    cause;
+    constructor(relDir, cause) {
+        super(`${relDir || '.'} could not be listed — ${cause instanceof Error ? cause.message : String(cause)}`);
+        this.relDir = relDir;
+        this.cause = cause;
+        this.name = 'WalkError';
+    }
+}
 //# sourceMappingURL=fs-walk.js.map

package/dist/shared/fs-walk.js.map

@@ -1 +1 @@
-{"version":3,"file":"fs-walk.js","sourceRoot":"","sources":["../../src/shared/fs-walk.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAElC;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,SAAS,CAAC,IAAY,EAAE,KAAoC;IAChF,MAAM,GAAG,GAAa,EAAE,CAAC;IACzB,MAAM,IAAI,GAAG,KAAK,EAAE,GAAW,EAAE,GAAW,EAAiB,EAAE;QAC7D,IAAI,OAAmC,CAAC;QACxC,IAAI,CAAC;YACH,OAAO,GAAG,MAAM,EAAE,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,CAAC;QAC3D,CAAC;QAAC,MAAM,CAAC;YACP,OAAO;QACT,CAAC;QACD,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;YAC5B,IAAI,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC;gBAAE,SAAS;YACzC,MAAM,QAAQ,GAAG,GAAG,CAAC,CAAC,CAAC,GAAG,GAAG,IAAI,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC;YAC3D,IAAI,KAAK,CAAC,WAAW,EAAE;gBAAE,MAAM,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,CAAC,EAAE,QAAQ,CAAC,CAAC;iBACrE,IAAI,KAAK,CAAC,MAAM,EAAE,IAAI,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC;gBAAE,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QACnE,CAAC;IACH,CAAC,CAAC;IACF,MAAM,IAAI,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;IACrB,GAAG,CAAC,IAAI,EAAE,CAAC;IACX,OAAO,GAAG,CAAC;AACb,CAAC"}
+{"version":3,"file":"fs-walk.js","sourceRoot":"","sources":["../../src/shared/fs-walk.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAEtD,OAAO,EAAE,cAAc,EAAE,CAAC;AAE1B;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,SAAS,CAC7B,IAAY,EACZ,KAAoC,EACpC,OAA6B,EAAE;IAE/B,MAAM,GAAG,GAAa,EAAE,CAAC;IACzB,MAAM,MAAM,CAAC,IAAI,EAAE;QACjB;YACE,MAAM,CAAC,GAAG,EAAE,IAAI;gBACd,IAAI,KAAK,CAAC,IAAI,CAAC;oBAAE,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,GAAG,IAAI,IAAI,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;YAC3D,CAAC;YACD,MAAM,CAAC,GAAG,EAAE,GAAG;gBACb,IAAI,IAAI,CAAC,MAAM;oBAAE,MAAM,IAAI,SAAS,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;YACjD,CAAC;SACF;KACF,CAAC,CAAC;IACH,GAAG,CAAC,IAAI,EAAE,CAAC;IACX,OAAO,GAAG,CAAC;AACb,CAAC;AAED,oHAAoH;AACpH,MAAM,OAAO,SAAU,SAAQ,KAAK;IAEvB;IACA;IAFX,YACW,MAAc,EACd,KAAc;QAEvB,KAAK,CAAC,GAAG,MAAM,IAAI,GAAG,0BAA0B,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;QAHjG,WAAM,GAAN,MAAM,CAAQ;QACd,UAAK,GAAL,KAAK,CAAS;QAGvB,IAAI,CAAC,IAAI,GAAG,WAAW,CAAC;IAC1B,CAAC;CACF"}

package/dist/shared/kb-walk.d.ts

@@ -0,0 +1,52 @@
+/**
+ * THE walk of a knowledge-base checkout.
+ *
+ * Every reader of the tree — the access resolver looking for rules, plugin
+ * discovery looking for manifests, a rename looking for grants, the catalog
+ * scanners — used to carry a recursive `readdir` loop of its own, each with
+ * its own skip list, its own idea of what an unreadable folder means and its
+ * own visiting order. Two loops that disagree on one of those are two
+ * answers to "what is in the tree", and every such disagreement was a bug.
+ *
+ * So there is one loop, and it decides three things once:
+ *
+ *   - WHAT IS SKIPPED: {@link isSkippedEntry} — dot-entries (`.git`, a parked
+ *     delete) and vendored dependencies. Nothing else is pruned; a listener
+ *     that stops at a leaf of its own (a skill folder, a plugin folder)
+ *     simply ignores what lies beneath it.
+ *   - IN WHAT ORDER: each folder's entries in {@link comparePathComponents}
+ *     order, so "first by path" means the same thing to every listener.
+ *   - WHAT A HOLE IS: a folder that exists but could not be listed is
+ *     reported as an event and in the result — never thrown, never silently
+ *     skipped — so a reader can show what it saw and a writer can refuse.
+ *     A folder that vanished between listing and visiting is not a hole.
+ *
+ * Listeners see the same events in the same order; what each makes of them
+ * is its own business (`.bevelignore` included — the explorer honours it,
+ * the resolver must not, so it is a listener's decision, not the walk's).
+ */
+export declare function isSkippedEntry(name: string): boolean;
+/** A directory entry as the walk presents it: a name and what it is. */
+export interface WalkedEntry {
+    name: string;
+    isDirectory(): boolean;
+    isFile(): boolean;
+}
+export interface KbWalkListener {
+    /** A folder was listed. `rel` is repo-relative (`''` for the root); `entries` are its children, skipped ones removed, in walk order. */
+    onDir?(rel: string, entries: readonly WalkedEntry[]): void | Promise<void>;
+    /** A file was seen. `dir` is its folder (`''` for the root), `name` its basename. */
+    onFile?(dir: string, name: string): void | Promise<void>;
+    /** A folder that exists but could not be listed. */
+    onHole?(rel: string, err: unknown): void | Promise<void>;
+}
+export interface KbWalkResult {
+    /** Every folder that could not be listed, repo-relative (`''` for the root). */
+    holes: string[];
+}
+/**
+ * Walk the checkout at `root`, driving every listener from one traversal.
+ * A missing root is an empty tree. Listener errors propagate untouched.
+ */
+export declare function walkKb(root: string, listeners: readonly KbWalkListener[]): Promise<KbWalkResult>;
+//# sourceMappingURL=kb-walk.d.ts.map

package/dist/shared/kb-walk.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"kb-walk.d.ts","sourceRoot":"","sources":["../../src/shared/kb-walk.ts"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEpD;AAED,wEAAwE;AACxE,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,IAAI,OAAO,CAAC;IACvB,MAAM,IAAI,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,cAAc;IAC7B,wIAAwI;IACxI,KAAK,CAAC,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,WAAW,EAAE,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3E,qFAAqF;IACrF,MAAM,CAAC,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACzD,oDAAoD;IACpD,MAAM,CAAC,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1D;AAED,MAAM,WAAW,YAAY;IAC3B,gFAAgF;IAChF,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AAED;;;GAGG;AACH,wBAAsB,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,SAAS,cAAc,EAAE,GAAG,OAAO,CAAC,YAAY,CAAC,CAiCtG"}

package/dist/shared/kb-walk.js

@@ -0,0 +1,76 @@
+import path from 'node:path';
+import fs from 'node:fs/promises';
+import { isAbsence } from './fs-errors.js';
+import { comparePathComponents } from './path-order.js';
+/**
+ * THE walk of a knowledge-base checkout.
+ *
+ * Every reader of the tree — the access resolver looking for rules, plugin
+ * discovery looking for manifests, a rename looking for grants, the catalog
+ * scanners — used to carry a recursive `readdir` loop of its own, each with
+ * its own skip list, its own idea of what an unreadable folder means and its
+ * own visiting order. Two loops that disagree on one of those are two
+ * answers to "what is in the tree", and every such disagreement was a bug.
+ *
+ * So there is one loop, and it decides three things once:
+ *
+ *   - WHAT IS SKIPPED: {@link isSkippedEntry} — dot-entries (`.git`, a parked
+ *     delete) and vendored dependencies. Nothing else is pruned; a listener
+ *     that stops at a leaf of its own (a skill folder, a plugin folder)
+ *     simply ignores what lies beneath it.
+ *   - IN WHAT ORDER: each folder's entries in {@link comparePathComponents}
+ *     order, so "first by path" means the same thing to every listener.
+ *   - WHAT A HOLE IS: a folder that exists but could not be listed is
+ *     reported as an event and in the result — never thrown, never silently
+ *     skipped — so a reader can show what it saw and a writer can refuse.
+ *     A folder that vanished between listing and visiting is not a hole.
+ *
+ * Listeners see the same events in the same order; what each makes of them
+ * is its own business (`.bevelignore` included — the explorer honours it,
+ * the resolver must not, so it is a listener's decision, not the walk's).
+ */
+export function isSkippedEntry(name) {
+    return name.startsWith('.') || name === 'node_modules';
+}
+/**
+ * Walk the checkout at `root`, driving every listener from one traversal.
+ * A missing root is an empty tree. Listener errors propagate untouched.
+ */
+export async function walkKb(root, listeners) {
+    const holes = [];
+    const visit = async (abs, rel) => {
+        let listed;
+        try {
+            listed = await fs.readdir(abs, { withFileTypes: true });
+        }
+        catch (err) {
+            if (isAbsence(err)) {
+                // The root: a checkout without this tree, an empty walk. Deeper: a
+                // folder that vanished between listing and visiting — not a hole.
+                return;
+            }
+            holes.push(rel);
+            for (const l of listeners)
+                await l.onHole?.(rel, err);
+            return;
+        }
+        const entries = listed
+            .filter((e) => !isSkippedEntry(e.name) && (e.isDirectory() || e.isFile()))
+            .sort((a, b) => comparePathComponents(a.name, b.name));
+        for (const l of listeners)
+            await l.onDir?.(rel, entries);
+        for (const entry of entries) {
+            const childRel = rel ? `${rel}/${entry.name}` : entry.name;
+            if (entry.isDirectory()) {
+                await visit(path.join(abs, entry.name), childRel);
+            }
+            else {
+                for (const l of listeners)
+                    await l.onFile?.(rel, entry.name);
+            }
+        }
+    };
+    await visit(root, '');
+    return { holes };
+}
+//# sourceMappingURL=kb-walk.js.map

package/dist/shared/kb-walk.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"kb-walk.js","sourceRoot":"","sources":["../../src/shared/kb-walk.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAClC,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC3C,OAAO,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAExD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,UAAU,cAAc,CAAC,IAAY;IACzC,OAAO,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,IAAI,KAAK,cAAc,CAAC;AACzD,CAAC;AAuBD;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,MAAM,CAAC,IAAY,EAAE,SAAoC;IAC7E,MAAM,KAAK,GAAa,EAAE,CAAC;IAE3B,MAAM,KAAK,GAAG,KAAK,EAAE,GAAW,EAAE,GAAW,EAAiB,EAAE;QAC9D,IAAI,MAAkC,CAAC;QACvC,IAAI,CAAC;YACH,MAAM,GAAG,MAAM,EAAE,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,CAAC;QAC1D,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAI,SAAS,CAAC,GAAG,CAAC,EAAE,CAAC;gBACnB,mEAAmE;gBACnE,kEAAkE;gBAClE,OAAO;YACT,CAAC;YACD,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;YAChB,KAAK,MAAM,CAAC,IAAI,SAAS;gBAAE,MAAM,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;YACtD,OAAO;QACT,CAAC;QACD,MAAM,OAAO,GAAkB,MAAM;aAClC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,cAAc,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,WAAW,EAAE,IAAI,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC;aACzE,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,qBAAqB,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;QACzD,KAAK,MAAM,CAAC,IAAI,SAAS;YAAE,MAAM,CAAC,CAAC,KAAK,EAAE,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;QACzD,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;YAC5B,MAAM,QAAQ,GAAG,GAAG,CAAC,CAAC,CAAC,GAAG,GAAG,IAAI,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC;YAC3D,IAAI,KAAK,CAAC,WAAW,EAAE,EAAE,CAAC;gBACxB,MAAM,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,CAAC,EAAE,QAAQ,CAAC,CAAC;YACpD,CAAC;iBAAM,CAAC;gBACN,KAAK,MAAM,CAAC,IAAI,SAAS;oBAAE,MAAM,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC;YAC/D,CAAC;QACH,CAAC;IACH,CAAC,CAAC;IAEF,MAAM,KAAK,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;IACtB,OAAO,EAAE,KAAK,EAAE,CAAC;AACnB,CAAC"}

package/dist/shared/path-order.d.ts

@@ -0,0 +1,18 @@
+/**
+ * The ONE ordering of repository paths: component by component, each
+ * component by `localeCompare`, a shorter path before its extensions. It is
+ * exactly the order a directory walk that sorts each level's entries visits
+ * them in — so a consumer that must agree with the walk on "first by path"
+ * (plugin discovery keeps the first of two folders sharing a slug; principal
+ * synthesis must pick the same one) sorts with this and nothing else. A
+ * whole-string `localeCompare` does not agree: it weighs the separator
+ * against the next character (`a-b/x` before `a/b/x`), the walk never does.
+ *
+ * TOTAL over distinct paths: two components the collation cannot tell apart
+ * (a precomposed `é` and its decomposed spelling) fall through to code-unit
+ * order, so no pair of distinct paths ever compares equal — an equal pair
+ * would leave "first" to whichever enumeration happened to run, and the two
+ * consumers could then pick different folders for one slug.
+ */
+export declare function comparePathComponents(a: string, b: string): number;
+//# sourceMappingURL=path-order.d.ts.map

package/dist/shared/path-order.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"path-order.d.ts","sourceRoot":"","sources":["../../src/shared/path-order.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,qBAAqB,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CASlE"}

package/dist/shared/path-order.js

@@ -0,0 +1,35 @@
+/**
+ * The ONE ordering of repository paths: component by component, each
+ * component by `localeCompare`, a shorter path before its extensions. It is
+ * exactly the order a directory walk that sorts each level's entries visits
+ * them in — so a consumer that must agree with the walk on "first by path"
+ * (plugin discovery keeps the first of two folders sharing a slug; principal
+ * synthesis must pick the same one) sorts with this and nothing else. A
+ * whole-string `localeCompare` does not agree: it weighs the separator
+ * against the next character (`a-b/x` before `a/b/x`), the walk never does.
+ *
+ * TOTAL over distinct paths: two components the collation cannot tell apart
+ * (a precomposed `é` and its decomposed spelling) fall through to code-unit
+ * order, so no pair of distinct paths ever compares equal — an equal pair
+ * would leave "first" to whichever enumeration happened to run, and the two
+ * consumers could then pick different folders for one slug.
+ */
+export function comparePathComponents(a, b) {
+    const as = a.split('/');
+    const bs = b.split('/');
+    const n = Math.min(as.length, bs.length);
+    for (let i = 0; i < n; i++) {
+        const order = compareComponent(as[i], bs[i]);
+        if (order !== 0)
+            return order;
+    }
+    return as.length - bs.length;
+}
+/** One component against another: collation first, code units to break a tie. */
+function compareComponent(a, b) {
+    const order = a.localeCompare(b);
+    if (order !== 0)
+        return order;
+    return a < b ? -1 : a > b ? 1 : 0;
+}
+//# sourceMappingURL=path-order.js.map

package/dist/shared/path-order.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"path-order.js","sourceRoot":"","sources":["../../src/shared/path-order.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,qBAAqB,CAAC,CAAS,EAAE,CAAS;IACxD,MAAM,EAAE,GAAG,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IACxB,MAAM,EAAE,GAAG,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IACxB,MAAM,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,CAAC;IACzC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;QAC3B,MAAM,KAAK,GAAG,gBAAgB,CAAC,EAAE,CAAC,CAAC,CAAE,EAAE,EAAE,CAAC,CAAC,CAAE,CAAC,CAAC;QAC/C,IAAI,KAAK,KAAK,CAAC;YAAE,OAAO,KAAK,CAAC;IAChC,CAAC;IACD,OAAO,EAAE,CAAC,MAAM,GAAG,EAAE,CAAC,MAAM,CAAC;AAC/B,CAAC;AAED,iFAAiF;AACjF,SAAS,gBAAgB,CAAC,CAAS,EAAE,CAAS;IAC5C,MAAM,KAAK,GAAG,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC;IACjC,IAAI,KAAK,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IAC9B,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AACpC,CAAC"}

package/dist/shared/ttl-cache.d.ts

@@ -8,9 +8,36 @@ export declare class TtlCache<T> {
     private readonly ttlMs;
     private readonly now;
     private entry;
+    /**
+     * Bumped by every `invalidate()`. A fetch carries the value this had when it
+     * started, and `set` refuses a value whose fetch straddled a drop — see there.
+     */
+    private generation;
     constructor(ttlMs: number, now?: () => number);
     get(): T | null;
-    set(value: T): void;
+    /**
+     * Take a token BEFORE starting the fetch whose result you will `set`.
+     *
+     * Every caller of this cache reads the disk across an `await`, and the whole
+     * point of `invalidate()` is that it fires during exactly that window: the
+     * merge pulls the new tree in while a catalog read that started on the old
+     * one is still in flight. Without a token that late `set` wins, and the cache
+     * holds the PRE-invalidation scan for a fresh full TTL — the drop silently
+     * undone, and the staleness it existed to prevent restored.
+     */
+    begin(): number;
+    /**
+     * Store a value fetched under `token`. Required, not optional: a caller that
+     * could forget it is a caller that reintroduces the race above, and there are
+     * few enough call sites to make the token cheap.
+     *
+     * A stale token means an `invalidate()` landed mid-fetch, so this value
+     * describes a tree that is already gone: it is DISCARDED rather than stored.
+     * The fetcher still returns it to its own caller — that read is merely as old
+     * as the moment it started, which is true of any read — but the next caller
+     * re-scans instead of inheriting it.
+     */
+    set(value: T, token: number): void;
     invalidate(): void;
 }
 //# sourceMappingURL=ttl-cache.d.ts.map

package/dist/shared/ttl-cache.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ttl-cache.d.ts","sourceRoot":"","sources":["../../src/shared/ttl-cache.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,qBAAa,QAAQ,CAAC,CAAC;IAInB,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,GAAG;IAJtB,OAAO,CAAC,KAAK,CAAyC;gBAGnC,KAAK,EAAE,MAAM,EACb,GAAG,GAAE,MAAM,MAAiB;IAG/C,GAAG,IAAI,CAAC,GAAG,IAAI;IAKf,GAAG,CAAC,KAAK,EAAE,CAAC,GAAG,IAAI;IAInB,UAAU,IAAI,IAAI;CAGnB"}
+{"version":3,"file":"ttl-cache.d.ts","sourceRoot":"","sources":["../../src/shared/ttl-cache.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,qBAAa,QAAQ,CAAC,CAAC;IASnB,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,GAAG;IATtB,OAAO,CAAC,KAAK,CAAyC;IACtD;;;OAGG;IACH,OAAO,CAAC,UAAU,CAAK;gBAGJ,KAAK,EAAE,MAAM,EACb,GAAG,GAAE,MAAM,MAAiB;IAG/C,GAAG,IAAI,CAAC,GAAG,IAAI;IAKf;;;;;;;;;OASG;IACH,KAAK,IAAI,MAAM;IAIf;;;;;;;;;;OAUG;IACH,GAAG,CAAC,KAAK,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI;IAKlC,UAAU,IAAI,IAAI;CAInB"}

package/dist/shared/ttl-cache.js

@@ -8,6 +8,11 @@ export class TtlCache {
     ttlMs;
     now;
     entry = null;
+    /**
+     * Bumped by every `invalidate()`. A fetch carries the value this had when it
+     * started, and `set` refuses a value whose fetch straddled a drop — see there.
+     */
+    generation = 0;
     constructor(ttlMs, now = Date.now) {
         this.ttlMs = ttlMs;
         this.now = now;
@@ -17,11 +22,38 @@ export class TtlCache {
             return this.entry.value;
         return null;
     }
-    set(value) {
+    /**
+     * Take a token BEFORE starting the fetch whose result you will `set`.
+     *
+     * Every caller of this cache reads the disk across an `await`, and the whole
+     * point of `invalidate()` is that it fires during exactly that window: the
+     * merge pulls the new tree in while a catalog read that started on the old
+     * one is still in flight. Without a token that late `set` wins, and the cache
+     * holds the PRE-invalidation scan for a fresh full TTL — the drop silently
+     * undone, and the staleness it existed to prevent restored.
+     */
+    begin() {
+        return this.generation;
+    }
+    /**
+     * Store a value fetched under `token`. Required, not optional: a caller that
+     * could forget it is a caller that reintroduces the race above, and there are
+     * few enough call sites to make the token cheap.
+     *
+     * A stale token means an `invalidate()` landed mid-fetch, so this value
+     * describes a tree that is already gone: it is DISCARDED rather than stored.
+     * The fetcher still returns it to its own caller — that read is merely as old
+     * as the moment it started, which is true of any read — but the next caller
+     * re-scans instead of inheriting it.
+     */
+    set(value, token) {
+        if (token !== this.generation)
+            return;
         this.entry = { at: this.now(), value };
     }
     invalidate() {
         this.entry = null;
+        this.generation++;
     }
 }
 //# sourceMappingURL=ttl-cache.js.map

package/dist/shared/ttl-cache.js.map

@@ -1 +1 @@
-{"version":3,"file":"ttl-cache.js","sourceRoot":"","sources":["../../src/shared/ttl-cache.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,OAAO,QAAQ;IAIA;IACA;IAJX,KAAK,GAAoC,IAAI,CAAC;IAEtD,YACmB,KAAa,EACb,MAAoB,IAAI,CAAC,GAAG;QAD5B,UAAK,GAAL,KAAK,CAAQ;QACb,QAAG,GAAH,GAAG,CAAyB;IAC5C,CAAC;IAEJ,GAAG;QACD,IAAI,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,EAAE,GAAG,IAAI,CAAC,KAAK;YAAE,OAAO,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC;QACnF,OAAO,IAAI,CAAC;IACd,CAAC;IAED,GAAG,CAAC,KAAQ;QACV,IAAI,CAAC,KAAK,GAAG,EAAE,EAAE,EAAE,IAAI,CAAC,GAAG,EAAE,EAAE,KAAK,EAAE,CAAC;IACzC,CAAC;IAED,UAAU;QACR,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC;IACpB,CAAC;CACF"}
+{"version":3,"file":"ttl-cache.js","sourceRoot":"","sources":["../../src/shared/ttl-cache.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,OAAO,QAAQ;IASA;IACA;IATX,KAAK,GAAoC,IAAI,CAAC;IACtD;;;OAGG;IACK,UAAU,GAAG,CAAC,CAAC;IAEvB,YACmB,KAAa,EACb,MAAoB,IAAI,CAAC,GAAG;QAD5B,UAAK,GAAL,KAAK,CAAQ;QACb,QAAG,GAAH,GAAG,CAAyB;IAC5C,CAAC;IAEJ,GAAG;QACD,IAAI,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,EAAE,GAAG,IAAI,CAAC,KAAK;YAAE,OAAO,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC;QACnF,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;;;;;;;;OASG;IACH,KAAK;QACH,OAAO,IAAI,CAAC,UAAU,CAAC;IACzB,CAAC;IAED;;;;;;;;;;OAUG;IACH,GAAG,CAAC,KAAQ,EAAE,KAAa;QACzB,IAAI,KAAK,KAAK,IAAI,CAAC,UAAU;YAAE,OAAO;QACtC,IAAI,CAAC,KAAK,GAAG,EAAE,EAAE,EAAE,IAAI,CAAC,GAAG,EAAE,EAAE,KAAK,EAAE,CAAC;IACzC,CAAC;IAED,UAAU;QACR,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC;QAClB,IAAI,CAAC,UAAU,EAAE,CAAC;IACpB,CAAC;CACF"}

package/kb-template/.bevelignore

@@ -22,4 +22,4 @@ CLAUDE.md
 **/access.md
 roles.yaml
 
-Plugins/
+{{pluginsDir}}/