@bevel-software/platform-core-backend 0.7.4 → 0.8.0

package/src/modules/workflow/git/__tests__/git.service.commitFile.test.ts

@@ -139,8 +139,10 @@ describe('GitService.commitFile — skipValidator', () => {
       'knowledge-base',
     );
 
-    const relPath = 'Purchasing/[Updated 03.09.2025] Purchasing_How to search_Product detail page.md';
-    await fs.mkdir(path.join(repo, 'Purchasing'), { recursive: true });
+    // Shape mirrors the reported filename (bracketed status prefix carrying a
+    // date, underscores, spaces) without reproducing anyone's actual content.
+    const relPath = 'Handbook/[Updated 03.09.2025] Handbook_How to search_Detail page.md';
+    await fs.mkdir(path.join(repo, 'Handbook'), { recursive: true });
     await fs.writeFile(path.join(repo, relPath), 'content\n');
 
     const change = await svc.commitFile(workspaceId, USER, relPath);
@@ -168,15 +170,18 @@ describe('GitService.commitFile — skipValidator', () => {
       'knowledge-base',
     );
 
+    // Synthetic segments matching the SHAPE of real deep-KB naming (numbered
+    // prefixes, parenthesised abbreviations, kebab tails) — the property under
+    // test is only the total length, asserted below.
     const deepDir = path.join(
-      'Product',
+      'Handbook',
       'Knowledge',
-      '1. Service Commitment Management',
-      '1.1 In - Architecture Layering (AL)',
-      '0-Governance',
-      '0.5-Layer-Group-Specific-Governance-Principles',
+      '1. First-Level Section With A Long Name',
+      '1.1 In - Second-Level Subsection (SL)',
+      '0-Reference',
+      '0.5-Third-Level-Reference-Naming-Convention',
     );
-    const fileName = '0.5.5-Buyer-Side-Commercial-Agreement-Governance.md';
+    const fileName = '0.5.5-A-Deeply-Nested-Reference-Document-With-A-Long-Name.md';
     const relPath = path.posix.join(deepDir.split(path.sep).join('/'), fileName);
     expect(`Update ${relPath}`.length).toBeGreaterThan(200);
 

package/src/modules/workflow/git/__tests__/git.service.deleteBranch.test.ts

@@ -134,7 +134,7 @@ function fakeAccessControl(adminEmails: string[]): IAccessControl {
     canOwner: async () => notImpl(),
     invalidate: () => {},
     findEmailByHash: async () => null,
-    kbPrincipals: async () => ({ groups: [], people: [] }),
+    kbPrincipals: async () => ({ plugins: [], people: [] }),
     validateRolesYaml: () => ({ ok: true }),
     referencesToRole: async () => [],
     canWriteAtRef: async () => null,

package/src/modules/workflow/git/__tests__/pull-request.service.test.ts

@@ -64,7 +64,7 @@ function makeAccessControl(byRef: WritersByRefAndPath): IAccessControl {
     eligibleWritersAtRef: async () => null,
     eligibleWritersForPathsAtRef: async () => null,
     findEmailByHash: async () => null,
-    kbPrincipals: async () => ({ groups: [], people: [] }),
+    kbPrincipals: async () => ({ plugins: [], people: [] }),
     validateRolesYaml: () => ({ ok: true }),
     referencesToRole: async () => [],
   };

package/src/modules/workflow/git/git.service.ts

@@ -1047,12 +1047,12 @@ export class GitService implements IGitService {
       // protected pushes; that's defence-in-depth against local rebases or
       // `commit-tree` shenanigans that might bypass the commit-time gate.
       // `systemAuthorized` skips the gate for flows whose ENDPOINT is the
-      // authorization — group provisioning commits an access.md into a
+      // authorization — plugin provisioning commits an access.md into a
       // folder that does not exist at origin yet, which this gate can only
       // ever read as "write: Admin". The provisioning service has already
       // decided the write is legitimate (unused name, exclusive create);
       // gating it here again just refuses every non-admin the product
-      // promised a group to.
+      // promised a plugin to.
       if (isProtectedBranch(branch) && !opts?.systemAuthorized) {
         const touched = await this.unpushedTouchedPaths(cwd);
         await this.assertCanWriteAtRef(

package/src/modules/workflow/pending-commits.service.ts

@@ -276,18 +276,7 @@ export class PendingCommitsService {
   async claimNext(rawWorkspaceId: string, now: Date): Promise<PendingCommit | null> {
     // Match the canonical form `enqueue` stores (see `canonicalWorkspaceId`).
     const workspaceId = canonicalWorkspaceId(rawWorkspaceId);
-    // Backoff schedule as a SQL CASE so the gate runs server-side instead
-    // of round-tripping the row to compute eligibility. Index in BACKOFF_MS
-    // matches `attempts` directly — covers `attempts == 0` (a recovery-reset
-    // row whose `lastAttemptedAt` is non-null; without this, it would fall
-    // into ELSE = max backoff and be stuck waiting 30s after every recovery).
-    const caseArms = BACKOFF_MS.map((ms, i) => sql`WHEN ${i} THEN ${ms}`);
-    const lastMs = BACKOFF_MS[BACKOFF_MS.length - 1];
-    const backoffMsExpr = sql`(CASE ${pendingCommits.attempts} ${sql.join(caseArms, sql` `)} ELSE ${lastMs} END)`;
-    const readyExpr = or(
-      isNull(pendingCommits.lastAttemptedAt),
-      sql`${pendingCommits.lastAttemptedAt} + (${backoffMsExpr} || ' milliseconds')::interval <= ${now}`,
-    );
+    const readyExpr = readyPredicate(now);
     const claimed = await this.db
       .update(pendingCommits)
       .set({ status: 'running', lastAttemptedAt: now })
@@ -306,6 +295,32 @@ export class PendingCommitsService {
     return claimed.length > 0 ? rowToPending(claimed[0]) : null;
   }
 
+  /**
+   * Whether another row is ready for `workspaceId` right now — a peek, with
+   * the same readiness rule `claimNext` uses but claiming nothing.
+   *
+   * The worker asks this AFTER claiming a row, to learn whether the one in
+   * hand is the last of a burst. Everything before the last can skip the
+   * advisory commit validator: it parses the whole KB to produce a report
+   * that is only logged, and re-parsing per file made a bulk change (a
+   * migration, an agent run) cost one full parse per commit.
+   */
+  async hasReadyRow(rawWorkspaceId: string, now: Date): Promise<boolean> {
+    const workspaceId = canonicalWorkspaceId(rawWorkspaceId);
+    const rows = await this.db
+      .select({ id: pendingCommits.id })
+      .from(pendingCommits)
+      .where(
+        and(
+          eq(pendingCommits.workspaceId, workspaceId),
+          eq(pendingCommits.status, 'pending'),
+          readyPredicate(now),
+        ),
+      )
+      .limit(1);
+    return rows.length > 0;
+  }
+
   /**
    * Commit + push landed. Drop the row.
    */
@@ -481,3 +496,24 @@ export class PendingCommitsService {
   }
 }
 
+
+/**
+ * The "ready to attempt" gate, shared by `claimNext` and `hasReadyRow` so a
+ * peek can never disagree with the claim that follows it.
+ *
+ * Backoff is a SQL CASE so the gate runs server-side instead of round-tripping
+ * every row to compute eligibility. The index into `BACKOFF_MS` is `attempts`
+ * directly, not `attempts - 1`: that covers the recovery-reset case where
+ * `attempts` is 0 but `lastAttemptedAt` is non-null, which would otherwise
+ * fall into the default arm and idle for the maximum backoff after every
+ * recovery run.
+ */
+function readyPredicate(now: Date) {
+  const caseArms = BACKOFF_MS.map((ms, i) => sql`WHEN ${i} THEN ${ms}`);
+  const lastMs = BACKOFF_MS[BACKOFF_MS.length - 1];
+  const backoffMsExpr = sql`(CASE ${pendingCommits.attempts} ${sql.join(caseArms, sql` `)} ELSE ${lastMs} END)`;
+  return or(
+    isNull(pendingCommits.lastAttemptedAt),
+    sql`${pendingCommits.lastAttemptedAt} + (${backoffMsExpr} || ' milliseconds')::interval <= ${now}`,
+  );
+}

package/src/modules/workflow/pending-commits.worker.ts

@@ -56,6 +56,16 @@ export const consoleSystemNoticeSink: ISystemNoticeSink = {
  */
 const POLL_INTERVAL_MS = 500;
 
+/**
+ * Ceiling on rows drained from ONE workspace before the sweep moves on.
+ * Fairness, not throughput: the loop holds the single in-flight commit slot,
+ * so an unbounded drain would let one workspace's thousand-file migration
+ * stall every other user's save until it finished. At this size a normal
+ * bulk change (tens of files) still lands in one sweep, and a huge one gives
+ * way after a bounded stretch and resumes on the next pass.
+ */
+const MAX_BURST_PER_WORKSPACE = 50;
+
 /**
  * The recovery-agent dispatcher the worker calls when a row exhausts its
  * transient budget. Pulled behind an interface so the unit tests can
@@ -99,6 +109,7 @@ export interface WorkflowCommitDriver {
     branch: string,
     path: string,
     user: AuthUser,
+    opts?: { skipValidation?: boolean },
   ): Promise<void>;
 }
 
@@ -176,18 +187,61 @@ export class PendingCommitsWorker {
   }
 
   /**
-   * Run one drain pass: rotate through known workspaces, claim+process
-   * one row from each. Exposed publicly so tests can step the loop
-   * deterministically without driving `setTimeout`.
+   * Run one drain pass: rotate through known workspaces, draining each
+   * one's ready rows before moving on. Exposed publicly so tests can step
+   * the loop deterministically without driving `setTimeout`.
+   *
+   * Draining a BURST rather than a single row per sweep is what keeps a
+   * bulk change honest. One row per sweep, with a `POLL_INTERVAL_MS` sleep
+   * after every pass, capped a workspace at ~2 commits/second no matter how
+   * fast git was — so a migration or an agent run that touched a hundred
+   * files spent a minute of pure polling latency, and anything waiting on
+   * the queue to settle (a change request being applied) waited with it.
+   *
+   * A failing row cannot spin this loop: `markTransientFailure` leaves
+   * `lastAttemptedAt` set, so the backoff gate in `claimNext` refuses to
+   * hand the same row back within the same sweep.
    */
   async drainOnce(): Promise<void> {
     for (const workspace of this.deps.workspaces.knownWorkspaces()) {
       // Bail mid-sweep if stop() fired — the in-flight workspace gets
       // to finish but we don't start a new one.
       if (!this.running) return;
-      const row = await this.deps.service.claimNext(workspace.id, this.deps.now());
-      if (!row) continue;
-      await this.processRow(row);
+      for (let drained = 0; drained < MAX_BURST_PER_WORKSPACE; drained += 1) {
+        if (!this.running) return;
+        const row = await this.deps.service.claimNext(workspace.id, this.deps.now());
+        if (!row) break;
+        // Is this the last commit of the burst? Everything before it can skip
+        // the advisory commit validator, which parses the whole KB to produce
+        // a report that is only logged. Running it per file made a bulk change
+        // pay one full parse per commit; running it on the last one reports
+        // the same end state once. Asked AFTER the claim, so the row in hand
+        // is already out of `pending` and cannot answer for itself.
+        //
+        // At the burst ceiling this IS the last commit of the pass, however
+        // many rows remain queued — so it must validate, or a backlog larger
+        // than the cap would end every sweep on a skipped validation. Known
+        // without asking, so the ceiling is checked BEFORE the peek rather
+        // than folded in after it: on a big backlog that would be one wasted
+        // round-trip per sweep, on the hot path this change exists to speed up.
+        let lastOfBurst = drained === MAX_BURST_PER_WORKSPACE - 1;
+        if (!lastOfBurst) {
+          // The peek is an OPTIMISATION, never a gate: the row is already
+          // claimed and `running`, and throwing here would abandon it in that
+          // state — nothing resets it, so the workspace would stop draining
+          // until the process restarted. A failed peek therefore means
+          // "assume last", costing one extra validation pass and nothing else.
+          try {
+            lastOfBurst = !(await this.deps.service.hasReadyRow(workspace.id, this.deps.now()));
+          } catch (peekErr) {
+            console.warn(
+              `[pending-commits] ready-row peek failed for ws=${workspace.id}; validating this commit: ${sanitizeError(peekErr)}`,
+            );
+            lastOfBurst = true;
+          }
+        }
+        await this.processRow(row, { skipValidation: !lastOfBurst });
+      }
     }
   }
 
@@ -226,7 +280,7 @@ export class PendingCommitsWorker {
    *   - throws, transient exhausted, recovery budget remains → spawn agent.
    *   - throws, recovery exhausted → markNeedsAttention + feedback notice.
    */
-  private async processRow(row: PendingCommit): Promise<void> {
+  private async processRow(row: PendingCommit, opts?: { skipValidation?: boolean }): Promise<void> {
     const user: AuthUser = {
       // The worker doesn't have a real `users.id` for the commit author —
       // commit attribution flows through `git commit --author="Name <email>"`,
@@ -237,7 +291,9 @@ export class PendingCommitsWorker {
       name: row.authorName,
     };
     try {
-      await this.deps.workflow.runPendingCommit(row.workspaceId, row.branch, row.path, user);
+      await this.deps.workflow.runPendingCommit(row.workspaceId, row.branch, row.path, user, {
+        skipValidation: opts?.skipValidation,
+      });
       await this.deps.service.markSucceeded(row.id);
       return;
     } catch (err) {

package/src/modules/workflow/review-workflow/__tests__/approval-states.test.ts

@@ -164,7 +164,7 @@ function makeAccessControl(byPath: EligibilityByPath): IAccessControl {
       return result;
     },
     findEmailByHash: async () => null,
-    kbPrincipals: async () => ({ groups: [], people: [] }),
+    kbPrincipals: async () => ({ plugins: [], people: [] }),
     validateRolesYaml: () => ({ ok: true }),
     referencesToRole: async () => [],
   };

package/src/modules/workflow/review-workflow/__tests__/cancel-pr.test.ts

@@ -53,7 +53,7 @@ function makeAccessControl(adminEmails: string[] = []): IAccessControl {
     eligibleWritersAtRef: async () => null,
     eligibleWritersForPathsAtRef: async () => null,
     findEmailByHash: async () => null,
-    kbPrincipals: async () => ({ groups: [], people: [] }),
+    kbPrincipals: async () => ({ plugins: [], people: [] }),
     validateRolesYaml: () => ({ ok: true }),
     referencesToRole: async () => [],
   };

package/src/modules/workflow/workflow-hooks.ts

@@ -1,101 +1,101 @@
-import type { ValidationReport } from '@bevel-software/platform-shared';
-
-/**
- * Workflow lifecycle hooks — the generic seam that replaced the
- * constructor-injected KB validator (and the core-owned ontology write block).
- * Core code invokes the hooks at fixed lifecycle points; the modules that OWN
- * the behavior (the enterprise kb/kb-graph modules today) register handlers in
- * the composition root, right after `createCoreServices` returns. Core
- * registers none, so a core-only deployment runs every hook point as a no-op.
- *
- * Two hook kinds with deliberately different failure semantics:
- *
- *   - `commitValidation` — ADVISORY. Runs at commit time in `GitService`
- *     (`commit` / `commitFile`), exactly where the injected `IKbValidator`
- *     used to run. A returned report with `mustFix` entries is logged/surfaced
- *     but NEVER blocks the commit, and a hook that throws is caught and logged
- *     (see CLAUDE.md "Validation is advisory"). The signature mirrors the old
- *     `runValidation(workspaceId)` shape so `KbValidatorService` registers
- *     with a one-line adapter.
- *
- *   - `preWrite` — BLOCKING. Runs before a gated agent write (file-write
- *     tools) or a write-capable shell command; a hook that throws REJECTS the
- *     operation (the error propagates to the tool caller). This is where the
- *     enterprise ontology-session block registers; core registers nothing, so
- *     core never blocks (touch TRACKING stays core — see
- *     `session-ontology.gate.ts`).
- */
-
-/** What `GitService` knows at the advisory commit-validation point. */
-export interface CommitValidationContext {
-  workspaceId: string;
-  branch: string;
-  /**
-   * Repo-relative paths the commit will include — the full touched set for
-   * `commit()`, a single element for the one-file `commitFile()` path.
-   */
-  paths: string[];
-}
-
-/**
- * Advisory commit-time validation. Return a report to have the caller log /
- * surface it (or `void` for "nothing to say"). Throwing is tolerated — the
- * caller catches and logs, never blocks the commit.
- */
-export type CommitValidationHook = (
-  ctx: CommitValidationContext,
-) => Promise<ValidationReport | void>;
-
-/**
- * What the pre-write gate knows when it consults the blocking hooks. The core
- * gate has already resolved all skip conditions (boundary flag off, neutral
- * path, non-agent caller, recovery bot, missing session id — see
- * `resolveGatedSession`), so by hook time there is always a session id.
- */
-export type PreWriteContext =
-  /** A path-addressed content write (write_file/edit_file/mkdir/move/copy/unzip…). */
-  | { kind: 'file-write'; sessionId: string; wsPath: string }
-  /** A write-capable operation with no resolvable target path (execute_command). */
-  | { kind: 'shell'; sessionId: string };
-
-/** Blocking pre-write hook: throw to reject the write; return to allow. */
-export type PreWriteHook = (ctx: PreWriteContext) => Promise<void>;
-
-/**
- * The registry instance. ONE per composition (created in
- * `createCoreServices`, shared by `GitService` and exposed as
- * `WorkflowService.hooks` for the composition root to register against).
- */
-export class WorkflowHooks {
-  private readonly commitValidation: CommitValidationHook[] = [];
-  private readonly preWrite: PreWriteHook[] = [];
-
-  /** Register an advisory commit-time validation hook. */
-  onCommitValidation(hook: CommitValidationHook): void {
-    this.commitValidation.push(hook);
-  }
-
-  /** Register a blocking pre-write hook. */
-  onPreWrite(hook: PreWriteHook): void {
-    this.preWrite.push(hook);
-  }
-
-  /**
-   * The registered commit-validation hooks, for the caller (`GitService`) to
-   * iterate with its own advisory catch-and-log semantics.
-   */
-  commitValidationHooks(): readonly CommitValidationHook[] {
-    return this.commitValidation;
-  }
-
-  /**
-   * Run every blocking pre-write hook in registration order. The first throw
-   * propagates and rejects the write; with no hooks registered (core-only)
-   * this resolves immediately.
-   */
-  async runPreWrite(ctx: PreWriteContext): Promise<void> {
-    for (const hook of this.preWrite) {
-      await hook(ctx);
-    }
-  }
-}
+import type { ValidationReport } from '@bevel-software/platform-shared';
+
+/**
+ * Workflow lifecycle hooks — the generic seam that replaced the
+ * constructor-injected KB validator (and the core-owned ontology write block).
+ * Core code invokes the hooks at fixed lifecycle points; the modules that OWN
+ * the behavior (the enterprise kb/kb-graph modules today) register handlers in
+ * the composition root, right after `createCoreServices` returns. Core
+ * registers none, so a core-only deployment runs every hook point as a no-op.
+ *
+ * Two hook kinds with deliberately different failure semantics:
+ *
+ *   - `commitValidation` — ADVISORY. Runs at commit time in `GitService`
+ *     (`commit` / `commitFile`), exactly where the injected `IKbValidator`
+ *     used to run. A returned report with `mustFix` entries is logged/surfaced
+ *     but NEVER blocks the commit, and a hook that throws is caught and logged
+ *     (see CLAUDE.md "Validation is advisory"). The signature mirrors the old
+ *     `runValidation(workspaceId)` shape so `KbValidatorService` registers
+ *     with a one-line adapter.
+ *
+ *   - `preWrite` — BLOCKING. Runs before a gated agent write (file-write
+ *     tools) or a write-capable shell command; a hook that throws REJECTS the
+ *     operation (the error propagates to the tool caller). This is where the
+ *     enterprise ontology-session block registers; core registers nothing, so
+ *     core never blocks (touch TRACKING stays core — see
+ *     `session-ontology.gate.ts`).
+ */
+
+/** What `GitService` knows at the advisory commit-validation point. */
+export interface CommitValidationContext {
+  workspaceId: string;
+  branch: string;
+  /**
+   * Repo-relative paths the commit will include — the full touched set for
+   * `commit()`, a single element for the one-file `commitFile()` path.
+   */
+  paths: string[];
+}
+
+/**
+ * Advisory commit-time validation. Return a report to have the caller log /
+ * surface it (or `void` for "nothing to say"). Throwing is tolerated — the
+ * caller catches and logs, never blocks the commit.
+ */
+export type CommitValidationHook = (
+  ctx: CommitValidationContext,
+) => Promise<ValidationReport | void>;
+
+/**
+ * What the pre-write gate knows when it consults the blocking hooks. The core
+ * gate has already resolved all skip conditions (boundary flag off, neutral
+ * path, non-agent caller, recovery bot, missing session id — see
+ * `resolveGatedSession`), so by hook time there is always a session id.
+ */
+export type PreWriteContext =
+  /** A path-addressed content write (write_file/edit_file/mkdir/move/copy/unzip…). */
+  | { kind: 'file-write'; sessionId: string; wsPath: string }
+  /** A write-capable operation with no resolvable target path (execute_command). */
+  | { kind: 'shell'; sessionId: string };
+
+/** Blocking pre-write hook: throw to reject the write; return to allow. */
+export type PreWriteHook = (ctx: PreWriteContext) => Promise<void>;
+
+/**
+ * The registry instance. ONE per composition (created in
+ * `createCoreServices`, shared by `GitService` and exposed as
+ * `WorkflowService.hooks` for the composition root to register against).
+ */
+export class WorkflowHooks {
+  private readonly commitValidation: CommitValidationHook[] = [];
+  private readonly preWrite: PreWriteHook[] = [];
+
+  /** Register an advisory commit-time validation hook. */
+  onCommitValidation(hook: CommitValidationHook): void {
+    this.commitValidation.push(hook);
+  }
+
+  /** Register a blocking pre-write hook. */
+  onPreWrite(hook: PreWriteHook): void {
+    this.preWrite.push(hook);
+  }
+
+  /**
+   * The registered commit-validation hooks, for the caller (`GitService`) to
+   * iterate with its own advisory catch-and-log semantics.
+   */
+  commitValidationHooks(): readonly CommitValidationHook[] {
+    return this.commitValidation;
+  }
+
+  /**
+   * Run every blocking pre-write hook in registration order. The first throw
+   * propagates and rejects the write; with no hooks registered (core-only)
+   * this resolves immediately.
+   */
+  async runPreWrite(ctx: PreWriteContext): Promise<void> {
+    for (const hook of this.preWrite) {
+      await hook(ctx);
+    }
+  }
+}

package/src/modules/workflow/workflow.service.ts

@@ -808,9 +808,20 @@ export class WorkflowService implements IWorkflowService {
     branch: string,
     targetPath: string,
     user: AuthUser,
-    opts?: { systemAuthorized?: boolean },
+    opts?: { systemAuthorized?: boolean; skipValidation?: boolean },
   ): Promise<void> {
-    const change = await this.git.commitFile(workspaceId, user, targetPath);
+    // `skipValidation` is the worker telling us this commit is not the last of
+    // a burst. The validator is advisory — it parses the whole KB to produce a
+    // report nothing reads but the log — so running it once on the burst's
+    // final state says the same thing as running it per file, for a fraction
+    // of the work. Nothing downstream depends on it having run.
+    const change = await this.git.commitFile(
+      workspaceId,
+      user,
+      targetPath,
+      undefined,
+      opts?.skipValidation,
+    );
     if (!change) {
       // No-op commit — the path was already clean. Usually a double-enqueue
       // or a save of bytes identical to HEAD, BUT a clean tree does NOT