@bevel-software/platform-core-backend 0.32.0 → 0.33.0

package/src/modules/access/reference-scan.ts

@@ -31,7 +31,7 @@ import {
   isAccessMdPath,
   parseAccessEntry,
   stripComment,
-} from '../access-model/access-grammar.js';
+} from '../access-model/index.js';
 
 /**
  * Resolve the [start, end) line range that role rewrites may touch — the YAML

package/src/modules/access/roles-admin.service.ts

@@ -36,7 +36,7 @@ import { workspaceIdForBranch } from '../../shared/workspace-id.js';
 import { logger } from '../../shared/logging.js';
 
 const log = logger('roles.recover');
-import type { WorkflowEventBus } from '../workflow/event-bus.js';
+import type { WorkflowEventBus } from '../workflow/index.js';
 import type { AuthUser, IWorkspaceService, IWorkflowService } from '@bevel-software/platform-shared';
 import { WorkflowDomainError } from '../../shared/domain-errors.js';
 import type { IAccessControl } from './access-control.interface.js';
@@ -45,10 +45,9 @@ import {
   ROLE_TOKEN_PREFIX,
   canonicalRoleName,
   canonicalEmail,
-} from '../access-model/access-grammar.js';
+} from '../access-model/index.js';
 import { loadActiveGroups } from './access-control.service.js';
-import { makeRolesYamlWriteValidator } from '../access-model/roles-yaml-guard.js';
-import { renderRolesYaml } from '../access-model/render-roles-yaml.js';
+import { makeRolesYamlWriteValidator, renderRolesYaml, GROUPS_YAML, SYNCED_GROUPS_YAML, validateGroupsFile, GROUP_REF_PREFIX, RESERVED_ROLE_NAMES } from '../access-model/index.js';
 import {
   parseRolesModel,
   deleteRole as editDeleteRole,
@@ -60,7 +59,6 @@ import {
   RolesEditError,
   type EditResult,
 } from './roles-edit.js';
-import { GROUPS_YAML, SYNCED_GROUPS_YAML, validateGroupsFile } from '../access-model/group-files.js';
 import {
   GroupsEditError,
   assertSafeGroupDisplayName,
@@ -68,7 +66,6 @@ import {
   parseGroupsModel,
 } from './groups-edit.js';
 import { capabilityRoleFor, isLegacyPeopleSetRole } from './capability-registry.js';
-import { GROUP_REF_PREFIX, RESERVED_ROLE_NAMES } from '../access-model/access-grammar.js';
 import { AdminLockedCommits } from './admin-locked-commit.js';
 import { KbReferenceScanner } from './reference-scan.js';
 

package/src/modules/access/roles-edit.ts

@@ -39,7 +39,7 @@ import {
   canonicalEmail,
   EMAIL_REGEX,
   GROUP_REF_PREFIX,
-} from '../access-model/access-grammar.js';
+} from '../access-model/index.js';
 
 /** Bad-input failure when editing roles.yaml (invalid name/email, unknown role). */
 export class RolesEditError extends Error {

package/src/modules/access/synced-groups-committer.ts

@@ -3,12 +3,12 @@ import { logger } from '../../shared/logging.js';
 
 const log = logger('directory-sync');
 import type { AuthUser, IWorkflowService } from '@bevel-software/platform-shared';
-import type { WorkspaceService } from '../workspace/workspace.service.js';
+import type { WorkspaceService } from '../workspace/index.js';
 import { workspaceIdForBranch } from '../../shared/workspace-id.js';
 import type { AccessControlService } from './access-control.service.js';
-import { SYNCED_GROUPS_YAML } from '../access-model/group-files.js';
-import type { WorkflowEventBus } from '../workflow/event-bus.js';
-import { LockingFilesystem } from '../kb-fs/locking-filesystem.js';
+import { SYNCED_GROUPS_YAML } from '../access-model/index.js';
+import type { WorkflowEventBus } from '../workflow/index.js';
+import { LockingFilesystem } from '../kb-fs/index.js';
 import { PushNeedsAgentResolutionError, WorkflowDomainError } from '../../shared/domain-errors.js';
 import { isAbsence } from '../../shared/fs.contract.js';
 import type { SyncedGroupsWriterDeps } from './synced-groups-writer.js';

package/src/modules/access/synced-groups-writer.ts

@@ -4,8 +4,8 @@ import {
   canonicalEmail,
   canonicalRoleName,
   RESERVED_ROLE_NAMES,
-} from '../access-model/access-grammar.js';
-import { unsafeNameReason } from '../access-model/group-files.js';
+} from '../access-model/index.js';
+import { unsafeNameReason } from '../access-model/index.js';
 import { printable } from '../../shared/printable.js';
 
 /**

package/src/modules/access/user-access-removal.service.ts

@@ -37,7 +37,7 @@
  */
 
 import { workspaceIdForBranch } from '../../shared/workspace-id.js';
