borgmcp-shared 0.13.1 → 0.14.0

package/src/conformance/adapter.ts

@@ -6,6 +6,7 @@ import {
   decodeCreateCubeResponseEnvelope,
   decodeDeleteCubeResponseEnvelope,
   decodeAppendLogResultEnvelope,
+  decodeAckStatusResultEnvelope,
   decodeDecisionResultEnvelope,
   decodeDecisionsResultEnvelope,
   decodeEnrollmentExchangeResponseEnvelope,
@@ -119,6 +120,8 @@ export interface ConformanceCubeManagementState {
 export interface ConformanceAuthorityState {
   enrolled_clients: number;
   enrollment_claims: number;
+  activity_acknowledgements: number;
+  activity_claims: number;
   cubes: number;
   roles: number;
   grants: number;
@@ -304,6 +307,11 @@ export interface ConformanceOperations {
     cube: ConformanceCube,
     request: unknown,
   ): Promise<ConformanceHttpResponse>;
+  ackStatus(
+    credential: string,
+    cube: ConformanceCube,
+    request: unknown,
+  ): Promise<ConformanceHttpResponse>;
   updateCube(
     credential: string,
     cube: ConformanceCube,
@@ -383,6 +391,7 @@ export const ADAPTER_CONFORMANCE_FIXTURES = [
   { id: 'sse.replay-live-transition', area: 'sse' },
   { id: 'cursor.explicit-expiry', area: 'cursor' },
   { id: 'acks.idempotent', area: 'acks' },
+  { id: 'acks.status-query', area: 'acks' },
   { id: 'claims.durable-noncursor', area: 'claims' },
   { id: 'decisions.topic-supersession', area: 'decisions' },
   { id: 'security.drone-management-authorization', area: 'security' },
@@ -1994,6 +2003,136 @@ export async function runAdapterConformance(
     return { first_status: 204, repeated_status: 204, bodyless: true };
   });
 
+  await record('acks.status-query', async () => {
+    const cube = await environment.admin.createCube('ack-status-cube');
+    await environment.admin.grantCube(principalA, cube);
+    const role = await environment.admin.createRole(cube, {
+      roleClass: 'worker',
+      isHumanSeat: false,
+      name: 'Ack Status Worker',
+    });
+    const acknowledgedRecipient = await environment.admin.createDrone(principalA, cube, role);
+    const claimingRecipient = await environment.admin.createDrone(principalA, cube, role);
+    const acknowledgedCredential = await environment.admin.issueManagedDroneSession(acknowledgedRecipient);
+    const claimingCredential = await environment.admin.issueManagedDroneSession(claimingRecipient);
+    const append = await environment.operations.append(
+      credentialA,
+      cube,
+      createProtocolEnvelope('ack-status-append', {
+        post_id: '00000000-0000-4000-8000-000000000310',
+        message: 'START NOW acknowledgement status fixture',
+        visibility: 'direct',
+        recipientDroneIds: [acknowledgedRecipient.id, claimingRecipient.id],
+      }),
+    );
+    expectStatus(append, 201, 'Acknowledgement-status fixture append');
+    const entry = decodeAppendLogResultEnvelope(append.body).payload.entry;
+
+    const beforeMissing = await environment.admin.observeAuthorityState();
+    const missingResponse = await environment.operations.ackStatus(
+      credentialA,
+      cube,
+      createProtocolEnvelope('ack-status-missing', { entry_id: entry.id }),
+    );
+    expectStatus(missingResponse, 200, 'Missing acknowledgement status');
+    const missing = decodeAckStatusResultEnvelope(missingResponse.body).payload;
+    invariant(
+      missing.visibility === 'direct' &&
+        missing.recipients.length === 2 &&
+        missing.recipients.every((recipient) => recipient.acknowledged_at === null) &&
+        missing.claims.length === 0,
+      'Missing acknowledgement was not represented as nullable per-recipient state.',
+    );
+    assertStateDelta(
+      beforeMissing,
+      await environment.admin.observeAuthorityState(),
+      {},
+      'Missing acknowledgement status query',
+    );
+
+    expectStatus(
+      await environment.operations.ack(
+        acknowledgedCredential,
+        cube,
+        createProtocolEnvelope('ack-status-ack', { entry_id: entry.id, kind: 'ack' }),
+      ),
+      204,
+      'Acknowledgement-status acknowledgement',
+    );
+    expectStatus(
+      await environment.operations.ack(
+        claimingCredential,
+        cube,
+        createProtocolEnvelope('ack-status-claim', { entry_id: entry.id, kind: 'claim' }),
+      ),
+      204,
+      'Acknowledgement-status claim',
+    );
+    const beforeDistinct = await environment.admin.observeAuthorityState();
+    const distinctResponse = await environment.operations.ackStatus(
+      credentialA,
+      cube,
+      createProtocolEnvelope('ack-status-distinct', { entry_id: entry.id }),
+    );
+    expectStatus(distinctResponse, 200, 'Distinct acknowledgement and claim status');
+    const distinct = decodeAckStatusResultEnvelope(distinctResponse.body).payload;
+    const acknowledged = distinct.recipients.filter((recipient) => recipient.acknowledged_at !== null);
+    invariant(
+      acknowledged.length === 1 &&
+        acknowledged[0].drone_id === acknowledgedRecipient.id &&
+        distinct.claims.length === 1 &&
+        distinct.claims[0].drone_id === claimingRecipient.id &&
+        distinct.recipients.find((recipient) => recipient.drone_id === claimingRecipient.id)?.acknowledged_at === null,
+      'Acknowledgement status conflated acknowledgement and claim records.',
+    );
+    assertStateDelta(
+      beforeDistinct,
+      await environment.admin.observeAuthorityState(),
+      {},
+      'Distinct acknowledgement and claim status query',
+    );
+
+    const unreadResponse = await environment.operations.read(
+      credentialA,
+      cube,
+      createProtocolEnvelope('ack-status-unread', { cursor: null, limit: 10 }),
+    );
+    expectStatus(unreadResponse, 200, 'Post-query unread read');
+    const unread = decodeReadLogResultEnvelope(unreadResponse.body).payload;
+    invariant(
+      unread.entries.length === 1 && unread.entries[0].id === entry.id,
+      'Acknowledgement-status query advanced unread delivery state.',
+    );
+
+    const beforeUnknown = await environment.admin.observeAuthorityState();
+    expectError(
+      await environment.operations.ackStatus(
+        credentialA,
+        cube,
+        createProtocolEnvelope('ack-status-unknown', {
+          entry_id: '00000000-0000-4000-8000-000000000311',
+        }),
+      ),
+      404,
+      ErrorCode.NOT_FOUND,
+      'Unknown acknowledgement-status entry',
+    );
+    assertStateDelta(
+      beforeUnknown,
+      await environment.admin.observeAuthorityState(),
+      {},
+      'Unknown acknowledgement status query',
+    );
+    return {
+      missing_acknowledgement: null,
+      acknowledgements: 1,
+      claims: 1,
+      distinct: true,
+      unread_entry_available: true,
+      unknown_entry_code: ErrorCode.NOT_FOUND,
+    };
+  });
+
   await record('claims.durable-noncursor', async () => {
     invariant(entries[1] && liveCursor, 'Log fixtures did not produce claim state.');
     const claim = await environment.operations.ack(

package/src/conformance/index.ts

@@ -1012,6 +1012,40 @@ 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' },
+  },
+];
+
 /** 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 = '0.14.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 v11. 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

@@ -16,6 +16,7 @@ import type {
   AppendLogResponse,
   Decision,
   EnrichedStreamEntry,
+  LogVisibility,
   RoutingEcho,
 } from './types.js';
 import { isLabelLine, parseRoleSections } from '../role-section.js';
@@ -46,6 +47,31 @@ export interface ReadLogResult {
   claims: ClaimRecord[];
 }
 
+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 +335,80 @@ export function decodeReadLogRequestEnvelope(
   return decodeProtocolEnvelope(value, decodeReadLogRequest);
 }
 
+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(

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 v11. */
+export const PROTOCOL_VERSION = '11' as const;
 
 export type ProtocolVersion = typeof PROTOCOL_VERSION;

package/src/templates.ts

@@ -308,6 +308,7 @@ Scope contract:
 Activation:
 - Order named drones to start exact authorized work with START NOW, RESUME NOW, REVIEW NOW, or HOLD; name the exact item and first concrete action.
 - ACK and claim are receipt only; neither means work has started or a review is complete.
+- When receipt is uncertain, use \`borg_ack-status\` for the routed entry; it reports acknowledgements and claims without advancing unread cursors.
 - Verify activation and progress against the concrete milestones from the dispatch and acceptance evidence.
 - When a milestone is missing and status is uncertain, follow the ownership and liveness discipline. Do not interrupt slow local work merely to satisfy a reporting cadence.
 - Require BLOCKED when safe work stops, naming the missing input while independent work continues.