@bevel-software/platform-core-backend 0.10.0 → 0.11.1

package/dist/modules/access/admin-locked-commit.d.ts

@@ -0,0 +1,134 @@
+/**
+ * SHARED transactional lock/commit helper for the admin roster services
+ * (roles + groups). The two services used to carry twin copies of this
+ * machinery, which diverged once into a real bug — this is the single
+ * implementation both delegate to, parameterized only by the domain-error
+ * constructor, log tag, and contention wording.
+ *
+ * The shape of every roster write:
+ *
+ *   withFileLocks(paths, fn)          — acquire every path's lock (sorted,
+ *     all-or-nothing; strict even for the same user), run `fn`, release.
+ *     HOW each lock is released depends on the outcome (see the finally
+ *     block for the full reasoning):
+ *       - `fn` succeeded → releaseLockNoCommit for every path the batch
+ *         commit LANDED on (tracked by writeAndCommitLocked): the commit
+ *         landed AND pushed, so the tree there is clean (the discard
+ *         no-ops); releaseLock would instead ENQUEUE a commit before
+ *         dropping the row, and an enqueue failure then strands the lock
+ *         until TTL. A held path the batch never committed keeps
+ *         commit-on-release — it may carry a PRIOR holder's still-queued
+ *         work, which a discard would destroy.
+ *       - `fn` threw PushNeedsAgentResolutionError → releaseLock. The commit
+ *         landed but the push didn't; the enqueued release commit IS the
+ *         retry (the worker sees the clean tree, notices unpushed commits,
+ *         and re-runs the cooperative push ladder).
+ *       - `fn` threw anything else → releaseLock (commit-on-release): `fn`
+ *         restored its own bytes, so anything dirty at release time is
+ *         either clean (queued commit no-ops) or someone else's still-queued
+ *         work that must be preserved. The ONE exception: a path whose
+ *         restore itself failed (`unrestoredPaths` on the thrown error)
+ *         holds known-partial bytes → releaseLockNoCommit discards to HEAD.
+ *     Every release is per-path best-effort: one failed release logs and
+ *     moves on so it can never strand the REST of the held locks.
+ *
+ *   writeAndCommitLocked(files)       — the write half of a withFileLocks
+ *     flow: plain-write each file (the lock is already ours — strict
+ *     same-user acquire forbids LockingFilesystem here) and commit them as
+ *     ONE path-scoped change. On a PRE-commit failure, best-effort restore of
+ *     each file's original bytes (`original: null` = the file did not exist,
+ *     so restoration DELETES it). A POST-commit failure — the push after a
+ *     landed commit (`PushNeedsAgentResolutionError`, thrown with the commit
+ *     intact) — must NOT restore: the edit is committed locally and restoring
+ *     would publish a compensating revert of a landed change. It propagates
+ *     as-is ("saved locally … will be resolved"), locks release normally, and
+ *     the pending-commit ladder retries the share.
+ */
+import { LockingFilesystem } from '../workflow/locking-filesystem.js';
+import { WorkflowDomainError } from '../workflow/workflow.errors.js';
+import type { AuthUser, IWorkspaceService, IWorkflowService } from '@bevel-software/platform-shared';
+import type { FileContent } from '@mastra/core/workspace';
+export interface LockedCommitDeps {
+    workspaceService: IWorkspaceService;
+    workflowService: IWorkflowService;
+    kbDirName: string;
+    /** Live-binding thunk — DEFAULT_BRANCH stays empty until setup. */
+    defaultBranchOf: () => string;
+    /** Domain-error constructor (RolesAdminError / GroupsAdminError). */
+    makeError: (message: string, status: number, payload?: Record<string, unknown>) => WorkflowDomainError;
+    /** Log prefix, e.g. 'roles-admin' / 'groups-admin'. */
+    logTag: string;
+    /** Contention wording: what is "being edited by <holder>". */
+    contendedSubject: string;
+    /** Pre-disk write validator handed to LockingFilesystem writes. */
+    validateWrite?: (path: string, content: FileContent) => void;
+}
+export interface LockedWrite {
+    repoRel: string;
+    /** The new content; null = DELETE the file (restore writes `original` back). */
+    content: string | null;
+    /** null = the file did not exist before (restore DELETES it). */
+    original: string | null;
+}
+export declare class AdminLockedCommits {
+    private readonly deps;
+    /**
+     * Workspace-scoped ws-relative paths whose bytes a `writeAndCommitLocked`
+     * batch has committed (and pushed) while their locks are held — i.e. paths
+     * whose working tree is KNOWN clean. `withFileLocks` releases exactly these
+     * with `releaseLockNoCommit` on success (see the module doc) and clears
+     * each entry as it releases. Keyed `<workspaceId>\0<wsRelPath>` so two
+     * workspaces can't cross-talk.
+     */
+    private readonly committedCleanPaths;
+    constructor(deps: LockedCommitDeps);
+    private cleanKey;
+    private get defaultBranch();
+    wsRel(repoRel: string): string;
+    repoDir(workspaceId: string): Promise<string>;
+    /** Read a KB-root file; null when genuinely absent. */
+    readKbFile(workspaceId: string, repoRel: string): Promise<string | null>;
+    /**
+     * A lock-aware filesystem scoped to `actor` — writes auto-commit + push as
+     * the actor on release, through the same pipeline as the human editor and
+     * agent. Built per-op because the lock context captures the acting user.
+     * Only for flows that do NOT already hold the file locks (acquire is strict
+     * even same-user); a withFileLocks flow writes via writeAndCommitLocked.
+     */
+    lockingFsForActor(workspaceId: string, actor: AuthUser): Promise<LockingFilesystem>;
+    /**
+     * Map LockingFilesystem's status-less contention error ("Skipped editing …
+     * — locked by …") to the friendly 409. Callers pre-check the common case,
+     * but that is a TOCTOU check — this catches the race so contention always
+     * surfaces as a 409, never an unhandled 500.
+     */
+    mapLockContention<T>(write: () => Promise<T>): Promise<T>;
+    /**
+     * Run `fn` while HOLDING the named KB-file locks (sorted, all-or-nothing):
+     * read-modify-write flows must keep the lock across the READ too, or two
+     * concurrent edits (another tab, another admin, a conversion) both snapshot
+     * the same base and the second write silently discards the first. See the
+     * module doc for the release semantics.
+     *
+     * `opts.coordinationFiles` names files locked ONLY to serialize with their
+     * writer — `fn` never writes them. They're acquired with the workflow
+     * service's coordination flag (a pure mutex that skips the per-path write
+     * gate — required for machine-owned files like `synced-groups.yaml`, which
+     * a human actor may not, and need not, write) and always released with
+     * `releaseLockNoCommit`: there is never anything of ours to commit there,
+     * and enqueueing a release commit as an actor the path's write rule
+     * refuses would only feed the worker a doomed row. The discard inside that
+     * release no-ops: the machine writer commits synchronously under its own
+     * lock, so the path is clean whenever we could acquire it.
+     */
+    withFileLocks<T>(workspaceId: string, actor: AuthUser, repoRelFiles: string[], fn: () => Promise<T>, opts?: {
+        coordinationFiles?: string[];
+    }): Promise<T>;
+    /**
+     * Plain-write `files` and commit them as ONE path-scoped change — the write
+     * half of a `withFileLocks` flow. See the module doc for the pre- vs
+     * post-commit failure split; only PRE-commit failures restore.
+     */
+    writeAndCommitLocked(workspaceId: string, actor: AuthUser, files: LockedWrite[], summary: string): Promise<void>;
+}
+//# sourceMappingURL=admin-locked-commit.d.ts.map