-import type { WorkflowEventBus } from '../workflow/event-bus.js';
+import type { WorkflowEventBus } from '../workflow/index.js';
 import type { AuthUser, IWorkspaceService, IWorkflowService } from '@bevel-software/platform-shared';
 import { PushNeedsAgentResolutionError, WorkflowDomainError } from '../../shared/domain-errors.js';
 import type { IAccessControl } from './access-control.interface.js';
@@ -55,11 +55,8 @@ import {
   stripComment,
   type ParsedEntry,
   type Verb,
-} from '../access-model/access-grammar.js';
-import { spliceRevoke } from '../access-model/access-splice.js';
-import { scanFrontmatter } from '../access-model/frontmatter-lines.js';
-import { GROUPS_YAML, SYNCED_GROUPS_YAML, validateGroupsFile } from '../access-model/group-files.js';
-import { makeRolesYamlWriteValidator } from '../access-model/roles-yaml-guard.js';
+} from '../access-model/index.js';
+import { spliceRevoke, scanFrontmatter, GROUPS_YAML, SYNCED_GROUPS_YAML, validateGroupsFile, makeRolesYamlWriteValidator } from '../access-model/index.js';
 import { emitRolesModel, isGroupRefMember, parseRolesModel } from './roles-edit.js';
 import { emitGroupsModel, parseGroupsModel } from './groups-edit.js';
 import { AdminLockedCommits, type LockedWrite } from './admin-locked-commit.js';

package/src/modules/access-model/index.ts

@@ -2,12 +2,28 @@
  * The access model's public entry: what another module imports of it.
  *
  * The module is the grammar of `access.md` (how principals, roles, groups
- * and verbs are spelled), the errors a refused access is reported with, and
- * the gate a change is read through. A consumer outside the module imports
- * from here, not from the files; the files are the module's own layout and
- * free to move. The `access` module's own files predate this entry and still
- * import the files directly — they move here as they are touched.
+ * and verbs are spelled), the errors a refused access is reported with, the
+ * gate a change is read through, and the single-path read verdict every
+ * surface shares, so a module that must hide what a person may not read asks
+ * the same question the file routes ask. A consumer outside the module
+ * imports from here, not from the files; the files are the module's own
+ * layout and free to move. The `access` module's own files predate this
+ * entry and still import the files directly — they move here as they are
+ * touched.
  */
 export * from './access-grammar.js';
 export * from './access-errors.js';
 export type { ChangeReadVerdict, ChangeTargetKind, IChangeReadGate } from './change-gate.js';
+export { canReadWorkspacePath } from './kb-read-filter.js';
+// Reached by other modules; exported here so they stop importing the files.
+export { AccessSpliceError, spliceGrant, spliceRevoke, validatePrincipal } from './access-splice.js';
+export type { Principal, TokenMatch } from './access-splice.js';
+export { creatorPrincipal } from './creator.js';
+export type { CreationGrantPlan, Creator, ICreatorAccess } from './creator.js';
+export { scanFrontmatter } from './frontmatter-lines.js';
+export { GROUPS_YAML, SYNCED_GROUPS_YAML, parseGroupsFile, unsafeNameReason, validateGroupsFile } from './group-files.js';
+export type { GroupsIndex } from './group-files.js';
+export { resolveReadableMap, toKbRelative } from './kb-read-filter.js';
+export { synthesizePluginPrincipals } from './plugin-principals.js';
+export { renderRolesYaml } from './render-roles-yaml.js';
+export { ROLES_YAML_BASENAME, assertRolesYamlParsable, isRolesYamlPath, makeAgentRolesYamlWriteValidator, makeRolesYamlWriteValidator } from './roles-yaml-guard.js';

