borgmcp-shared 0.9.0 → 0.10.0

package/dist/protocol/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/protocol/errors.ts"],"names":[],"mappings":"AACA,oBAAY,SAAS;IACnB,YAAY,iBAAiB;IAC7B,YAAY,iBAAiB;IAC7B,YAAY,iBAAiB;IAC7B,qBAAqB,0BAA0B;IAC/C,aAAa,kBAAkB;IAC/B,aAAa,kBAAkB;IAC/B,iBAAiB,sBAAsB;IACvC,iBAAiB,sBAAsB;IACvC,mBAAmB,wBAAwB;IAC3C,cAAc,mBAAmB;IACjC,cAAc,mBAAmB;IACjC,sBAAsB,2BAA2B;IACjD,SAAS,cAAc;IACvB,6BAA6B,kCAAkC;IAC/D,uBAAuB,4BAA4B;IACnD,WAAW,gBAAgB;IAC3B,sBAAsB,2BAA2B;IACjD,YAAY,iBAAiB;IAC7B,aAAa,kBAAkB;IAC/B,YAAY,iBAAiB;IAC7B,4BAA4B,iCAAiC;IAC7D,cAAc,mBAAmB;IACjC,cAAc,mBAAmB;IACjC,eAAe,oBAAoB;IAQnC,gBAAgB,qBAAqB;CACtC;AAGD,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,SAAS,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/protocol/errors.ts"],"names":[],"mappings":"AACA,oBAAY,SAAS;IACnB,YAAY,iBAAiB;IAC7B,YAAY,iBAAiB;IAC7B,YAAY,iBAAiB;IAC7B,qBAAqB,0BAA0B;IAC/C,aAAa,kBAAkB;IAC/B,aAAa,kBAAkB;IAC/B,iBAAiB,sBAAsB;IACvC,iBAAiB,sBAAsB;IACvC,mBAAmB,wBAAwB;IAC3C,cAAc,mBAAmB;IACjC,cAAc,mBAAmB;IACjC,sBAAsB,2BAA2B;IACjD,SAAS,cAAc;IACvB,6BAA6B,kCAAkC;IAC/D,uBAAuB,4BAA4B;IACnD,WAAW,gBAAgB;IAC3B,qBAAqB,0BAA0B;IAC/C,aAAa,kBAAkB;IAC/B,eAAe,oBAAoB;IACnC,cAAc,mBAAmB;IACjC,sBAAsB,2BAA2B;IACjD,sBAAsB,2BAA2B;IACjD,YAAY,iBAAiB;IAC7B,aAAa,kBAAkB;IAC/B,YAAY,iBAAiB;IAC7B,4BAA4B,iCAAiC;IAC7D,cAAc,mBAAmB;IACjC,cAAc,mBAAmB;IACjC,eAAe,oBAAoB;IAQnC,gBAAgB,qBAAqB;CACtC;AAGD,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,SAAS,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB"}

package/dist/protocol/errors.js

@@ -16,6 +16,11 @@ export var ErrorCode;
     ErrorCode["REPOSITORY_ALREADY_ASSOCIATED"] = "REPOSITORY_ALREADY_ASSOCIATED";
     ErrorCode["CUBE_ALREADY_ASSOCIATED"] = "CUBE_ALREADY_ASSOCIATED";
     ErrorCode["ROLE_IN_USE"] = "ROLE_IN_USE";
+    ErrorCode["DEFAULT_ROLE_REQUIRED"] = "DEFAULT_ROLE_REQUIRED";
+    ErrorCode["ROLE_REQUIRED"] = "ROLE_REQUIRED";
+    ErrorCode["ROLE_REFERENCED"] = "ROLE_REFERENCED";
+    ErrorCode["ROLE_NOT_FOUND"] = "ROLE_NOT_FOUND";
+    ErrorCode["ROLE_SECTION_NOT_FOUND"] = "ROLE_SECTION_NOT_FOUND";
     ErrorCode["ROLE_HAS_FROZEN_DRONES"] = "ROLE_HAS_FROZEN_DRONES";
     ErrorCode["CUBE_DELETED"] = "CUBE_DELETED";
     ErrorCode["DRONE_EVICTED"] = "DRONE_EVICTED";

package/dist/protocol/errors.js.map

