borgmcp-shared 0.12.2 → 0.13.0

package/src/protocol/contract.ts

@@ -13,11 +13,15 @@ import type {
 } from './types.js';
 
 export const SHARED_PACKAGE_NAME = 'borgmcp-shared' as const;
-export const SHARED_PACKAGE_VERSION = '0.12.2' as const;
+export const SHARED_PACKAGE_VERSION = '0.13.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. */
 export const ROLE_TEXT_MAX_BYTES = 51_200 as const;
+export const DEFAULT_LOG_ENTRY_ADVISORY_BYTES = 1024 as const;
+export const DEFAULT_MAX_LOG_ENTRY_BYTES = 4096 as const;
+export const LOG_ENTRY_ADVISORY_ENV = 'BORG_SERVER_LOG_ENTRY_ADVISORY_BYTES' as const;
+export const MAX_LOG_ENTRY_ENV = 'BORG_SERVER_MAX_LOG_ENTRY_BYTES' as const;
 
 export const HEALTH_PATH = '/healthz' as const;
 export const PROTOCOL_INFO_PATH = '/api/protocol' as const;
@@ -30,12 +34,18 @@ export const REPOSITORY_CUBE_RESOLVE_PATH = '/api/repository-cubes/resolve' as c
 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;
+export const DOCUMENTS_PATH = '/api/cubes/:cubeId/documents' as const;
+export const DOCUMENT_PATH = '/api/cubes/:cubeId/documents/:documentId' as const;
 
 export const PROTOCOL_HTTP_CONTRACT = {
   health: { method: 'GET', path: HEALTH_PATH, authenticated: false, success_status: 204, bodyless: true },
   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 },
+  document_put: { method: 'PUT', path: DOCUMENTS_PATH, authenticated: true, success_status: 201, mutation: true },
+  document_list: { method: 'GET', path: DOCUMENTS_PATH, authenticated: true, success_status: 200, mutation: false },
+  document_get: { method: 'GET', path: DOCUMENT_PATH, authenticated: true, success_status: 200, mutation: false },
+  document_remove: { method: 'DELETE', path: DOCUMENT_PATH, authenticated: true, success_status: 200, mutation: true },
   cube_delete: {
     method: 'DELETE',
     path: CUBE_PATH,
@@ -104,7 +114,7 @@ export const PROTOCOL_HTTP_CONTRACT = {
 
 export const PROTOCOL_LIMIT_CEILINGS = {
   max_request_bytes: 10 * 1024 * 1024,
-  max_log_message_bytes: 1024 * 1024,
+  max_log_message_bytes: 65_536,
   max_read_page_size: 500,
   max_replay_page_size: 1000,
 } as const;
@@ -580,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 v9. The peer presents a different version. Update `borgmcp-server` and `borgmcp` to matching releases — server first, then client.',
+      'This client requires protocol v10. 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,12 +1007,12 @@ export function decodeAppendLogRequest(value: unknown): import('./types.js').App
   const input = record(value);
   exactKeys(
     input,
-    ['post_id', 'message', 'visibility', 'recipientDroneIds', 'class', 'to'],
+    ['post_id', 'message', 'visibility', 'recipientDroneIds', 'class', 'to', 'documents'],
     ['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']),
+    message: boundedString(input.message, 1, PROTOCOL_LIMIT_CEILINGS.max_log_message_bytes, ['message']),
   };
   if (input.visibility !== undefined) {
     if (input.visibility !== 'broadcast' && input.visibility !== 'direct') {
@@ -1024,6 +1034,10 @@ export function decodeAppendLogRequest(value: unknown): import('./types.js').App
   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]));
+  }
   return output;
 }
 

package/src/protocol/coordination.ts

