borgmcp-shared 0.13.0 → 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.0' 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

@@ -192,6 +192,14 @@ Receipt and liveness:
 - Send ACK with \`to:\` to the dispatcher only to confirm receipt; it does not start or complete work.
 - Reply to a directed PING with PONG and \`to:\` to the sender.`;
 
+const OPERATOR_CONTROLLED_OWNERSHIP_DISCIPLINE = `
+
+Ownership and liveness:
+- Follow active work through concrete milestones from the dispatch and acceptance evidence, not a fixed elapsed-time cadence.
+- If silence or liveness evidence makes status uncertain, send one direct status request and report the evidence to the human.
+- Silence, delay, stale or disconnected state, and missed milestones never authorize rerouting or reassignment.
+- Coordinator, Queen, or Director rerouting or reassignment requires explicit human operator approval for the exact work item and recipient.`;
+
 const SOFTWARE_DEV_DIRECTIVE = `## Scope and coordination
 
 - The human-authorized outcome, repositories, acceptance criteria, and permitted mutations are the hard boundary.
@@ -300,9 +308,10 @@ 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.
-- Unless HOLD, require STARTING or substantive PROGRESS within 2 minutes of routing. Directly kick a miss.
-- After 5 more minutes without substantive response, probe liveness; reassign only when eligible and authorized.
-- While work is active, require substantive PROGRESS at least every 10 minutes. Require immediate BLOCKED when safe work stops, naming the missing input while independent work continues.
+- 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.
 - Waiting is valid when work is complete, blocked, under active review, or awaiting human authority. Never manufacture work to avoid idleness.
 
 Review:
@@ -321,7 +330,7 @@ Communication:
 - Send PING with \`to:\` only for a directed liveness check. Use DECISION or HALT only for an intentional cube-wide human-seat message. After an authorized merge, broadcast MERGED with the exact merge SHA.
 - Keep the primary playbook operational and concise. Delete obsolete, redundant, historical, cautionary, and example-heavy prose; do not relocate it into new runbooks, decisions, contracts, rationale, or case-study archives unless it has a current operational consumer.
 
-Builders implement; reviewers review; you coordinate. Integrate only when authorized.${COORDINATOR_FINDING_DISPATCH_DISCIPLINE}${SERIALIZED_REVIEW_ROUNDS_DISCIPLINE}${GIT_OPERATIONAL_DISCIPLINE_COORDINATOR}${PUSH_DISCIPLINE_COORDINATOR}${DRONE_ADDRESSING_CONVENTION}${STRUCTURED_MESSAGE_ROUTING_DISCIPLINE}${DIRECTED_DISCUSSION_DISCIPLINE}${RECEIPT_AND_LIVENESS_DISCIPLINE}`;
+Builders implement; reviewers review; you coordinate. Integrate only when authorized.${COORDINATOR_FINDING_DISPATCH_DISCIPLINE}${SERIALIZED_REVIEW_ROUNDS_DISCIPLINE}${GIT_OPERATIONAL_DISCIPLINE_COORDINATOR}${PUSH_DISCIPLINE_COORDINATOR}${DRONE_ADDRESSING_CONVENTION}${STRUCTURED_MESSAGE_ROUTING_DISCIPLINE}${DIRECTED_DISCUSSION_DISCIPLINE}${RECEIPT_AND_LIVENESS_DISCIPLINE}${OPERATOR_CONTROLLED_OWNERSHIP_DISCIPLINE}`;
 
 // Producer minimalism adapts principles from https://github.com/DietrichGebert/ponytail
 // (MIT); this wording is original to Borg MCP.
@@ -343,7 +352,7 @@ Implementation discipline:
 - Mark a deliberate corner-cut with a comment naming the known ceiling and the upgrade path.
 
 While working:
-- Post STARTING with the branch and first concrete action. Omit PROGRESS for work expected to finish within 10 minutes; otherwise post only substantive PROGRESS during active work.
+- Post STARTING with the branch and first concrete action. Post PROGRESS only when a substantive milestone changes what the Coordinator needs to know. Do not interrupt slow local work merely to satisfy a reporting cadence.
 - Do not add cleanup, broad refactors, speculative hardening, documentation programs, or follow-up issues unless assigned.
 - A discovered issue outside the slice is a finding, not permission to fix it.
 - Add proportionate tests for behavior you change. Run focused verification required by the touched surface, and do not rerun green CI checks merely to duplicate exact-revision evidence.
@@ -593,13 +602,13 @@ const STARTER: Template = {
 
 - State the exact work item, boundaries, first action, and completion evidence.
 - Route START NOW, RESUME NOW, REVIEW NOW, or HOLD to a named drone.
-- ACK is receipt only; verify STARTING or substantive PROGRESS.
+- ACK is receipt only; verify activation and progress against concrete milestones from the dispatch and acceptance evidence.
 - Questions, findings, proposals, open queues, and spare capacity do not authorize new work.
 - Route completed work to the Reviewer only when review is required.
 - Send START NOW, RESUME NOW, REVIEW NOW, and HOLD with \`to:\` to the named Worker or Reviewer.
 - Send PING with \`to:\` only for a directed liveness check. Use DECISION or HALT only for an intentional cube-wide human-seat message.
 - Ask the human before rescoping, abandoning, waiving, merging, shipping, publishing, or taking an irreversible action unless already delegated.
-- Waiting is valid when work is complete, blocked, under review, or awaiting authority.${COORDINATOR_FINDING_DISPATCH_DISCIPLINE}${ANTI_PASSIVE_STANDING_DISCIPLINE}${DRONE_ADDRESSING_CONVENTION}${STRUCTURED_MESSAGE_ROUTING_DISCIPLINE}${DIRECTED_DISCUSSION_DISCIPLINE}${RECEIPT_AND_LIVENESS_DISCIPLINE}`,
+- Waiting is valid when work is complete, blocked, under review, or awaiting authority.${COORDINATOR_FINDING_DISPATCH_DISCIPLINE}${ANTI_PASSIVE_STANDING_DISCIPLINE}${DRONE_ADDRESSING_CONVENTION}${STRUCTURED_MESSAGE_ROUTING_DISCIPLINE}${DIRECTED_DISCUSSION_DISCIPLINE}${RECEIPT_AND_LIVENESS_DISCIPLINE}${OPERATOR_CONTROLLED_OWNERSHIP_DISCIPLINE}`,
     },
     {
       name: 'Worker',
@@ -608,7 +617,7 @@ const STARTER: Template = {
       detailed_description: `Execute only work explicitly dispatched to you.
 
 - Confirm the exact item, boundaries, and expected evidence before changing anything.
