borgmcp-shared 0.12.3 → 0.13.0

package/docs/cube-documents.md

@@ -0,0 +1,35 @@
+# Cube document contract
+
+Protocol v10 adds a cube-scoped working set for immutable text documents.
+Implementations accept only UTF-8 `text/markdown` and `text/plain` content. Each
+document has one opaque full id and a required, non-unique title of at most 120
+Unicode characters. Titles support discovery; only the complete id addresses a
+document.
+
+The default per-document budget is 65,536 bytes
+(`BORG_SERVER_MAX_DOCUMENT_BYTES`) and the default active budget per cube is
+524,288 bytes (`BORG_SERVER_MAX_ACTIVE_DOCUMENT_BYTES_PER_CUBE`). Servers may
+configure both budgets, validate their configuration at startup, and refuse a
+write atomically when either budget is exceeded. Superseded revisions continue
+to count until explicitly removed.
+
+Creation may carry `supersedes`, which must identify an existing document in the
+same cube. A document can be superseded by at most one later revision, producing
+a linear chain. Supersession never edits content or hides a revision.
+
+All cube seats may read documents. A write-authorized seat may create one. Only
+the author or a cube manager may remove it. Removal hides the document from the
+active list and active-byte budget but retains its immutable content and audit
+metadata for exact-id resolution by coordination records.
+
+Log creation may carry a structured `documents` array of full ids. The server
+validates every id before writing the entry. Log reads and streams render each
+citation as id, title, UTF-8 size, and current active, superseded, or removed
+state. Inline text that resembles an id has no citation semantics.
+
+The configurable defaults are `BORG_SERVER_LOG_ENTRY_ADVISORY_BYTES=1024` and
+`BORG_SERVER_MAX_LOG_ENTRY_BYTES=4096`. Valid non-default thresholds are carried
+on the wire; the server enforces its configured values. At the defaults, log
+text up to 1,024 UTF-8 bytes is accepted silently. Text through 4,096 bytes is
+accepted with the `STORE_AS_DOCUMENT` advisory. Larger log text is rejected;
+the caller stores the detail as a document and cites it from a shorter entry.

package/docs/release-records.json

@@ -185,5 +185,20 @@
     "verify_job_id": null,
     "publish_job_id": null,
     "artifact_integrity": "sha512-l459XEeqk0cSz1+Z8yk8cCVWik4/CX4OBTRZqj6n1SZYvDpzWJksUz82FA9k4taf//rs43Tfl1tpWXnRHAqxOQ=="
+  },
+  {
+    "outcome": "published",
+    "version": "0.12.3",
+    "tag": "v0.12.3",
+    "tag_object": "e410256092974dcef9619415ebdf74acde3e4484",
+    "commit": "9bfa43ced2af772d7a60f7be7828baaa146b4fd4",
+    "tree": "7605783c749615e13d9eb541c498856833ab690c",
+    "workflow_run_id": 31779837930,
+    "workflow_run_attempt": 1,
+    "workflow_conclusion": "success",
+    "verify_job_id": null,
+    "publish_job_id": null,
+    "artifact_integrity": "sha512-3GPQ1U7tBxg8Jp1Uac31CKKXQjMv4UNPhs5P6N83CyDXGJvkI88yowVJZGlLuo30eEk6jhERZ9AQWOjHst/sFA==",
+    "reconstructed": true
   }
 ]

package/docs/releases/0.13.0.md

@@ -0,0 +1,7 @@
+This release introduces the protocol v10 cube-document contract used by the
+matching Borg MCP server and client releases.
+
+- Cubes gain immutable Markdown and plain-text documents with bounded storage, linear supersession, and explicit removal semantics.
+- Log entries can cite documents by full id, with current document metadata rendered consistently in reads and streams.
+- Configurable log-entry thresholds provide a store-as-document advisory before oversized log text is rejected.
+- Conformance vectors cover document lifecycle, authorization, isolation, citations, and protocol v10 SSE envelopes.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "borgmcp-shared",
-  "version": "0.12.3",
+  "version": "0.13.0",
   "description": "Shared protocol, domain, templates, and conformance contracts for Borg MCP implementations.",
   "type": "module",
   "main": "./dist/index.js",