@@ -1,4 +1,5 @@
 import {
+  PROTOCOL_LIMIT_CEILINGS,
   ProtocolContractError,
   compareLogCursor,
   decodeCanonicalTimestamp,
@@ -376,7 +377,7 @@ function decodeUnreachableRecipient(
 
 export function decodeAppendLogResult(value: unknown): AppendLogResult {
   const input = object(value);
-  exact(input, ['entry', 'deduplicated', 'routing', 'unreachableRecipients'], ['entry', 'deduplicated']);
+  exact(input, ['entry', 'deduplicated', 'routing', 'unreachableRecipients', 'advisory'], ['entry', 'deduplicated']);
   if (typeof input.deduplicated !== 'boolean') {
     throw new ProtocolContractError('Invalid append-log deduplicated flag.');
   }
@@ -393,6 +394,19 @@ export function decodeAppendLogResult(value: unknown): AppendLogResult {
     }
     output.unreachableRecipients = input.unreachableRecipients.map(decodeUnreachableRecipient);
   }
+  if (input.advisory !== undefined) {
+    const advisory = object(input.advisory);
+    exact(advisory, ['code', 'threshold_bytes'], ['code', 'threshold_bytes']);
+    if (advisory.code !== 'STORE_AS_DOCUMENT') {
+      throw new ProtocolContractError('Invalid append-log document advisory.');
+    }
+    const threshold = positiveInteger(
+      advisory.threshold_bytes,
+      'advisory.threshold_bytes',
+      PROTOCOL_LIMIT_CEILINGS.max_log_message_bytes,
+    );
+    output.advisory = { code: 'STORE_AS_DOCUMENT', threshold_bytes: threshold };
+  }
   return output;
 }
 

package/src/protocol/documents.ts

@@ -0,0 +1,256 @@
+import { ErrorCode } from './errors.js';
+import {
+  ProtocolContractError,
+  decodeCanonicalTimestamp,
+  decodeOpaqueIdentifier,
+  decodeProtocolEnvelope,
+  decodeUuid,
+  utf8ByteLength,
+  type ProtocolEnvelope,
+} from './contract.js';
+
+export const DOCUMENT_CONTENT_TYPES = ['text/markdown', 'text/plain'] as const;
+export const DOCUMENT_DEFAULT_MAX_BYTES = 65_536 as const;
+export const DOCUMENT_DEFAULT_MAX_ACTIVE_BYTES_PER_CUBE = 524_288 as const;
+export const DOCUMENT_MAX_BYTES_ENV = 'BORG_SERVER_MAX_DOCUMENT_BYTES' as const;
+export const DOCUMENT_MAX_ACTIVE_BYTES_PER_CUBE_ENV =
+  'BORG_SERVER_MAX_ACTIVE_DOCUMENT_BYTES_PER_CUBE' as const;
+export type DocumentContentType = (typeof DOCUMENT_CONTENT_TYPES)[number];
+export type DocumentState = 'active' | 'superseded' | 'removed';
+
+export interface DocumentActor {
+  drone_id: string | null;
+  label: string | null;
+  role: string | null;
+}
+
+export interface DocumentCitation {
+  id: string;
+  title: string;
+  size_bytes: number;
+  state: DocumentState;
+}
+
+export interface CubeDocumentMetadata extends DocumentCitation {
+  content_type: DocumentContentType;
+  supersedes: string | null;
+  superseded_by: string | null;
+  author: DocumentActor;
+  created_at: string;
+  removed_by: DocumentActor | null;
+  removed_at: string | null;
+}
+
+export interface CubeDocument extends CubeDocumentMetadata {
+  content: string;
+}
+
+export interface PutDocumentRequest {
+  title: string;
+  content_type: DocumentContentType;
+  content: string;
+  supersedes?: string;
+}
+export interface PutDocumentResult { document: CubeDocument }
+export interface GetDocumentRequest { id: string }
+export interface GetDocumentResult { document: CubeDocument }
+export type ListDocumentsRequest = Record<string, never>;
+export interface ListDocumentsResult { documents: CubeDocumentMetadata[] }
+export interface RemoveDocumentRequest { id: string }
+export interface RemoveDocumentResult { document: CubeDocumentMetadata }
+
+function object(value: unknown): Record<string, unknown> {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+    throw new ProtocolContractError('Expected a document object.');
+  }
+  return value as Record<string, unknown>;
+}
+
+function exact(value: Record<string, unknown>, allowed: readonly string[], required: readonly string[]): void {
+  for (const key of Object.keys(value)) {
+    if (!allowed.includes(key)) throw new ProtocolContractError('Unknown document field.');
+  }
+  for (const key of required) {
+    if (!Object.prototype.hasOwnProperty.call(value, key)) {
+      throw new ProtocolContractError(`Missing document field "${key}".`);
+    }
+  }
+}
+
+function text(value: unknown, field: string, maximumBytes: number, allowEmpty = false): string {
+  if (typeof value !== 'string' || (!allowEmpty && value.length === 0) || utf8ByteLength(value) > maximumBytes) {
+    throw new ProtocolContractError(`Invalid document field "${field}".`);
+  }
+  for (let index = 0; index < value.length; index++) {
+    const code = value.charCodeAt(index);
+    if (code >= 0xd800 && code <= 0xdbff) {
+      const next = value.charCodeAt(index + 1);
+      if (!(next >= 0xdc00 && next <= 0xdfff)) throw new ProtocolContractError(`Invalid UTF-8 document field "${field}".`);
+      index++;
+    } else if (code >= 0xdc00 && code <= 0xdfff) {
+      throw new ProtocolContractError(`Invalid UTF-8 document field "${field}".`);
+    }
+  }
+  return value;
+}
+
+function title(value: unknown): string {
+  const decoded = text(value, 'title', 480);
+  if (Array.from(decoded).length > 120 || decoded !== decoded.trim() || /[\u0000-\u001f\u007f-\u009f]/.test(decoded)) {
+    throw new ProtocolContractError('Invalid document field "title".');
+  }
+  return decoded;
+}
+
+function contentType(value: unknown): DocumentContentType {
+  if (!DOCUMENT_CONTENT_TYPES.includes(value as DocumentContentType)) {
+    throw new ProtocolContractError(
+      'Unsupported document content type.',
+      ErrorCode.DOCUMENT_CONTENT_TYPE_UNSUPPORTED,
+      ['content_type'],
+    );
+  }
+  return value as DocumentContentType;
+}
+
+function count(value: unknown, field: string): number {
+  if (!Number.isSafeInteger(value) || (value as number) < 0 || (value as number) > 10 * 1024 * 1024) {
+    throw new ProtocolContractError(`Invalid document field "${field}".`);
+  }
+  return value as number;
+}
+
+function nullableId(value: unknown, field: string): string | null {
+  return value === null ? null : decodeOpaqueIdentifier(value, [field]);
+}
+
+function nullableText(value: unknown, field: string): string | null {
+  return value === null ? null : text(value, field, 120);
+}
+
+export function decodeDocumentActor(value: unknown): DocumentActor {
+  const input = object(value);
+  exact(input, ['drone_id', 'label', 'role'], ['drone_id', 'label', 'role']);
+  return {
+    drone_id: input.drone_id === null ? null : decodeUuid(input.drone_id, ['drone_id']),
+    label: nullableText(input.label, 'label'),
+    role: nullableText(input.role, 'role'),
+  };
+}
+
+export function decodeDocumentCitation(value: unknown): DocumentCitation {
+  const input = object(value);
+  exact(input, ['id', 'title', 'size_bytes', 'state'], ['id', 'title', 'size_bytes', 'state']);
+  if (!['active', 'superseded', 'removed'].includes(String(input.state))) {
+    throw new ProtocolContractError('Invalid document state.');
+  }
+  return {
+    id: decodeOpaqueIdentifier(input.id, ['id']),
+    title: title(input.title),
+    size_bytes: count(input.size_bytes, 'size_bytes'),
+    state: input.state as DocumentState,
+  };
+}
+
+export function decodeDocumentCitations(value: unknown): DocumentCitation[] {
+  if (!Array.isArray(value) || value.length < 1 || value.length > 100) {
+    throw new ProtocolContractError('Document citations must contain 1-100 entries.');
+  }
+  const citations = value.map(decodeDocumentCitation);
+  if (new Set(citations.map(({ id }) => id)).size !== citations.length) {
+    throw new ProtocolContractError('Document citation ids must be unique.');
+  }
+  return citations;
+}
+
+export function decodeCubeDocumentMetadata(value: unknown): CubeDocumentMetadata {
+  const input = object(value);
+  exact(input, ['id', 'title', 'size_bytes', 'state', 'content_type', 'supersedes', 'superseded_by', 'author', 'created_at', 'removed_by', 'removed_at'], ['id', 'title', 'size_bytes', 'state', 'content_type', 'supersedes', 'superseded_by', 'author', 'created_at', 'removed_by', 'removed_at']);
+  const citation = decodeDocumentCitation({ id: input.id, title: input.title, size_bytes: input.size_bytes, state: input.state });
+  const removed = citation.state === 'removed';
+  const hasRemovedBy = input.removed_by !== null;
+  const hasRemovedAt = input.removed_at !== null;
+  if (hasRemovedBy !== hasRemovedAt || removed !== hasRemovedBy) {
+    throw new ProtocolContractError('Removed document audit fields do not match its state.');
+  }
+  if (citation.state === 'active' && input.superseded_by !== null) {
+    throw new ProtocolContractError('Active document cannot have a superseding revision.');
+  }
+  if (citation.state === 'superseded' && input.superseded_by === null) {
+    throw new ProtocolContractError('Superseded document must identify its next revision.');
+  }
+  return {
+    ...citation,
+    content_type: contentType(input.content_type),
+    supersedes: nullableId(input.supersedes, 'supersedes'),
+    superseded_by: nullableId(input.superseded_by, 'superseded_by'),
+    author: decodeDocumentActor(input.author),
+    created_at: decodeCanonicalTimestamp(input.created_at, ['created_at']),
+    removed_by: input.removed_by === null ? null : decodeDocumentActor(input.removed_by),
+    removed_at: input.removed_at === null ? null : decodeCanonicalTimestamp(input.removed_at, ['removed_at']),
+  };
+}
+
+export function decodeCubeDocument(value: unknown): CubeDocument {
+  const input = object(value);
+  const content = text(input.content, 'content', 10 * 1024 * 1024, true);
+  const { content: _content, ...metadataInput } = input;
+  const metadata = decodeCubeDocumentMetadata(metadataInput);
+  if (metadata.size_bytes !== utf8ByteLength(content)) throw new ProtocolContractError('Document size does not match its UTF-8 content.');
+  return { ...metadata, content };
+}
+
+export function decodePutDocumentRequest(value: unknown): PutDocumentRequest {
+  const input = object(value);
+  exact(input, ['title', 'content_type', 'content', 'supersedes'], ['title', 'content_type', 'content']);
+  const output: PutDocumentRequest = {
+    title: title(input.title),
+    content_type: contentType(input.content_type),
+    content: text(input.content, 'content', 10 * 1024 * 1024, true),
+  };
+  if (input.supersedes !== undefined) output.supersedes = decodeOpaqueIdentifier(input.supersedes, ['supersedes']);
+  return output;
+}
+
+export function decodeGetDocumentRequest(value: unknown): GetDocumentRequest {
+  const input = object(value); exact(input, ['id'], ['id']);
+  return { id: decodeOpaqueIdentifier(input.id, ['id']) };
+}
+export function decodeListDocumentsRequest(value: unknown): ListDocumentsRequest {
+  const input = object(value); exact(input, [], []); return {};
+}
+export const decodeRemoveDocumentRequest = decodeGetDocumentRequest;
+
+function oneDocument<T>(value: unknown, decode: (input: unknown) => T): { document: T } {
+  const input = object(value); exact(input, ['document'], ['document']);
+  return { document: decode(input.document) };
+}
+export const decodePutDocumentResult = (value: unknown): PutDocumentResult => {
+  const result = oneDocument(value, decodeCubeDocument);
+  if (result.document.state !== 'active' || result.document.removed_at !== null || result.document.removed_by !== null) {
+    throw new ProtocolContractError('New document result must be active.');
+  }
+  return result;
+};
+export const decodeGetDocumentResult = (value: unknown): GetDocumentResult => oneDocument(value, decodeCubeDocument);
+export const decodeRemoveDocumentResult = (value: unknown): RemoveDocumentResult => {
+  const result = oneDocument(value, decodeCubeDocumentMetadata);
+  if (result.document.state !== 'removed') throw new ProtocolContractError('Removed document result must be removed.');
+  return result;
+};
+export function decodeListDocumentsResult(value: unknown): ListDocumentsResult {
+  const input = object(value); exact(input, ['documents'], ['documents']);
+  if (!Array.isArray(input.documents) || input.documents.length > 500) throw new ProtocolContractError('Invalid document list.');
+  const documents = input.documents.map(decodeCubeDocumentMetadata);
+  if (documents.some(({ state }) => state === 'removed')) throw new ProtocolContractError('Removed documents must be delisted.');
+  return { documents };
+}
+
+export const decodePutDocumentRequestEnvelope = (value: unknown): ProtocolEnvelope<PutDocumentRequest> => decodeProtocolEnvelope(value, decodePutDocumentRequest);
+export const decodePutDocumentResultEnvelope = (value: unknown): ProtocolEnvelope<PutDocumentResult> => decodeProtocolEnvelope(value, decodePutDocumentResult);
+export const decodeGetDocumentRequestEnvelope = (value: unknown): ProtocolEnvelope<GetDocumentRequest> => decodeProtocolEnvelope(value, decodeGetDocumentRequest);
+export const decodeGetDocumentResultEnvelope = (value: unknown): ProtocolEnvelope<GetDocumentResult> => decodeProtocolEnvelope(value, decodeGetDocumentResult);
+export const decodeListDocumentsRequestEnvelope = (value: unknown): ProtocolEnvelope<ListDocumentsRequest> => decodeProtocolEnvelope(value, decodeListDocumentsRequest);
+export const decodeListDocumentsResultEnvelope = (value: unknown): ProtocolEnvelope<ListDocumentsResult> => decodeProtocolEnvelope(value, decodeListDocumentsResult);
+export const decodeRemoveDocumentRequestEnvelope = (value: unknown): ProtocolEnvelope<RemoveDocumentRequest> => decodeProtocolEnvelope(value, decodeRemoveDocumentRequest);
+export const decodeRemoveDocumentResultEnvelope = (value: unknown): ProtocolEnvelope<RemoveDocumentResult> => decodeProtocolEnvelope(value, decodeRemoveDocumentResult);