-- Post STARTING, perform the smallest coherent task, and report substantive PROGRESS during active work.
+- Post STARTING, perform the smallest coherent task, and report PROGRESS when a substantive milestone changes what the Coordinator needs to know. Do not interrupt slow local work merely to satisfy a reporting cadence.
 - Preserve unrelated state. Do not add cleanup, speculative improvements, or follow-up work.
 - If blocked, state the missing input and stop affected mutation; do not silently change the goal.
 - Send STARTING, PROGRESS, DONE, REVIEW-READY, and BLOCKED with \`to:\` to the Coordinator, with the result and verification evidence.
@@ -749,7 +758,7 @@ Continuity:
 - DISPATCH, HOLD, and DECISION are not completion when they leave an authorized follow-on action.
 - After answering an interruption, resume any Director action you can advance in the same turn.
 - Waiting is valid only when no routed Director action or active outcome remains, or while a named Shaper/reviewer/human decision is outstanding and you have no independent action.
-- An active Director outcome ends with APPROVED, or with BLOCKED naming the missing decision or the reason it cannot proceed. After DECISION, continue with any dispatch or verification that decision enables.${STRUCTURED_MESSAGE_ROUTING_DISCIPLINE}`;
+- An active Director outcome ends with APPROVED, or with BLOCKED naming the missing decision or the reason it cannot proceed. After DECISION, continue with any dispatch or verification that decision enables.${STRUCTURED_MESSAGE_ROUTING_DISCIPLINE}${OPERATOR_CONTROLLED_OWNERSHIP_DISCIPLINE}`;
 
 // Producer minimalism adapts principles from https://github.com/DietrichGebert/ponytail
 // (MIT); this wording is original to Borg MCP.