borgmcp-shared 0.6.3 → 0.6.4

package/src/conformance/index.ts

@@ -1,8 +1,10 @@
 import type { BroadcastHwm } from '../log-stream-hwm.js';
 import type {
   AttachResponse,
+  AssociateRepositoryCubeRequest,
   CreateCubeRequest,
   EnrollmentExchangeRequest,
+  ResolveRepositoryCubeRequest,
 } from '../protocol/contract.js';
 
 export * from './adapter.js';
@@ -291,6 +293,150 @@ readonly CreateCubeAssociationConformanceVector[] = [
   },
 ];
 
+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

@@ -13,12 +13,14 @@ import type {
 } from './types.js';
 
 export const SHARED_PACKAGE_NAME = 'borgmcp-shared' as const;
-export const SHARED_PACKAGE_VERSION = '0.6.3' 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;
 
@@ -27,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',
@@ -148,6 +164,33 @@ export interface CreateCubeResponse {
   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';
@@ -455,10 +498,7 @@ export function decodeCreateCubeRequest(value: unknown): CreateCubeRequest {
   if (!/^[A-Za-z0-9][A-Za-z0-9 ._-]*$/.test(name)) {
     fail('Cube name contains unsupported characters.', ['name']);
   }
-  const workingRepoName = boundedString(input.working_repo_name, 1, 120, ['working_repo_name']);
-  if (!/^[A-Za-z0-9][A-Za-z0-9 ._-]*$/.test(workingRepoName)) {
-    fail('Cube name contains unsupported characters.', ['working_repo_name']);
-  }
+  const workingRepoName = decodeWorkingRepositoryName(input.working_repo_name, ['working_repo_name']);
   if (!CUBE_TEMPLATES.includes(input.template as CubeTemplate)) {
     fail('Unsupported cube template.', ['template']);
   }
@@ -509,10 +549,7 @@ export function decodeCreateCubeResponse(value: unknown): CreateCubeResponse {
   if (!/^[A-Za-z0-9][A-Za-z0-9 ._-]*$/.test(name)) {
     fail('Cube name contains unsupported characters.', ['name']);
   }
-  const workingRepoName = boundedString(input.working_repo_name, 1, 120, ['working_repo_name']);
-  if (!/^[A-Za-z0-9][A-Za-z0-9 ._-]*$/.test(workingRepoName)) {
-    fail('Cube name contains unsupported characters.', ['working_repo_name']);
-  }
+  const workingRepoName = decodeWorkingRepositoryName(input.working_repo_name, ['working_repo_name']);
   if (!CUBE_TEMPLATES.includes(input.template as CubeTemplate)) {
     fail('Unsupported cube template.', ['template']);
   }
@@ -559,6 +596,126 @@ export function decodeCreateCubeResponseEnvelope(value: unknown): ProtocolEnvelo
   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(

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 v4. */
-export const PROTOCOL_VERSION = '4' as const;
+/** Current Borg coordination protocol generation. Clean-slate v5. */
+export const PROTOCOL_VERSION = '5' as const;
 
 export type ProtocolVersion = typeof PROTOCOL_VERSION;