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

package/src/modules/database/core-schema.ts

@@ -147,6 +147,16 @@ export const changeRequests = pgTable('change_requests', {
   authorName: text('author_name').notNull(),
   state: text('state').notNull().default('open'), // 'open' | 'merged' | 'closed'
   mergedSha: text('merged_sha'),
+  // The last apply attempt that did not land (null when none, or once a gate
+  // input it depended on changed). Persisted rather than only pushed to the
+  // clicker so every viewer of the still-open request — its author first —
+  // sees the refusal.
+  applyFailureReason: text('apply_failure_reason'),
+  applyFailureConflicts: boolean('apply_failure_conflicts'),
+  applyFailedAt: timestamp('apply_failed_at'),
+  applyFailedByName: text('apply_failed_by_name'),
+  /** What refused the last apply: 'gate' (approvals), 'conflicts' (git), 'error' (anything else). */
+  applyFailureKind: text('apply_failure_kind'),
   createdAt: timestamp('created_at').defaultNow().notNull(),
   updatedAt: timestamp('updated_at'),
   closedAt: timestamp('closed_at'),
@@ -192,6 +202,25 @@ export const externalApiKeys = pgTable('api_tokens', {
   createdAt: timestamp('created_at').defaultNow().notNull(),
   lastUsedAt: timestamp('last_used_at'),
   revokedAt: timestamp('revoked_at'),
+  /**
+   * Who ended the key — `owner` (the person disconnected it themselves) or
+   * `admin` (an admin revoked it from the deployment overview). Null while
+   * the key is live, and on rows revoked before this column existed, which
+   * the UI reads as the owner's own doing. The owner's page uses it to say
+   * "revoked by an admin" rather than "disconnected", so nobody tries to
+   * reconnect a key that was taken from them.
+   */
+  revokedBy: text('revoked_by'),
+  /**
+   * When the owner deleted the key "for good" from their own pages. A
+   * DELETE in name only: the row stays, because the Audit log's events hang
+   * off it and a log its subject can erase is not one. Hidden from the
+   * owner's listings, shown to admins as deleted; gone for real only when
+   * the account is erased (the cascade) or its events have long been
+   * pruned. Always set on an already-revoked row — a live key is never
+   * deleted in one step.
+   */
+  deletedAt: timestamp('deleted_at'),
 }, (t) => ({
   byUser: index('api_tokens_by_user').on(t.userId),
 }));
@@ -427,12 +456,58 @@ export const oauthAuthCodes = pgTable('oauth_auth_codes', {
   byExpiry: index('oauth_auth_codes_by_expiry').on(t.expiresAt),
 }));
 
+/**
+ * "This person connected this agent" — the durable record behind the Audit
+ * log's agent rows. An OAuth grant cannot be that record: its token row is
+ * replaced on every refresh (hourly) and pruned once its refresh window
+ * closes, so nothing about it outlives a month. This row is made the first
+ * time a token is minted for a (user, client) pair, kept across every refresh
+ * (each new token row points at it), and REVOKED rather than deleted when the
+ * person or an admin cuts the agent off — its events stay readable under it.
+ *
+ * A connection is the AGENT, per person — not the OAuth client registration.
+ * Claude registers a fresh client on every re-authorisation (dynamic client
+ * registration mints a new id each time), so keying by registration gave one
+ * person five "Claude" rows for one agent. `agent_key` is what a connection is
+ * keyed by instead: the registered client name, folded (a name-less client
+ * falls back to its id), so every registration of "Claude" by one person
+ * lands on the same live row; `client_id` records the registration that
+ * first made it. `client_name` is that registration's name as shown.
+ *
+ * One LIVE connection per (user, agent): the partial unique index below. A
+ * reconnect after a revoke is a new row, so the old one's history and its
+ * "revoked by an admin" mark are never overwritten.
+ */
+export const agentConnections = pgTable('agent_connections', {
+  id: uuid('id').defaultRandom().primaryKey(),
+  userId: uuid('user_id').notNull().references(() => users.id, { onDelete: 'cascade' }),
+  clientId: text('client_id').notNull().references(() => oauthClients.clientId),
+  clientName: text('client_name'),
+  /** The folded client name, or the client id when the registration carried none. */
+  agentKey: text('agent_key').notNull(),
+  connectedAt: timestamp('connected_at').defaultNow().notNull(),
+  lastUsedAt: timestamp('last_used_at'),
+  revokedAt: timestamp('revoked_at'),
+  /** `owner` | `admin` — who ended it; null while live. Same vocabulary as `api_tokens.revoked_by`. */
+  revokedBy: text('revoked_by'),
+}, (t) => ({
+  byUser: index('agent_connections_by_user').on(t.userId),
+  liveUnq: uniqueIndex('agent_connections_live_unq')
+    .on(t.userId, t.agentKey)
+    .where(sql`${t.revokedAt} is null`),
+}));
+
 /**
  * OAuth access/refresh token pairs minted by the token endpoint. Like
  * `api_tokens`: plaintext shown only in the token response, SHA-256 hashes
  * stored, revoked-not-deleted so `last_used_at` keeps its audit value and a
  * revoked token can't be re-issued. One row per pair; refresh rotation
  * revokes the old row and inserts a new one.
+ *
+ * `connection_id` names the {@link agentConnections} row the pair belongs to,
+ * so every call made with the token is attributed to that agent and revoking
+ * the agent can revoke exactly its tokens. Null only on rows minted before
+ * the column existed.
  */
 export const oauthTokens = pgTable('oauth_tokens', {
   id: uuid('id').defaultRandom().primaryKey(),
@@ -440,6 +515,7 @@ export const oauthTokens = pgTable('oauth_tokens', {
   refreshTokenHash: text('refresh_token_hash').unique(),
   clientId: text('client_id').notNull().references(() => oauthClients.clientId),
   userId: uuid('user_id').notNull().references(() => users.id),
+  connectionId: uuid('connection_id').references(() => agentConnections.id, { onDelete: 'cascade' }),
   scope: text('scope'),
   resource: text('resource'),
   expiresAt: timestamp('expires_at').notNull(),
@@ -450,6 +526,53 @@ export const oauthTokens = pgTable('oauth_tokens', {
 }, (t) => ({
   byUser: index('oauth_tokens_by_user').on(t.userId),
   byExpiry: index('oauth_tokens_by_expiry').on(t.expiresAt),
+  byConnection: index('oauth_tokens_by_connection').on(t.connectionId),
+}));
+
+/**
+ * The Audit log's events: one row per thing an external agent called through
+ * the platform — a hexis capability (the platform's own tools, `read_file`,
+ * `call_tool_chain`, …), a tool from a `.tool` manual or a connected MCP
+ * server, or a skill it read. Append-only; pruned past the deployment's
+ * retention window (the `auditRetentionDays` setting).
+ *
+ * Deliberately WITHOUT arguments or results: a call's inputs can carry
+ * secrets and personal data, and the log's question is "what was used, by
+ * which agent, when" — not "what was said".
+ *
+ * Exactly one principal per row (the CHECK): the connection key or the agent
+ * connection the call arrived through. Both cascade, so deleting a key for
+ * good, revoking-then-erasing a person, or dropping a connection takes its
+ * events along — the same contract the LLM-usage rows already keep.
+ */
+export const agentEvents = pgTable('agent_events', {
+  id: uuid('id').defaultRandom().primaryKey(),
+  userId: uuid('user_id').notNull().references(() => users.id, { onDelete: 'cascade' }),
+  keyId: uuid('key_id').references(() => externalApiKeys.id, { onDelete: 'cascade' }),
+  connectionId: uuid('connection_id').references(() => agentConnections.id, { onDelete: 'cascade' }),
+  /** `capability` | `tool` | `skill`. */
+  kind: text('kind').notNull(),
+  /** The MCP server / `.tool` manual (catalog name) for a tool, the skill folder for a skill; null for a capability. */
+  manual: text('manual'),
+  /** The tool's bare name, or the skill's name. */
+  name: text('name').notNull(),
+  /** `ok` | `error` | `denied` (denied: the caller's sign-in for the tool was missing, so nothing ran). */
+  outcome: text('outcome').notNull(),
+  durationMs: integer('duration_ms'),
+  at: timestamp('at').defaultNow().notNull(),
+}, (t) => ({
+  // The two read paths: one principal's events, newest first.
+  byKey: index('agent_events_by_key').on(t.keyId, t.at),
+  byConnection: index('agent_events_by_connection').on(t.connectionId, t.at),
+  // The retention prune, and per-user counts.
+  byAt: index('agent_events_by_at').on(t.at),
+  byUser: index('agent_events_by_user').on(t.userId),
+  kindCheck: check('agent_events_kind', sql`${t.kind} IN ('capability', 'tool', 'skill')`),
+  outcomeCheck: check('agent_events_outcome', sql`${t.outcome} IN ('ok', 'error', 'denied')`),
+  principalCheck: check(
+    'agent_events_principal',
+    sql`(${t.keyId} IS NULL) <> (${t.connectionId} IS NULL)`,
+  ),
 }));
 
 export const sessionOntologyTouches = pgTable('session_ontology_touches', {
@@ -518,6 +641,13 @@ export const githubFacadeIdentity = pgTable('github_facade_identity', {
   publicKeyPem: text('public_key_pem').notNull(),
   createdAt: timestamp('created_at').defaultNow().notNull(),
   rotatedAt: timestamp('rotated_at'),
+  /**
+   * When an admin said the deployment is registered with their Claude
+   * organization; null while it is not. Nothing on the Claude side reports
+   * this back, so an admin states it. Not sealed: it is the one fact about
+   * this row every signed-in person may read.
+   */
+  registeredAt: timestamp('registered_at'),
 });
 
 /**
@@ -544,3 +674,100 @@ export const githubFacadeCodes = pgTable('github_facade_codes', {
   consumedAt: timestamp('consumed_at'),
   createdAt: timestamp('created_at').defaultNow().notNull(),
 });
+
+/**
+ * Join requests as the platform RECORDS them, distinct from the change
+ * request that eventually carries one.
+ *
+ * A join request used to be nothing but a change request: the endpoint did
+ * the branch, the clone, the grant commit, the push and the change request
+ * before it answered, so the row and the answer were the same event. The
+ * first request from a person is a full clone, which is many seconds on a
+ * real repository, and the click looked like a freeze. The record is what
+ * lets the click be answered first: the route writes a row and returns, and
+ * the git work runs after, against the row.
+ *
+ * Which makes the row the durable statement "this person asked", and the
+ * only one — the change request is a CONSEQUENCE of it, recorded back here
+ * as `change_request_number` once it exists. That is the whole reason this
+ * is a table and not a queue in memory: a process that dies between the
+ * answer and the push must leave the ask behind, and the boot sweep re-runs
+ * every row still `pending`.
+ *
+ *   pending   asked, and the git work has not finished (or has not started)
+ *   opened    the change request exists; its number is here
+ *   failed    the git work refused, and `failure_reason` says what it said
+ *
+ * `(requester_email, plugin_key)` is UNIQUE, which is what makes two tabs and
+ * two clicks one request: the second ask upserts the same row. A `failed` row
+ * is revived to `pending` by the next ask rather than replaced, so a retry
+ * continues the recorded request instead of opening a second one.
+ *
+ * `plugin_key` is the plugin's primary FOLDER below the plugins root — the
+ * same key the join BRANCH is cut from, so a record and its branch cannot
+ * drift, and renaming the plugin's identity (which moves no folder) orphans
+ * no record.
+ */
+export const pluginJoinRequests = pgTable('plugin_join_requests', {
+  id: uuid('id').defaultRandom().primaryKey(),
+  requesterEmail: text('requester_email').notNull(), // lowercased at insert
+  /** Denormalised for the commit/change-request authorship, like `file_locks.holder_name`. */
+  requesterName: text('requester_name').notNull(),
+  pluginKey: text('plugin_key').notNull(),
+  status: text('status').notNull().default('pending'),
+  /** What the git work said when it refused — shown to the requester verbatim. */
+  failureReason: text('failure_reason'),
+  changeRequestNumber: integer('change_request_number'),
+  /**
+   * When a process took this row's git work, and the whole of the mutual
+   * exclusion over it.
+   *
+   * A redeploy runs two processes for as long as the changeover takes, and
+   * both sweep. Their single-flight maps are per-process, so without this
+   * they would clone, commit and push the same branch against the same shared
+   * workspace at the same time. Claiming is one conditional UPDATE — the row
+   * is taken only if nobody holds it — so the loser simply does not run.
+   *
+   * A CLAIM EXPIRES, because a process can die holding one and the request
+   * would otherwise be owed forever. The window has to exceed the longest
+   * honest attempt, which is a first-ever request's full clone; past it, the
+   * next sweep or click takes the row over. A row that was never claimed at
+   * all — recorded a moment before the process died — is claimable at once,
+   * which is the common restart case.
+   */
+  claimedAt: timestamp('claimed_at'),
+  /**
+   * WHICH claim `claimed_at` is the liveness of — a fencing token, fresh on
+   * every claim.
+   *
+   * A timestamp alone says a row is held; it cannot say by whom. So a worker
+   * that misses the stale window — a long GC pause, a host that froze, a
+   * network partition that outlived three beats — carries on believing it
+   * holds the row that somebody else has since taken, and its `markOpened`
+   * or `markFailed`, addressed by id alone, lands on the NEW attempt: the
+   * second worker's run is settled by the first worker's outcome, or a row
+   * mid-flight is stamped `failed` under it. Two change requests for one
+   * request is the same race a step earlier.
+   *
+   * Every write that decides or holds the row therefore names the token it
+   * believes it holds, and matches nothing if the token has moved on. A
+   * superseded worker's writes become no-ops rather than corruption, and it
+   * learns it was superseded from its next beat returning false — which is
+   * also how it learns the row was DELETED out from under it, the shape
+   * account erasure takes.
+   */
+  claimToken: uuid('claim_token'),
+  createdAt: timestamp('created_at').defaultNow().notNull(),
+  updatedAt: timestamp('updated_at').defaultNow().notNull(),
+}, (t) => ({
+  // One request per person per plugin — the DB's rule, not a caller's. Also
+  // the index the plugin listing's by-requester read is served from.
+  requesterPluginUnq: uniqueIndex('plugin_join_requests_requester_plugin_unq')
+    .on(t.requesterEmail, t.pluginKey),
+  // The boot sweep: every row still `pending`, without a full scan.
+  byStatus: index('plugin_join_requests_by_status').on(t.status),
+  statusCheck: check(
+    'plugin_join_requests_status',
+    sql`${t.status} IN ('pending', 'opened', 'failed')`,
+  ),
+}));

package/src/modules/database/migrate.ts

@@ -1,5 +1,9 @@
 import { migrate } from 'drizzle-orm/node-postgres/migrator';
+import { logger } from '../../shared/logging.js';
+
+const log = logger('database');
 import type { Database } from './connection.js';
+import { AdvisoryLock, withAdvisoryLock } from './advisory-lock.js';
 
 /*
  * ── Per-tier migration folders ──────────────────────────────────────────────
@@ -22,13 +26,25 @@ import type { Database } from './connection.js';
  * Note: drizzle-orm's node-postgres `migrate()` accepts `migrationsTable` (and
  * `migrationsSchema`) in the installed version (0.45.x) — see
  * `drizzle-orm/migrator.d.ts` (`MigrationConfig`).
+ *
+ * BOTH RUNNERS TAKE AN ADVISORY LOCK. Drizzle's migrator takes none of its own:
+ * it reads the newest applied migration, then opens a transaction and applies
+ * everything newer — so two processes booting at once read the same watermark
+ * and both apply. The idempotence described above covers a RE-run, which is a
+ * different thing from a CONCURRENT one, and it only covers the init migration
+ * anyway; 0002 onward are plain DDL, where the second process fails on an
+ * already-applied `ALTER TABLE` and crash-loops. Two processes booting at once
+ * is not hypothetical here — it is every redeploy, for as long as the outgoing
+ * container takes to exit. See `advisory-lock.ts` for the mechanism.
  */
 
 /** Apply the CORE migration history from `folder`, tracked in `__drizzle_migrations_core`. */
 export async function runCoreMigrations(db: Database, folder: string): Promise<void> {
-  console.log('Running core database migrations...');
-  await migrate(db, { migrationsFolder: folder, migrationsTable: '__drizzle_migrations_core' });
-  console.log('Core migrations complete.');
+  await withAdvisoryLock(db, AdvisoryLock.Migrations, async () => {
+    log.info('Running core database migrations...');
+    await migrate(db, { migrationsFolder: folder, migrationsTable: '__drizzle_migrations_core' });
+    log.info('Core migrations complete.');
+  });
 }
 
 /**
@@ -37,7 +53,12 @@ export async function runCoreMigrations(db: Database, folder: string): Promise<v
  * enterprise tables FK into core tables.
  */
 export async function runEnterpriseMigrations(db: Database, folder: string): Promise<void> {
-  console.log('Running enterprise database migrations...');
-  await migrate(db, { migrationsFolder: folder, migrationsTable: '__drizzle_migrations_enterprise' });
-  console.log('Enterprise migrations complete.');
+  await withAdvisoryLock(db, AdvisoryLock.Migrations, async () => {
+    log.info('Running enterprise database migrations...');
+    await migrate(db, {
+      migrationsFolder: folder,
+      migrationsTable: '__drizzle_migrations_enterprise',
+    });
+    log.info('Enterprise migrations complete.');
+  });
 }

package/src/modules/declared-variables/declared-variables.routes.ts

@@ -1,4 +1,7 @@
 import express, { type Request, type RequestHandler } from 'express';
+import { logger } from '../../shared/logging.js';
+
+const log = logger('declared-variables');
 import { utcpNamespacedKey } from '../../shared/utcp-namespace.js';
 import type { IToolManualService } from '../tool-manuals/tool-manuals.contract.js';
 import type { ISecretsVaultService } from '../secrets-vault/secrets-vault.contract.js';
@@ -136,13 +139,13 @@ export function createDeclaredVariableRoutes(
         key: utcpNamespacedKey(manual.name, v.name),
       }));
       const { values, missing } = await resolveAll(who.userId, entries);
-      console.info(
-        `[declared-variables] local tool "${manual.path}" resolved for user=${who.userId}: ` +
+      log.info(
+        `local tool "${manual.path}" resolved for user=${who.userId}: ` +
           `provided=[${Object.keys(values).join(',')}] missing=[${missing.join(',')}]`,
       );
       res.set('Cache-Control', 'no-store').json({ name: manual.name, variables: values, missing });
     } catch (err) {
-      console.error('[declared-variables] local tool resolve failed:', err instanceof Error ? err.message : err);
+      log.error('local tool resolve failed:', { err });
       res.status(500).json({ error: 'Failed to resolve variables' });
     }
   });

package/src/modules/diff/__tests__/diff.service.seed-atomicity.test.ts

@@ -1,4 +1,5 @@
 import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { NodeFs } from '../../kb-fs/node-fs.js';
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import os from 'node:os';
@@ -55,6 +56,7 @@ async function setup(): Promise<Fixture> {
     workspacesRoot,
     'https://github.com/Bevel-Software/knowledge-base.git',
     'knowledge-base',
+    new NodeFs(),
   );
   const mutex = new WorkspaceMutex();
   const diffService = new DiffService(
@@ -63,6 +65,7 @@ async function setup(): Promise<Fixture> {
     workspacesRoot,
     backupsRoot,
     'knowledge-base',
+    new NodeFs(),
   );
   workspaceService.setDiffService(diffService);
   return { workspacesRoot, backupsRoot, workspaceDir, repoDir, workspaceId, workspaceService, diffService };

package/src/modules/diff/__tests__/diff.service.test.ts

@@ -1,4 +1,5 @@
 import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { NodeFs } from '../../kb-fs/node-fs.js';
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import os from 'node:os';
@@ -41,6 +42,7 @@ async function setup(): Promise<Fixture> {
     workspacesRoot,
     'https://github.com/Bevel-Software/knowledge-base.git',
     'knowledge-base',
+    new NodeFs(),
   );
   const mutex = new WorkspaceMutex();
   const diffService = new DiffService(
@@ -49,6 +51,7 @@ async function setup(): Promise<Fixture> {
     workspacesRoot,
     backupsRoot,
     'knowledge-base',
+    new NodeFs(),
   );
   workspaceService.setDiffService(diffService);
   return { workspacesRoot, backupsRoot, workspaceDir, repoDir, workspaceId, workspaceService, diffService };

package/src/modules/diff/diff.routes.ts

@@ -5,6 +5,7 @@ import type { AuthService } from '../auth/auth.service.js';
 import type { IAccessControl } from '../access/access-control.interface.js';
 import { canReadWorkspacePath, toKbRelative, resolveReadableMap } from '../access-model/kb-read-filter.js';
 import { WorkflowDomainError, WorkflowValidationError } from '../../shared/domain-errors.js';
+import { domainErrorBody } from '../../shared/http-errors.js';
 import { LockingFilesystem } from '../kb-fs/locking-filesystem.js';
 import { branchForWorkspaceId } from '../../shared/workspace-id.js';
 import '../auth/auth.middleware.js';
@@ -13,10 +14,7 @@ function toHttpError(
   err: unknown,
 ): { status: number; body: Record<string, unknown> } {
   if (err instanceof WorkflowDomainError) {
-    return {
-      status: err.status,
-      body: { error: err.message, ...(err.payload ?? {}) },
-    };
+    return { status: err.status, body: domainErrorBody(err) };
   }
   const message = err instanceof Error ? err.message : 'Unknown error';
   return { status: 500, body: { error: message } };