@@ -1 +1 @@
-{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/protocol/errors.ts"],"names":[],"mappings":"AACA,MAAM,CAAN,IAAY,SAiCX;AAjCD,WAAY,SAAS;IACnB,0CAA6B,CAAA;IAC7B,0CAA6B,CAAA;IAC7B,0CAA6B,CAAA;IAC7B,4DAA+C,CAAA;IAC/C,4CAA+B,CAAA;IAC/B,4CAA+B,CAAA;IAC/B,oDAAuC,CAAA;IACvC,oDAAuC,CAAA;IACvC,wDAA2C,CAAA;IAC3C,8CAAiC,CAAA;IACjC,8CAAiC,CAAA;IACjC,8DAAiD,CAAA;IACjD,oCAAuB,CAAA;IACvB,4EAA+D,CAAA;IAC/D,gEAAmD,CAAA;IACnD,wCAA2B,CAAA;IAC3B,8DAAiD,CAAA;IACjD,0CAA6B,CAAA;IAC7B,4CAA+B,CAAA;IAC/B,0CAA6B,CAAA;IAC7B,0EAA6D,CAAA;IAC7D,8CAAiC,CAAA;IACjC,8CAAiC,CAAA;IACjC,gDAAmC,CAAA;IAQnC,kDAAqC,CAAA;AACvC,CAAC,EAjCW,SAAS,KAAT,SAAS,QAiCpB"}
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/protocol/errors.ts"],"names":[],"mappings":"AACA,MAAM,CAAN,IAAY,SAsCX;AAtCD,WAAY,SAAS;IACnB,0CAA6B,CAAA;IAC7B,0CAA6B,CAAA;IAC7B,0CAA6B,CAAA;IAC7B,4DAA+C,CAAA;IAC/C,4CAA+B,CAAA;IAC/B,4CAA+B,CAAA;IAC/B,oDAAuC,CAAA;IACvC,oDAAuC,CAAA;IACvC,wDAA2C,CAAA;IAC3C,8CAAiC,CAAA;IACjC,8CAAiC,CAAA;IACjC,8DAAiD,CAAA;IACjD,oCAAuB,CAAA;IACvB,4EAA+D,CAAA;IAC/D,gEAAmD,CAAA;IACnD,wCAA2B,CAAA;IAC3B,4DAA+C,CAAA;IAC/C,4CAA+B,CAAA;IAC/B,gDAAmC,CAAA;IACnC,8CAAiC,CAAA;IACjC,8DAAiD,CAAA;IACjD,8DAAiD,CAAA;IACjD,0CAA6B,CAAA;IAC7B,4CAA+B,CAAA;IAC/B,0CAA6B,CAAA;IAC7B,0EAA6D,CAAA;IAC7D,8CAAiC,CAAA;IACjC,8CAAiC,CAAA;IACjC,gDAAmC,CAAA;IAQnC,kDAAqC,CAAA;AACvC,CAAC,EAtCW,SAAS,KAAT,SAAS,QAsCpB"}

package/dist/protocol/version.d.ts

@@ -1,3 +1,3 @@
-export declare const PROTOCOL_VERSION: "7";
+export declare const PROTOCOL_VERSION: "8";
 export type ProtocolVersion = typeof PROTOCOL_VERSION;
 //# sourceMappingURL=version.d.ts.map

package/dist/protocol/version.js

@@ -1,2 +1,2 @@
-export const PROTOCOL_VERSION = '7';
+export const PROTOCOL_VERSION = '8';
 //# sourceMappingURL=version.js.map

package/docs/compatibility.md

@@ -66,7 +66,7 @@ close. Former authorized parent and drone credentials receive
 `410 CUBE_DELETED` for that cube, including after authority restart; callers
 that were never authorized still receive non-enumerating `404 NOT_FOUND`.
 
-The `borgmcp-shared@0.9.0` release candidate retains protocol v7 and carries
+Published `borgmcp-shared@0.9.0` retains protocol v7 and carries
 the v2 invitation artifact: a canonical opaque token carrying the HTTPS
 endpoint, CA SPKI SHA-256 pin, enrollment authority, secret, and integrity
 binding. Decision write requests cap each `decision` and optional `rationale`
@@ -74,6 +74,14 @@ field at 512 UTF-8 bytes independently; response decoders retain longer
 historical values. The strict codec rejects legacy or non-canonical invitation
 forms before enrollment dispatch.
 
+The `borgmcp-shared@0.10.0` release candidate carries protocol v8. It adds
+manage-gated `DELETE /api/cubes/:cubeId/roles/:roleId` with integrity refusals
+for active, default, mandatory, human-seat, and taxonomy-referenced roles. It
+also adds the read-authorized `POST /api/cubes/:cubeId/role-rationale` lookup for
+one named, plain-label section of a role description. A v7 peer and a v8 peer
+reject each other during credential-free preflight before either new route is
+dispatched.
+
 Removing or reinterpreting an existing field is a protocol-breaking change even
 when TypeScript permits it. Implementations must not infer compatibility from a
 successful build alone — they must run the shared conformance suite against the

package/docs/enrollment.md

@@ -25,11 +25,8 @@ mutation and must never be rerun or moved. `borgmcp-shared@0.6.1`,
 `fa8a2dc072d4ffe2a16d5f02576fead822a2f72e`; successful attempt-1 workflow run
 `30169732628` published registry integrity
 `sha512-Wm4b0uoOAw9JCz5OTHD0Q2uXKkeWYdkVksdeZvRG8l62XGMY+G8GkNEsZT9L533LbVbQ29GhgF0htjDenQThDg==`.
-Never rerun or move that tag. `borgmcp-shared@0.7.0` and
-`borgmcp-shared@0.7.1` are published and immutable. This source now identifies
-the unpublished `0.9.0` protocol-v7 decision-limit release candidate. The
-version bump grants no tag or publication authority: creating `v0.9.0` and
-publishing the reviewed artifact remain separate, independently gated steps.
+Never rerun or move that tag. `borgmcp-shared@0.7.0`,
+`borgmcp-shared@0.7.1`, and `borgmcp-shared@0.9.0` are published and immutable.
 There is no compatibility path that returns a bearer from the server.
 
 A client verifies the credential-free `GET /api/protocol` tag preflight before

package/docs/release-records.json

@@ -12,5 +12,19 @@
     "verify_job_id": null,
     "publish_job_id": null,
     "artifact_integrity": "sha512-d4GE7ezGyoFN0uwA62gvRPUMfMdJ1kxhTunqU8dW3Qhy1n2SlNXZWr1Nthm6Goo0bAgvax8KEywyReodA6FyQA=="
+  },
+  {
+    "outcome": "published",
+    "version": "0.9.0",
+    "tag": "v0.9.0",
+    "tag_object": "4e9a1d2d62494efc0e4d9e3f3d7e1f142dac12c7",
+    "commit": "f57c9d9fffb8875830f65f12104c661b1e66fba6",
+    "tree": "b8e1825accee5bb619fca00e60a080f4ca973990",
+    "workflow_run_id": 30924764414,
+    "workflow_run_attempt": 1,
+    "workflow_conclusion": "success",
+    "verify_job_id": null,
+    "publish_job_id": null,
+    "artifact_integrity": "sha512-bfZPP9JGgBQrCFoZetabqKHc8HLaUqHVR3GJLb/1F1oon7z/B4el4aeBHVvXlxN9+2G7kU/ymPZ/K25nVQapmQ=="
   }
 ]

