borgmcp-shared 0.13.1 → 1.0.0

package/src/conformance/index.ts

@@ -100,8 +100,6 @@ const APPEND_LOG_ENTRY: EnrichedStreamEntry = {
 const APPEND_LOG_ROUTING = {
   class: 'review',
   recipients: ['one-of-one-reviewer'],
-  fellOpen: false,
-  message: 'Routing applied.',
 } as const;
 
 export interface AppendLogResultConformanceVector {
@@ -119,31 +117,71 @@ export interface AppendLogRequestConformanceVector {
 export interface AppendLogIdempotencyConformanceVector {
   name: string;
   actor: 'same' | 'different';
-  mutation: 'none' | 'message' | 'visibility' | 'recipient_set' | 'ignored_request_shape' | 'resolved_class_routing';
+  mutation: 'none' | 'message' | 'audience' | 'recipient_set' | 'classification';
   expected: 'deduplicated' | 'POST_ID_CONFLICT' | 'created';
 }
 
-/** Author-scoped post identity and exact resolved-routing retry outcomes. */
+/** Author-scoped post identity and exact resolved-delivery retry outcomes. */
 export const APPEND_LOG_IDEMPOTENCY_CONFORMANCE: readonly AppendLogIdempotencyConformanceVector[] = [
   { name: 'deduplicates an exact same-author retry', actor: 'same', mutation: 'none', expected: 'deduplicated' },
   { name: 'rejects a same-author message collision', actor: 'same', mutation: 'message', expected: 'POST_ID_CONFLICT' },
-  { name: 'rejects a same-author visibility collision', actor: 'same', mutation: 'visibility', expected: 'POST_ID_CONFLICT' },
+  { name: 'rejects a same-author audience collision', actor: 'same', mutation: 'audience', expected: 'POST_ID_CONFLICT' },
   { name: 'rejects a same-author recipient-set collision', actor: 'same', mutation: 'recipient_set', expected: 'POST_ID_CONFLICT' },
-  { name: 'deduplicates ignored class selectors with identical resolved delivery', actor: 'same', mutation: 'ignored_request_shape', expected: 'deduplicated' },
-  { name: 'rejects a same-author resolved class-routing collision', actor: 'same', mutation: 'resolved_class_routing', expected: 'POST_ID_CONFLICT' },
+  { name: 'deduplicates changed classification with identical explicit delivery', actor: 'same', mutation: 'classification', expected: 'deduplicated' },
   { name: 'creates an independent cross-author post', actor: 'different', mutation: 'none', expected: 'created' },
 ];
 
 const APPEND_LOG_REQUEST = {
   post_id: '00000000-0000-4000-8000-000000000205',
   message: 'REVIEW-READY: example',
+  to: 'broadcast',
 } satisfies AppendLogRequest;
 
 export const APPEND_LOG_REQUEST_CONFORMANCE: readonly AppendLogRequestConformanceVector[] = [
   { name: 'accepts a canonical post UUID', request: APPEND_LOG_REQUEST, accepts: true },
-  { name: 'rejects an omitted post UUID', request: { message: APPEND_LOG_REQUEST.message }, accepts: false },
+  { name: 'rejects an omitted post UUID', request: { message: APPEND_LOG_REQUEST.message, to: 'broadcast' }, accepts: false },
   { name: 'rejects an invalid post UUID', request: { ...APPEND_LOG_REQUEST, post_id: 'not-a-uuid' }, accepts: false },
   { name: 'rejects unknown request fields', request: { ...APPEND_LOG_REQUEST, extra: true }, accepts: false },
+  {
+    name: 'rejects omitted addressing',
+    request: { post_id: APPEND_LOG_REQUEST.post_id, message: APPEND_LOG_REQUEST.message },
+    accepts: false,
+  },
+  {
+    name: 'accepts explicit broadcast addressing',
+    request: APPEND_LOG_REQUEST,
+    accepts: true,
+  },
+  {
+    name: 'accepts a non-empty recipient selector union branch',
+    request: { ...APPEND_LOG_REQUEST, to: ['Builder', 'id:3336cde1'] },
+    accepts: true,
+  },
+  {
+    name: 'rejects null addressing',
+    request: { ...APPEND_LOG_REQUEST, to: null },
+    accepts: false,
+  },
+  {
+    name: 'rejects an empty recipient selector array',
+    request: { ...APPEND_LOG_REQUEST, to: [] },
+    accepts: false,
+  },
+  {
+    name: 'rejects an arbitrary scalar audience',
+    request: { ...APPEND_LOG_REQUEST, to: 'all' },
+    accepts: false,
+  },
+  {
+    name: 'rejects retired visibility without falling open',
+    request: { ...APPEND_LOG_REQUEST, visibility: 'broadcast' },
+    accepts: false,
+  },
+  {
+    name: 'rejects retired recipient ids without falling open',
+    request: { ...APPEND_LOG_REQUEST, recipientDroneIds: ['00000000-0000-4000-8000-000000000204'] },
+    accepts: false,
+  },
 ];
 
 /** Runtime response vectors keep the append-log decoder aligned with its public type. */
@@ -214,13 +252,8 @@ export const APPEND_LOG_RESULT_CONFORMANCE: readonly AppendLogResultConformanceV
     accepts: false,
   },
   {
-    name: 'rejects an invalid routing fell-open flag',
-    response: { entry: APPEND_LOG_ENTRY, deduplicated: false, routing: { ...APPEND_LOG_ROUTING, fellOpen: 'false' } },
-    accepts: false,
-  },
-  {
-    name: 'rejects an invalid routing message',
-    response: { entry: APPEND_LOG_ENTRY, deduplicated: false, routing: { ...APPEND_LOG_ROUTING, message: 7 } },
+    name: 'rejects legacy fall-open routing metadata',
+    response: { entry: APPEND_LOG_ENTRY, deduplicated: false, routing: { ...APPEND_LOG_ROUTING, fellOpen: false } },
     accepts: false,
   },
   {
@@ -883,7 +916,6 @@ export interface RoleDeleteConformanceVector {
     | 'default'
     | 'mandatory'
     | 'human-seat'
-    | 'taxonomy-reference'
     | 'unknown';
   expected:
     | {
@@ -895,7 +927,7 @@ export interface RoleDeleteConformanceVector {
     }
     | {
       status: 409;
-      error: 'ROLE_IN_USE' | 'DEFAULT_ROLE_REQUIRED' | 'ROLE_REQUIRED' | 'ROLE_REFERENCED';
+      error: 'ROLE_IN_USE' | 'DEFAULT_ROLE_REQUIRED' | 'ROLE_REQUIRED';
       mutation: 'none';
       message?: typeof ROLE_IN_USE_DELETE_MESSAGE;
     }
@@ -945,11 +977,6 @@ export const ROLE_DELETE_CONFORMANCE: readonly RoleDeleteConformanceVector[] = [
     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',
@@ -1012,6 +1039,79 @@ export const ROLE_RATIONALE_CONFORMANCE: readonly RoleRationaleConformanceVector
   },
 ];
 
+export interface AckStatusConformanceVector {
+  name: string;
+  fixture: 'missing-ack' | 'ack-and-claim' | 'unread-preserved' | 'unknown-entry';
+  expected:
+    | { status: 200; acknowledged_at: null; mutation: 'none' }
+    | { status: 200; acknowledgements: 1; claims: 1; distinct: true; mutation: 'none' }
+    | { status: 200; unread_entry_available: true; mutation: 'none' }
+    | { status: 404; error: 'NOT_FOUND'; mutation: 'none' };
+}
+
+/** Portable acknowledgement-status outcomes for one exact log entry. */
+export const ACK_STATUS_CONFORMANCE: readonly AckStatusConformanceVector[] = [
+  {
+    name: 'reports an intended recipient with no acknowledgement',
+    fixture: 'missing-ack',
+    expected: { status: 200, acknowledged_at: null, mutation: 'none' },
+  },
+  {
+    name: 'keeps acknowledgements and claims in separate result collections',
+    fixture: 'ack-and-claim',
+    expected: { status: 200, acknowledgements: 1, claims: 1, distinct: true, mutation: 'none' },
+  },
+  {
+    name: 'does not consume the queried entry from unread delivery',
+    fixture: 'unread-preserved',
+    expected: { status: 200, unread_entry_available: true, mutation: 'none' },
+  },
+  {
+    name: 'returns not found for an unknown entry instead of missing acknowledgement state',
+    fixture: 'unknown-entry',
+    expected: { status: 404, error: 'NOT_FOUND', mutation: 'none' },
+  },
+];
+
+export interface EntryQueryConformanceVector {
+  name: string;
+  fixture: 'full-uuid' | 'unique-prefix' | 'unknown' | 'ambiguous-prefix' | 'read-only';
+  expected:
+    | { status: 200; exact_entry: true; mutation: 'none' }
+    | { status: 404; error: 'NOT_FOUND'; mutation: 'none' }
+    | { status: 409; error: 'LOG_ENTRY_PREFIX_AMBIGUOUS'; mutation: 'none' }
+    | { status: 200; unread_entry_available: true; mutation: 'none' };
+}
+
+/** Portable exact-entry lookup outcomes for canonical UUID and short-prefix selectors. */
+export const ENTRY_QUERY_CONFORMANCE: readonly EntryQueryConformanceVector[] = [
+  {
+    name: 'resolves one canonical full UUID',
+    fixture: 'full-uuid',
+    expected: { status: 200, exact_entry: true, mutation: 'none' },
+  },
+  {
+    name: 'resolves one unique eight-hex prefix',
+    fixture: 'unique-prefix',
+    expected: { status: 200, exact_entry: true, mutation: 'none' },
+  },
+  {
+    name: 'hides an unknown or inaccessible selector',
+    fixture: 'unknown',
+    expected: { status: 404, error: 'NOT_FOUND', mutation: 'none' },
+  },
+  {
+    name: 'refuses an ambiguous eight-hex prefix',
+    fixture: 'ambiguous-prefix',
+    expected: { status: 409, error: 'LOG_ENTRY_PREFIX_AMBIGUOUS', mutation: 'none' },
+  },
+  {
+    name: 'does not advance unread or mutate acknowledgement, claim, log, or authority state',
+    fixture: 'read-only',
+    expected: { status: 200, unread_entry_available: true, 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,7 +13,7 @@ import type {
 } from './types.js';
 
 export const SHARED_PACKAGE_NAME = 'borgmcp-shared' as const;
-export const SHARED_PACKAGE_VERSION = '0.13.1' as const;
+export const SHARED_PACKAGE_VERSION = '1.0.0' 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. */
@@ -590,7 +590,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 v10. The peer presents a different version. Update `borgmcp-server` and `borgmcp` to matching releases — server first, then client.',
+      'This client requires protocol v12. The peer presents a different version. Update `borgmcp-server` and `borgmcp` to matching releases — server first, then client.',
       ErrorCode.UNSUPPORTED_PROTOCOL_VERSION,
       ['protocol_version'],
     );
@@ -1007,33 +1007,17 @@ export function decodeAppendLogRequest(value: unknown): import('./types.js').App
   const input = record(value);
   exactKeys(
     input,
-    ['post_id', 'message', 'visibility', 'recipientDroneIds', 'class', 'to', 'documents'],
-    ['post_id', 'message'],
+    ['post_id', 'message', 'to', 'class', 'documents'],
+    ['post_id', 'message', 'to'],
   );
   const output: import('./types.js').AppendLogRequest = {
     post_id: decodeUuid(input.post_id, ['post_id']),
     message: boundedString(input.message, 1, PROTOCOL_LIMIT_CEILINGS.max_log_message_bytes, ['message']),
+    to: input.to === 'broadcast' ? 'broadcast' : decodeRecipientSelectors(input.to),
   };
-  if (input.visibility !== undefined) {
-    if (input.visibility !== 'broadcast' && input.visibility !== 'direct') {
-      fail('Invalid log visibility.', ['visibility']);
-    }
-    output.visibility = input.visibility;
-  }
-  if (input.recipientDroneIds !== undefined) {
-    if (!Array.isArray(input.recipientDroneIds) || input.recipientDroneIds.length === 0 || input.recipientDroneIds.length > 100) {
-      fail('Expected recipientDroneIds to contain 1-100 UUIDs.', ['recipientDroneIds']);
-    }
-    output.recipientDroneIds = input.recipientDroneIds.map((id, index) =>
-      decodeUuid(id, ['recipientDroneIds', index])
-    );
-  }
   if (input.class !== undefined) {
     output.class = boundedString(input.class, 1, 64, ['class']);
   }
-  if (input.to !== undefined) {
-    output.to = decodeStringArray(input.to, 'to', 100, 120);
-  }
   if (input.documents !== undefined) {
     output.documents = decodeStringArray(input.documents, 'documents', 100, 128)
       .map((id, index) => decodeOpaqueIdentifier(id, ['documents', index]));
@@ -1041,6 +1025,16 @@ export function decodeAppendLogRequest(value: unknown): import('./types.js').App
   return output;
 }
 
+function decodeRecipientSelectors(value: unknown): string[] {
+  const selectors = decodeStringArray(value, 'to', 100, 120);
+  for (const [index, selector] of selectors.entries()) {
+    if (selector !== selector.trim() || /[\u0000-\u001f\u007f-\u009f]/.test(selector)) {
+      fail('Recipient selectors must be trimmed and control-free.', ['to', index]);
+    }
+  }
+  return selectors;
+}
+
 function decodeStringArray(value: unknown, field: string, maxItems: number, maxLength: number): string[] {
   if (!Array.isArray(value) || value.length === 0 || value.length > maxItems) {
     fail(`Expected ${field} to contain 1-${maxItems} values.`, [field]);

package/src/protocol/coordination.ts

@@ -16,6 +16,7 @@ import type {
   AppendLogResponse,
   Decision,
   EnrichedStreamEntry,
+  LogVisibility,
   RoutingEcho,
 } from './types.js';
 import { isLabelLine, parseRoleSections } from '../role-section.js';
@@ -46,6 +47,39 @@ export interface ReadLogResult {
   claims: ClaimRecord[];
 }
 
+export interface EntryQueryRequest {
+  entry_id: string;
+}
+
+export interface EntryQueryResult {
+  entry: EnrichedStreamEntry;
+}
+
+export interface AckStatusRequest {
+  entry_id: string;
+}
+
+export interface AckStatusRecipient {
+  drone_id: string;
+  drone_label: string | null;
+  drone_role: string | null;
+  acknowledged_at: string | null;
+}
+
+export interface AckStatusClaim {
+  drone_id: string;
+  drone_label: string | null;
+  drone_role: string | null;
+  claimed_at: string;
+}
+
+export interface AckStatusResult {
+  entry_id: string;
+  visibility: LogVisibility;
+  recipients: AckStatusRecipient[];
+  claims: AckStatusClaim[];
+}
+
 export interface ReassignDroneRequest {
   role_id: string;
 }
@@ -309,6 +343,106 @@ export function decodeReadLogRequestEnvelope(
   return decodeProtocolEnvelope(value, decodeReadLogRequest);
 }
 
+export function decodeEntryQueryRequest(value: unknown): EntryQueryRequest {
+  const input = object(value);
+  exact(input, ['entry_id'], ['entry_id']);
+  const entryId = boundedString(input.entry_id, 'entry_id', 36);
+  if (/^[0-9a-f]{8}$/i.test(entryId)) return { entry_id: entryId.toLowerCase() };
+  return { entry_id: decodeUuid(entryId, ['entry_id']) };
+}
+
+export function decodeEntryQueryRequestEnvelope(
+  value: unknown,
+): ProtocolEnvelope<EntryQueryRequest> {
+  return decodeProtocolEnvelope(value, decodeEntryQueryRequest);
+}
+
+export function decodeEntryQueryResult(value: unknown): EntryQueryResult {
+  const input = object(value);
+  exact(input, ['entry'], ['entry']);
+  return { entry: decodeEnrichedStreamEntry(input.entry) };
+}
+
+export function decodeEntryQueryResultEnvelope(
+  value: unknown,
+): ProtocolEnvelope<EntryQueryResult> {
+  return decodeProtocolEnvelope(value, decodeEntryQueryResult);
+}
+
+export function decodeAckStatusRequest(value: unknown): AckStatusRequest {
+  const input = object(value);
+  exact(input, ['entry_id'], ['entry_id']);
+  return { entry_id: decodeUuid(input.entry_id, ['entry_id']) };
+}
+
+export function decodeAckStatusRequestEnvelope(
+  value: unknown,
+): ProtocolEnvelope<AckStatusRequest> {
+  return decodeProtocolEnvelope(value, decodeAckStatusRequest);
+}
+
+function decodeAckStatusRecipient(value: unknown): AckStatusRecipient {
+  const input = object(value);
+  exact(
+    input,
+    ['drone_id', 'drone_label', 'drone_role', 'acknowledged_at'],
+    ['drone_id', 'drone_label', 'drone_role', 'acknowledged_at'],
+  );
+  return {
+    drone_id: decodeUuid(input.drone_id, ['drone_id']),
+    drone_label: nullableString(input.drone_label, 'drone_label', 120),
+    drone_role: nullableString(input.drone_role, 'drone_role', 120),
+    acknowledged_at: input.acknowledged_at === null
+      ? null
+      : decodeCanonicalTimestamp(input.acknowledged_at, ['acknowledged_at']),
+  };
+}
+
+function decodeAckStatusClaim(value: unknown): AckStatusClaim {
+  const input = object(value);
+  exact(
+    input,
+    ['drone_id', 'drone_label', 'drone_role', 'claimed_at'],
+    ['drone_id', 'drone_label', 'drone_role', 'claimed_at'],
+  );
+  return {
+    drone_id: decodeUuid(input.drone_id, ['drone_id']),
+    drone_label: nullableString(input.drone_label, 'drone_label', 120),
+    drone_role: nullableString(input.drone_role, 'drone_role', 120),
+    claimed_at: decodeCanonicalTimestamp(input.claimed_at, ['claimed_at']),
+  };
+}
+
+export function decodeAckStatusResult(value: unknown): AckStatusResult {
+  const input = object(value);
+  exact(
+    input,
+    ['entry_id', 'visibility', 'recipients', 'claims'],
+    ['entry_id', 'visibility', 'recipients', 'claims'],
+  );
+  if (input.visibility !== 'broadcast' && input.visibility !== 'direct') {
+    throw new ProtocolContractError('Invalid acknowledgement-status visibility.');
+  }
+  if (!Array.isArray(input.recipients) || input.recipients.length > 500) {
+    throw new ProtocolContractError('Invalid acknowledgement-status recipients.');
+  }
+  if (!Array.isArray(input.claims) || input.claims.length > 500) {
+    throw new ProtocolContractError('Invalid acknowledgement-status claims.');
+  }
+  return {
+    entry_id: decodeUuid(input.entry_id, ['entry_id']),
+    visibility: input.visibility,
+    recipients: input.recipients.map(decodeAckStatusRecipient),
+    claims: input.claims.map(decodeAckStatusClaim),
+  };
+}
+
+export function decodeAckStatusResultEnvelope(
+  value: unknown,
+): ProtocolEnvelope<AckStatusResult> {
+  return decodeProtocolEnvelope(value, decodeAckStatusResult);
+}
+
 function decodeClaimRecord(value: unknown): ClaimRecord {
   const input = object(value);
   exact(
@@ -345,22 +479,17 @@ function decodeRoutingEcho(value: unknown): RoutingEcho {
   const input = object(value);
   exact(
     input,
-    ['class', 'recipients', 'fellOpen', 'message'],
-    ['class', 'recipients', 'fellOpen', 'message'],
+    ['class', 'recipients'],
+    ['class', 'recipients'],
   );
   if (!Array.isArray(input.recipients) || input.recipients.length > 100) {
     throw new ProtocolContractError('Invalid routing recipient list.');
   }
-  if (typeof input.fellOpen !== 'boolean') {
-    throw new ProtocolContractError('Invalid routing fell-open flag.');
-  }
   return {
     class: nullableString(input.class, 'routing.class', 64),
     recipients: input.recipients.map((recipient) =>
       boundedString(recipient, 'routing.recipients', 120)
     ),
-    fellOpen: input.fellOpen,
-    message: nullableString(input.message, 'routing.message', 512),
   };
 }
 

package/src/protocol/errors.ts

@@ -15,10 +15,10 @@ export enum ErrorCode {
   REPOSITORY_ALREADY_ASSOCIATED = 'REPOSITORY_ALREADY_ASSOCIATED',
   CUBE_ALREADY_ASSOCIATED = 'CUBE_ALREADY_ASSOCIATED',
   POST_ID_CONFLICT = 'POST_ID_CONFLICT',
+  LOG_ENTRY_PREFIX_AMBIGUOUS = 'LOG_ENTRY_PREFIX_AMBIGUOUS',
   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',

package/src/protocol/types.ts

@@ -168,17 +168,13 @@ export interface ReadLogResponse {
 export interface RoutingEcho {
   class: string | null;
   recipients: string[];
-  fellOpen: boolean;
-  message: string | null;
 }
 
 export interface AppendLogRequest {
   post_id: string;
   message: string;
-  visibility?: LogVisibility;
-  recipientDroneIds?: string[];
+  to: 'broadcast' | string[];
   class?: string;
-  to?: string[];
   documents?: string[];
 }
 

package/src/protocol/version.ts

@@ -1,4 +1,4 @@
-/** Current Borg coordination protocol generation. Clean-slate v10. */
-export const PROTOCOL_VERSION = '10' as const;
+/** Current Borg coordination protocol generation. Clean-slate v12. */
+export const PROTOCOL_VERSION = '12' as const;
 
 export type ProtocolVersion = typeof PROTOCOL_VERSION;