package/dist/modules/access/admin-locked-commit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"admin-locked-commit.d.ts","sourceRoot":"","sources":["../../../src/modules/access/admin-locked-commit.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AAIH,OAAO,EAAE,iBAAiB,EAAE,MAAM,mCAAmC,CAAC;AACtE,OAAO,EAAiC,mBAAmB,EAAE,MAAM,gCAAgC,CAAC;AACpG,OAAO,KAAK,EAAE,QAAQ,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,iCAAiC,CAAC;AACrG,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAE1D,MAAM,WAAW,gBAAgB;IAC/B,gBAAgB,EAAE,iBAAiB,CAAC;IACpC,eAAe,EAAE,gBAAgB,CAAC;IAClC,SAAS,EAAE,MAAM,CAAC;IAClB,mEAAmE;IACnE,eAAe,EAAE,MAAM,MAAM,CAAC;IAC9B,qEAAqE;IACrE,SAAS,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,mBAAmB,CAAC;IACvG,uDAAuD;IACvD,MAAM,EAAE,MAAM,CAAC;IACf,8DAA8D;IAC9D,gBAAgB,EAAE,MAAM,CAAC;IACzB,mEAAmE;IACnE,aAAa,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,KAAK,IAAI,CAAC;CAC9D;AAED,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,gFAAgF;IAChF,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,iEAAiE;IACjE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;CACzB;AAED,qBAAa,kBAAkB;IAWjB,OAAO,CAAC,QAAQ,CAAC,IAAI;IAVjC;;;;;;;OAOG;IACH,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAqB;gBAE5B,IAAI,EAAE,gBAAgB;IAEnD,OAAO,CAAC,QAAQ;IAIhB,OAAO,KAAK,aAAa,GAExB;IAED,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM;IAIxB,OAAO,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAKnD,uDAAuD;IACjD,UAAU,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAa9E;;;;;;OAMG;IACG,iBAAiB,CAAC,WAAW,EAAE,MAAM,EAAE,KAAK,EAAE,QAAQ,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAczF;;;;;OAKG;IACG,iBAAiB,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IAc/D;;;;;;;;;;;;;;;;;OAiBG;IACG,aAAa,CAAC,CAAC,EACnB,WAAW,EAAE,MAAM,EACnB,KAAK,EAAE,QAAQ,EACf,YAAY,EAAE,MAAM,EAAE,EACtB,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACpB,IAAI,CAAC,EAAE;QAAE,iBAAiB,CAAC,EAAE,MAAM,EAAE,CAAA;KAAE,GACtC,OAAO,CAAC,CAAC,CAAC;IAgFb;;;;OAIG;IACG,oBAAoB,CACxB,WAAW,EAAE,MAAM,EACnB,KAAK,EAAE,QAAQ,EACf,KAAK,EAAE,WAAW,EAAE,EACpB,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,IAAI,CAAC;CAqDjB"}