package/src/modules/access-model/roles-yaml-guard.ts

@@ -25,7 +25,7 @@ import type { FileContent } from '@mastra/core/workspace';
 import { GROUP_REF_PREFIX, canonicalRoleName, parseRolesYaml, parseYamlSubset } from './access-grammar.js';
 import type { GroupsIndex } from './group-files.js';
 import { WorkflowDomainError } from '../../shared/domain-errors.js';
-import type { WriteValidator } from '../kb-fs/locking-filesystem.js';
+import type { WriteValidator } from '../kb-fs/index.js';
 
 /** Repo-relative basename of the roles file (it lives at the KB repo root). */
 export const ROLES_YAML_BASENAME = 'roles.yaml';

package/src/modules/admin/admin-access.routes.ts

@@ -1,6 +1,6 @@
 import express from 'express';
 import type { IAdminAccessService } from './admin.interface.js';
-import '../auth/auth.middleware.js'; // Express Request augmentation
+import '../auth/index.js'; // Express Request augmentation
 
 /**
  * The CORE slice of the admin surface: just the admin-status resolver the

package/src/modules/admin/admin-access.service.ts

@@ -1,8 +1,8 @@
-import type { IAccessControl } from '../access/access-control.interface.js';
+import type { IAccessControl } from '../access/index.js';
 import { logger } from '../../shared/logging.js';
 
 const log = logger('admin');
-import { type WorkspaceService } from '../workspace/workspace.service.js';
+import { type WorkspaceService } from '../workspace/index.js';
 import { workspaceIdForBranch } from '../../shared/workspace-id.js';
 import { canonicalEmail } from '../../shared/email-identity.js';
 import type { IAdminAccessService } from './admin.interface.js';

package/src/modules/admin/index.ts

@@ -0,0 +1,7 @@
+/**
+ * What the admin module offers the other modules: the contract of the
+ * deployment admin check — a person is an admin iff they hold the `Admin`
+ * role in the knowledge base's `roles.yaml`. Routes that gate on it take the
+ * contract; the implementation is wired by the composition root.
+ */
+export type { IAdminAccessService } from './admin.interface.js';

package/src/modules/agent-guide/__tests__/agent-guide.test.ts

