@bevel-software/platform-core-backend 0.34.0 → 0.36.1

package/src/modules/auth/account-erasure.service.ts

@@ -5,7 +5,7 @@ const log = logger('account-erasure');
 import { and, eq, notExists } from 'drizzle-orm';
 import { isEncryptedBlob } from '../../shared/column-crypto.js';
 import type { Database } from '../database/index.js';
-import type { IReviewWorkflowService } from '../workflow/index.js';
+import type { IChangeRequestReviewService } from '../version-control/index.js';
 import {
   changeRequests,
   externalApiKeys,
@@ -114,14 +114,32 @@ export class AccountErasureService implements IAccountErasureService {
   constructor(
     private readonly db: Database,
     /**
-     * The review workflow owns the approvals and the lock their writers take,
-     * so it does the rewrite (see `IReviewWorkflowService.eraseApprover`);
+     * The change-request review owns the approvals and the lock their writers take,
+     * so it does the rewrite (see `IChangeRequestReviewService.eraseApprover`);
      * this module only decides WHEN, inside its own transaction.
      */
-    private readonly reviewWorkflow: Pick<IReviewWorkflowService, 'eraseApprover'>,
+    private readonly changeRequestReview: Pick<IChangeRequestReviewService, 'eraseApprover'>,
+    /**
+     * The distribution's slices (`CorePorts.erasureParticipants`): held by
+     * reference, read at erasure time, so a root may fill the array after
+     * construction.
+     */
     private readonly participants: IErasureParticipant[] = [],
+    /**
+     * Core's own module slices (the vault's managed sign-ins, say), run
+     * BEFORE the distribution's. Kept apart from the port's array so core
+     * never writes into an array it does not own: a root that builds a graph
+     * over the same array more than once would otherwise accumulate every
+     * past graph's slices, each still pointing at that graph's closed pool.
+     */
+    private readonly coreParticipants: IErasureParticipant[] = [],
   ) {}
 
+  /** Every slice, core's first, as it is at erasure time. */
+  private allParticipants(): IErasureParticipant[] {
+    return [...this.coreParticipants, ...this.participants];
+  }
+
   async listUsers(): Promise<AdminUserView[]> {
     // Sorted in-process: `email` is ciphertext in the database, so ORDER BY
     // would sort by IV noise. One row per team member.
@@ -162,7 +180,7 @@ export class AccountErasureService implements IAccountErasureService {
     // outside the transaction on purpose: external stores are separate
     // systems, and the pre-passes are idempotent, so a failure here leaves a
     // retryable state rather than a half-committed one.
-    for (const p of this.participants) {
+    for (const p of this.allParticipants()) {
       if (p.before) await p.before(target);
     }
 
@@ -209,14 +227,14 @@ export class AccountErasureService implements IAccountErasureService {
 
       // Audit rows: anonymize in place (no user FK on these; they key by email).
       //
-      // The approvals belong to the review workflow, and so does the lock
+      // The approvals belong to the change-request review, and so does the lock
       // their writers take — one of those writers COPIES rows (a change request
       // bringing itself up to date re-pins the approvals its merge did not
       // disturb onto the new head), and a copy that read this person's row a
       // moment before the rewrite would insert their real address back
-      // afterwards. The workflow takes that lock exclusively and rewrites the
+      // afterwards. The version-control service takes that lock exclusively and rewrites the
       // rows, in THIS transaction, so it stays held until the erasure commits.
-      await this.reviewWorkflow.eraseApprover(tx, target.email, {
+      await this.changeRequestReview.eraseApprover(tx, target.email, {
         email: target.erasedEmail,
         name: target.erasedName,
       });
@@ -251,7 +269,7 @@ export class AccountErasureService implements IAccountErasureService {
       // still satisfiable — and so a participant that MISSES rows makes the
       // users delete below fail on its RESTRICT FK, rolling everything back:
       // a loud retry, never a silent orphan.
-      for (const p of this.participants) {
+      for (const p of this.allParticipants()) {
         if (!p.inTransaction) continue;
         const cb = await p.inTransaction(tx, target);
         if (cb) postCommit.push(cb);

package/src/modules/auth/account-hooks.ts

@@ -41,8 +41,27 @@ export interface IAccountHooks {
   onAccountInvited(hook: AccountInvitedHook): void;
   /** Run every listener in registration order; the channels that reached the person, in that order. */
   runAccountInvited(event: AccountInvitedEvent): Promise<string[]>;
+  onAccountDeactivated(hook: AccountDeactivatedHook): void;
+  /** Run every listener in registration order; what each cleaned up, in that order. */
+  runAccountDeactivated(event: AccountDeactivatedEvent): Promise<string[]>;
 }
 
+/**
+ * An admin switched an account off (or a directory told the deployment the
+ * person left). The account keeps its row; what it HOLDS elsewhere — the
+ * sign-ins it made to outside systems — is what listeners let go of.
+ */
+export interface AccountDeactivatedEvent {
+  userId: string;
+  email: string;
+}
+
+/**
+ * A listener answers what it cleaned up — `'managed-connections'`, say — or
+ * null when there was nothing; same rule as {@link AccountInvitedHook}.
+ */
+export type AccountDeactivatedHook = NotifyingListener<AccountDeactivatedEvent>;
+
 export class AccountHooks implements IAccountHooks {
   // The account exists whether or not the person was told: the admin's
   // answer says they were not, and the admin sends the link themselves.
@@ -50,6 +69,13 @@ export class AccountHooks implements IAccountHooks {
     log,
     'an account-invited listener failed; the person was not notified by it:',
   );
+  // The account is off whether or not a listener cleaned up after it: a
+  // failure here is logged, and the sign-ins it left are refused on use
+  // like everything else a deactivated account holds.
+  private readonly deactivated = new ListenerSeam<AccountDeactivatedEvent>(
+    log,
+    'an account-deactivated listener failed; what it cleans up is still there:',
+  );
 
   onAccountInvited(hook: AccountInvitedHook): void {
     this.invited.add(hook);
@@ -58,4 +84,12 @@ export class AccountHooks implements IAccountHooks {
   runAccountInvited(event: AccountInvitedEvent): Promise<string[]> {
     return this.invited.run(event);
   }
+
+  onAccountDeactivated(hook: AccountDeactivatedHook): void {
+    this.deactivated.add(hook);
+  }
+
+  runAccountDeactivated(event: AccountDeactivatedEvent): Promise<string[]> {
+    return this.deactivated.run(event);
+  }
 }

package/src/modules/auth/account-switch-lock.ts

@@ -1,7 +1,7 @@
 import { sql } from 'drizzle-orm';
 import type { Database } from '../database/index.js';
 import { canonicalEmail } from '../../shared/email-identity.js';
-import { WorkflowDomainError } from '../../shared/domain-errors.js';
+import { VersionControlDomainError } from '../../shared/domain-errors.js';
 import { pgErrorCode } from '../database/index.js';
 
 /** The handle `db.transaction` hands its callback. */
@@ -51,7 +51,7 @@ export async function takeAccountSwitchLock(
   } catch (err) {
     // Drizzle wraps the driver's error, so the SQLSTATE is on its cause.
     if (pgErrorCode(err) === LOCK_NOT_AVAILABLE) {
-      throw new WorkflowDomainError(ACCOUNT_BUSY_MESSAGE, 409, { kind: 'account-busy' });
+      throw new VersionControlDomainError(ACCOUNT_BUSY_MESSAGE, 409, { kind: 'account-busy' });
     }
     throw err;
   }

package/src/modules/auth/account.routes.ts

@@ -12,7 +12,7 @@ import { erasedAccountId, type IAccountErasureService } from './account-erasure.
 import type { IAdminAccessService } from '../admin/index.js';
 import type { UserAccessRemovalService } from '../access/index.js';
 import { sendError } from '../access/index.js';
-import { WorkflowDomainError } from '../../shared/domain-errors.js';
+import { VersionControlDomainError } from '../../shared/domain-errors.js';
 import { canonicalEmail } from '../../shared/email-identity.js';
 import './auth.middleware.js'; // Express Request augmentation
 
@@ -42,8 +42,13 @@ export function createAccountRoutes(
   >,
   adminAccess: IAdminAccessService,
   accountErasure: Pick<IAccountErasureService, 'eraseUser'>,
-  /** Who tells an invited person (see {@link IAccountHooks}); core registers nobody. */
-  accountHooks: Pick<IAccountHooks, 'runAccountInvited'>,
+  /**
+   * Who tells an invited person, and who cleans up after an account is
+   * switched off (see {@link IAccountHooks}); core registers nobody for
+   * either. A distribution registers what it holds for a person elsewhere
+   * (its managed-connector sign-ins, say) where it builds that.
+   */
+  accountHooks: Pick<IAccountHooks, 'runAccountInvited' | 'runAccountDeactivated'>,
   accessRemoval?: Pick<UserAccessRemovalService, 'report' | 'assertRemovable' | 'remove' | 'filesNaming'>,
 ): express.Router {
   const router = express.Router();
@@ -176,11 +181,24 @@ export function createAccountRoutes(
       return;
     }
     try {
+      // Read before the switch, so the listeners get the address the account
+      // had; the row keeps it either way, so a failed read is tried once more
+      // after the switch, and never costs the switch-off itself.
+      let target = await authService.getUserById(userId).catch(() => undefined);
       if (!(await authService.deactivate(userId))) {
         res.status(404).json({ error: 'No such user' });
         return;
       }
       log.info('account audit:', { action: 'deactivate', actorUserId: req.userId, targetUserId: userId });
+      if (!target) target = await authService.getUserById(userId).catch(() => undefined);
+      if (!target) {
+        log.warn('account deactivated, but its address could not be read for the listeners', { targetUserId: userId });
+      }
+      // What the account HELD elsewhere — the sign-ins it made to outside
+      // systems — is let go of now rather than left to lapse. Awaited, so
+      // the admin's answer means it: a listener that fails is logged by the
+      // seam and never fails the switch-off that already happened.
+      await accountHooks.runAccountDeactivated({ userId, email: target?.email ?? '' });
       res.status(204).end();
     } catch (error) {
       if (error instanceof AccountChangeRefusedError) {
@@ -191,7 +209,7 @@ export function createAccountRoutes(
       // invite's promotion committing roles.yaml, say): the 409 the lock
       // promises, with its words, so the admin tries again rather than
       // reading an outage.
-      if (error instanceof WorkflowDomainError) {
+      if (error instanceof VersionControlDomainError) {
         res.status(error.status).json({ error: error.message, ...(error.payload ?? {}) });
         return;
       }
@@ -343,7 +361,7 @@ export function createAccountRoutes(
         log.warn(`could not list the files still naming erased account ${accountId}: ${errorText(scanErr)}`);
       }
       const message =
-        err instanceof WorkflowDomainError && err.status < 500
+        err instanceof VersionControlDomainError && err.status < 500
           ? err.message
           : 'The change to roles, groups and access rules could not be committed.';
       res.json({ erased: true, accessRemoval: { ok: false, error: message, removedFrom: [], stillNamedIn } });

package/src/modules/auth/auth.service.ts

@@ -20,11 +20,11 @@ import {
   timingSafeStringEqual,
   MIN_PASSWORD_LENGTH,
 } from './password-hash.js';
-import { RECOVERY_BOT_EMAIL } from '../workflow/index.js';
+import { RECOVERY_BOT_EMAIL } from '../version-control/index.js';
 import { DIRECTORY_SYNC_BOT_EMAIL } from '../access/index.js';
 import { takeAccountSwitchLock } from './account-switch-lock.js';
 import type { IAccountSwitchGuard } from './account-switch-guard.js';
-import { WorkflowDomainError } from '../../shared/domain-errors.js';
+import { VersionControlDomainError } from '../../shared/domain-errors.js';
 
 const EMAIL_REGEX = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
 
@@ -895,7 +895,7 @@ export class AuthService implements IAccountSwitchGuard {
         .from(users)
         .where(eq(users.emailBidx, canonicalEmail(email)));
       if (account?.deactivatedAt) {
-        throw new WorkflowDomainError('This account is switched off', 409, { kind: 'deactivated' });
+        throw new VersionControlDomainError('This account is switched off', 409, { kind: 'deactivated' });
       }
       await write();
     });
@@ -965,7 +965,7 @@ export class AuthService implements IAccountSwitchGuard {
 
   /**
    * The live accounts behind a set of addresses — the approvers of a change
-   * request just opened, which the workflow module hands to the deployment's
+   * request just opened, which the version-control module hands to the deployment's
    * notification listeners as people with accounts (`ApproverAccounts`).
    *
    * One indexed read through the email's blind index, never a scan of every

package/src/modules/auth/index.ts

@@ -32,3 +32,4 @@ import './auth.middleware.js';
 // Reached by other modules; exported here so they stop importing the files.
 export type { IAccountSwitchGuard } from './account-switch-guard.js';
 export type { AuthService } from './auth.service.js';
+export type { IAccountErasureService } from './account-erasure.service.js';

package/src/modules/code-mode/code-mode.tool.ts

@@ -51,7 +51,7 @@ export function createCallToolChainTool(
       `There is NO single calling shape: some tools take their arguments under a \`body\` object, others take them flat. Call each tool as the \`Call:\` line at the top of its own description shows — it is generated from that tool's input schema, and every tool in \`${ns}\` has one. Every argument a tool declares REQUIRED must be present; for the knowledge-base tools that includes \`branch\`. Arguments that do not match the schema are refused before anything is sent or run, and the refusal carries the tool's interface.`,
       'Error handling inside the chain: a failing tool call THROWS, and the thrown error\'s `.message` holds the server\'s actual reason (e.g. a 403 with the explanation, not just a status code). If you catch it, surface `err.message` (and `err.status` / `err.data` when present) — NEVER `return { error: err }` or otherwise return the raw Error object, because an Error serializes to `{}` (its `message` is non-enumerable) and the reason is lost. If you don\'t need to handle it, just let it throw — the runtime already reports `err.message` back to you.',
       `Failures are answered, never dropped: a chain that throws comes back with \`success: false\` and the reason, and one that outlives \`timeout\` (default ${CHAIN_TIMEOUT_DEFAULT_MS} ms, maximum ${CHAIN_TIMEOUT_MAX_MS} ms) comes back saying it timed out — raise \`timeout\` or split the work and run it again. Either way your next tool call works as usual.`,
-      'Large return values: if the returned value exceeds `max_output_size`, the full JSON is auto-spilled to a shared spill store (outside any workspace, never committed) and the response contains only a `__tool_chain_spill__/…` ref + a truncated marker. You can read the spill back with the regular `read_file` tool — pass that ref as `path` (its `branch` is ignored) plus `offset` / `limit` to slice it, never read a multi-MB file in full. Order of preference: (1) re-run `call_tool_chain` with a follow-up code chain that filters/maps the data inline and returns just what you need; (2) narrow the API call — shorter `fields`, tighter date window, lower `limit`; (3) last resort — `read_file` against the spill ref with `offset` / `limit`. The spill is read-only context only; do NOT use it as a way to persist KB content — for KB writes use the regular `write_file` / `edit_file` tools, which go through the lock/commit pipeline.',
+      'Large return values: if the returned value exceeds `max_output_size`, the full JSON is auto-spilled to a shared spill store (outside any workspace, never committed) and the response contains only a `__tool_chain_spill__/…` ref + a truncated marker. You can read the spill back with the regular `read_file` tool — pass that ref as `path` (any existing branch as `branch`; it is not used) plus `offset` / `limit` to slice it, never read a multi-MB file in full. Order of preference: (1) re-run `call_tool_chain` with a follow-up code chain that filters/maps the data inline and returns just what you need; (2) narrow the API call — shorter `fields`, tighter date window, lower `limit`; (3) last resort — `read_file` against the spill ref with `offset` / `limit`. The spill is read-only context only; do NOT use it as a way to persist KB content — for KB writes use the regular `write_file` / `edit_file` tools, which go through the lock/commit pipeline.',
     ].join('\n\n'),
     inputSchema: z.object({
       code: z
@@ -121,7 +121,7 @@ export function createCallToolChainTool(
           truncated: true,
           result_ref: ref,
           result_bytes: bytes,
-          message: `Combined result+logs payload was ${fullJson.length} characters (exceeded max_output_size of ${maxOutputSize}). Full JSON (both \`result\` and \`logs\`) saved to the shared spill store as \`${ref}\` (outside any workspace, uncommitted). Read it back with \`read_file\` — pass that ref as \`path\` (\`branch\` is ignored) plus \`offset\` / \`limit\` for a slice — or, usually better, narrow the next \`call_tool_chain\` call (smaller fields list, tighter date window, lower limit) so the result fits inline.`,
+          message: `Combined result+logs payload was ${fullJson.length} characters (exceeded max_output_size of ${maxOutputSize}). Full JSON (both \`result\` and \`logs\`) saved to the shared spill store as \`${ref}\` (outside any workspace, uncommitted). Read it back with \`read_file\` — pass that ref as \`path\` (any existing branch as \`branch\`; it is not used) plus \`offset\` / \`limit\` for a slice — or, usually better, narrow the next \`call_tool_chain\` call (smaller fields list, tighter date window, lower limit) so the result fits inline.`,
         };
       } catch (err) {
         // The chain itself SUCCEEDED and only its delivery failed, so the logs

package/src/modules/connection-probe/__tests__/connection-probe.service.test.ts

@@ -4,8 +4,8 @@ import type {
   IToolManualService,
   ToolHealthCheck,
   ToolProbeTarget,
-} from '../../tool-manuals/tool-manuals.contract.js';
-import type { ISecretsVaultService } from '../../secrets-vault/secrets-vault.contract.js';
+} from '../../tool-manuals/index.js';
+import type { ISecretsVaultService } from '../../secrets-vault/index.js';
 
 /**
  * The three-way verdict is the whole point of this module, and the line that
@@ -33,7 +33,7 @@ vi.mock('@utcp/code-mode', () => ({
   CodeModeUtcpClient: { create: () => createClientMock() },
 }));
 
-const { ConnectionProbeService, readCapped } = await import('../connection-probe.service.js');
+const { ConnectionProbeService } = await import('../connection-probe.service.js');
 
 const DECLARED_PROBE: ToolHealthCheck = {
   url: 'https://api.acme.test/me',
@@ -739,25 +739,6 @@ describe('ConnectionProbeService: what the probe concludes', () => {
     expect(r?.detail!.length).toBeLessThan(400);
     expect(cancelled).toBe(true);
   });
-
-  /**
-   * The cap has to bound what is DECODED, not merely how many times we loop.
-   * Counting a chunk against the budget after decoding it lets a provider that
-   * answers in one huge chunk put the whole thing through the decoder — the
-   * bound bypassed by exactly the party it exists to bound. Asserted on
-   * `readCapped` directly because the caller's 200-character snippet is
-   * identical either way, which is how the first version of this passed.
-   */
-  it('holds one oversized chunk to the byte budget, not just the loop', async () => {
-    const oneHugeChunk = new ReadableStream<Uint8Array>({
-      start(controller) {
-        controller.enqueue(new TextEncoder().encode('x'.repeat(5_000_000)));
-        controller.close();
-      },
-    });
-
-    const out = await readCapped(new Response(oneHugeChunk), 8 * 1024);
-
-    expect(out.length).toBe(8 * 1024);
-  });
+  // The byte budget's own property (one oversized chunk held to the cap) is
+  // asserted on the shared reader in `shared/__tests__/read-capped.test.ts`.
 });

package/src/modules/connection-probe/connection-probe.service.ts

@@ -12,6 +12,7 @@ import type { ISecretsVaultService } from '../secrets-vault/index.js';
 import { bevelSecretsLoaderConfig } from '../secrets-vault/index.js';
 import { utcpNamespacedKey } from '../../shared/utcp-namespace.js';
 import { assertSafeFetchUrl } from '../../shared/ssrf.js';
+import { readCapped } from '../../shared/read-capped.js';
 import type { IConnectionProbeService, ProbeStatus, ProbeVerdict } from './connection-probe.contract.js';
 
 /** How long a probe may take before we call it inconclusive. */
@@ -753,37 +754,3 @@ async function describeRejection(res: Response, redactor: SecretRedactor): Promi
   }
 }
 
-/**
- * At most `limit` bytes of a response body, decoded as text.
- *
- * Each CHUNK is sliced to the remaining budget before being decoded, not just
- * counted against it: a provider that answers in one 5MB chunk would otherwise
- * put the whole thing through the decoder before the loop noticed it was over,
- * which is the bound bypassed by the very party it is meant to bound.
- *
- * Exported for its test — the property here is how much is held in memory,
- * which the caller's 200-character snippet hides completely.
- */
-export async function readCapped(res: Response, limit: number): Promise<string> {
-  const reader = res.body?.getReader();
-  // No stream (a mocked or already-consumed response): fall back to the whole
-  // body, which for those cases is ours and small.
-  if (!reader) return (await res.text()).slice(0, limit);
-  const decoder = new TextDecoder();
-  let out = '';
-  let read = 0;
-  try {
-    while (read < limit) {
-      const { done, value } = await reader.read();
-      if (done) break;
-      const remaining = limit - read;
-      const chunk = value.byteLength > remaining ? value.subarray(0, remaining) : value;
-      read += chunk.byteLength;
-      out += decoder.decode(chunk, { stream: true });
-      if (chunk.byteLength < value.byteLength) break;
-    }
-  } finally {
-    await reader.cancel().catch(() => {});
-  }
-  return out;
-}