package/dist/modules/access/admin-locked-commit.js

@@ -0,0 +1,277 @@
+/**
+ * SHARED transactional lock/commit helper for the admin roster services
+ * (roles + groups). The two services used to carry twin copies of this
+ * machinery, which diverged once into a real bug — this is the single
+ * implementation both delegate to, parameterized only by the domain-error
+ * constructor, log tag, and contention wording.
+ *
+ * The shape of every roster write:
+ *
+ *   withFileLocks(paths, fn)          — acquire every path's lock (sorted,
+ *     all-or-nothing; strict even for the same user), run `fn`, release.
+ *     HOW each lock is released depends on the outcome (see the finally
+ *     block for the full reasoning):
+ *       - `fn` succeeded → releaseLockNoCommit for every path the batch
+ *         commit LANDED on (tracked by writeAndCommitLocked): the commit
+ *         landed AND pushed, so the tree there is clean (the discard
+ *         no-ops); releaseLock would instead ENQUEUE a commit before
+ *         dropping the row, and an enqueue failure then strands the lock
+ *         until TTL. A held path the batch never committed keeps
+ *         commit-on-release — it may carry a PRIOR holder's still-queued
+ *         work, which a discard would destroy.
+ *       - `fn` threw PushNeedsAgentResolutionError → releaseLock. The commit
+ *         landed but the push didn't; the enqueued release commit IS the
+ *         retry (the worker sees the clean tree, notices unpushed commits,
+ *         and re-runs the cooperative push ladder).
+ *       - `fn` threw anything else → releaseLock (commit-on-release): `fn`
+ *         restored its own bytes, so anything dirty at release time is
+ *         either clean (queued commit no-ops) or someone else's still-queued
+ *         work that must be preserved. The ONE exception: a path whose
+ *         restore itself failed (`unrestoredPaths` on the thrown error)
+ *         holds known-partial bytes → releaseLockNoCommit discards to HEAD.
+ *     Every release is per-path best-effort: one failed release logs and
+ *     moves on so it can never strand the REST of the held locks.
+ *
+ *   writeAndCommitLocked(files)       — the write half of a withFileLocks
+ *     flow: plain-write each file (the lock is already ours — strict
+ *     same-user acquire forbids LockingFilesystem here) and commit them as
+ *     ONE path-scoped change. On a PRE-commit failure, best-effort restore of
+ *     each file's original bytes (`original: null` = the file did not exist,
+ *     so restoration DELETES it). A POST-commit failure — the push after a
+ *     landed commit (`PushNeedsAgentResolutionError`, thrown with the commit
+ *     intact) — must NOT restore: the edit is committed locally and restoring
+ *     would publish a compensating revert of a landed change. It propagates
+ *     as-is ("saved locally … will be resolved"), locks release normally, and
+ *     the pending-commit ladder retries the share.
+ */
+import path from 'node:path';
+import { LockingFilesystem } from '../workflow/locking-filesystem.js';
+import { PushNeedsAgentResolutionError } from '../workflow/workflow.errors.js';
+export class AdminLockedCommits {
+    deps;
+    /**
+     * Workspace-scoped ws-relative paths whose bytes a `writeAndCommitLocked`
+     * batch has committed (and pushed) while their locks are held — i.e. paths
+     * whose working tree is KNOWN clean. `withFileLocks` releases exactly these
+     * with `releaseLockNoCommit` on success (see the module doc) and clears
+     * each entry as it releases. Keyed `<workspaceId>\0<wsRelPath>` so two
+     * workspaces can't cross-talk.
+     */
+    committedCleanPaths = new Set();
+    constructor(deps) {
+        this.deps = deps;
+    }
+    cleanKey(workspaceId, wsRelPath) {
+        return `${workspaceId}\0${wsRelPath}`;
+    }
+    get defaultBranch() {
+        return this.deps.defaultBranchOf();
+    }
+    wsRel(repoRel) {
+        return `${this.deps.kbDirName}/${repoRel}`;
+    }
+    async repoDir(workspaceId) {
+        const wsDir = await this.deps.workspaceService.getWorkspacePath(workspaceId);
+        return path.join(wsDir, this.deps.kbDirName);
+    }
+    /** Read a KB-root file; null when genuinely absent. */
+    async readKbFile(workspaceId, repoRel) {
+        try {
+            return await this.deps.workspaceService.readFile(workspaceId, path.posix.join(this.deps.kbDirName, repoRel));
+        }
+        catch (err) {
+            const code = err?.code;
+            if (code === 'ENOENT' || code === 'ENOTDIR')
+                return null;
+            throw err;
+        }
+    }
+    /**
+     * A lock-aware filesystem scoped to `actor` — writes auto-commit + push as
+     * the actor on release, through the same pipeline as the human editor and
+     * agent. Built per-op because the lock context captures the acting user.
+     * Only for flows that do NOT already hold the file locks (acquire is strict
+     * even same-user); a withFileLocks flow writes via writeAndCommitLocked.
+     */
+    async lockingFsForActor(workspaceId, actor) {
+        const basePath = await this.deps.workspaceService.getWorkspacePath(workspaceId);
+        return new LockingFilesystem({ basePath, contained: true }, {
+            workflow: this.deps.workflowService,
+            workspaceId,
+            branch: this.defaultBranch,
+            user: actor,
+            validateWrite: this.deps.validateWrite,
+        });
+    }
+    /**
+     * Map LockingFilesystem's status-less contention error ("Skipped editing …
+     * — locked by …") to the friendly 409. Callers pre-check the common case,
+     * but that is a TOCTOU check — this catches the race so contention always
+     * surfaces as a 409, never an unhandled 500.
+     */
+    async mapLockContention(write) {
+        try {
+            return await write();
+        }
+        catch (err) {
+            if (err instanceof Error && /locked by /.test(err.message)) {
+                throw this.deps.makeError(`${this.deps.contendedSubject} are being edited by another admin. Try again in a moment.`, 409);
+            }
+            throw err;
+        }
+    }
+    /**
+     * Run `fn` while HOLDING the named KB-file locks (sorted, all-or-nothing):
+     * read-modify-write flows must keep the lock across the READ too, or two
+     * concurrent edits (another tab, another admin, a conversion) both snapshot
+     * the same base and the second write silently discards the first. See the
+     * module doc for the release semantics.
+     *
+     * `opts.coordinationFiles` names files locked ONLY to serialize with their
+     * writer — `fn` never writes them. They're acquired with the workflow
+     * service's coordination flag (a pure mutex that skips the per-path write
+     * gate — required for machine-owned files like `synced-groups.yaml`, which
+     * a human actor may not, and need not, write) and always released with
+     * `releaseLockNoCommit`: there is never anything of ours to commit there,
+     * and enqueueing a release commit as an actor the path's write rule
+     * refuses would only feed the worker a doomed row. The discard inside that
+     * release no-ops: the machine writer commits synchronously under its own
+     * lock, so the path is clean whenever we could acquire it.
+     */
+    async withFileLocks(workspaceId, actor, repoRelFiles, fn, opts) {
+        const coordination = new Set((opts?.coordinationFiles ?? []).map((f) => this.wsRel(f)));
+        // One globally-sorted acquire order across BOTH kinds of path — a split
+        // order would reintroduce the deadlock the sort exists to prevent.
+        const paths = [...new Set([...repoRelFiles.map((f) => this.wsRel(f)), ...coordination])].sort();
+        const held = [];
+        let failure = null;
+        let unrestored = null;
+        try {
+            for (const p of paths) {
+                const res = await this.deps.workflowService.acquireLock(workspaceId, this.defaultBranch, p, actor, coordination.has(p) ? { coordination: true } : undefined);
+                if (!res.acquired) {
+                    throw this.deps.makeError(`${this.deps.contendedSubject} are being edited by ${res.lock.holderName || 'another admin'}. Try again in a moment.`, 409);
+                }
+                held.push(p);
+            }
+            return await fn();
+        }
+        catch (err) {
+            failure = err;
+            unrestored = err?.unrestoredPaths ?? null;
+            throw err;
+        }
+        finally {
+            // Outcome-dependent release — see the module doc. The key hazard this
+            // guards: `releaseLock` ENQUEUES the release commit BEFORE dropping the
+            // lock row (deliberately, so a crash can't orphan bytes), which means an
+            // enqueue failure leaves the row held until TTL. After a SUCCESSFUL
+            // batch commit there is nothing left to commit — writeAndCommitLocked
+            // committed and pushed these exact paths, and we hold their locks, so
+            // the tree there is clean — so releaseLockNoCommit (whose discard
+            // no-ops on a clean path) releases without ever touching the queue.
+            //
+            // EXCEPT on the push-retry path: PushNeedsAgentResolutionError means
+            // the commit landed but the push didn't, and the enqueued release
+            // commit is what retries the push (runPendingCommit: clean tree +
+            // unpushed commits → pushWithRecovery). That path MUST releaseLock.
+            // Failures there log + continue so one bad enqueue strands at most its
+            // own lock (TTL backstop), never the rest.
+            const pushRetry = failure instanceof PushNeedsAgentResolutionError;
+            for (const h of held) {
+                const committedClean = this.committedCleanPaths.delete(this.cleanKey(workspaceId, h)) && !pushRetry;
+                try {
+                    if (coordination.has(h) || committedClean || unrestored?.has(h)) {
+                        // Coordination-only hold (see the method doc): `fn` never wrote
+                        // it, so no outcome — push-retry included — has anything to
+                        // commit there; the no-commit release just drops the row. Or:
+                        // Batch-committed path (clean tree — discard no-ops) — even when
+                        // `fn` threw AFTER the commit+push landed: the failure says
+                        // nothing about the tree, and releaseLock would enqueue a
+                        // pointless commit whose enqueue failure strands a known-clean
+                        // lock until TTL. Or known-partial bytes (restore failed —
+                        // discarding to HEAD beats committing them).
+                        await this.deps.workflowService.releaseLockNoCommit(workspaceId, this.defaultBranch, h, actor);
+                    }
+                    else {
+                        // Push-retry (the enqueued commit retries the share), the
+                        // restored-failure path, and any held path the batch never
+                        // committed (commit-on-release: a prior holder's still-queued
+                        // work must be preserved, never discarded).
+                        await this.deps.workflowService.releaseLock(workspaceId, this.defaultBranch, h, actor);
+                    }
+                }
+                catch (releaseErr) {
+                    console.warn(`[${this.deps.logTag}] could not release lock on ${h}${pushRetry ? ' (push-retry release)' : ''}; ` +
+                        'it frees on TTL — continuing with the remaining locks:', releaseErr instanceof Error ? releaseErr.message : releaseErr);
+                }
+            }
+        }
+    }
+    /**
+     * Plain-write `files` and commit them as ONE path-scoped change — the write
+     * half of a `withFileLocks` flow. See the module doc for the pre- vs
+     * post-commit failure split; only PRE-commit failures restore.
+     */
+    async writeAndCommitLocked(workspaceId, actor, files, summary) {
+        const { workspaceService, workflowService, logTag } = this.deps;
+        try {
+            for (const f of files) {
+                if (f.content === null) {
+                    // A DELETE entry. Tolerate an already-absent file — that IS the
+                    // desired state (and the caller checked existence under the lock).
+                    try {
+                        await workspaceService.deleteFile(workspaceId, this.wsRel(f.repoRel));
+                    }
+                    catch (err) {
+                        if (err?.code !== 'ENOENT')
+                            throw err;
+                    }
+                }
+                else {
+                    await workspaceService.writeFile(workspaceId, this.wsRel(f.repoRel), f.content);
+                }
+            }
+            await workflowService.commitChanges(workspaceId, actor, summary, files.map((f) => this.wsRel(f.repoRel)));
+            // Commit landed AND pushed — the tree at these paths is clean. Mark
+            // them so withFileLocks releases them WITHOUT enqueueing a release
+            // commit (see the module doc — an enqueue failure would strand the
+            // lock until TTL for a commit there is nothing left to make).
+            for (const f of files)
+                this.committedCleanPaths.add(this.cleanKey(workspaceId, this.wsRel(f.repoRel)));
+        }
+        catch (err) {
+            // POST-commit failure: the commit landed and only the PUSH needs help
+            // (thrown "with the commit intact"). The bytes on disk match the landed
+            // commit — restoring pre-edit bytes here would publish a compensating
+            // revert of a change that exists. No restore; release proceeds
+            // normally; the error itself tells the caller "saved locally, sharing
+            // will be resolved" and the pending-commit ladder retries the push.
+            if (err instanceof PushNeedsAgentResolutionError) {
+                console.warn(`[${logTag}] commit landed but the push needs resolution — edit saved; publishing will be retried`);
+                throw err;
+            }
+            const unrestored = new Set();
+            for (const f of files) {
+                try {
+                    if (f.original === null)
+                        await workspaceService.deleteFile(workspaceId, this.wsRel(f.repoRel));
+                    else
+                        await workspaceService.writeFile(workspaceId, this.wsRel(f.repoRel), f.original);
+                }
+                catch (restoreErr) {
+                    // Deleting an already-absent file IS the original state.
+                    if (f.original === null && restoreErr?.code === 'ENOENT')
+                        continue;
+                    unrestored.add(this.wsRel(f.repoRel));
+                    console.warn(`[${logTag}] could not restore ${f.repoRel} after a failed commit`);
+                }
+            }
+            if (unrestored.size > 0 && typeof err === 'object' && err !== null) {
+                err.unrestoredPaths = unrestored;
+            }
+            throw err;
+        }
+    }
+}
+//# sourceMappingURL=admin-locked-commit.js.map

