borgmcp-shared 0.9.0 → 0.10.1

package/src/conformance/index.ts

@@ -12,6 +12,7 @@ import {
   type InvitationArtifact,
 } from '../protocol/contract.js';
 import type { EnrichedStreamEntry } from '../protocol/types.js';
+import { ROLE_IN_USE_DELETE_MESSAGE } from '../protocol/coordination.js';
 
 export * from './adapter.js';
 
@@ -775,6 +776,144 @@ export interface RuntimeMetadataRepositoryConformanceVector {
   expected: { working_repo_name: string; working_repo_origin: string } | null;
 }
 
+export interface RoleDeleteConformanceVector {
+  name: string;
+  fixture:
+    | 'deletable'
+    | 'evicted-drone'
+    | 'active-drone'
+    | 'default'
+    | 'mandatory'
+    | 'human-seat'
+    | 'taxonomy-reference'
+    | 'unknown';
+  expected:
+    | {
+      status: 200;
+      response: { deleted: true };
+      mutation: 'delete-role';
+      evicted_drone_retarget?: 'default-role';
+      activity_log_attribution?: 'preserved';
+    }
+    | {
+      status: 409;
+      error: 'ROLE_IN_USE' | 'DEFAULT_ROLE_REQUIRED' | 'ROLE_REQUIRED' | 'ROLE_REFERENCED';
+      mutation: 'none';
+      message?: typeof ROLE_IN_USE_DELETE_MESSAGE;
+    }
+    | { status: 404; error: 'NOT_FOUND'; mutation: 'none' };
+}
+
+/** Portable role-deletion outcomes, including every integrity refusal. */
+export const ROLE_DELETE_CONFORMANCE: readonly RoleDeleteConformanceVector[] = [
+  {
+    name: 'deletes an unreferenced unassigned ordinary role',
+    fixture: 'deletable',
+    expected: { status: 200, response: { deleted: true }, mutation: 'delete-role' },
+  },
+  {
+    name: 'retargets evicted drones without losing existing log attribution',
+    fixture: 'evicted-drone',
+    expected: {
+      status: 200,
+      response: { deleted: true },
+      mutation: 'delete-role',
+      evicted_drone_retarget: 'default-role',
+      activity_log_attribution: 'preserved',
+    },
+  },
+  {
+    name: 'refuses a role held by an active drone with an actionable message',
+    fixture: 'active-drone',
+    expected: {
+      status: 409,
+      error: 'ROLE_IN_USE',
+      mutation: 'none',
+      message: ROLE_IN_USE_DELETE_MESSAGE,
+    },
+  },
+  {
+    name: 'refuses the cube default role',
+    fixture: 'default',
+    expected: { status: 409, error: 'DEFAULT_ROLE_REQUIRED', mutation: 'none' },
+  },
+  {
+    name: 'refuses a mandatory role',
+    fixture: 'mandatory',
+    expected: { status: 409, error: 'ROLE_REQUIRED', mutation: 'none' },
+  },
+  {
+    name: 'refuses a human-seat role',
+    fixture: 'human-seat',
+    expected: { status: 409, error: 'ROLE_REQUIRED', mutation: 'none' },
+  },
+  {
+    name: 'refuses a taxonomy default-recipient role',
+    fixture: 'taxonomy-reference',
+    expected: { status: 409, error: 'ROLE_REFERENCED', mutation: 'none' },
+  },
+  {
+    name: 'hides an unknown or inaccessible role',
+    fixture: 'unknown',
+    expected: { status: 404, error: 'NOT_FOUND', mutation: 'none' },
+  },
+];
+
+export interface RoleRationaleConformanceVector {
+  name: string;
+  fixture:
+    | 'uuid-exact'
+    | 'name-case-insensitive'
+    | 'unknown-role'
+    | 'inaccessible-role'
+    | 'unknown-section'
+    | 'ambiguous-role-name'
+    | 'invalid-selector';
+  expected:
+    | { status: 200; canonical_heading: true; exact_body: true; mutation: 'none' }
+    | { status: 404; error: 'ROLE_NOT_FOUND' | 'ROLE_SECTION_NOT_FOUND'; mutation: 'none' }
+    | { status: 400; error: 'INVALID_INPUT'; mutation: 'none' };
+}
+
+/** Portable role-rationale lookup outcomes for the named-section route. */
+export const ROLE_RATIONALE_CONFORMANCE: readonly RoleRationaleConformanceVector[] = [
+  {
+    name: 'resolves an exact role UUID and returns the exact stored section',
+    fixture: 'uuid-exact',
+    expected: { status: 200, canonical_heading: true, exact_body: true, mutation: 'none' },
+  },
+  {
+    name: 'resolves a role name and section heading case-insensitively',
+    fixture: 'name-case-insensitive',
+    expected: { status: 200, canonical_heading: true, exact_body: true, mutation: 'none' },
+  },
+  {
+    name: 'returns a typed refusal for an unknown role',
+    fixture: 'unknown-role',
+    expected: { status: 404, error: 'ROLE_NOT_FOUND', mutation: 'none' },
+  },
+  {
+    name: 'does not resolve a role outside the addressed cube',
+    fixture: 'inaccessible-role',
+    expected: { status: 404, error: 'ROLE_NOT_FOUND', mutation: 'none' },
+  },
+  {
+    name: 'returns a typed refusal for an unknown section',
+    fixture: 'unknown-section',
+    expected: { status: 404, error: 'ROLE_SECTION_NOT_FOUND', mutation: 'none' },
+  },
+  {
+    name: 'rejects a role name with multiple case-insensitive matches',
+    fixture: 'ambiguous-role-name',
+    expected: { status: 400, error: 'INVALID_INPUT', mutation: 'none' },
+  },
+  {
+    name: 'rejects malformed or ambiguous selectors',
+    fixture: 'invalid-selector',
+    expected: { status: 400, error: 'INVALID_INPUT', mutation: 'none' },
+  },
+];
+
 /** One canonical corpus consumed unchanged by shared, server, and client tests. */
 export const RUNTIME_METADATA_REPOSITORY_CONFORMANCE:
 readonly RuntimeMetadataRepositoryConformanceVector[] = [

package/src/protocol/contract.ts

@@ -13,15 +13,19 @@ import type {
 } from './types.js';
 
 export const SHARED_PACKAGE_NAME = 'borgmcp-shared' as const;
-export const SHARED_PACKAGE_VERSION = '0.9.0' as const;
+export const SHARED_PACKAGE_VERSION = '0.10.1' as const;
 /** Maximum UTF-8 payload for each newly recorded decision text field. */
 export const DECISION_TEXT_MAX_BYTES = 512 as const;
+/** Maximum UTF-8 size of role detailed-description text and any returned section slice. */
+export const ROLE_TEXT_MAX_BYTES = 51_200 as const;
 
 export const HEALTH_PATH = '/healthz' as const;
 export const PROTOCOL_INFO_PATH = '/api/protocol' as const;
 export const ENROLLMENT_EXCHANGE_PATH = '/api/enrollment/exchange' as const;
 export const CUBES_PATH = '/api/cubes' as const;
 export const CUBE_PATH = '/api/cubes/:cubeId' as const;
+export const ROLE_PATH = '/api/cubes/:cubeId/roles/:roleId' as const;
+export const ROLE_RATIONALE_PATH = '/api/cubes/:cubeId/role-rationale' as const;
 export const REPOSITORY_CUBE_RESOLVE_PATH = '/api/repository-cubes/resolve' as const;
 export const REPOSITORY_CUBE_ASSOCIATION_PATH = '/api/repository-cubes/association' as const;
 export const ATTACH_PATH = '/api/client/attach' as const;
@@ -39,6 +43,20 @@ export const PROTOCOL_HTTP_CONTRACT = {
     success_status: 200,
     mutation: true,
   },
+  role_delete: {
+    method: 'DELETE',
+    path: ROLE_PATH,
+    authenticated: true,
+    success_status: 200,
+    mutation: true,
+  },
+  role_rationale: {
+    method: 'POST',
+    path: ROLE_RATIONALE_PATH,
+    authenticated: true,
+    success_status: 200,
+    mutation: false,
+  },
   repository_cube_resolve: {
     method: 'POST',
     path: REPOSITORY_CUBE_RESOLVE_PATH,
@@ -74,7 +92,6 @@ export const PROTOCOL_HTTP_CONTRACT = {
   },
   auth_missing_status: 401,
   auth_invalid_status: 401,
-  auth_expired_status: 401,
   session_revoked_status: 401,
   session_rejected_status: 401,
   cursor_expired_status: 410,
@@ -563,7 +580,7 @@ export function decodeProtocolTagPreflight(value: unknown): ProtocolTagPreflight
   exactKeys(input, ['protocol_version'], ['protocol_version']);
   if (input.protocol_version !== PROTOCOL_VERSION) {
     throw new ProtocolContractError(
-      'This client requires protocol v7. The peer presents a different version. Update `borgmcp-server` and `borgmcp` to matching releases — server first, then client.',
+      'This client requires protocol v8. The peer presents a different version. Update `borgmcp-server` and `borgmcp` to matching releases — server first, then client.',
       ErrorCode.UNSUPPORTED_PROTOCOL_VERSION,
       ['protocol_version'],
     );

package/src/protocol/coordination.ts

@@ -5,6 +5,7 @@ import {
   decodeLogCursor,
   decodeProtocolEnvelope,
   decodeUuid,
+  ROLE_TEXT_MAX_BYTES,
   utf8ByteLength,
   type LogCursor,
   type ProtocolEnvelope,
@@ -16,6 +17,7 @@ import type {
   EnrichedStreamEntry,
   RoutingEcho,
 } from './types.js';
+import { isLabelLine, parseRoleSections } from '../role-section.js';
 
 export interface ReadLogRequest {
   cursor: LogCursor | null;
@@ -65,6 +67,34 @@ export interface EvictDroneResult {
   evicted: true;
 }
 
+export type DeleteRoleRequest = Record<string, never>;
+
+export const ROLE_IN_USE_DELETE_MESSAGE =
+  'Reassign or evict every drone assigned to this role before deleting it.' as const;
+
+export interface DeleteRoleResult {
+  role_id: string;
+  deleted: true;
+}
+
+export interface RoleRationaleRequest {
+  role: string;
+  section: string;
+}
+
+export interface RoleRationaleResult {
+  role_id: string;
+  role_name: string;
+  section: {
+    heading: string;
+    body: string;
+  };
+}
+
+/** Maximum UTF-8 payload for one returned role-description section. */
+export const ROLE_RATIONALE_SECTION_BODY_MAX_BYTES =
+  ROLE_TEXT_MAX_BYTES;
+
 function object(value: unknown): Record<string, unknown> {
   if (typeof value !== 'object' || value === null || Array.isArray(value)) {
     throw new ProtocolContractError('Expected a coordination object.');
@@ -171,6 +201,97 @@ export function decodeEvictDroneResultEnvelope(
   return decodeProtocolEnvelope(value, decodeEvictDroneResult);
 }
 
+export function decodeDeleteRoleRequest(value: unknown): DeleteRoleRequest {
+  const input = object(value);
+  exact(input, [], []);
+  return {};
+}
+
+export function decodeDeleteRoleRequestEnvelope(
+  value: unknown,
+): ProtocolEnvelope<DeleteRoleRequest> {
+  return decodeProtocolEnvelope(value, decodeDeleteRoleRequest);
+}
+
+export function decodeDeleteRoleResult(value: unknown): DeleteRoleResult {
+  const input = object(value);
+  exact(input, ['role_id', 'deleted'], ['role_id', 'deleted']);
+  if (input.deleted !== true) throw new ProtocolContractError('Invalid role deletion result.');
+  return { role_id: decodeUuid(input.role_id, ['role_id']), deleted: true };
+}
+
+export function decodeDeleteRoleResultEnvelope(
+  value: unknown,
+): ProtocolEnvelope<DeleteRoleResult> {
+  return decodeProtocolEnvelope(value, decodeDeleteRoleResult);
+}
+
+function plainRoleSectionHeading(value: unknown): string {
+  const heading = boundedString(value, 'section', 60);
+  if (
+    heading !== heading.trim() ||
+    /[\u0000-\u001f\u007f-\u009f]/.test(heading) ||
+    !isLabelLine(`${heading}:`)
+  ) {
+    throw new ProtocolContractError('Invalid coordination field "section".');
+  }
+  return heading;
+}
+
+export function decodeRoleRationaleRequest(value: unknown): RoleRationaleRequest {
+  const input = object(value);
+  exact(input, ['role', 'section'], ['role', 'section']);
+  const role = boundedString(input.role, 'role', 120);
+  if (role !== role.trim() || /[\u0000-\u001f\u007f-\u009f]/.test(role)) {
+    throw new ProtocolContractError('Invalid coordination field "role".');
+  }
+  return { role, section: plainRoleSectionHeading(input.section) };
+}
+
+export function decodeRoleRationaleRequestEnvelope(
+  value: unknown,
+): ProtocolEnvelope<RoleRationaleRequest> {
+  return decodeProtocolEnvelope(value, decodeRoleRationaleRequest);
+}
+
+export function decodeRoleRationaleResult(value: unknown): RoleRationaleResult {
+  const input = object(value);
+  exact(input, ['role_id', 'role_name', 'section'], ['role_id', 'role_name', 'section']);
+  const section = object(input.section);
+  exact(section, ['heading', 'body'], ['heading', 'body']);
+  const heading = plainRoleSectionHeading(section.heading);
+  const body = boundedString(
+    section.body,
+    'section.body',
+    ROLE_RATIONALE_SECTION_BODY_MAX_BYTES,
+  );
+  const parsed = parseRoleSections(body);
+  if (
+    parsed.length !== 2 ||
+    parsed[0]?.kind !== 'preamble' ||
+    parsed[0].body !== '' ||
+    parsed[1]?.kind !== 'label' ||
+    parsed[1].heading !== heading ||
+    parsed[1].body !== body
+  ) {
+    throw new ProtocolContractError('Invalid coordination field "section.body".');
+  }
+  return {
+    role_id: decodeUuid(input.role_id, ['role_id']),
+    role_name: boundedString(input.role_name, 'role_name', 120),
+    section: {
+      heading,
+      body,
+    },
+  };
+}
+
+export function decodeRoleRationaleResultEnvelope(
+  value: unknown,
+): ProtocolEnvelope<RoleRationaleResult> {
+  return decodeProtocolEnvelope(value, decodeRoleRationaleResult);
+}
+
 export function decodeReadLogRequest(value: unknown): ReadLogRequest {
   const input = object(value);
   exact(input, ['cursor', 'limit'], ['cursor']);

package/src/protocol/errors.ts

@@ -2,7 +2,6 @@
 export enum ErrorCode {
   AUTH_MISSING = 'AUTH_MISSING',
   AUTH_INVALID = 'AUTH_INVALID',
-  AUTH_EXPIRED = 'AUTH_EXPIRED',
   SUBSCRIPTION_REQUIRED = 'SUBSCRIPTION_REQUIRED',
   ACCESS_DENIED = 'ACCESS_DENIED',
   INVALID_INPUT = 'INVALID_INPUT',
@@ -16,6 +15,11 @@ export enum ErrorCode {
   REPOSITORY_ALREADY_ASSOCIATED = 'REPOSITORY_ALREADY_ASSOCIATED',
   CUBE_ALREADY_ASSOCIATED = 'CUBE_ALREADY_ASSOCIATED',
   ROLE_IN_USE = 'ROLE_IN_USE',
+  DEFAULT_ROLE_REQUIRED = 'DEFAULT_ROLE_REQUIRED',
+  ROLE_REQUIRED = 'ROLE_REQUIRED',
+  ROLE_REFERENCED = 'ROLE_REFERENCED',
+  ROLE_NOT_FOUND = 'ROLE_NOT_FOUND',
+  ROLE_SECTION_NOT_FOUND = 'ROLE_SECTION_NOT_FOUND',
   ROLE_HAS_FROZEN_DRONES = 'ROLE_HAS_FROZEN_DRONES',
   CUBE_DELETED = 'CUBE_DELETED',
   DRONE_EVICTED = 'DRONE_EVICTED',
@@ -28,8 +32,7 @@ export enum ErrorCode {
    * The presented session bearer does not match the seat it targets: a fresh or
    * non-matching bearer against an already-bound active seat. Distinct from
    * SESSION_REVOKED (a formerly valid credential that was explicitly revoked).
-   * AUTH_EXPIRED is the only recoverable expired-session outcome. Carried by the
-   * server's typed 401 takeover rejection.
+   * Carried by the server's typed 401 takeover rejection.
    */
   SESSION_REJECTED = 'SESSION_REJECTED',
 }

package/src/protocol/version.ts

@@ -1,4 +1,4 @@
-/** Current Borg coordination protocol generation. Clean-slate v7. */
-export const PROTOCOL_VERSION = '7' as const;
+/** Current Borg coordination protocol generation. Clean-slate v8. */
+export const PROTOCOL_VERSION = '8' as const;
 
 export type ProtocolVersion = typeof PROTOCOL_VERSION;