package/docs/releasing.md

@@ -179,12 +179,8 @@ mutation. Never rerun or move that tag. `borgmcp-shared@0.6.1`,
 `fa8a2dc072d4ffe2a16d5f02576fead822a2f72e`; successful attempt-1 workflow run
 `30169732628` published registry integrity
 `sha512-Wm4b0uoOAw9JCz5OTHD0Q2uXKkeWYdkVksdeZvRG8l62XGMY+G8GkNEsZT9L533LbVbQ29GhgF0htjDenQThDg==`.
-Never rerun or move that tag. `borgmcp-shared@0.7.0` and
-`borgmcp-shared@0.7.1` are published and immutable. This source identifies the
-unpublished `0.9.0` protocol-v7 decision-limit release candidate. Its release requires
-reviewed source and explicit publication authorization through one protected
-publish run whose terminal boundary is successful `npm publish`. The workflow
-performs no post-publication registry readback. Consumers must update the
-reviewed shared artifact before adopting the matching server and client
-releases; incompatible protocol v2, v3, v4, v5, v6, and v7 peers fail closed at
-credential-free preflight.
+Never rerun or move that tag. `borgmcp-shared@0.7.0`,
+`borgmcp-shared@0.7.1`, and `borgmcp-shared@0.9.0` are published and immutable.
+Consumers must update the reviewed shared artifact before adopting the matching
+server and client releases; incompatible protocol v2, v3, v4, v5, v6, and v7
+peers fail closed at credential-free preflight.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "borgmcp-shared",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "Shared protocol, domain, templates, and conformance contracts for Borg MCP implementations.",
   "type": "module",
   "main": "./dist/index.js",