package/dist/modules/access/admin-locked-commit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"admin-locked-commit.js","sourceRoot":"","sources":["../../../src/modules/access/admin-locked-commit.ts"],"names":[],"mappings":"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"}

package/dist/modules/access/admin-route-helpers.d.ts

@@ -0,0 +1,32 @@
+/**
+ * SHARED route plumbing for the access-family routers (access.routes,
+ * groups-admin.routes) — one error shape, one input-coercion rule, so the two
+ * surfaces can't drift apart again.
+ *
+ * Error shape: a sub-500 `WorkflowDomainError` renders as its own status +
+ * message + payload; everything else — a raw error OR a 500-status domain
+ * error (e.g. AccessMutationService wraps unexpected raw errors in a 500
+ * AccessMutationError, message included) — is an INTERNAL error: logged
+ * server-side in full, answered with a generic message. A raw `err.message`
+ * must never leak through a 500 (it can carry fs/db paths and internals the
+ * caller has no business seeing).
+ */
+import type express from 'express';
+/** One error shape for every access-family route. */
+export declare function toHttpError(err: unknown, logTag: string): {
+    status: number;
+    body: Record<string, unknown>;
+};
+/** Answer `res` with the shared error shape. */
+export declare function sendError(res: express.Response, err: unknown, logTag: string): void;
+/**
+ * Coerce a request-body field that must be a non-empty string. Rejects arrays,
+ * objects, numbers, null — anything `String()` would silently stringify into a
+ * bogus principal name / email (`[object Object]`, `"a,b"`) — with a 400
+ * instead of persisting garbage. Returns the raw string (untrimmed by default
+ * — services trim; pass `trim: true` where the route owns normalization).
+ */
+export declare function requireNonEmptyString(value: unknown, field: string, opts?: {
+    trim?: boolean;
+}): string;
+//# sourceMappingURL=admin-route-helpers.d.ts.map

