borgmcp-shared 0.6.2 → 0.6.4

package/src/conformance/index.ts

@@ -1,5 +1,11 @@
 import type { BroadcastHwm } from '../log-stream-hwm.js';
-import type { AttachResponse, EnrollmentExchangeRequest } from '../protocol/contract.js';
+import type {
+  AttachResponse,
+  AssociateRepositoryCubeRequest,
+  CreateCubeRequest,
+  EnrollmentExchangeRequest,
+  ResolveRepositoryCubeRequest,
+} from '../protocol/contract.js';
 
 export * from './adapter.js';
 
@@ -167,6 +173,270 @@ export const ENROLLMENT_RETRY_CONFORMANCE: readonly EnrollmentRetryConformanceVe
   },
 ];
 
+export interface CreateCubeRetryConformanceVector {
+  name: string;
+  initial: CreateCubeRequest;
+  retry: CreateCubeRequest;
+  expected:
+    | { outcome: 'resolved_response'; status: 201 }
+    | { outcome: 'retry_tuple_mismatch'; status: 409; error: 'INVALID_INPUT' };
+}
+
+const CREATE_CUBE_RETRY_KEY = '00000000-0000-4000-8000-000000000121';
+const CREATE_CUBE_INITIAL: CreateCubeRequest = {
+  retry_key: CREATE_CUBE_RETRY_KEY,
+  name: 'Repository One',
+  working_repo_name: 'repository-one',
+  repository: { kind: 'origin', value: 'https://github.com/Byte-Ventures/repository-one' },
+  template: 'default',
+};
+
+/** Stateful vectors: name, repository identity, and template bind the retry key. */
+export const CREATE_CUBE_RETRY_CONFORMANCE: readonly CreateCubeRetryConformanceVector[] = [
+  {
+    name: 'exact retry resolves the authoritative response',
+    initial: CREATE_CUBE_INITIAL,
+    retry: CREATE_CUBE_INITIAL,
+    expected: { outcome: 'resolved_response', status: 201 },
+  },
+  {
+    name: 'changed repository display metadata resolves stored authoritative display',
+    initial: CREATE_CUBE_INITIAL,
+    retry: { ...CREATE_CUBE_INITIAL, working_repo_name: 'repository-one-renamed' },
+    expected: { outcome: 'resolved_response', status: 201 },
+  },
+  {
+    name: 'cube-name mismatch is rejected',
+    initial: CREATE_CUBE_INITIAL,
+    retry: { ...CREATE_CUBE_INITIAL, name: 'Repository One Renamed' },
+    expected: { outcome: 'retry_tuple_mismatch', status: 409, error: 'INVALID_INPUT' },
+  },
+  {
+    name: 'template mismatch is rejected',
+    initial: CREATE_CUBE_INITIAL,
+    retry: { ...CREATE_CUBE_INITIAL, template: 'software-dev' },
+    expected: { outcome: 'retry_tuple_mismatch', status: 409, error: 'INVALID_INPUT' },
+  },
+  {
+    name: 'repository kind mismatch is rejected',
+    initial: CREATE_CUBE_INITIAL,
+    retry: {
+      ...CREATE_CUBE_INITIAL,
+      repository: { kind: 'local', value: '00000000-0000-4000-8000-000000000122' },
+    },
+    expected: { outcome: 'retry_tuple_mismatch', status: 409, error: 'INVALID_INPUT' },
+  },
+  {
+    name: 'repository value mismatch is rejected',
+    initial: CREATE_CUBE_INITIAL,
+    retry: {
+      ...CREATE_CUBE_INITIAL,
+      repository: { kind: 'origin', value: 'https://github.com/Byte-Ventures/repository-two' },
+    },
+    expected: { outcome: 'retry_tuple_mismatch', status: 409, error: 'INVALID_INPUT' },
+  },
+];
+
+export interface CreateCubeAssociationConformanceVector {
+  name: string;
+  created: CreateCubeRequest;
+  request: CreateCubeRequest;
+  expected:
+    | { outcome: 'resolved'; authority_state_delta: Record<string, never> }
+    | {
+      outcome: 'created';
+      authority_state_delta: {
+        cubes: 1;
+        roles: 2;
+        grants: 1;
+        cube_create_bindings: 1;
+        repository_associations: 1;
+      };
+    };
+}
+
+/** A creator-scoped repository association resolves independently of operation retry keys. */
+export const CREATE_CUBE_ASSOCIATION_CONFORMANCE:
+readonly CreateCubeAssociationConformanceVector[] = [
+  {
+    name: 'fresh retry for the same repository resolves stored authoritative fields',
+    created: CREATE_CUBE_INITIAL,
+    request: {
+      ...CREATE_CUBE_INITIAL,
+      retry_key: '00000000-0000-4000-8000-000000000123',
+      name: 'Ignored New Cube Name',
+      working_repo_name: 'ignored-new-display',
+      template: 'starter',
+    },
+    expected: { outcome: 'resolved', authority_state_delta: {} },
+  },
+  {
+    name: 'fresh retry for a different repository may create',
+    created: CREATE_CUBE_INITIAL,
+    request: {
+      ...CREATE_CUBE_INITIAL,
+      retry_key: '00000000-0000-4000-8000-000000000124',
+      name: 'Repository Two',
+      working_repo_name: 'repository-two',
+      repository: { kind: 'origin', value: 'https://github.com/Byte-Ventures/repository-two' },
+    },
+    expected: {
+      outcome: 'created',
+      authority_state_delta: {
+        cubes: 1,
+        roles: 2,
+        grants: 1,
+        cube_create_bindings: 1,
+        repository_associations: 1,
+      },
+    },
+  },
+];
+
+export interface ResolveRepositoryCubeConformanceVector {
+  name: string;
+  request: ResolveRepositoryCubeRequest;
+  associated: boolean;
+  expected:
+    | { outcome: 'none'; status: 200; authority_state_delta: Record<string, never> }
+    | { outcome: 'resolved'; status: 200; authority_state_delta: Record<string, never> };
+}
+
+const REPOSITORY_CUBE_ONE = '00000000-0000-4000-8000-000000000131';
+const REPOSITORY_ONE: ResolveRepositoryCubeRequest = {
+  working_repo_name: 'repository-one',
+  repository: { kind: 'origin', value: 'https://github.com/Byte-Ventures/repository-one' },
+};
+const REPOSITORY_TWO: ResolveRepositoryCubeRequest = {
+  working_repo_name: 'repository-two',
+  repository: { kind: 'origin', value: 'https://github.com/Byte-Ventures/repository-two' },
+};
+
+/** Resolution is read-only and returns only explicit none or authoritative stored fields. */
+export const RESOLVE_REPOSITORY_CUBE_CONFORMANCE:
+readonly ResolveRepositoryCubeConformanceVector[] = [
+  {
+    name: 'unassociated repository resolves explicit none without mutation',
+    request: REPOSITORY_ONE,
+    associated: false,
+    expected: { outcome: 'none', status: 200, authority_state_delta: {} },
+  },
+  {
+    name: 'associated repository resolves authoritative stored fields without mutation',
+    request: { ...REPOSITORY_ONE, working_repo_name: 'ignored-new-display' },
+    associated: true,
+    expected: { outcome: 'resolved', status: 200, authority_state_delta: {} },
+  },
+];
+
+export interface AssociateRepositoryCubeConformanceVector {
+  name: string;
+  initial: AssociateRepositoryCubeRequest;
+  retry: AssociateRepositoryCubeRequest;
+  expected:
+    | {
+      outcome: 'resolved';
+      status: 200;
+      initial_authority_state_delta: { repository_associations: 1 };
+      retry_authority_state_delta: Record<string, never>;
+    }
+    | {
+      outcome: 'repository_conflict' | 'cube_conflict';
+      status: 409;
+      error: 'REPOSITORY_ALREADY_ASSOCIATED' | 'CUBE_ALREADY_ASSOCIATED';
+      diagnostic_disclosure: 'none';
+      retry_authority_state_delta: Record<string, never>;
+    };
+}
+
+/** Explicit cube IDs bind atomically; names never select or identify a cube. */
+export const ASSOCIATE_REPOSITORY_CUBE_CONFORMANCE:
+readonly AssociateRepositoryCubeConformanceVector[] = [
+  {
+    name: 'same explicit cube and repository binding is idempotent',
+    initial: { cube_id: REPOSITORY_CUBE_ONE, ...REPOSITORY_ONE },
+    retry: { cube_id: REPOSITORY_CUBE_ONE, ...REPOSITORY_ONE },
+    expected: {
+      outcome: 'resolved',
+      status: 200,
+      initial_authority_state_delta: { repository_associations: 1 },
+      retry_authority_state_delta: {},
+    },
+  },
+  {
+    name: 'repository already bound to another cube conflicts without mutation',
+    initial: { cube_id: REPOSITORY_CUBE_ONE, ...REPOSITORY_ONE },
+    retry: { cube_id: '00000000-0000-4000-8000-000000000132', ...REPOSITORY_ONE },
+    expected: {
+      outcome: 'repository_conflict',
+      status: 409,
+      error: 'REPOSITORY_ALREADY_ASSOCIATED',
+      diagnostic_disclosure: 'none',
+      retry_authority_state_delta: {},
+    },
+  },
+  {
+    name: 'cube already bound to another repository conflicts without mutation',
+    initial: { cube_id: REPOSITORY_CUBE_ONE, ...REPOSITORY_ONE },
+    retry: { cube_id: REPOSITORY_CUBE_ONE, ...REPOSITORY_TWO },
+    expected: {
+      outcome: 'cube_conflict',
+      status: 409,
+      error: 'CUBE_ALREADY_ASSOCIATED',
+      diagnostic_disclosure: 'none',
+      retry_authority_state_delta: {},
+    },
+  },
+];
+
+export const REPOSITORY_CUBE_PERMISSION_CONFORMANCE = [
+  {
+    name: 'association denies an inaccessible explicit cube without mutation',
+    request: { cube_id: REPOSITORY_CUBE_ONE, ...REPOSITORY_ONE },
+    expected: { status: 403, error: 'ACCESS_DENIED', authority_state_delta: {} },
+  },
+  {
+    name: 'same-client binding to an inaccessible cube is non-enumerating',
+    request: { cube_id: REPOSITORY_CUBE_ONE, ...REPOSITORY_ONE },
+    precondition: 'repository_bound_to_inaccessible_cube',
+    expected: {
+      resolve: { status: 200, outcome: 'none', authority_state_delta: {} },
+      associate: {
+        status: 403,
+        error: 'ACCESS_DENIED',
+        diagnostic_disclosure: 'none',
+        authority_state_delta: {},
+      },
+    },
+  },
+  {
+    name: 'another client binding is neither resolved nor treated as a conflict',
+    request: { cube_id: REPOSITORY_CUBE_ONE, ...REPOSITORY_ONE },
+    precondition: 'repository_bound_by_another_client',
+    expected: {
+      resolve: { status: 200, outcome: 'none', authority_state_delta: {} },
+      associate: {
+        status: 200,
+        outcome: 'resolved',
+        authority_state_delta: { repository_associations: 1 },
+      },
+    },
+  },
+] as const;
+
+export const REPOSITORY_CUBE_AUTHORITATIVE_STATE_CONFORMANCE = [
+  {
+    name: 'legacy cube with invalid authoritative roles is rejected without mutation',
+    request: { cube_id: REPOSITORY_CUBE_ONE, ...REPOSITORY_ONE },
+    expected: {
+      status: 409,
+      error: 'INVALID_INPUT',
+      diagnostic_disclosure: 'none',
+      authority_state_delta: {},
+    },
+  },
+] as const;
+
 export const ENROLLMENT_AUTHORITY_CONFORMANCE = [
   {
     name: 'ordinary enrollment creates no authority or cube state',

package/src/protocol/contract.ts

@@ -1,6 +1,7 @@
 import { ErrorCode } from './errors.js';
 import { PROTOCOL_VERSION, type ProtocolVersion } from './version.js';
 import {
+  canonicalizeRepositoryIdentity,
   RuntimeMetadataValidationError,
   validateRuntimeMetadata,
   validateRuntimeMetadataPatch,
@@ -12,12 +13,14 @@ import type {
 } from './types.js';
 
 export const SHARED_PACKAGE_NAME = 'borgmcp-shared' as const;
-export const SHARED_PACKAGE_VERSION = '0.6.2' as const;
+export const SHARED_PACKAGE_VERSION = '0.6.4' 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 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;
 export const SELF_RUNTIME_METADATA_PATH = '/api/cubes/:cubeId/drones/self/metadata' as const;
 
@@ -26,6 +29,20 @@ export const PROTOCOL_HTTP_CONTRACT = {
   protocol: { method: 'GET', path: PROTOCOL_INFO_PATH, authenticated: false, success_status: 200 },
   enrollment: { method: 'POST', path: ENROLLMENT_EXCHANGE_PATH, authenticated: 'invitation', success_status: 201 },
   cubes: { method: 'POST', path: CUBES_PATH, authenticated: true, success_status: 201 },
+  repository_cube_resolve: {
+    method: 'POST',
+    path: REPOSITORY_CUBE_RESOLVE_PATH,
+    authenticated: true,
+    success_status: 200,
+    mutation: false,
+  },
+  repository_cube_association: {
+    method: 'PUT',
+    path: REPOSITORY_CUBE_ASSOCIATION_PATH,
+    authenticated: true,
+    success_status: 200,
+    mutation: true,
+  },
   attach: { method: 'POST', path: ATTACH_PATH, authenticated: true, success_status: 200 },
   drone_reassign: {
     method: 'PATCH',
@@ -120,22 +137,60 @@ export type EnrollmentExchangeResponse =
   | ClientEnrollmentExchangeResponse
   | OwnerEnrollmentExchangeResponse;
 
-export const CUBE_TEMPLATES = ['default'] as const;
+export const CUBE_TEMPLATES = ['default', 'software-dev', 'starter'] as const;
 export type CubeTemplate = (typeof CUBE_TEMPLATES)[number];
 
+export type CreateCubeRepository =
+  | { kind: 'origin'; value: string }
+  | { kind: 'local'; value: string };
+
 export interface CreateCubeRequest {
   retry_key: string;
   name: string;
+  working_repo_name: string;
+  repository: CreateCubeRepository;
   template: CubeTemplate;
 }
 
 export interface CreateCubeResponse {
+  result: 'created' | 'resolved';
+  cube_id: string;
+  name: string;
+  working_repo_name: string;
+  repository: CreateCubeRepository;
+  template: CubeTemplate;
+  human_seat_role_id: string;
+  default_worker_role_id: string;
+  access: 'manage';
+}
+
+export interface ResolveRepositoryCubeRequest {
+  working_repo_name: string;
+  repository: CreateCubeRepository;
+}
+
+export interface AssociateRepositoryCubeRequest extends ResolveRepositoryCubeRequest {
+  cube_id: string;
+}
+
+export interface ResolvedRepositoryCube {
+  result: 'resolved';
   cube_id: string;
+  name: string;
+  working_repo_name: string;
+  repository: CreateCubeRepository;
+  template: CubeTemplate;
   human_seat_role_id: string;
   default_worker_role_id: string;
   access: 'manage';
 }
 
+export type ResolveRepositoryCubeResponse =
+  | { result: 'none' }
+  | ResolvedRepositoryCube;
+
+export type AssociateRepositoryCubeResponse = ResolvedRepositoryCube;
+
 export interface AckLogRequest {
   entry_id: string;
   kind: 'ack' | 'claim';
@@ -434,17 +489,24 @@ function decodeExactServerCapabilities(
 
 export function decodeCreateCubeRequest(value: unknown): CreateCubeRequest {
   const input = record(value);
-  exactKeys(input, ['retry_key', 'name', 'template'], ['retry_key', 'name', 'template']);
+  exactKeys(
+    input,
+    ['retry_key', 'name', 'working_repo_name', 'repository', 'template'],
+    ['retry_key', 'name', 'working_repo_name', 'repository', 'template'],
+  );
   const name = boundedString(input.name, 1, 120, ['name']);
   if (!/^[A-Za-z0-9][A-Za-z0-9 ._-]*$/.test(name)) {
     fail('Cube name contains unsupported characters.', ['name']);
   }
+  const workingRepoName = decodeWorkingRepositoryName(input.working_repo_name, ['working_repo_name']);
   if (!CUBE_TEMPLATES.includes(input.template as CubeTemplate)) {
     fail('Unsupported cube template.', ['template']);
   }
   return {
     retry_key: decodeUuid(input.retry_key, ['retry_key']),
     name,
+    working_repo_name: workingRepoName,
+    repository: decodeCreateCubeRepository(input.repository, ['repository']),
     template: input.template as CubeTemplate,
   };
 }
@@ -457,22 +519,203 @@ export function decodeCreateCubeResponse(value: unknown): CreateCubeResponse {
   const input = record(value);
   exactKeys(
     input,
-    ['cube_id', 'human_seat_role_id', 'default_worker_role_id', 'access'],
-    ['cube_id', 'human_seat_role_id', 'default_worker_role_id', 'access'],
+    [
+      'result',
+      'cube_id',
+      'name',
+      'working_repo_name',
+      'repository',
+      'template',
+      'human_seat_role_id',
+      'default_worker_role_id',
+      'access',
+    ],
+    [
+      'result',
+      'cube_id',
+      'name',
+      'working_repo_name',
+      'repository',
+      'template',
+      'human_seat_role_id',
+      'default_worker_role_id',
+      'access',
+    ],
   );
+  if (input.result !== 'created' && input.result !== 'resolved') {
+    fail('Invalid cube creation result.', ['result']);
+  }
+  const name = boundedString(input.name, 1, 120, ['name']);
+  if (!/^[A-Za-z0-9][A-Za-z0-9 ._-]*$/.test(name)) {
+    fail('Cube name contains unsupported characters.', ['name']);
+  }
+  const workingRepoName = decodeWorkingRepositoryName(input.working_repo_name, ['working_repo_name']);
+  if (!CUBE_TEMPLATES.includes(input.template as CubeTemplate)) {
+    fail('Unsupported cube template.', ['template']);
+  }
   if (input.access !== 'manage') fail('Created cube access must be manage.', ['access']);
   return {
+    result: input.result,
     cube_id: decodeUuid(input.cube_id, ['cube_id']),
+    name,
+    working_repo_name: workingRepoName,
+    repository: decodeCreateCubeRepository(input.repository, ['repository']),
+    template: input.template as CubeTemplate,
     human_seat_role_id: decodeUuid(input.human_seat_role_id, ['human_seat_role_id']),
     default_worker_role_id: decodeUuid(input.default_worker_role_id, ['default_worker_role_id']),
     access: 'manage',
   };
 }
 
+function decodeCreateCubeRepository(
+  value: unknown,
+  path: readonly (string | number)[],
+): CreateCubeRepository {
+  const input = record(value, path);
+  exactKeys(input, ['kind', 'value'], ['kind', 'value'], path);
+  if (input.kind === 'local') {
+    return { kind: 'local', value: decodeUuid(input.value, [...path, 'value']) };
+  }
+  if (input.kind !== 'origin') fail('Unsupported repository identity kind.', [...path, 'kind']);
+  const origin = boundedString(input.value, 1, 512, [...path, 'value']);
+  try {
+    if (canonicalizeRepositoryIdentity(origin).working_repo_origin !== origin) {
+      fail('Repository origin must be canonical.', [...path, 'value']);
+    }
+  } catch (error) {
+    if (error instanceof ProtocolContractError) throw error;
+    if (error instanceof RuntimeMetadataValidationError) {
+      fail('Repository origin must be canonical.', [...path, 'value']);
+    }
+    throw error;
+  }
+  return { kind: 'origin', value: origin };
+}
+
 export function decodeCreateCubeResponseEnvelope(value: unknown): ProtocolEnvelope<CreateCubeResponse> {
   return decodeProtocolEnvelope(value, decodeCreateCubeResponse);
 }
 
+export function decodeResolveRepositoryCubeRequest(value: unknown): ResolveRepositoryCubeRequest {
+  const input = record(value);
+  exactKeys(input, ['working_repo_name', 'repository'], ['working_repo_name', 'repository']);
+  return {
+    working_repo_name: decodeWorkingRepositoryName(input.working_repo_name, ['working_repo_name']),
+    repository: decodeCreateCubeRepository(input.repository, ['repository']),
+  };
+}
+
+export function decodeResolveRepositoryCubeRequestEnvelope(
+  value: unknown,
+): ProtocolEnvelope<ResolveRepositoryCubeRequest> {
+  return decodeProtocolEnvelope(value, decodeResolveRepositoryCubeRequest);
+}
+
+export function decodeAssociateRepositoryCubeRequest(value: unknown): AssociateRepositoryCubeRequest {
+  const input = record(value);
+  exactKeys(
+    input,
+    ['cube_id', 'working_repo_name', 'repository'],
+    ['cube_id', 'working_repo_name', 'repository'],
+  );
+  return {
+    cube_id: decodeUuid(input.cube_id, ['cube_id']),
+    working_repo_name: decodeWorkingRepositoryName(input.working_repo_name, ['working_repo_name']),
+    repository: decodeCreateCubeRepository(input.repository, ['repository']),
+  };
+}
+
+export function decodeAssociateRepositoryCubeRequestEnvelope(
+  value: unknown,
+): ProtocolEnvelope<AssociateRepositoryCubeRequest> {
+  return decodeProtocolEnvelope(value, decodeAssociateRepositoryCubeRequest);
+}
+
+function decodeResolvedRepositoryCube(value: unknown): ResolvedRepositoryCube {
+  const input = record(value);
+  exactKeys(
+    input,
+    [
+      'result',
+      'cube_id',
+      'name',
+      'working_repo_name',
+      'repository',
+      'template',
+      'human_seat_role_id',
+      'default_worker_role_id',
+      'access',
+    ],
+    [
+      'result',
+      'cube_id',
+      'name',
+      'working_repo_name',
+      'repository',
+      'template',
+      'human_seat_role_id',
+      'default_worker_role_id',
+      'access',
+    ],
+  );
+  if (input.result !== 'resolved') fail('Invalid repository cube result.', ['result']);
+  const name = boundedString(input.name, 1, 120, ['name']);
+  if (!/^[A-Za-z0-9][A-Za-z0-9 ._-]*$/.test(name)) {
+    fail('Cube name contains unsupported characters.', ['name']);
+  }
+  if (!CUBE_TEMPLATES.includes(input.template as CubeTemplate)) {
+    fail('Unsupported cube template.', ['template']);
+  }
+  if (input.access !== 'manage') fail('Repository cube access must be manage.', ['access']);
+  return {
+    result: 'resolved',
+    cube_id: decodeUuid(input.cube_id, ['cube_id']),
+    name,
+    working_repo_name: decodeWorkingRepositoryName(input.working_repo_name, ['working_repo_name']),
+    repository: decodeCreateCubeRepository(input.repository, ['repository']),
+    template: input.template as CubeTemplate,
+    human_seat_role_id: decodeUuid(input.human_seat_role_id, ['human_seat_role_id']),
+    default_worker_role_id: decodeUuid(input.default_worker_role_id, ['default_worker_role_id']),
+    access: 'manage',
+  };
+}
+
+export function decodeResolveRepositoryCubeResponse(value: unknown): ResolveRepositoryCubeResponse {
+  const input = record(value);
+  if (input.result === 'none') {
+    exactKeys(input, ['result'], ['result']);
+    return { result: 'none' };
+  }
+  return decodeResolvedRepositoryCube(input);
+}
+
+export function decodeResolveRepositoryCubeResponseEnvelope(
+  value: unknown,
+): ProtocolEnvelope<ResolveRepositoryCubeResponse> {
+  return decodeProtocolEnvelope(value, decodeResolveRepositoryCubeResponse);
+}
+
+export function decodeAssociateRepositoryCubeResponse(value: unknown): AssociateRepositoryCubeResponse {
+  return decodeResolvedRepositoryCube(value);
+}
+
+export function decodeAssociateRepositoryCubeResponseEnvelope(
+  value: unknown,
+): ProtocolEnvelope<AssociateRepositoryCubeResponse> {
+  return decodeProtocolEnvelope(value, decodeAssociateRepositoryCubeResponse);
+}
+
+function decodeWorkingRepositoryName(
+  value: unknown,
+  path: readonly (string | number)[],
+): string {
+  const name = boundedString(value, 1, 120, path);
+  if (!/^[A-Za-z0-9][A-Za-z0-9 ._-]*$/.test(name)) {
+    fail('Repository name contains unsupported characters.', path);
+  }
+  return name;
+}
+
 export function decodeAppendLogRequest(value: unknown): import('./types.js').AppendLogRequest {
   const input = record(value);
   exactKeys(
@@ -698,7 +941,7 @@ export function decodeUpdateDroneRuntimeMetadataResponseEnvelope(
   return decodeProtocolEnvelope(value, decodeUpdateDroneRuntimeMetadataResponse);
 }
 
-// ── v3 clean-slate wire types ──────────────────────────────────────────────
+// ── Clean-slate attach wire types (introduced in v3) ──────────────────────
 
 export interface AttachRequest {
   cube_id: string;
@@ -800,7 +1043,7 @@ function decodeAttachSession(value: unknown, path: readonly (string | number)[])
 }
 
 /**
- * Decode a v3 attach request. Strict: exact keys, bounded sizes,
+ * Decode an attach request. Strict: exact keys, bounded sizes,
  * session_credential is token-safe and never echoed in errors.
  */
 export function decodeAttachRequest(value: unknown): AttachRequest {
@@ -825,7 +1068,7 @@ export function decodeAttachRequest(value: unknown): AttachRequest {
 }
 
 /**
- * Create a v3 attach request envelope. Stamps the canonical protocol version.
+ * Create an attach request envelope. Stamps the canonical protocol version.
  */
 export function createAttachRequestEnvelope(
   requestId: string,
@@ -839,7 +1082,7 @@ export function createAttachRequestEnvelope(
 }
 
 /**
- * Decode a v3 attach request envelope. Verifies protocol_version === PROTOCOL_VERSION
+ * Decode an attach request envelope. Verifies protocol_version === PROTOCOL_VERSION
  * BEFORE decoding the payload — a wrong tag never invokes the payload decoder
  * and never exposes or returns the supplied session_credential.
  * Uses a static token-safe diagnostic; does not interpolate attacker-controlled text.
@@ -869,7 +1112,7 @@ export function decodeAttachRequestEnvelope(
 }
 
 /**
- * Decode a v3 attach response. Strict: exact keys and result discriminant.
+ * Decode an attach response. Strict: exact keys and result discriminant.
  */
 export function decodeAttachResponse(value: unknown): AttachResponse {
   const input = record(value);
@@ -893,7 +1136,7 @@ export function decodeAttachResponse(value: unknown): AttachResponse {
 }
 
 /**
- * Decode a v3 attach response wrapped in a ProtocolEnvelope.
+ * Decode an attach response wrapped in a ProtocolEnvelope.
  * Verifies protocol_version === PROTOCOL_VERSION before decoding payload.
  */
 export function decodeAttachResponseEnvelope(value: unknown): ProtocolEnvelope<AttachResponse> {

package/src/protocol/errors.ts

@@ -13,6 +13,8 @@ export enum ErrorCode {
   DATABASE_ERROR = 'DATABASE_ERROR',
   EXTERNAL_SERVICE_ERROR = 'EXTERNAL_SERVICE_ERROR',
   NOT_FOUND = 'NOT_FOUND',
+  REPOSITORY_ALREADY_ASSOCIATED = 'REPOSITORY_ALREADY_ASSOCIATED',
+  CUBE_ALREADY_ASSOCIATED = 'CUBE_ALREADY_ASSOCIATED',
   ROLE_IN_USE = 'ROLE_IN_USE',
   ROLE_HAS_FROZEN_DRONES = 'ROLE_HAS_FROZEN_DRONES',
   DRONE_EVICTED = 'DRONE_EVICTED',

package/src/protocol/version.ts

@@ -1,4 +1,4 @@
-/** Current Borg coordination protocol generation. Clean-slate v3. */
-export const PROTOCOL_VERSION = '3' as const;
+/** Current Borg coordination protocol generation. Clean-slate v5. */
+export const PROTOCOL_VERSION = '5' as const;
 
 export type ProtocolVersion = typeof PROTOCOL_VERSION;