package/src/conformance/adapter.ts

@@ -22,6 +22,10 @@ import {
   decodeResolveRepositoryCubeResponseEnvelope,
   decodeReassignDroneResultEnvelope,
   decodeUpdateDroneRuntimeMetadataResponseEnvelope,
+  decodeGetDocumentResultEnvelope,
+  decodeListDocumentsResultEnvelope,
+  decodePutDocumentResultEnvelope,
+  decodeRemoveDocumentResultEnvelope,
   decodeSseFrames,
   PROTOCOL_LIMIT_CEILINGS,
   PROTOCOL_HTTP_CONTRACT,
@@ -35,6 +39,7 @@ import {
   type LogCursor,
   type StreamEvent,
   type DroneRuntimeMetadata,
+  type CubeDocument,
 } from '../protocol/index.js';
 import {
   APPEND_LOG_IDEMPOTENCY_CONFORMANCE,
@@ -42,6 +47,7 @@ import {
   CREATE_CUBE_RETRY_CONFORMANCE,
   INVITATION_ARTIFACT_CONFORMANCE,
   ENROLLMENT_RETRY_CONFORMANCE,
+  DOCUMENT_CONFORMANCE,
 } from './index.js';
 
 export interface ConformanceHttpResponse {
@@ -265,6 +271,10 @@ export interface ConformanceOperations {
     cube: ConformanceCube,
     request: unknown,
   ): Promise<ConformanceHttpResponse>;
+  putDocument(credential: string, cube: ConformanceCube, request: unknown): Promise<ConformanceHttpResponse>;
+  getDocument(credential: string, cube: ConformanceCube, request: unknown): Promise<ConformanceHttpResponse>;
+  listDocuments(credential: string, cube: ConformanceCube, request: unknown): Promise<ConformanceHttpResponse>;
+  removeDocument(credential: string, cube: ConformanceCube, request: unknown): Promise<ConformanceHttpResponse>;
   resolveRepositoryCube(credential: string | null, request: unknown): Promise<ConformanceHttpResponse>;
   associateRepositoryCube(credential: string | null, request: unknown): Promise<ConformanceHttpResponse>;
   attach(credential: string, request: unknown): Promise<ConformanceHttpResponse>;
@@ -364,6 +374,7 @@ export const ADAPTER_CONFORMANCE_FIXTURES = [
   { id: 'enrollment.invitation-artifact', area: 'enrollment' },
   { id: 'enrollment.retry-authority', area: 'enrollment' },
   { id: 'repository.explicit-association', area: 'repository' },
+  { id: 'documents.lifecycle', area: 'documents' },
   { id: 'security.adapter-boundary-injection', area: 'security' },
   { id: 'security.oversize-request', area: 'security' },
   { id: 'security.cross-cube-isolation', area: 'security' },
@@ -619,7 +630,7 @@ function expectSecretFreeError(
   expectError(response, status, code, operation);
   const diagnostic = JSON.stringify(response.body);
   for (const secret of new Set(secrets)) {
-    invariant(!diagnostic.includes(secret), `${operation} exposed retry material.`);
+    invariant(!diagnostic.includes(secret), `${operation} exposed sensitive material.`);
   }
 }
 
@@ -1327,6 +1338,334 @@ export async function runAdapterConformance(
     };
   });
 
+  await record('documents.lifecycle', async () => {
+    const outcomes = new Map<string, string>();
+    const documentPrincipal = await environment.admin.createPrincipal('document-lifecycle');
+    const documentCube = await environment.admin.createCube('document-lifecycle');
+    await environment.admin.grantCube(documentPrincipal, documentCube, 'write');
+    const documentCredential = await environment.admin.issueDroneSession(documentPrincipal);
+    const reader = await environment.admin.createPrincipal('document-reader');
+    const peer = await environment.admin.createPrincipal('document-peer');
+    const manager = await environment.admin.createPrincipal('document-manager');
+    await environment.admin.grantCube(reader, documentCube, 'read');
+    await environment.admin.grantCube(peer, documentCube, 'write');
+    await environment.admin.grantCube(manager, documentCube, 'manage');
+    const readerCredential = await environment.admin.issueDroneSession(reader);
+    const peerCredential = await environment.admin.issueDroneSession(peer);
+    const managerCredential = await environment.admin.issueDroneSession(manager);
+    const foreignPrincipal = await environment.admin.createPrincipal('document-foreign');
+    const foreignCube = await environment.admin.createCube('document-foreign');
+    await environment.admin.grantCube(foreignPrincipal, foreignCube, 'write');
+    const foreignCredential = await environment.admin.issueDroneSession(foreignPrincipal);
+    const foreignPut = await environment.operations.putDocument(
+      foreignCredential,
+      foreignCube,
+      createProtocolEnvelope('document-foreign-put', {
+        title: 'Foreign evidence', content_type: 'text/plain', content: 'Foreign immutable content.',
+      }),
+    );
+    expectStatus(foreignPut, 201, 'Foreign document put');
+    const foreignDocument = decodePutDocumentResultEnvelope(foreignPut.body).payload.document;
+    expectError(await environment.operations.putDocument(
+      readerCredential,
+      documentCube,
+      createProtocolEnvelope('document-read-only-put', { title: 'Denied', content_type: 'text/plain', content: 'denied' }),
+    ), 403, ErrorCode.ACCESS_DENIED, 'Read-only document put');
+    expectError(await environment.operations.putDocument(
+      documentCredential,
+      documentCube,
+      createProtocolEnvelope('document-bad-type', { title: 'Binary', content_type: 'application/octet-stream', content: 'x' }),
+    ), 400, ErrorCode.DOCUMENT_CONTENT_TYPE_UNSUPPORTED, 'Unsupported document type');
+    outcomes.set('unsupported-content-type', ErrorCode.DOCUMENT_CONTENT_TYPE_UNSUPPORTED);
+    expectError(await environment.operations.putDocument(
+      documentCredential,
+      documentCube,
+      createProtocolEnvelope('document-bad-title', { title: 'x'.repeat(121), content_type: 'text/plain', content: 'x' }),
+    ), 400, ErrorCode.INVALID_INPUT, 'Oversized document title');
+    outcomes.set('oversize-title', ErrorCode.INVALID_INPUT);
+    expectError(await environment.operations.putDocument(
+      documentCredential,
+      documentCube,
+      createProtocolEnvelope('document-oversize', { title: 'Too large', content_type: 'text/plain', content: 'x'.repeat(65_537) }),
+    ), 413, ErrorCode.DOCUMENT_BUDGET_EXCEEDED, 'Oversized document');
+    const budgetCube = await environment.admin.createCube('document-budget');
+    await environment.admin.grantCube(documentPrincipal, budgetCube, 'write');
+    let budgetPredecessor: CubeDocument | undefined;
+    for (let index = 0; index < 8; index++) {
+      const response = await environment.operations.putDocument(
+        documentCredential,
+        budgetCube,
+        createProtocolEnvelope(`document-budget-${index}`, {
+          title: `Budget ${index}`, content_type: 'text/plain', content: 'x'.repeat(65_536),
+        }),
+      );
+      expectStatus(response, 201, `Document budget fill ${index}`);
+      if (index === 0) budgetPredecessor = decodePutDocumentResultEnvelope(response.body).payload.document;
+    }
+    invariant(budgetPredecessor !== undefined, 'Budget predecessor was not created.');
+    expectError(await environment.operations.putDocument(
+      documentCredential,
+      budgetCube,
+      createProtocolEnvelope('document-budget-overflow', {
+        title: 'Overflow', content_type: 'text/plain', content: 'x', supersedes: budgetPredecessor.id,
+      }),
+    ), 413, ErrorCode.DOCUMENT_BUDGET_EXCEEDED, 'Active document budget');
+    const budgetList = decodeListDocumentsResultEnvelope((await environment.operations.listDocuments(
+      documentCredential, budgetCube, createProtocolEnvelope('document-budget-list', {}),
+    )).body).payload.documents;
+    invariant(budgetList.length === 8, 'Budget refusal partially mutated the document set.');
+    const budgetRetained = decodeGetDocumentResultEnvelope((await environment.operations.getDocument(
+      documentCredential,
+      budgetCube,
+      createProtocolEnvelope('document-budget-get-predecessor', { id: budgetPredecessor.id }),
+    )).body).payload.document;
+    invariant(
+      budgetRetained.state === 'active' && budgetRetained.superseded_by === null &&
+        budgetRetained.content === budgetPredecessor.content,
+      'Budget refusal partially mutated its predecessor.',
+    );
+    expectError(await environment.operations.putDocument(
+      documentCredential,
+      documentCube,
+      createProtocolEnvelope('document-unknown-supersedes', { title: 'Unknown', content_type: 'text/plain', content: 'x', supersedes: 'unknown_full_id' }),
+    ), 409, ErrorCode.DOCUMENT_SUPERSESSION_INVALID, 'Unknown document supersession');
+    outcomes.set('foreign-supersedes', ErrorCode.DOCUMENT_SUPERSESSION_INVALID);
+    const put = await environment.operations.putDocument(
+      documentCredential,
+      documentCube,
+      createProtocolEnvelope('document-put', {
+        title: 'Review evidence',
+        content_type: 'text/markdown',
+        content: '# Evidence\n\nPortable UTF-8: €\n',
+      }),
+    );
+    expectStatus(put, 201, 'Document put');
+    const created = decodePutDocumentResultEnvelope(put.body).payload.document;
+    outcomes.set('markdown', 'created');
+    invariant(created.size_bytes === utf8ByteLength(created.content), 'Document size is not its UTF-8 byte size.');
+    expectSecretFreeError(await environment.operations.getDocument(
+      documentCredential,
+      documentCube,
+      createProtocolEnvelope('document-foreign-get', { id: foreignDocument.id }),
+    ), 404, ErrorCode.DOCUMENT_NOT_FOUND, 'Foreign document get', [foreignDocument.title, foreignDocument.content]);
+    expectSecretFreeError(await environment.operations.listDocuments(
+      documentCredential,
+      foreignCube,
+      createProtocolEnvelope('document-foreign-list', {}),
+    ), 404, ErrorCode.NOT_FOUND, 'Foreign document list', [foreignDocument.title, foreignDocument.content]);
+    expectSecretFreeError(await environment.operations.removeDocument(
+      documentCredential,
+      documentCube,
+      createProtocolEnvelope('document-foreign-remove', { id: foreignDocument.id }),
+    ), 404, ErrorCode.DOCUMENT_NOT_FOUND, 'Foreign document remove', [foreignDocument.title, foreignDocument.content]);
+    const entriesBeforeForeignCitation = decodeReadLogResultEnvelope((await environment.operations.read(
+      documentCredential,
+      documentCube,
+      createProtocolEnvelope('document-read-before-foreign-cite', { cursor: null, limit: 100 }),
+    )).body).payload.entries.length;
+    expectSecretFreeError(await environment.operations.append(
+      documentCredential,
+      documentCube,
+      createProtocolEnvelope('document-foreign-citation', {
+        post_id: '00000000-0000-4000-8000-00000000031f',
+        message: 'Foreign evidence must remain hidden.',
+        documents: [foreignDocument.id],
+      }),
+    ), 404, ErrorCode.DOCUMENT_NOT_FOUND, 'Foreign document citation', [foreignDocument.title, foreignDocument.content]);
+    const entriesAfterForeignCitation = decodeReadLogResultEnvelope((await environment.operations.read(
+      documentCredential,
+      documentCube,
+      createProtocolEnvelope('document-read-after-foreign-cite', { cursor: null, limit: 100 }),
+    )).body).payload.entries.length;
+    invariant(entriesAfterForeignCitation === entriesBeforeForeignCitation, 'Denied foreign citation mutated the log.');
+
+    const successorResponse = await environment.operations.putDocument(
+      documentCredential,
+      documentCube,
+      createProtocolEnvelope('document-put-successor', {
+        title: 'Review evidence revision 2',
+        content_type: 'text/markdown',
+        content: '# Revised evidence\n',
+        supersedes: created.id,
+      }),
+    );
+    expectStatus(successorResponse, 201, 'Document successor put');
+    const successor = decodePutDocumentResultEnvelope(successorResponse.body).payload.document;
+    invariant(successor.supersedes === created.id, 'Document successor did not bind the full prior id.');
+    expectError(await environment.operations.putDocument(
+      documentCredential,
+      documentCube,
+      createProtocolEnvelope('document-branch', { title: 'Branch', content_type: 'text/plain', content: 'x', supersedes: created.id }),
+    ), 409, ErrorCode.DOCUMENT_SUPERSESSION_INVALID, 'Branched document supersession');
+    outcomes.set('branched-supersedes', ErrorCode.DOCUMENT_SUPERSESSION_INVALID);
+    expectError(await environment.operations.putDocument(
+      credentialA,
+      cubeA,
+      createProtocolEnvelope('document-cross-cube', { title: 'Cross cube', content_type: 'text/plain', content: 'x', supersedes: created.id }),
+    ), 409, ErrorCode.DOCUMENT_SUPERSESSION_INVALID, 'Cross-cube document supersession');
+
+    const citationResponse = await environment.operations.append(
+      documentCredential,
+      documentCube,
+      createProtocolEnvelope('document-citation', {
+        post_id: '00000000-0000-4000-8000-000000000320',
+        message: 'See the document evidence.',
+        documents: [created.id, successor.id],
+      }),
+    );
+    expectStatus(citationResponse, 201, 'Document citation append');
+    const cited = decodeAppendLogResultEnvelope(citationResponse.body).payload.entry.documents;
+    invariant(cited?.length === 2 && cited[0].state === 'superseded', 'Log citations did not render document metadata and state.');
+    expectError(await environment.operations.append(
+      documentCredential,
+      documentCube,
+      createProtocolEnvelope('document-citation-conflict', {
+        post_id: '00000000-0000-4000-8000-000000000320',
+        message: 'See the document evidence.',
+        documents: [successor.id],
+      }),
+    ), 409, ErrorCode.POST_ID_CONFLICT, 'Document citation post-id conflict');
+
+    const listed = await environment.operations.listDocuments(
+      readerCredential,
+      documentCube,
+      createProtocolEnvelope('document-list', {}),
+    );
+    expectStatus(listed, 200, 'Document list');
+    const list = decodeListDocumentsResultEnvelope(listed.body).payload.documents;
+    invariant(
+      list.length === 2 && list.some(({ id, state, superseded_by }) =>
+        id === created.id && state === 'superseded' && superseded_by === successor.id),
+      'Linear document supersession was not listed by full ids.',
+    );
+    invariant(!('content' in list[0]), 'Document list exposed immutable content.');
+    invariant(!list.some(({ id }) => id === foreignDocument.id), 'Document list leaked a foreign document.');
+    expectStatus(await environment.operations.getDocument(
+      readerCredential,
+      documentCube,
+      createProtocolEnvelope('document-reader-get', { id: created.id }),
+    ), 200, 'Read-only document get');
+    expectError(await environment.operations.removeDocument(
+      readerCredential,
+      documentCube,
+      createProtocolEnvelope('document-reader-remove', { id: created.id }),
+    ), 403, ErrorCode.DOCUMENT_REMOVE_DENIED, 'Read-only document remove');
+    expectError(await environment.operations.removeDocument(
+      peerCredential,
+      documentCube,
+      createProtocolEnvelope('document-peer-remove', { id: created.id }),
+    ), 403, ErrorCode.DOCUMENT_REMOVE_DENIED, 'Peer document remove');
+    outcomes.set('peer-remove', ErrorCode.DOCUMENT_REMOVE_DENIED);
+
+    const authorDocumentResponse = await environment.operations.putDocument(
+      documentCredential,
+      documentCube,
+      createProtocolEnvelope('document-author-put', {
+        title: 'Author removable', content_type: 'text/plain', content: 'Author content.',
+      }),
+    );
+    expectStatus(authorDocumentResponse, 201, 'Author document put');
+    outcomes.set('plain', 'created');
+    const authorDocument = decodePutDocumentResultEnvelope(authorDocumentResponse.body).payload.document;
+    expectStatus(await environment.operations.removeDocument(
+      documentCredential,
+      documentCube,
+      createProtocolEnvelope('document-author-remove', { id: authorDocument.id }),
+    ), 200, 'Author document remove');
+
+    const got = await environment.operations.getDocument(
+      documentCredential,
+      documentCube,
+      createProtocolEnvelope('document-get', { id: created.id }),
+    );
+    expectStatus(got, 200, 'Document get');
+    invariant(
+      decodeGetDocumentResultEnvelope(got.body).payload.document.content === created.content,
+      'Document get did not preserve immutable content and metadata.',
+    );
+
+    const removed = await environment.operations.removeDocument(
+      managerCredential,
+      documentCube,
+      createProtocolEnvelope('document-remove', { id: created.id }),
+    );
+    expectStatus(removed, 200, 'Document remove');
+    invariant(
+      decodeRemoveDocumentResultEnvelope(removed.body).payload.document.state === 'removed',
+      'Document removal did not produce audit-retained removed state.',
+    );
+    const afterResponse = await environment.operations.listDocuments(
+      readerCredential,
+      documentCube,
+      createProtocolEnvelope('document-list-after', {}),
+    );
+    expectStatus(afterResponse, 200, 'Read-only document list after removal');
+    const after = decodeListDocumentsResultEnvelope(afterResponse.body).payload.documents;
+    invariant(after.length === 1 && after[0].id === successor.id, 'Removed document remained in active listing.');
+    const retainedResponse = await environment.operations.getDocument(
+      readerCredential,
+      documentCube,
+      createProtocolEnvelope('document-get-removed', { id: created.id }),
+    );
+    expectStatus(retainedResponse, 200, 'Read-only audit-retained document get');
+    const retained = decodeGetDocumentResultEnvelope(retainedResponse.body).payload.document;
+    invariant(retained.state === 'removed' && retained.content === created.content, 'Removed content was not forensically resolvable.');
+    const foreignRetained = decodeGetDocumentResultEnvelope((await environment.operations.getDocument(
+      foreignCredential,
+      foreignCube,
+      createProtocolEnvelope('document-foreign-retained', { id: foreignDocument.id }),
+    )).body).payload.document;
+    invariant(
+      foreignRetained.state === 'active' && foreignRetained.content === foreignDocument.content,
+      'Denied foreign operations leaked mutation into the foreign document.',
+    );
+    outcomes.set('removed', 'audit-resolvable');
+    const entriesBeforeUnknownCitation = (await environment.operations.read(
+      documentCredential, documentCube, createProtocolEnvelope('document-read-before-unknown-cite', { cursor: null, limit: 100 }),
+    ));
+    const beforeCount = decodeReadLogResultEnvelope(entriesBeforeUnknownCitation.body).payload.entries.length;
+    expectError(await environment.operations.append(
+      documentCredential,
+      documentCube,
+      createProtocolEnvelope('document-unknown-citation', {
+        post_id: '00000000-0000-4000-8000-000000000321', message: 'Unknown.', documents: ['unknown_full_id'],
+      }),
+    ), 404, ErrorCode.DOCUMENT_NOT_FOUND, 'Unknown document citation');
+    const longAccepted = await environment.operations.append(
+      documentCredential,
+      documentCube,
+      createProtocolEnvelope('document-advisory', {
+        post_id: '00000000-0000-4000-8000-000000000322', message: 'x'.repeat(1025),
+      }),
+    );
+    expectStatus(longAccepted, 201, 'Advisory log append');
+    invariant(decodeAppendLogResultEnvelope(longAccepted.body).payload.advisory?.threshold_bytes === 1024, 'Configured advisory was not returned.');
+    expectError(await environment.operations.append(
+      documentCredential,
+      documentCube,
+      createProtocolEnvelope('document-hard-cap', {
+        post_id: '00000000-0000-4000-8000-000000000323', message: 'x'.repeat(4097),
+      }),
+    ), 413, ErrorCode.CONTENT_TOO_LARGE, 'Hard-cap log append');
+    const citedRead = decodeReadLogResultEnvelope((await environment.operations.read(
+      documentCredential,
+      documentCube,
+      createProtocolEnvelope('document-citation-read', { cursor: null, limit: 10 }),
+    )).body).payload.entries[0].documents;
+    invariant(citedRead?.[0].state === 'removed', 'Log citation did not resolve the audit-retained removed state.');
+    const finalCount = decodeReadLogResultEnvelope((await environment.operations.read(
+      documentCredential, documentCube, createProtocolEnvelope('document-final-read', { cursor: null, limit: 100 }),
+    )).body).payload.entries.length;
+    invariant(finalCount === beforeCount + 1, 'Rejected document or log operations partially mutated state.');
+    for (const vector of DOCUMENT_CONFORMANCE) {
+      invariant(
+        outcomes.get(vector.fixture) === vector.expected,
+        `${vector.name} produced ${outcomes.get(vector.fixture) ?? 'no outcome'}; expected ${vector.expected}.`,
+      );
+    }
+    return { refusals: true, put: 201, cited: true, active_listed: true, removed_hidden: true, audit_resolvable: true };
+  });
+
   await record('security.adapter-boundary-injection', async () => {
     const injectedMessage = "'); DROP TABLE log_entries; --\r\ndata: forged-sse-frame";
     const injectedBody = JSON.stringify(

package/src/conformance/index.ts

@@ -23,6 +23,17 @@ export interface ConformanceVector<Input, Output> {
   expected: Output;
 }
 
+export const DOCUMENT_CONFORMANCE = [
+  { name: 'accepts markdown UTF-8 content', fixture: 'markdown', expected: 'created' },
+  { name: 'accepts plain UTF-8 content', fixture: 'plain', expected: 'created' },
+  { name: 'rejects unsupported content types', fixture: 'unsupported-content-type', expected: 'DOCUMENT_CONTENT_TYPE_UNSUPPORTED' },
+  { name: 'requires a title of at most 120 characters', fixture: 'oversize-title', expected: 'INVALID_INPUT' },
+  { name: 'rejects an unknown or cross-cube supersedes id', fixture: 'foreign-supersedes', expected: 'DOCUMENT_SUPERSESSION_INVALID' },
+  { name: 'rejects a branch in the linear supersession chain', fixture: 'branched-supersedes', expected: 'DOCUMENT_SUPERSESSION_INVALID' },
+  { name: 'delists removed content while retaining exact-id resolution', fixture: 'removed', expected: 'audit-resolvable' },
+  { name: 'allows only the author or a cube manager to remove', fixture: 'peer-remove', expected: 'DOCUMENT_REMOVE_DENIED' },
+] as const;
+
 export interface BroadcastHwmComparisonInput {
   a: BroadcastHwm;
   b: BroadcastHwm;

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.3' 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;
 }