package/dist/modules/access/admin-route-helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"admin-route-helpers.d.ts","sourceRoot":"","sources":["../../../src/modules/access/admin-route-helpers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,OAAO,MAAM,SAAS,CAAC;AAGnC,qDAAqD;AACrD,wBAAgB,WAAW,CACzB,GAAG,EAAE,OAAO,EACZ,MAAM,EAAE,MAAM,GACb;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,CASnD;AAED,gDAAgD;AAChD,wBAAgB,SAAS,CAAC,GAAG,EAAE,OAAO,CAAC,QAAQ,EAAE,GAAG,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAGnF;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,OAAO,EACd,KAAK,EAAE,MAAM,EACb,IAAI,CAAC,EAAE;IAAE,IAAI,CAAC,EAAE,OAAO,CAAA;CAAE,GACxB,MAAM,CAKR"}

package/dist/modules/access/admin-route-helpers.js

@@ -0,0 +1,44 @@
+/**
+ * SHARED route plumbing for the access-family routers (access.routes,
+ * groups-admin.routes) — one error shape, one input-coercion rule, so the two
+ * surfaces can't drift apart again.
+ *
+ * Error shape: a sub-500 `WorkflowDomainError` renders as its own status +
+ * message + payload; everything else — a raw error OR a 500-status domain
+ * error (e.g. AccessMutationService wraps unexpected raw errors in a 500
+ * AccessMutationError, message included) — is an INTERNAL error: logged
+ * server-side in full, answered with a generic message. A raw `err.message`
+ * must never leak through a 500 (it can carry fs/db paths and internals the
+ * caller has no business seeing).
+ */
+import { WorkflowDomainError } from '../workflow/workflow.errors.js';
+/** One error shape for every access-family route. */
+export function toHttpError(err, logTag) {
+    if (err instanceof WorkflowDomainError && err.status < 500) {
+        // Spread the payload FIRST and assign `error` LAST — a payload key named
+        // `error` must never overwrite the message the client renders.
+        return { status: err.status, body: { ...(err.payload ?? {}), error: err.message } };
+    }
+    console.error(`[${logTag}] route failure:`, err instanceof Error ? err.stack ?? err.message : err);
+    const status = err instanceof WorkflowDomainError ? err.status : 500;
+    return { status, body: { error: 'Internal error.' } };
+}
+/** Answer `res` with the shared error shape. */
+export function sendError(res, err, logTag) {
+    const { status, body } = toHttpError(err, logTag);
+    res.status(status).json(body);
+}
+/**
+ * Coerce a request-body field that must be a non-empty string. Rejects arrays,
+ * objects, numbers, null — anything `String()` would silently stringify into a
+ * bogus principal name / email (`[object Object]`, `"a,b"`) — with a 400
+ * instead of persisting garbage. Returns the raw string (untrimmed by default
+ * — services trim; pass `trim: true` where the route owns normalization).
+ */
+export function requireNonEmptyString(value, field, opts) {
+    if (typeof value !== 'string' || value.trim() === '') {
+        throw new WorkflowDomainError(`${field} must be a non-empty string`, 400);
+    }
+    return opts?.trim ? value.trim() : value;
+}
+//# sourceMappingURL=admin-route-helpers.js.map