@@ -387,6 +387,11 @@ describe('the HTML views section', () => {
     }
     expect(text).toContain('`window.bevel.tools` is `null` wherever tools are not available');
     expect(text).toContain('Check it before every use');
+    // The skill page answers a page's tools as the file page does
+    // (htmlToolBridge.ts's host list): the guide says so, and never that a
+    // skill page leaves `tools` null.
+    expect(text).toContain("on the app's file page and on a skill's page");
+    expect(text).not.toMatch(/on a skill page and in any preview/);
     expect(text).toContain('**Reading runs at once; writing asks first.**');
     expect(text).toContain('"<page name> wants to write to the knowledge base"');
     expect(text).toContain('Allow while open and Deny');

package/src/modules/agent-guide/agent-guide.tools.ts

@@ -1,10 +1,8 @@
 import type { Router, RequestHandler } from 'express';
-import type { IToolRegistry, UtcpTool } from '../tool-registry/tool.contract.js';
-import { GET_AGENT_GUIDE_TOOL } from '../tool-registry/guide-first.js';
-import { TOOL_DESCRIPTION_CAP } from '../tool-registry/description-length.js';
-import { ToolError } from '../tool-helpers/tool.contract.js';
-import { toolDef } from '../tool-helpers/tool-def.js';
-import type { ToolHandlerFactory } from '../tool-helpers/tool-handler.js';
+import type { IToolRegistry, UtcpTool } from '../tool-registry/index.js';
+import { GET_AGENT_GUIDE_TOOL, TOOL_DESCRIPTION_CAP } from '../tool-registry/index.js';
+import { ToolError, toolDef } from '../tool-helpers/index.js';
+import type { ToolHandlerFactory } from '../tool-helpers/index.js';
 import { AGENT_GUIDE_FILE, joinGuideSections, type AgentGuideSectionsReader } from './agent-guide.js';
 
 export { GET_AGENT_GUIDE_TOOL };

package/src/modules/agent-guide/agent-guide.ts

@@ -35,7 +35,7 @@ import {
   type KbLayout,
 } from '@bevel-software/platform-shared';
 import { agentGuideDir } from '../../assets.js';
-import { sharedFileRulesSection } from '../agent-instructions/shared-file-rules.js';
+import { sharedFileRulesSection } from '../agent-instructions/index.js';
 
 /** One section of the guide. */
 export interface AgentGuideSection {

package/src/modules/agent-guide/index.ts

@@ -19,4 +19,4 @@ export {
   type RenderedGuideSection,
 } from './agent-guide.js';
 export { GET_AGENT_GUIDE_TOOL, registerAgentGuideTool } from './agent-guide.tools.js';
-export { GUIDE_FIRST_SENTENCE, withGuideFirst } from '../tool-registry/guide-first.js';
+export { GUIDE_FIRST_SENTENCE, withGuideFirst } from '../tool-registry/index.js';

package/src/modules/agent-instructions/read-preamble.ts

@@ -2,7 +2,7 @@ import fs from 'node:fs/promises';
 import path from 'node:path';
 import type { KbContext } from '../../shared/kb-context.js';
 import { isAbsence, type IFsProbe } from '../../shared/fs.contract.js';
-import type { WorkspaceService } from '../workspace/workspace.service.js';
+import type { WorkspaceService } from '../workspace/index.js';
 import { PREAMBLE_FILE } from './compose.js';
 
 /** The one reader both the hosted proxy and the agent-facing route call. */

package/src/modules/audit/agent-audit.service.ts

@@ -1,8 +1,8 @@
 import { and, count, desc, eq, isNotNull, isNull, lt, max, min, or, type SQL } from 'drizzle-orm';
 import { logger } from '../../shared/logging.js';
-import type { Database } from '../database/connection.js';
-import { agentConnections, agentEvents, externalApiKeys, oauthTokens, users } from '../database/schema.js';
-import type { IExternalApiKeyService } from '../tool-auth/external-api-key.interface.js';
+import type { Database } from '../database/index.js';
+import { agentConnections, agentEvents, externalApiKeys, oauthTokens, users } from '../database/index.js';
+import type { IExternalApiKeyService } from '../tool-auth/index.js';
 import {
   AuditPrincipalNotFoundError,
   InvalidCursorError,

package/src/modules/audit/agent-connection.routes.ts

@@ -1,7 +1,7 @@
 import express from 'express';
 import { logger } from '../../shared/logging.js';
 import type { IAgentConnectionStatus } from './audit.contract.js';
-import '../auth/auth.middleware.js'; // Express Request augmentation (req.userId)
+import '../auth/index.js'; // Express Request augmentation (req.userId)
 
 const log = logger('audit');
 

package/src/modules/audit/agent-rest-audit.middleware.ts

@@ -2,7 +2,7 @@ import type { RequestHandler } from 'express';
 import { logger } from '../../shared/logging.js';
 import type { IAgentEventRecorder } from './audit.contract.js';
 import { classifyToolCall, skillReadPath, type SkillFolder } from './event-classifier.js';
-import '../tool-auth/tool-auth.middleware.js'; // Express Request augmentation (req.toolAuth)
+import '../tool-auth/index.js'; // Express Request augmentation (req.toolAuth)
 
 const log = logger('audit');
 

package/src/modules/audit/audit.routes.ts

@@ -1,8 +1,8 @@
 import express from 'express';
 import { logger } from '../../shared/logging.js';
-import type { IAdminAccessService } from '../admin/admin.interface.js';
-import { TokenNotFoundError } from '../tool-auth/external-api-key.errors.js';
-import type { IExternalApiKeyService } from '../tool-auth/external-api-key.interface.js';
+import type { IAdminAccessService } from '../admin/index.js';
+import { TokenNotFoundError } from '../tool-auth/index.js';
+import type { IExternalApiKeyService } from '../tool-auth/index.js';
 import {
   AuditPrincipalNotFoundError,
   InvalidCursorError,
@@ -12,7 +12,7 @@ import {
   type IAgentAuditService,
 } from './audit.contract.js';
 import { MAX_EVENT_PAGE } from './agent-audit.service.js';
-import '../auth/auth.middleware.js'; // Express Request augmentation (req.userId / req.userEmail)
+import '../auth/index.js'; // Express Request augmentation (req.userId / req.userEmail)
 
 const log = logger('audit');
 

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

@@ -4,8 +4,8 @@ import { logger } from '../../shared/logging.js';
 const log = logger('account-erasure');
 import { and, eq, notExists } from 'drizzle-orm';
 import { isEncryptedBlob } from '../../shared/column-crypto.js';
-import type { Database } from '../database/connection.js';
-import type { IReviewWorkflowService } from '../workflow/review-workflow/review-workflow.interface.js';
+import type { Database } from '../database/index.js';
+import type { IReviewWorkflowService } from '../workflow/index.js';
 import {
   changeRequests,
   externalApiKeys,
@@ -14,11 +14,10 @@ import {
   oauthTokens,
   pendingCommits,
   pluginJoinRequests,
-  prComments,
   prFileApprovals,
   prMergeLog,
   users,
-} from '../database/schema.js';
+} from '../database/index.js';
 
 /** The anonymised id of one erasure — how a commit or log may name the account. */
 export function erasedAccountId(erasureId: string): string {
@@ -88,7 +87,7 @@ export interface IErasureParticipant {
  *    CASCADE (account links, watchlist sources/findings, connector configs,
  *    vault secrets); deleting a connection key cascades its usage metering.
  *  - Audit rows that must survive for the review trail (approvals, merge log,
- *    review comments, change requests, queued commits — and, via participants,
+ *    change requests, queued commits — and, via participants,
  *    e.g. routine authorship) are kept but ANONYMIZED with the per-erasure
  *    placeholder identity.
  *
@@ -225,10 +224,6 @@ export class AccountErasureService implements IAccountErasureService {
         .update(prMergeLog)
         .set({ triggeredByEmail: target.erasedEmail, triggeredByEmailBidx: erasedBidx, triggeredByName: target.erasedName })
         .where(eq(prMergeLog.triggeredByEmailBidx, emailBidx));
-      await tx
-        .update(prComments)
-        .set({ authorEmail: target.erasedEmail, authorEmailBidx: erasedBidx, authorName: target.erasedName })
-        .where(eq(prComments.authorEmailBidx, emailBidx));
       await tx
         .update(changeRequests)
         .set({ authorEmail: target.erasedEmail, authorEmailBidx: erasedBidx, authorName: target.erasedName })

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

@@ -1,8 +1,8 @@
 import { sql } from 'drizzle-orm';
-import type { Database } from '../database/connection.js';
+import type { Database } from '../database/index.js';
 import { canonicalEmail } from '../../shared/email-identity.js';
 import { WorkflowDomainError } from '../../shared/domain-errors.js';
-import { pgErrorCode } from '../database/pg-error.js';
+import { pgErrorCode } from '../database/index.js';
 
 /** The handle `db.transaction` hands its callback. */
 type Tx = Parameters<Parameters<Database['transaction']>[0]>[0];

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

@@ -9,9 +9,9 @@ import type { AuthService } from './auth.service.js';
 import type { IAccountHooks } from './account-hooks.js';
 import { AccountAdmissionRefusedError, AccountChangeRefusedError } from './account-admission.js';
 import { erasedAccountId, type IAccountErasureService } from './account-erasure.service.js';
-import type { IAdminAccessService } from '../admin/admin.interface.js';
-import type { UserAccessRemovalService } from '../access/user-access-removal.service.js';
-import { sendError } from '../access/admin-route-helpers.js';
+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 { canonicalEmail } from '../../shared/email-identity.js';
 import './auth.middleware.js'; // Express Request augmentation

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

@@ -1,7 +1,7 @@
 import jwt from 'jsonwebtoken';
 import { and, eq, getTableColumns, inArray, isNotNull, isNull, sql } from 'drizzle-orm';
-import type { Database } from '../database/connection.js';
-import { users } from '../database/schema.js';
+import type { Database } from '../database/index.js';
+import { users } from '../database/index.js';
 import type { AuthUser } from '@bevel-software/platform-shared';
 import { canonicalEmail } from '../../shared/email-identity.js';
 import {
@@ -19,8 +19,8 @@ import {
   timingSafeStringEqual,
   MIN_PASSWORD_LENGTH,
 } from './password-hash.js';
-import { RECOVERY_BOT_EMAIL } from '../workflow/recovery-bot.js';
-import { DIRECTORY_SYNC_BOT_EMAIL } from '../access/directory-sync-bot.js';
+import { RECOVERY_BOT_EMAIL } from '../workflow/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';

package/src/modules/auth/index.ts

@@ -27,3 +27,6 @@ export { timingSafeStringEqual } from './password-hash.js';
 // The Express `Request` augmentation (`req.userId`, …): a module whose routes
 // read it imports this entry, never the middleware file.
 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';

package/src/modules/auth/oidc-auth-provider.ts

@@ -8,7 +8,7 @@ import { AUTH_COOKIE_MAX_AGE_S } from './auth.routes.js';
 import { AUTH_COOKIE_NAME } from './auth.middleware.js';
 import type { AuthService } from './auth.service.js';
 import { AccountAdmissionRefusedError, AccountDeactivatedError } from './account-admission.js';
-import { normalizeIssuerUrl } from '../settings/oidc-check.js';
+import { normalizeIssuerUrl } from '../settings/index.js';
 
 // Short-lived CSRF state + PKCE verifier for the OAuth round-trip: set before
 // redirecting to the provider, verified/consumed on callback.

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

@@ -13,7 +13,7 @@ import {
   runToolChain,
   withCallExample,
 } from '@bevel-software/platform-mcp-core';
-import type { SpillStore } from '../workspace/spill-store.js';
+import type { SpillStore } from '../workspace/index.js';
 import { utcpNameToTsInterfaceName, findToolByName, AmbiguousToolNameError } from './code-mode-names.js';
 
 /**

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

@@ -7,12 +7,9 @@ import '@utcp/mcp'; // side effect: registers the 'mcp' protocol (remote MCP `.t
 import { CommunicationProtocol, UtcpClientConfigSerializer, type CallTemplate } from '@utcp/sdk';
 import { CodeModeUtcpClient } from '@utcp/code-mode';
 import { registerManual } from '@bevel-software/platform-mcp-core';
-import type { IToolManualService, ToolHealthCheck, ToolProbeTarget } from '../tool-manuals/tool-manuals.contract.js';
-import type { ISecretsVaultService } from '../secrets-vault/secrets-vault.contract.js';
-// The concrete module, NOT the `secrets-vault` barrel: that barrel re-exports
-// the routes, and the routes import this module's contract — so going through
-// it would close an import cycle between the two modules.
-import { bevelSecretsLoaderConfig } from '../secrets-vault/secrets-variable-loader.js';
+import type { IToolManualService, ToolHealthCheck, ToolProbeTarget } from '../tool-manuals/index.js';
+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 type { IConnectionProbeService, ProbeStatus, ProbeVerdict } from './connection-probe.contract.js';

package/src/modules/database/__tests__/legacy-change-request-body.test.ts

@@ -0,0 +1,118 @@
+import { describe, expect, it } from 'vitest';
+import { parseLegacyChangeRequestBody } from '@bevel-software/platform-shared';
+
+/**
+ * The grammar bodies carried before a request's body became its description:
+ * the generated `## Affected owners` block, an access request's level and
+ * note in hidden markers, and identity markers. `moveLegacyRequestBodies`
+ * reads every stored body through this once; what it keeps and what it moves
+ * is pinned here.
+ */
+const GENERATED = [
+  '## Affected owners',
+  '',
+  '- `KnowledgeBase/Engineering/Knowledge/Avi-Checkin.md` — Admin',
+  '- `KnowledgeBase/GTM/Notes.md` — GTM Team',
+].join('\n');
+
+describe('parseLegacyChangeRequestBody', () => {
+  it('drops the generated owners block and keeps what the author typed', () => {
+    expect(parseLegacyChangeRequestBody(`Please take a look.\n\n${GENERATED}`)).toEqual({
+      description: 'Please take a look.',
+      changed: true,
+    });
+    expect(parseLegacyChangeRequestBody(GENERATED)).toEqual({ description: '', changed: true });
+  });
+
+  it("keeps the author's own headings, cutting only the LAST owners heading", () => {
+    const out = parseLegacyChangeRequestBody(`Lead.\n\n## Why now\n\nBecause.\n\n## Affected owners\n\nI mean the GTM ones.\n\n${GENERATED}`);
+    expect(out.description).toBe('Lead.\n\n## Why now\n\nBecause.\n\n## Affected owners\n\nI mean the GTM ones.');
+    expect(out.description).not.toContain('Avi-Checkin');
+  });
+
+  it("keeps a heading the author wrote with prose under it: the cut takes only the block openChangeRequest wrote", () => {
+    const prose = 'Lead.\n\n## Affected owners\n\nThe GTM ones, I think.';
+    expect(parseLegacyChangeRequestBody(prose)).toEqual({ description: prose, changed: false });
+    const mixed = 'Lead.\n\n## Affected owners\n\nSee below.\n\n- `KnowledgeBase/GTM/Notes.md` — GTM Team';
+    expect(parseLegacyChangeRequestBody(mixed)).toEqual({ description: mixed, changed: false });
+  });
+
+  it('cuts a block that ends in the summary line a request with many paths got', () => {
+    const long = `${GENERATED}\n\n…and 3 more changed path(s). All eligible approvers across this change: Admin; GTM Team`;
+    expect(parseLegacyChangeRequestBody(`Lead.\n\n${long}`)).toEqual({ description: 'Lead.', changed: true });
+  });
+
+
+  it("moves an access request's level and note out of the prose, keeping the quoted lines as prose", () => {
+    const body = [
+      '<!--hexis:access-request-level:owner-->',
+      'Rita \\(rita@x\\.io\\) asked for **Owner** on Research\\.',
+      '',
+      'Note from Rita:',
+      '',
+      '<!--hexis:access-request-note-->',
+      '> I maintain these pages \\*now\\*',
+      '> and the index',
+      '<!--/hexis:access-request-note-->',
+      '',
+      "Anyone who can edit this folder's access answers it.",
+      '',
+      GENERATED,
+    ].join('\n');
+    expect(parseLegacyChangeRequestBody(body)).toEqual({
+      description: [
+        'Rita \\(rita@x\\.io\\) asked for **Owner** on Research\\.',
+        '',
+        'Note from Rita:',
+        '',
+        '> I maintain these pages \\*now\\*',
+        '> and the index',
+        '',
+        "Anyone who can edit this folder's access answers it.",
+      ].join('\n'),
+      accessRequestLevel: 'owner',
+      accessRequestNote: 'I maintain these pages *now*\nand the index',
+      changed: true,
+    });
+  });
+
+  it('reads a level with no note, and a level alone', () => {
+    expect(parseLegacyChangeRequestBody('<!--hexis:access-request-level:write-->\nAna asked for **Can edit**.')).toEqual({
+      description: 'Ana asked for **Can edit**.',
+      accessRequestLevel: 'write',
+      changed: true,
+    });
+    expect(parseLegacyChangeRequestBody('<!--hexis:access-request-level:owner-->')).toEqual({
+      description: '',
+      accessRequestLevel: 'owner',
+      changed: true,
+    });
+  });
+
+  it("strips the identity markers older bodies carry, and only those — an author's own comment is prose", () => {
+    expect(parseLegacyChangeRequestBody('<!-- bevel:author:abc123 -->\nMy reason.')).toEqual({
+      description: 'My reason.',
+      changed: true,
+    });
+    expect(parseLegacyChangeRequestBody('My reason.\n<!-- TODO: ask Mia about the title -->')).toEqual({
+      description: 'My reason.\n<!-- TODO: ask Mia about the title -->',
+      changed: false,
+    });
+  });
+
+  it('leaves a body of the new shape alone', () => {
+    expect(parseLegacyChangeRequestBody('P2 - Planned\n\nA multi-line\nreason.')).toEqual({
+      description: 'P2 - Planned\n\nA multi-line\nreason.',
+      changed: false,
+    });
+    expect(parseLegacyChangeRequestBody('')).toEqual({ description: '', changed: false });
+  });
+
+  it('counts a body it only trims as changed, so the stored text ends up exactly what is shown', () => {
+    // The ends and runs of blank lines go; spaces inside a line are the author's.
+    expect(parseLegacyChangeRequestBody('  Lead.  \n\n\n\nMore.\n')).toEqual({
+      description: 'Lead.  \n\nMore.',
+      changed: true,
+    });
+  });
+});