package/src/conformance/adapter.ts

@@ -13,6 +13,8 @@ import {
   decodeAttachResponseEnvelope,
   decodeDroneRuntimeMetadataPatch,
   decodeEvictDroneResultEnvelope,
+  decodeDeleteRoleResultEnvelope,
+  decodeRoleRationaleResultEnvelope,
   decodeProtocolEnvelope,
   decodeProtocolErrorEnvelope,
   decodeProtocolTagPreflight,
@@ -24,6 +26,7 @@ import {
   PROTOCOL_LIMIT_CEILINGS,
   PROTOCOL_HTTP_CONTRACT,
   PROTOCOL_VERSION,
+  ROLE_IN_USE_DELETE_MESSAGE,
   utf8ByteLength,
   type CreateCubeResponse,
   type CreateCubeRepository,
@@ -199,7 +202,12 @@ export interface ConformanceAdmin {
   createRole(cube: ConformanceCube, input: {
     readonly roleClass: 'queen' | 'worker';
     readonly isHumanSeat: boolean;
+    readonly name?: string;
+    readonly detailedDescription?: string;
+    readonly isDefault?: boolean;
+    readonly isMandatory?: boolean;
   }): Promise<ConformanceRole>;
+  referenceRoleFromTaxonomy(cube: ConformanceCube, role: ConformanceRole): Promise<void>;
   createDrone(
     principal: ConformancePrincipal,
     cube: ConformanceCube,
@@ -322,6 +330,17 @@ export interface ConformanceOperations {
     drone: ConformanceDrone,
     request: unknown,
   ): Promise<ConformanceHttpResponse>;
+  deleteRole(
+    credential: string,
+    cube: ConformanceCube,
+    role: ConformanceRole,
+    request: unknown,
+  ): Promise<ConformanceHttpResponse>;
+  roleRationale(
+    credential: string,
+    cube: ConformanceCube,
+    request: unknown,
+  ): Promise<ConformanceHttpResponse>;
   openStream(
     credential: string,
     cube: ConformanceCube,
@@ -354,6 +373,8 @@ export const ADAPTER_CONFORMANCE_FIXTURES = [
   { id: 'drones.reassign-invariants', area: 'drones' },
   { id: 'security.cross-cube-drone-management', area: 'security' },
   { id: 'drones.evict-terminal-signal', area: 'drones' },
+  { id: 'roles.delete-contract', area: 'roles' },
+  { id: 'roles.rationale-contract', area: 'roles' },
   { id: 'security.drone-session-rejection-causes', area: 'security' },
   { id: 'metadata.attach-report', area: 'metadata' },
   { id: 'metadata.self-heal-patch', area: 'metadata' },
@@ -408,6 +429,14 @@ function protocolError(response: ConformanceHttpResponse): ErrorCode | null {
   }
 }
 
+function protocolErrorMessage(response: ConformanceHttpResponse): string | null {
+  try {
+    return decodeProtocolErrorEnvelope(response.body).error.message;
+  } catch {
+    return null;
+  }
+}
+
 function delay(milliseconds: number): Promise<void> {
   const setTimeoutValue = (globalThis as unknown as {
     setTimeout?: (callback: () => void, delay: number) => unknown;
@@ -2014,6 +2043,350 @@ export async function runAdapterConformance(
     };
   });
 
+  let roleContractCube!: ConformanceCube;
+  let roleContractPrincipal!: ConformancePrincipal;
+  let roleContractCredential = '';
+  let roleContractReadCredential = '';
+  await record('roles.delete-contract', async () => {
+    roleContractPrincipal = await environment.admin.createPrincipal('role-contract-manager');
+    const roleContractReader = await environment.admin.createPrincipal('role-contract-reader');
+    roleContractCube = await environment.admin.createCube('role-contract-cube');
+    await environment.admin.grantCube(roleContractPrincipal, roleContractCube, 'manage');
+    await environment.admin.grantCube(roleContractReader, roleContractCube, 'read');
+    const managerInvitation = await environment.admin.issueSingleUseInvitation(
+      roleContractPrincipal,
+      'client',
+    );
+    const readerInvitation = await environment.admin.issueSingleUseInvitation(
+      roleContractReader,
+      'client',
+    );
+    roleContractCredential = `${'D'.repeat(42)}Q`;
+    roleContractReadCredential = `${'L'.repeat(42)}Q`;
+    expectStatus(await environment.operations.enroll(createProtocolEnvelope(
+      'role-contract-manager-enroll',
+      {
+        invitation: managerInvitation,
+        retry_key: '00000000-0000-4000-8000-000000000351',
+        client_credential: roleContractCredential,
+      },
+    )), 201, 'Role-contract manager enrollment');
+    expectStatus(await environment.operations.enroll(createProtocolEnvelope(
+      'role-contract-reader-enroll',
+      {
+        invitation: readerInvitation,
+        retry_key: '00000000-0000-4000-8000-000000000352',
+        client_credential: roleContractReadCredential,
+      },
+    )), 201, 'Role-contract reader enrollment');
+
+    const defaultRole = await environment.admin.createRole(roleContractCube, {
+      roleClass: 'worker',
+      isHumanSeat: false,
+      name: 'Default Worker',
+      isDefault: true,
+    });
+    const mandatoryRole = await environment.admin.createRole(roleContractCube, {
+      roleClass: 'worker',
+      isHumanSeat: false,
+      name: 'Mandatory Worker',
+      isMandatory: true,
+    });
+    const humanRole = await environment.admin.createRole(roleContractCube, {
+      roleClass: 'queen',
+      isHumanSeat: true,
+      name: 'Human Seat',
+    });
+    const referencedRole = await environment.admin.createRole(roleContractCube, {
+      roleClass: 'worker',
+      isHumanSeat: false,
+      name: 'Routed Reviewer',
+    });
+    await environment.admin.referenceRoleFromTaxonomy(roleContractCube, referencedRole);
+    const activeRole = await environment.admin.createRole(roleContractCube, {
+      roleClass: 'worker',
+      isHumanSeat: false,
+      name: 'Active Worker',
+    });
+    await environment.admin.createDrone(roleContractPrincipal, roleContractCube, activeRole);
+
+    const refusals = [
+      [defaultRole, ErrorCode.DEFAULT_ROLE_REQUIRED, 'default role'],
+      [mandatoryRole, ErrorCode.ROLE_REQUIRED, 'mandatory role'],
+      [humanRole, ErrorCode.ROLE_REQUIRED, 'human-seat role'],
+      [referencedRole, ErrorCode.ROLE_REFERENCED, 'taxonomy-referenced role'],
+      [activeRole, ErrorCode.ROLE_IN_USE, 'active-drone role'],
+    ] as const;
+    for (const [index, [role, code, label]] of refusals.entries()) {
+      const before = await environment.admin.inspectCubeManagementState(roleContractCube);
+      const response = await environment.operations.deleteRole(
+        roleContractCredential,
+        roleContractCube,
+        role,
+        createProtocolEnvelope(`delete-refusal-${index}`, {}),
+      );
+      expectError(response, 409, code, `Delete ${label}`);
+      invariant(
+        same(await environment.admin.inspectCubeManagementState(roleContractCube), before),
+        `Delete ${label} mutated cube state after refusal.`,
+      );
+      if (code === ErrorCode.ROLE_IN_USE) {
+        const message = protocolErrorMessage(response) ?? '';
+        invariant(
+          message === ROLE_IN_USE_DELETE_MESSAGE,
+          'ROLE_IN_USE did not direct the caller to reassign or evict the drones first.',
+        );
+      }
+    }
+
+    const unknownRole = { id: '00000000-0000-4000-8000-000000000398' };
+    expectError(
+      await environment.operations.deleteRole(
+        roleContractCredential,
+        roleContractCube,
+        unknownRole,
+        createProtocolEnvelope('delete-unknown-role', {}),
+      ),
+      404,
+      ErrorCode.NOT_FOUND,
+      'Delete unknown role',
+    );
+
+    const deletableRole = await environment.admin.createRole(roleContractCube, {
+      roleClass: 'worker',
+      isHumanSeat: false,
+      name: 'Disposable Worker',
+    });
+    const beforeReadDenial = await environment.admin.inspectCubeManagementState(roleContractCube);
+    expectError(
+      await environment.operations.deleteRole(
+        roleContractReadCredential,
+        roleContractCube,
+        deletableRole,
+        createProtocolEnvelope('delete-role-read-denied', {}),
+      ),
+      403,
+      ErrorCode.ACCESS_DENIED,
+      'Delete role with read authority',
+    );
+    invariant(
+      same(
+        await environment.admin.inspectCubeManagementState(roleContractCube),
+        beforeReadDenial,
+      ),
+      'Read-authority role deletion mutated cube state.',
+    );
+    const deleted = await environment.operations.deleteRole(
+      roleContractCredential,
+      roleContractCube,
+      deletableRole,
+      createProtocolEnvelope('delete-empty-role', {}),
+    );
+    expectStatus(deleted, 200, 'Delete unassigned role');
+    invariant(
+      same(decodeDeleteRoleResultEnvelope(deleted.body).payload, {
+        role_id: deletableRole.id,
+        deleted: true,
+      }),
+      'Role deletion response did not identify the deleted role.',
+    );
+
+    const evictedRole = await environment.admin.createRole(roleContractCube, {
+      roleClass: 'worker',
+      isHumanSeat: false,
+      name: 'Former Worker',
+    });
+    const evictedDrone = await environment.admin.createDrone(
+      roleContractPrincipal,
+      roleContractCube,
+      evictedRole,
+    );
+    const evictedSession = await environment.admin.issueManagedDroneSession(evictedDrone);
+    const attributed = await environment.operations.append(
+      evictedSession,
+      roleContractCube,
+      createProtocolEnvelope('role-delete-attribution', { message: 'attribution survives' }),
+    );
+    expectStatus(attributed, 201, 'Pre-delete attributed log');
+    const attributedEntry = decodeAppendLogResultEnvelope(attributed.body).payload.entry;
+    expectStatus(await environment.operations.evictDrone(
+      roleContractCredential,
+      roleContractCube,
+      evictedDrone,
+      createProtocolEnvelope('role-delete-evict', {}),
+    ), 200, 'Pre-delete drone eviction');
+    expectStatus(await environment.operations.deleteRole(
+      roleContractCredential,
+      roleContractCube,
+      evictedRole,
+      createProtocolEnvelope('delete-evicted-role', {}),
+    ), 200, 'Delete role held only by an evicted drone');
+    invariant(
+      (await environment.admin.inspectManagedDrone(evictedDrone)).role_id === defaultRole.id,
+      'Role deletion did not retarget the evicted drone to the surviving default role.',
+    );
+    const read = await environment.operations.read(
+      roleContractCredential,
+      roleContractCube,
+      createProtocolEnvelope('read-role-delete-attribution', { cursor: null, limit: 500 }),
+    );
+    expectStatus(read, 200, 'Post-delete attributed log read');
+    invariant(
+      decodeReadLogResultEnvelope(read.body).payload.entries.some(
+        (entry) => entry.id === attributedEntry.id && entry.drone_id === evictedDrone.id,
+      ),
+      'Deleting the evicted drone role lost the drone attribution of an existing log entry.',
+    );
+
+    return {
+      success_status: 200,
+      hidden_status: 404,
+      refusal_codes: [
+        ErrorCode.ROLE_IN_USE,
+        ErrorCode.DEFAULT_ROLE_REQUIRED,
+        ErrorCode.ROLE_REQUIRED,
+        ErrorCode.ROLE_REFERENCED,
+      ],
+      in_use_message_actionable: true,
+      evicted_drone_retargeted: true,
+      activity_log_attribution_preserved: true,
+    };
+  });
+
+  await record('roles.rationale-contract', async () => {
+    const detailedDescription = [
+      'Implements assigned work.',
+      '',
+      'Workflow rationale:',
+      'This exact stored section body is returned.',
+      '',
+      'Boundaries:',
+      'Do not expand scope.',
+    ].join('\n');
+    const role = await environment.admin.createRole(roleContractCube, {
+      roleClass: 'worker',
+      isHumanSeat: false,
+      name: 'Rationale Builder',
+      detailedDescription,
+    });
+    const expectedSection = {
+      heading: 'Workflow rationale',
+      body: 'Workflow rationale:\nThis exact stored section body is returned.\n\n',
+    };
+    for (const [index, [selector, section]] of [
+      [role.id, 'Workflow rationale'],
+      ['rAtIoNaLe BuIlDeR', 'wOrKfLoW rAtIoNaLe'],
+    ].entries()) {
+      const response = await environment.operations.roleRationale(
+        roleContractReadCredential,
+        roleContractCube,
+        createProtocolEnvelope(`rationale-lookup-${index}`, { role: selector, section }),
+      );
+      expectStatus(response, 200, 'Role rationale lookup');
+      const result = decodeRoleRationaleResultEnvelope(response.body).payload;
+      invariant(
+        result.role_id === role.id &&
+          result.role_name === 'Rationale Builder' &&
+          same(result.section, expectedSection),
+        'Role rationale lookup did not return the canonical heading and exact stored section body.',
+      );
+    }
+    expectError(
+      await environment.operations.roleRationale(
+        roleContractReadCredential,
+        roleContractCube,
+        createProtocolEnvelope('rationale-unknown-role', {
+          role: 'Unknown Role',
+          section: 'Workflow rationale',
+        }),
+      ),
+      404,
+      ErrorCode.ROLE_NOT_FOUND,
+      'Unknown role rationale lookup',
+    );
+    const inaccessibleRole = await environment.admin.createRole(cubeB, {
+      roleClass: 'worker',
+      isHumanSeat: false,
+      name: 'Foreign Rationale Role',
+      detailedDescription,
+    });
+    expectError(
+      await environment.operations.roleRationale(
+        roleContractReadCredential,
+        roleContractCube,
+        createProtocolEnvelope('rationale-inaccessible-role', {
+          role: inaccessibleRole.id,
+          section: 'Workflow rationale',
+        }),
+      ),
+      404,
+      ErrorCode.ROLE_NOT_FOUND,
+      'Inaccessible role rationale lookup',
+    );
+    expectError(
+      await environment.operations.roleRationale(
+        roleContractReadCredential,
+        roleContractCube,
+        createProtocolEnvelope('rationale-unknown-section', {
+          role: role.id,
+          section: 'Missing rationale',
+        }),
+      ),
+      404,
+      ErrorCode.ROLE_SECTION_NOT_FOUND,
+      'Unknown role section lookup',
+    );
+    await environment.admin.createRole(roleContractCube, {
+      roleClass: 'worker',
+      isHumanSeat: false,
+      name: 'Ambiguous Role',
+      detailedDescription,
+    });
+    await environment.admin.createRole(roleContractCube, {
+      roleClass: 'worker',
+      isHumanSeat: false,
+      name: 'AMBIGUOUS ROLE',
+      detailedDescription,
+    });
+    expectError(
+      await environment.operations.roleRationale(
+        roleContractReadCredential,
+        roleContractCube,
+        createProtocolEnvelope('rationale-ambiguous-role', {
+          role: 'ambiguous role',
+          section: 'Workflow rationale',
+        }),
+      ),
+      400,
+      ErrorCode.INVALID_INPUT,
+      'Ambiguous role rationale lookup',
+    );
+    expectError(
+      await environment.operations.roleRationale(
+        roleContractReadCredential,
+        roleContractCube,
+        createProtocolEnvelope('rationale-invalid-selector', {
+          role: ' Rationale Builder',
+          section: 'Workflow rationale',
+        }),
+      ),
+      400,
+      ErrorCode.INVALID_INPUT,
+      'Invalid role rationale selector',
+    );
+    return {
+      uuid_lookup: true,
+      case_insensitive_name_lookup: true,
+      canonical_heading: true,
+      exact_body: true,
+      unknown_role_code: ErrorCode.ROLE_NOT_FOUND,
+      inaccessible_role_code: ErrorCode.ROLE_NOT_FOUND,
+      unknown_section_code: ErrorCode.ROLE_SECTION_NOT_FOUND,
+      ambiguous_role_code: ErrorCode.INVALID_INPUT,
+      invalid_selector_code: ErrorCode.INVALID_INPUT,
+    };
+  });
+
   await record('security.drone-session-rejection-causes', async () => {
     const revokedDrone = await environment.admin.createDrone(principalA, cubeA, workerRoleA);
     const expiredDrone = await environment.admin.createDrone(principalA, cubeA, workerRoleA);