borgmcp-shared 0.10.1 → 0.12.0

package/src/conformance/index.ts

@@ -11,7 +11,7 @@ import {
   encodeInvitationArtifact,
   type InvitationArtifact,
 } from '../protocol/contract.js';
-import type { EnrichedStreamEntry } from '../protocol/types.js';
+import type { AppendLogRequest, EnrichedStreamEntry } from '../protocol/types.js';
 import { ROLE_IN_USE_DELETE_MESSAGE } from '../protocol/coordination.js';
 
 export * from './adapter.js';
@@ -99,17 +99,53 @@ export interface AppendLogResultConformanceVector {
   accepts: boolean;
 }
 
+export interface AppendLogRequestConformanceVector {
+  name: string;
+  request: unknown;
+  accepts: boolean;
+}
+
+export interface AppendLogIdempotencyConformanceVector {
+  name: string;
+  actor: 'same' | 'different';
+  mutation: 'none' | 'message' | 'visibility' | 'recipient_set' | 'resolved_class_routing';
+  expected: 'deduplicated' | 'POST_ID_CONFLICT' | 'created';
+}
+
+/** Author-scoped post identity and exact resolved-routing 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 recipient-set collision', actor: 'same', mutation: 'recipient_set', expected: 'POST_ID_CONFLICT' },
+  { name: 'rejects a same-author resolved class-routing collision', actor: 'same', mutation: 'resolved_class_routing', expected: 'POST_ID_CONFLICT' },
+  { 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',
+} 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 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 },
+];
+
 /** Runtime response vectors keep the append-log decoder aligned with its public type. */
 export const APPEND_LOG_RESULT_CONFORMANCE: readonly AppendLogResultConformanceVector[] = [
   {
     name: 'accepts a response without optional routing metadata',
-    response: { entry: APPEND_LOG_ENTRY },
+    response: { entry: APPEND_LOG_ENTRY, deduplicated: false },
     accepts: true,
   },
   {
     name: 'accepts exact routing metadata and unreachable recipients',
     response: {
       entry: APPEND_LOG_ENTRY,
+      deduplicated: false,
       routing: APPEND_LOG_ROUTING,
       unreachableRecipients: [{ id: 'missing-reviewer', label: 'Missing Reviewer' }],
     },
@@ -117,73 +153,84 @@ export const APPEND_LOG_RESULT_CONFORMANCE: readonly AppendLogResultConformanceV
   },
   {
     name: 'accepts a null routing echo and an empty unreachable-recipient list',
-    response: { entry: APPEND_LOG_ENTRY, routing: null, unreachableRecipients: [] },
+    response: { entry: APPEND_LOG_ENTRY, deduplicated: true, routing: null, unreachableRecipients: [] },
     accepts: true,
   },
+  {
+    name: 'rejects an omitted deduplication result',
+    response: { entry: APPEND_LOG_ENTRY },
+    accepts: false,
+  },
+  {
+    name: 'rejects a non-boolean deduplication result',
+    response: { entry: APPEND_LOG_ENTRY, deduplicated: 'false' },
+    accepts: false,
+  },
   {
     name: 'rejects unknown top-level response fields',
-    response: { entry: APPEND_LOG_ENTRY, routing: APPEND_LOG_ROUTING, extra: true },
+    response: { entry: APPEND_LOG_ENTRY, deduplicated: false, routing: APPEND_LOG_ROUTING, extra: true },
     accepts: false,
   },
   {
     name: 'rejects a non-object routing echo',
-    response: { entry: APPEND_LOG_ENTRY, routing: 'review' },
+    response: { entry: APPEND_LOG_ENTRY, deduplicated: false, routing: 'review' },
     accepts: false,
   },
   {
     name: 'rejects missing routing fields',
-    response: { entry: APPEND_LOG_ENTRY, routing: { class: 'review' } },
+    response: { entry: APPEND_LOG_ENTRY, deduplicated: false, routing: { class: 'review' } },
     accepts: false,
   },
   {
     name: 'rejects unknown routing fields',
-    response: { entry: APPEND_LOG_ENTRY, routing: { ...APPEND_LOG_ROUTING, extra: true } },
+    response: { entry: APPEND_LOG_ENTRY, deduplicated: false, routing: { ...APPEND_LOG_ROUTING, extra: true } },
     accepts: false,
   },
   {
     name: 'rejects an invalid routing class',
-    response: { entry: APPEND_LOG_ENTRY, routing: { ...APPEND_LOG_ROUTING, class: 7 } },
+    response: { entry: APPEND_LOG_ENTRY, deduplicated: false, routing: { ...APPEND_LOG_ROUTING, class: 7 } },
     accepts: false,
   },
   {
     name: 'rejects an invalid routing recipient collection',
-    response: { entry: APPEND_LOG_ENTRY, routing: { ...APPEND_LOG_ROUTING, recipients: 'reviewer' } },
+    response: { entry: APPEND_LOG_ENTRY, deduplicated: false, routing: { ...APPEND_LOG_ROUTING, recipients: 'reviewer' } },
     accepts: false,
   },
   {
     name: 'rejects invalid routing recipient members',
-    response: { entry: APPEND_LOG_ENTRY, routing: { ...APPEND_LOG_ROUTING, recipients: [7] } },
+    response: { entry: APPEND_LOG_ENTRY, deduplicated: false, routing: { ...APPEND_LOG_ROUTING, recipients: [7] } },
     accepts: false,
   },
   {
     name: 'rejects an invalid routing fell-open flag',
-    response: { entry: APPEND_LOG_ENTRY, routing: { ...APPEND_LOG_ROUTING, fellOpen: 'false' } },
+    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, routing: { ...APPEND_LOG_ROUTING, message: 7 } },
+    response: { entry: APPEND_LOG_ENTRY, deduplicated: false, routing: { ...APPEND_LOG_ROUTING, message: 7 } },
     accepts: false,
   },
   {
     name: 'rejects a non-array unreachable-recipient list',
-    response: { entry: APPEND_LOG_ENTRY, unreachableRecipients: {} },
+    response: { entry: APPEND_LOG_ENTRY, deduplicated: false, unreachableRecipients: {} },
     accepts: false,
   },
   {
     name: 'rejects a non-object unreachable recipient',
-    response: { entry: APPEND_LOG_ENTRY, unreachableRecipients: ['missing-reviewer'] },
+    response: { entry: APPEND_LOG_ENTRY, deduplicated: false, unreachableRecipients: ['missing-reviewer'] },
     accepts: false,
   },
   {
     name: 'rejects missing unreachable-recipient fields',
-    response: { entry: APPEND_LOG_ENTRY, unreachableRecipients: [{ id: 'missing-reviewer' }] },
+    response: { entry: APPEND_LOG_ENTRY, deduplicated: false, unreachableRecipients: [{ id: 'missing-reviewer' }] },
     accepts: false,
   },
   {
     name: 'rejects unknown unreachable-recipient fields',
     response: {
       entry: APPEND_LOG_ENTRY,
+      deduplicated: false,
       unreachableRecipients: [{ id: 'missing-reviewer', label: 'Missing Reviewer', extra: true }],
     },
     accepts: false,
@@ -192,6 +239,7 @@ export const APPEND_LOG_RESULT_CONFORMANCE: readonly AppendLogResultConformanceV
     name: 'rejects an invalid unreachable-recipient id',
     response: {
       entry: APPEND_LOG_ENTRY,
+      deduplicated: false,
       unreachableRecipients: [{ id: 7, label: 'Missing Reviewer' }],
     },
     accepts: false,
@@ -200,6 +248,7 @@ export const APPEND_LOG_RESULT_CONFORMANCE: readonly AppendLogResultConformanceV
     name: 'rejects an invalid unreachable-recipient label',
     response: {
       entry: APPEND_LOG_ENTRY,
+      deduplicated: false,
       unreachableRecipients: [{ id: 'missing-reviewer', label: null }],
     },
     accepts: false,
@@ -750,11 +799,48 @@ const ATTACH_RESPONSE = {
     runtime_metadata_reported: false,
   },
   session: { id: '40000000-0000-4000-8000-000000000001' },
+  initial_log_cursor: null,
 } satisfies AttachResponse;
 
 /** Wire vectors for the v3 non-expiring attach-session response. */
 export const ATTACH_SESSION_CONFORMANCE: readonly AttachSessionConformanceVector[] = [
   { name: 'accepts exact non-expiring session id', response: ATTACH_RESPONSE, accepts: true },
+  {
+    name: 'accepts a canonical initial log cursor',
+    response: {
+      ...ATTACH_RESPONSE,
+      initial_log_cursor: {
+        id: '50000000-0000-4000-8000-000000000001',
+        created_at: '2026-07-14T10:00:00.000Z',
+      },
+    },
+    accepts: true,
+  },
+  {
+    name: 'rejects an omitted initial log cursor',
+    response: (({ initial_log_cursor: _, ...response }) => response)(ATTACH_RESPONSE),
+    accepts: false,
+  },
+  {
+    name: 'rejects an invalid initial log cursor UUID',
+    response: {
+      ...ATTACH_RESPONSE,
+      initial_log_cursor: { id: 'not-a-uuid', created_at: '2026-07-14T10:00:00.000Z' },
+    },
+    accepts: false,
+  },
+  {
+    name: 'rejects unknown initial log cursor fields',
+    response: {
+      ...ATTACH_RESPONSE,
+      initial_log_cursor: {
+        id: '50000000-0000-4000-8000-000000000001',
+        created_at: '2026-07-14T10:00:00.000Z',
+        extra: true,
+      },
+    },
+    accepts: false,
+  },
   {
     name: 'rejects retired expires_at field',
     response: {

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.10.1' as const;
+export const SHARED_PACKAGE_VERSION = '0.12.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. */
@@ -580,7 +580,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 v8. The peer presents a different version. Update `borgmcp-server` and `borgmcp` to matching releases — server first, then client.',
+      'This client requires protocol v9. The peer presents a different version. Update `borgmcp-server` and `borgmcp` to matching releases — server first, then client.',
       ErrorCode.UNSUPPORTED_PROTOCOL_VERSION,
       ['protocol_version'],
     );
@@ -997,10 +997,11 @@ export function decodeAppendLogRequest(value: unknown): import('./types.js').App
   const input = record(value);
   exactKeys(
     input,
-    ['message', 'visibility', 'recipientDroneIds', 'class', 'to'],
-    ['message'],
+    ['post_id', 'message', 'visibility', 'recipientDroneIds', 'class', 'to'],
+    ['post_id', 'message'],
   );
   const output: import('./types.js').AppendLogRequest = {
+    post_id: decodeUuid(input.post_id, ['post_id']),
     message: boundedString(input.message, 1, 10_240, ['message']),
   };
   if (input.visibility !== undefined) {
@@ -1259,6 +1260,7 @@ export interface AttachResponse {
   role: AttachRole;
   drone: AttachDrone;
   session: AttachSession;
+  initial_log_cursor: LogCursor | null;
 }
 
 function decodeAttachCube(value: unknown, path: readonly (string | number)[]): AttachCube {
@@ -1393,12 +1395,13 @@ export function decodeAttachRequestEnvelope(
  */
 export function decodeAttachResponse(value: unknown): AttachResponse {
   const input = record(value);
-  exactKeys(input, ['result', 'cube', 'role', 'drone', 'session'], [
+  exactKeys(input, ['result', 'cube', 'role', 'drone', 'session', 'initial_log_cursor'], [
     'result',
     'cube',
     'role',
     'drone',
     'session',
+    'initial_log_cursor',
   ]);
   if (input.result !== 'created' && input.result !== 'reused') {
     fail('Expected result "created" or "reused".', ['result']);
@@ -1409,6 +1412,9 @@ export function decodeAttachResponse(value: unknown): AttachResponse {
     role: decodeAttachRole(input.role, ['role']),
     drone: decodeAttachDrone(input.drone, ['drone']),
     session: decodeAttachSession(input.session, ['session']),
+    initial_log_cursor: input.initial_log_cursor === null
+      ? null
+      : decodeLogCursor(input.initial_log_cursor, ['initial_log_cursor']),
   };
 }
 

package/src/protocol/coordination.ts

@@ -376,8 +376,14 @@ function decodeUnreachableRecipient(
 
 export function decodeAppendLogResult(value: unknown): AppendLogResult {
   const input = object(value);
-  exact(input, ['entry', 'routing', 'unreachableRecipients'], ['entry']);
-  const output: AppendLogResult = { entry: decodeEnrichedStreamEntry(input.entry) };
+  exact(input, ['entry', 'deduplicated', 'routing', 'unreachableRecipients'], ['entry', 'deduplicated']);
+  if (typeof input.deduplicated !== 'boolean') {
+    throw new ProtocolContractError('Invalid append-log deduplicated flag.');
+  }
+  const output: AppendLogResult = {
+    entry: decodeEnrichedStreamEntry(input.entry),
+    deduplicated: input.deduplicated,
+  };
   if (input.routing !== undefined) {
     output.routing = input.routing === null ? null : decodeRoutingEcho(input.routing);
   }

package/src/protocol/errors.ts

@@ -14,6 +14,7 @@ export enum ErrorCode {
   NOT_FOUND = 'NOT_FOUND',
   REPOSITORY_ALREADY_ASSOCIATED = 'REPOSITORY_ALREADY_ASSOCIATED',
   CUBE_ALREADY_ASSOCIATED = 'CUBE_ALREADY_ASSOCIATED',
+  POST_ID_CONFLICT = 'POST_ID_CONFLICT',
   ROLE_IN_USE = 'ROLE_IN_USE',
   DEFAULT_ROLE_REQUIRED = 'DEFAULT_ROLE_REQUIRED',
   ROLE_REQUIRED = 'ROLE_REQUIRED',

package/src/protocol/types.ts

@@ -171,6 +171,7 @@ export interface RoutingEcho {
 }
 
 export interface AppendLogRequest {
+  post_id: string;
   message: string;
   visibility?: LogVisibility;
   recipientDroneIds?: string[];
@@ -180,6 +181,7 @@ export interface AppendLogRequest {
 
 export interface AppendLogResponse {
   entry: ActivityLogEntry;
+  deduplicated: boolean;
   routing?: RoutingEcho | null;
   unreachableRecipients?: Array<{ id: string; label: string }>;
 }

package/src/protocol/version.ts

@@ -1,4 +1,4 @@
-/** Current Borg coordination protocol generation. Clean-slate v8. */
-export const PROTOCOL_VERSION = '8' as const;
+/** Current Borg coordination protocol generation. Clean-slate v9. */
+export const PROTOCOL_VERSION = '9' as const;
 
 export type ProtocolVersion = typeof PROTOCOL_VERSION;