package/src/protocol/errors.ts

@@ -22,6 +22,11 @@ export enum ErrorCode {
   ROLE_NOT_FOUND = 'ROLE_NOT_FOUND',
   ROLE_SECTION_NOT_FOUND = 'ROLE_SECTION_NOT_FOUND',
   ROLE_HAS_FROZEN_DRONES = 'ROLE_HAS_FROZEN_DRONES',
+  DOCUMENT_NOT_FOUND = 'DOCUMENT_NOT_FOUND',
+  DOCUMENT_CONTENT_TYPE_UNSUPPORTED = 'DOCUMENT_CONTENT_TYPE_UNSUPPORTED',
+  DOCUMENT_BUDGET_EXCEEDED = 'DOCUMENT_BUDGET_EXCEEDED',
+  DOCUMENT_SUPERSESSION_INVALID = 'DOCUMENT_SUPERSESSION_INVALID',
+  DOCUMENT_REMOVE_DENIED = 'DOCUMENT_REMOVE_DENIED',
   CUBE_DELETED = 'CUBE_DELETED',
   DRONE_EVICTED = 'DRONE_EVICTED',
   DRONE_FROZEN = 'DRONE_FROZEN',

package/src/protocol/index.ts

@@ -3,5 +3,6 @@ export * from './types.js';
 export * from './version.js';
 export * from './contract.js';
 export * from './coordination.js';
+export * from './documents.js';
 export * from './sse.js';
 export type { BroadcastHwm } from '../log-stream-hwm.js';

package/src/protocol/sse.ts

@@ -1,4 +1,5 @@
 import type { EnrichedStreamEntry } from './types.js';
+import { decodeDocumentCitations } from './documents.js';
 import {
   ProtocolContractError,
   decodeCanonicalTimestamp,
@@ -6,15 +7,41 @@ import {
   decodeLogCursor,
   decodeOpaqueIdentifier,
   decodeUuid,
+  PROTOCOL_LIMIT_CEILINGS,
   utf8ByteLength,
   type LogCursor,
   type ProtocolErrorEnvelope,
 } from './contract.js';
 
+const MAX_UUID = '00000000-0000-4000-8000-000000000000';
+const MAX_TIMESTAMP = '0000-00-00T00:00:00.000Z';
+const MAX_LOG_DATA_BYTES = utf8ByteLength(JSON.stringify({
+  cursor: { created_at: MAX_TIMESTAMP, id: MAX_UUID },
+  entry: {
+    id: MAX_UUID,
+    cube_id: MAX_UUID,
+    drone_id: MAX_UUID,
+    message: '\0'.repeat(PROTOCOL_LIMIT_CEILINGS.max_log_message_bytes),
+    visibility: 'broadcast',
+    created_at: MAX_TIMESTAMP,
+    drone_label: '\0'.repeat(120),
+    role_name: '\0'.repeat(120),
+    recipient_drone_ids: Array.from({ length: 100 }, () => MAX_UUID),
+    documents: Array.from({ length: 100 }, (_, index) => ({
+      id: `${index.toString().padStart(3, '0')}${'x'.repeat(125)}`,
+      title: '😀'.repeat(120),
+      size_bytes: 10 * 1024 * 1024,
+      state: 'superseded',
+    })),
+  },
+}));
+const MAX_LOG_FRAME_BYTES = MAX_LOG_DATA_BYTES +
+  utf8ByteLength(`event: log\nid: ${MAX_UUID}\ndata: `);
+
 export const SSE_LIMITS = {
   total_bytes: 1024 * 1024,
-  frame_bytes: 65_536,
-  data_bytes: 65_536,
+  frame_bytes: MAX_LOG_FRAME_BYTES,
+  data_bytes: MAX_LOG_DATA_BYTES,
   frame_count: 1000,
   unknown_data_bytes: 4096,
 } as const;
@@ -97,6 +124,7 @@ export function decodeEnrichedStreamEntry(value: unknown): EnrichedStreamEntry {
       'drone_label',
       'role_name',
       'recipient_drone_ids',
+      'documents',
     ],
     [
       'id',
@@ -120,7 +148,11 @@ export function decodeEnrichedStreamEntry(value: unknown): EnrichedStreamEntry {
     id: decodeUuid(entry.id, ['entry', 'id']),
     cube_id: decodeUuid(entry.cube_id, ['entry', 'cube_id']),
     drone_id: entry.drone_id === null ? null : decodeUuid(entry.drone_id, ['entry', 'drone_id']),
-    message: boundedString(entry.message, 'message', 10_240),
+    message: boundedString(
+      entry.message,
+      'message',
+      PROTOCOL_LIMIT_CEILINGS.max_log_message_bytes,
+    ),
     visibility: entry.visibility,
     created_at: decodeCanonicalTimestamp(entry.created_at, ['entry', 'created_at']),
     drone_label: nullableString(entry.drone_label, 'drone_label', 120),
@@ -128,6 +160,9 @@ export function decodeEnrichedStreamEntry(value: unknown): EnrichedStreamEntry {
     recipient_drone_ids: entry.recipient_drone_ids.map((id, index) =>
       decodeUuid(id, ['entry', 'recipient_drone_ids', index])
     ),
+    ...(entry.documents === undefined ? {} : {
+      documents: decodeDocumentCitations(entry.documents),
+    }),
   };
 }
 

package/src/protocol/types.ts

@@ -1,4 +1,5 @@
 import type { MessageTaxonomy } from '../templates.js';
+import type { DocumentCitation } from './documents.js';
 
 export type AgentKind = 'claude' | 'codex' | 'opencode';
 export type RoleClass = 'queen' | 'worker';
@@ -100,6 +101,7 @@ export interface ActivityLogEntry {
   message: string;
   visibility: LogVisibility;
   created_at: string;
+  documents?: DocumentCitation[];
 }
 
 export interface EnrichedStreamEntry extends ActivityLogEntry {
@@ -177,6 +179,7 @@ export interface AppendLogRequest {
   recipientDroneIds?: string[];
   class?: string;
   to?: string[];
+  documents?: string[];
 }
 
 export interface AppendLogResponse {
@@ -184,6 +187,10 @@ export interface AppendLogResponse {
   deduplicated: boolean;
   routing?: RoutingEcho | null;
   unreachableRecipients?: Array<{ id: string; label: string }>;
+  advisory?: {
+    code: 'STORE_AS_DOCUMENT';
+    threshold_bytes: number;
+  };
 }
 
 export interface Decision {

package/src/protocol/version.ts

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

package/src/templates.ts

@@ -103,7 +103,8 @@ Integration and release:
 - Review approval does not itself authorize merge, deployment, publication, tagging, or release.
 - Perform those actions only when the user request or a standing delegation explicitly includes them.
 - Use the repository's protected workflow and bind every gate to the exact revision being integrated.
-- Never substitute, move, overwrite, or rerun an immutable release artifact without explicit recovery authority.`;
+- A release tag starts the tag-restricted staging workflow automatically; npm stage approval is the sole human publication boundary.
+- Before npm accepts a stage, correct a failed workflow and retry the same immutable tag. Never move, replace, or force-update the tag.`;
 
 export const GIT_OPERATIONAL_DISCIPLINE_BUILDER = `
 
@@ -200,7 +201,7 @@ const SOFTWARE_DEV_DIRECTIVE = `## Scope and coordination
 - When an outcome includes a separately published external surface, the Coordinator names one owning role or seat for its implementation. Other seats report findings or perform routed review; they do not mutate that surface.
 - Waiting is valid when no authorized action is available.
 - Merge, deploy, publish, tag, release, credential, and live-operator actions require explicit authority.
-- Keep cube-log signals concise. Put durable reasoning in the relevant issue, change, or existing maintained documentation only when it has an operational consumer.${SAME_REPOSITORY_WORKFLOW_DISCIPLINE}`;
+- Keep cube-log signals concise. Put durable reasoning in the relevant issue, change, or existing maintained documentation only when it has an operational consumer.${SAME_REPOSITORY_WORKFLOW_DISCIPLINE}${RELEASE_CYCLE_SHAPES}`;
 
 const SOFTWARE_DEV_TAXONOMY: MessageTaxonomy = [
   {
@@ -308,6 +309,8 @@ Review:
 - Classify findings as in-scope blocker, touched-surface safety blocker, or out-of-scope finding.
 - Drop an observation when it changes no decision; do not create work merely to preserve it.
 - Reviewers provide evidence; they do not redefine the work unit. Route one due gate at a time, proportionate to the changed surface. Never pre-route a later gate.
+- Require one proof per property. Mechanical, version, lock, and generated changes require exact-revision CI plus one Code Review only.
+- Give a successor revision delta review. Carry unchanged green evidence without rerunning it.
 - Bind every verdict to the exact revision. Before claiming gate completion, reread the source log and verify every required verdict.
 - After two blocked rounds, stop and ask the human for the smallest next choice.
 
@@ -340,10 +343,11 @@ 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, then substantive PROGRESS during active work.
+- 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.
 - 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 the repository checks required by the touched surface.
+- 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.
+- Check documentation or a separately published site only when the changed behavior, public API, package metadata, or named user claim belongs to that surface.
 
 Handoff:
 - Verify the final diff contains only the authorized slice.