package/dist/modules/access/admin-route-helpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"admin-route-helpers.js","sourceRoot":"","sources":["../../../src/modules/access/admin-route-helpers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,EAAE,mBAAmB,EAAE,MAAM,gCAAgC,CAAC;AAErE,qDAAqD;AACrD,MAAM,UAAU,WAAW,CACzB,GAAY,EACZ,MAAc;IAEd,IAAI,GAAG,YAAY,mBAAmB,IAAI,GAAG,CAAC,MAAM,GAAG,GAAG,EAAE,CAAC;QAC3D,yEAAyE;QACzE,+DAA+D;QAC/D,OAAO,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,IAAI,EAAE,EAAE,GAAG,CAAC,GAAG,CAAC,OAAO,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,GAAG,CAAC,OAAO,EAAE,EAAE,CAAC;IACtF,CAAC;IACD,OAAO,CAAC,KAAK,CAAC,IAAI,MAAM,kBAAkB,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,IAAI,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;IACnG,MAAM,MAAM,GAAG,GAAG,YAAY,mBAAmB,CAAC,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC;IACrE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,EAAE,KAAK,EAAE,iBAAiB,EAAE,EAAE,CAAC;AACxD,CAAC;AAED,gDAAgD;AAChD,MAAM,UAAU,SAAS,CAAC,GAAqB,EAAE,GAAY,EAAE,MAAc;IAC3E,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,WAAW,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;IAClD,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAChC,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,qBAAqB,CACnC,KAAc,EACd,KAAa,EACb,IAAyB;IAEzB,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC;QACrD,MAAM,IAAI,mBAAmB,CAAC,GAAG,KAAK,6BAA6B,EAAE,GAAG,CAAC,CAAC;IAC5E,CAAC;IACD,OAAO,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC;AAC3C,CAAC"}

package/dist/modules/access/capability-registry.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Capability registry — the "what you can do in the app" half of the
+ * roles/groups split.
+ *
+ * Roles are CODE-DEFINED capability bundles: the product decides which roles
+ * exist and what each unlocks; admins assign them (to individuals, and to
+ * groups via `group:` members in roles.yaml — every role, Admin included,
+ * kept safe by the parse-time at-least-one-direct-email invariant on Admin).
+ * Something like "Developer" is not a role; that's a group.
+ *
+ * Adding a future role (the planned Plugin Creator) is a registry entry plus
+ * capability gates at its feature surfaces — never a parser change: the
+ * roles.yaml grammar, expansion, and admin surfaces are already
+ * role-name-agnostic.
+ *
+ * A roles.yaml role NOT in this registry is a LEGACY people-set role from
+ * before the split (e.g. "Product") — still valid as a grant principal, but
+ * really a group; the roles admin surface flags it with a convert action.
+ */
+/** A capability an app surface gates on. Grow this union with the gates. */
+export type Capability = 'manage-deployment' | 'manage-accounts' | 'manage-roles' | 'manage-groups' | 'manage-directory';
+export interface CapabilityRole {
+    canonical: string;
+    displayName: string;
+    /** Admin-facing one-liner for the Roles page. */
+    description: string;
+    capabilities: readonly Capability[];
+    /**
+     * Whether the role may be assigned to groups. True for every role, Admin
+     * included — with the parse-time invariant that Admin ALWAYS keeps at least
+     * one direct email member (see `parseRolesYaml`), so a misconfigured or
+     * unreachable directory can never leave the deployment without a
+     * directory-independent admin.
+     */
+    groupAssignable: boolean;
+}
+export declare const CAPABILITY_ROLES: readonly CapabilityRole[];
+export declare function capabilityRoleFor(roleName: string): CapabilityRole | null;
+/** A roles.yaml role that is NOT a capability role — a pre-split people-set. */
+export declare function isLegacyPeopleSetRole(roleName: string): boolean;
+//# sourceMappingURL=capability-registry.d.ts.map

package/dist/modules/access/capability-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capability-registry.d.ts","sourceRoot":"","sources":["../../../src/modules/access/capability-registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAIH,4EAA4E;AAC5E,MAAM,MAAM,UAAU,GAClB,mBAAmB,GACnB,iBAAiB,GACjB,cAAc,GACd,eAAe,GACf,kBAAkB,CAAC;AAEvB,MAAM,WAAW,cAAc;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,iDAAiD;IACjD,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,SAAS,UAAU,EAAE,CAAC;IACpC;;;;;;OAMG;IACH,eAAe,EAAE,OAAO,CAAC;CAC1B;AAED,eAAO,MAAM,gBAAgB,EAAE,SAAS,cAAc,EAiBrD,CAAC;AAEF,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,cAAc,GAAG,IAAI,CAGzE;AAED,gFAAgF;AAChF,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAE/D"}

package/dist/modules/access/capability-registry.js

@@ -0,0 +1,46 @@
+/**
+ * Capability registry — the "what you can do in the app" half of the
+ * roles/groups split.
+ *
+ * Roles are CODE-DEFINED capability bundles: the product decides which roles
+ * exist and what each unlocks; admins assign them (to individuals, and to
+ * groups via `group:` members in roles.yaml — every role, Admin included,
+ * kept safe by the parse-time at-least-one-direct-email invariant on Admin).
+ * Something like "Developer" is not a role; that's a group.
+ *
+ * Adding a future role (the planned Plugin Creator) is a registry entry plus
+ * capability gates at its feature surfaces — never a parser change: the
+ * roles.yaml grammar, expansion, and admin surfaces are already
+ * role-name-agnostic.
+ *
+ * A roles.yaml role NOT in this registry is a LEGACY people-set role from
+ * before the split (e.g. "Product") — still valid as a grant principal, but
+ * really a group; the roles admin surface flags it with a convert action.
+ */
+import { ADMIN_CANONICAL, canonicalRoleName } from './access-control.service.js';
+export const CAPABILITY_ROLES = [
+    {
+        canonical: ADMIN_CANONICAL,
+        displayName: 'Admin',
+        description: 'Detailed configuration: deployment settings, user accounts, roles & groups, and the directory connection.',
+        capabilities: [
+            'manage-deployment',
+            'manage-accounts',
+            'manage-roles',
+            'manage-groups',
+            'manage-directory',
+        ],
+        groupAssignable: true,
+    },
+    // Planned next (lands with its feature gates, not before):
+    // { canonical: 'plugin creator', displayName: 'Plugin Creator', … }
+];
+export function capabilityRoleFor(roleName) {
+    const canonical = canonicalRoleName(roleName);
+    return CAPABILITY_ROLES.find((r) => r.canonical === canonical) ?? null;
+}
+/** A roles.yaml role that is NOT a capability role — a pre-split people-set. */
+export function isLegacyPeopleSetRole(roleName) {
+    return capabilityRoleFor(roleName) === null;
+}
+//# sourceMappingURL=capability-registry.js.map

package/dist/modules/access/capability-registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"capability-registry.js","sourceRoot":"","sources":["../../../src/modules/access/capability-registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,6BAA6B,CAAC;AA0BjF,MAAM,CAAC,MAAM,gBAAgB,GAA8B;IACzD;QACE,SAAS,EAAE,eAAe;QAC1B,WAAW,EAAE,OAAO;QACpB,WAAW,EACT,2GAA2G;QAC7G,YAAY,EAAE;YACZ,mBAAmB;YACnB,iBAAiB;YACjB,cAAc;YACd,eAAe;YACf,kBAAkB;SACnB;QACD,eAAe,EAAE,IAAI;KACtB;IACD,2DAA2D;IAC3D,oEAAoE;CACrE,CAAC;AAEF,MAAM,UAAU,iBAAiB,CAAC,QAAgB;IAChD,MAAM,SAAS,GAAG,iBAAiB,CAAC,QAAQ,CAAC,CAAC;IAC9C,OAAO,gBAAgB,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,SAAS,KAAK,SAAS,CAAC,IAAI,IAAI,CAAC;AACzE,CAAC;AAED,gFAAgF;AAChF,MAAM,UAAU,qBAAqB,CAAC,QAAgB;IACpD,OAAO,iBAAiB,CAAC,QAAQ,CAAC,KAAK,IAAI,CAAC;AAC9C,CAAC"}

package/dist/modules/access/directory-sync-bot.d.ts

@@ -0,0 +1,13 @@
+import type { AuthUser } from '@bevel-software/platform-shared';
+import type { Database } from '../database/connection.js';
+/**
+ * Synthetic identity for the synced-groups materializer's commits: every
+ * `synced-groups.yaml` regeneration lands attributed to this bot, so the git
+ * history reads as "the system mirrored the IdP", never as any human.
+ * Same `<role>-bot@<host>` convention (and race-safe ensure shape) as the
+ * recovery bot.
+ */
+export declare const DIRECTORY_SYNC_BOT_EMAIL: string;
+export declare const DIRECTORY_SYNC_BOT_NAME = "Directory Sync Bot";
+export declare function ensureDirectorySyncBot(db: Database): Promise<AuthUser>;
+//# sourceMappingURL=directory-sync-bot.d.ts.map

package/dist/modules/access/directory-sync-bot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"directory-sync-bot.d.ts","sourceRoot":"","sources":["../../../src/modules/access/directory-sync-bot.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,iCAAiC,CAAC;AAChE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,2BAA2B,CAAC;AAG1D;;;;;;GAMG;AAKH,eAAO,MAAM,wBAAwB,QAEtB,CAAC;AAEhB,eAAO,MAAM,uBAAuB,uBAAuB,CAAC;AAE5D,wBAAsB,sBAAsB,CAAC,EAAE,EAAE,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC,CAqD5E"}