borgmcp-shared 0.10.1 → 0.12.0

package/docs/release-records.json

@@ -1,4 +1,49 @@
 [
+  {
+    "outcome": "published",
+    "version": "0.6.3",
+    "tag": "v0.6.3",
+    "tag_object": "fd6aa8858e6565ad49a69144736e8fe12a8295bb",
+    "commit": "f9d79866e1f7fe0f9ea31099bce1b36af9388ecc",
+    "tree": "2fd38cc7b1a0332e987cb95881c2ca8ffe2a28e3",
+    "workflow_run_id": 30096375533,
+    "workflow_run_attempt": 1,
+    "workflow_conclusion": "success",
+    "verify_job_id": null,
+    "publish_job_id": null,
+    "artifact_integrity": "sha512-9osP68zH3a2IbyZr4BHiiz9SF+F4kqqxkwUQiun0GXUzu8Vw/+JorCG8OnyRFm8KpXNZ2Yh3KQxqcRD583l1NA==",
+    "reconstructed": true
+  },
+  {
+    "outcome": "published",
+    "version": "0.6.4",
+    "tag": "v0.6.4",
+    "tag_object": "f79b0683686d3c359023a17f6e8a92efd888104a",
+    "commit": "fa8a2dc072d4ffe2a16d5f02576fead822a2f72e",
+    "tree": "2efa6d9553ca7f80c5c477ca39cf35bef55ad01c",
+    "workflow_run_id": 30169732628,
+    "workflow_run_attempt": 1,
+    "workflow_conclusion": "success",
+    "verify_job_id": null,
+    "publish_job_id": null,
+    "artifact_integrity": "sha512-Wm4b0uoOAw9JCz5OTHD0Q2uXKkeWYdkVksdeZvRG8l62XGMY+G8GkNEsZT9L533LbVbQ29GhgF0htjDenQThDg==",
+    "reconstructed": true
+  },
+  {
+    "outcome": "published",
+    "version": "0.7.0",
+    "tag": "v0.7.0",
+    "tag_object": "5ddaf5821c49ac0893fdffbac6115b48d0795281",
+    "commit": "30af2629052014feba3f3ebf4d9eb29e977e38a7",
+    "tree": "da7b7d67f2d00403d3536923897bd52b73a479db",
+    "workflow_run_id": 30337670996,
+    "workflow_run_attempt": 1,
+    "workflow_conclusion": "success",
+    "verify_job_id": null,
+    "publish_job_id": null,
+    "artifact_integrity": "sha512-CLpQo3P/fE9GzC/R7Xw61LWxxsgcVLwmpGb5Ot5PDRe1Bvnf+EB31kiBdU5rvyvvPhiK4oUQtJAZE4ULFRAA2A==",
+    "reconstructed": true
+  },
   {
     "outcome": "published",
     "version": "0.7.1",
@@ -13,6 +58,36 @@
     "publish_job_id": null,
     "artifact_integrity": "sha512-d4GE7ezGyoFN0uwA62gvRPUMfMdJ1kxhTunqU8dW3Qhy1n2SlNXZWr1Nthm6Goo0bAgvax8KEywyReodA6FyQA=="
   },
+  {
+    "outcome": "published",
+    "version": "0.8.0",
+    "tag": "v0.8.0",
+    "tag_object": "b43710281df47f9a6f3d1dafd8ef6b2b527e718d",
+    "commit": "24d260cd882b306b48c5c9397b6c3eb21b8b4990",
+    "tree": "3067a71b57ec96041269282ce3d71f38ec624cc5",
+    "workflow_run_id": 30720286941,
+    "workflow_run_attempt": 1,
+    "workflow_conclusion": "success",
+    "verify_job_id": null,
+    "publish_job_id": null,
+    "artifact_integrity": "sha512-0p/ZC03Y6G4N6bfBjMD5b+WcQXcLalhU/3QqGjSWYCFKa3q2/183O53w6Tu6y8h2DkhTw5prnamsOozmVpXZew==",
+    "reconstructed": true
+  },
+  {
+    "outcome": "published",
+    "version": "0.8.1",
+    "tag": "v0.8.1",
+    "tag_object": "cc690f6d41aa34b3f2884db500bc9979ab2de1db",
+    "commit": "d29c5cf9285dc62b01258b640102f8cf21a9ec21",
+    "tree": "b2134c0e54041554e87bf4b4d044e3f476cb1f2b",
+    "workflow_run_id": 30853413999,
+    "workflow_run_attempt": 1,
+    "workflow_conclusion": "success",
+    "verify_job_id": null,
+    "publish_job_id": null,
+    "artifact_integrity": "sha512-0+UfSDnAO0mWYIqxzzppekatya1gCF9ntZmuk7VVr2Hnf9QeM1S7uPLP/TWwDSTLtczB4EUoKA71E1WZJH2mbg==",
+    "reconstructed": true
+  },
   {
     "outcome": "published",
     "version": "0.9.0",
@@ -40,5 +115,33 @@
     "verify_job_id": null,
     "publish_job_id": null,
     "artifact_integrity": "sha512-NYZJi6z0g/Txb6ge+5NgRPNRszVEi0eNmICxkoZq5bGkJWm5qEvNSt3ws90Xz8IOKuWcyHC9i6sAK6cbZxwYDw=="
+  },
+  {
+    "outcome": "published",
+    "version": "0.10.1",
+    "tag": "v0.10.1",
+    "tag_object": "7fbf92b057988c6893ad4ff2af13dfa7bc50c131",
+    "commit": "691c9498c6248363a6f7d056178321443d12cf43",
+    "tree": "331d100770eb2d23f6e06d56a595141a6a9c1749",
+    "workflow_run_id": 31265832036,
+    "workflow_run_attempt": 1,
+    "workflow_conclusion": "success",
+    "verify_job_id": null,
+    "publish_job_id": null,
+    "artifact_integrity": "sha512-IAESc6+VpUGECNabFkO60agvga0B8Fx0hk2RMUkSDCnlIjMvDodMFKlqw+TOzdXtjf0Uk9LJi9ZCU4HfRYRRhw=="
+  },
+  {
+    "outcome": "published",
+    "version": "0.11.0",
+    "tag": "v0.11.0",
+    "tag_object": "9086deca3f3d05b4702a415c6d50b19c54bcc7f2",
+    "commit": "c1df96a858ff7c587d42508d388aa517a0b8545c",
+    "tree": "84a5599afba05d9630e0e41beb401f700d83cd68",
+    "workflow_run_id": 31531549256,
+    "workflow_run_attempt": 1,
+    "workflow_conclusion": "success",
+    "verify_job_id": null,
+    "publish_job_id": null,
+    "artifact_integrity": "sha512-I8mixCbSrLKyOAAyqEI/HZJ8cML2rz3r812Up8pr547OdAk9LxZevdCo7ojG42ZwrUmS5u7iKQPg7Vk1XvtX1g=="
   }
 ]

package/docs/releases/0.12.0.md

@@ -0,0 +1,7 @@
+This release introduces the protocol v9 reliable-coordination contract used by
+the matching Borg MCP server and client releases.
+
+- Log posts now carry a canonical UUID so an interrupted write can be retried safely.
+- Exact same-author retries return the original entry and identify the result as deduplicated.
+- Reusing that UUID with changed message or routing returns a typed conflict, while another author may use the same UUID independently.
+- Fresh attach responses include the current log cursor so clients can resume without missing activity between attachment and stream startup.

package/docs/releasing.md

@@ -13,16 +13,18 @@ The release lane has one build, test, package, and publication authority:
 1. verifies the public repository context, exact package version, annotated tag,
    tag commit, and ancestry on protected `main`;
 2. installs locked dependencies without lifecycle scripts and runs dependency
-   audit, type checks, the full test suite, one clean build, and generated-output
-   drift detection;
+   audit, one clean build, type checks, and the full test suite;
 3. creates one local tarball, enforces the packed-artifact policy, and installs
    that tarball into a clean consumer that imports every public export;
 4. rejects an existing immutable version or a package not owned solely by the
    configured npm owner before any registry mutation;
-5. publishes that exact local tarball through npm Trusted Publishing with
-   provenance. Successful completion of `npm publish` is the workflow's terminal
-   release boundary; no post-publication registry readback can fail the immutable
-   release after npm has accepted it.
+5. stages that exact local tarball through npm Trusted Publishing with
+   provenance. Successful completion of `npm stage publish` means npm accepted
+   the immutable stage; it does not mean the version is publicly available.
+
+The release becomes live only after the authorized operator approves the stage
+with 2FA and the canonical registry exposes the expected version and integrity.
+No workflow post-publication readback can fail a release after that boundary.
 
 npm and GitHub produce the registry signature and publish attestation as part of
 Trusted Publishing. The repository does not reconstruct or immediately read back
@@ -37,6 +39,7 @@ Keep these controls in place:
 
 1. `publish.yml` is the only npm Trusted Publisher workflow for organization
    `Byte-Ventures`, repository `borg-mcp-shared`, and environment `npm-publish`.
+   Its allowed actions enable `npm stage publish` and disable `npm publish`.
 2. The `npm-publish` environment requires the authorized sole operator
    `TheodorStorm`, permits that operator's self-review, prevents administrator
    bypass, and allows only protected `v*.*.*` tags.
@@ -64,9 +67,12 @@ repository, workflow output, artifact, issue, or shell history.
 
 ## Release Procedure
 
-1. Merge the exact version, lockfile, generated output, and release documentation
+1. Merge the exact version, lockfile, source, and release documentation
    to protected `main` after the required exact-SHA Code Review, Security Review,
    and Release Quality gates.
+   Release documentation includes curated `docs/releases/<version>.md` notes.
+   The GitHub Release operator reads those exact bytes from the tagged commit
+   under `News and fixes`; it links the merged release PR but never renders its body.
 2. Verify repository controls with the configuration guard above. Confirm the
    target version does not already exist and `borgmcp-shared` is owned solely by
    `byteventures`.
@@ -78,16 +84,70 @@ repository, workflow output, artifact, issue, or shell history.
 5. Obtain the separately required environment approval, then approve that exact
    pending job. Approval does not permit a local rebuild or alternate artifact.
 6. Require the protected publish job to complete successfully before announcing
-   the version or updating consumers. Registry propagation and later consumer
-   availability are operational observations, not release-workflow gates.
+   that the stage is ready. Record its stage UUID; do not announce the version,
+   update consumers, synchronize the site, create a GitHub Release, or record a
+   `published` outcome while it remains staged.
+
+Before release preparation or trusted identity verification can pass, the
+greatest stable npm version below the current package version must already have a
+`published` ledger entry. This prevents a later release from silently skipping
+the immediately previous publication. A final `"reconstructed": true` marker
+means the entry was recovered later from the same annotated-tag, Actions-run, and
+npm-integrity authorities; it does not weaken verification or change the outcome.
+
+## Coupled Stage Approval
+
+For a coordinated shared, server, and client release, require all three tag
+workflows to succeed before approving any stage. Use authenticated `npm stage
+list` and `npm stage view` to record and verify each UUID, package, version, and
+`latest` tag. Bind each source run, annotated tag, and commit separately from
+GitHub workflow and tag evidence. Before any approval, run `npm stage download
+<UUID>` for every package. For server and client, verify the downloaded SHA-512
+against the same-run artifact report. For shared, independently compute and
+record the stage-download SHA-512 SRI, then carry that exact value into the
+required post-approval `--integrity` argument; shared has no same-run artifact
+report. Exercise the exact downloaded coupled set before approving any stage.
+Confirm public `latest` and the public version lists still describe the prior
+coherent set.
+
+Approve the verified stages in one operator session with 2FA:
+
+1. `npm stage approve <shared-stage-uuid>`
+2. `npm stage approve <server-stage-uuid>`
+3. `npm stage approve <client-stage-uuid>`
+
+The three approvals are not atomic. Shared-first does not change the exact
+shared pins of the live client and server. Server-second opens a bounded window
+in which `latest` client and server may not match; client-third closes it. Staging
+reduces that window to the approval sequence but does not eliminate it.
+
+After each approval, continue only while the remaining stage is still the exact
+verified candidate. Resolve an ambiguous approval through authenticated stage
+state and canonical public version/integrity state; never repeat it blindly.
+After all approvals:
+
+1. Verify the three live versions, integrities, and registry provenance
+   attestations, and exercise a fresh coupled install. Only then announce,
+   record, close, or synchronize the release.
+2. Create the three GitHub Releases in the same operator session, in shared,
+   server, then client order. For shared, pass the SHA-512 SRI computed from the
+   mandatory stage download during promotion:
+
+```sh
+GITHUB_TOKEN="$(gh auth token)" node scripts/create-github-release.mjs <version> --integrity <sha512-SRI>
+```
+
+This required value binds npm-live to the independently verified staged bytes.
+Unlike server and client, shared uploads no same-run artifact report; do not
+derive the expected integrity from npm or alter `publish.yml` to create one.
 
 ## Coupled Publication Window
 
-The shared, server, and client packages are published independently. The current
-release workflows publish directly to npm's default `latest` dist-tag, so the
-least-bad order is shared first, server second, and client third. This keeps each
-consumer pointed at an immutable shared artifact, but it cannot make the three
-`latest` pointers atomic.
+The shared, server, and client packages are approved independently from private
+npm stages. Pending stages are not publicly installable and do not change
+`latest` or the public version list. Approval order is shared first, server
+second, and client third. This keeps each consumer pointed at an immutable shared
+artifact, but it cannot make the three approvals atomic.
 
 During that sequence, a user can install the newest server and newest client
 while they still carry different protocol tags. Their credential-free preflight
@@ -95,33 +155,47 @@ fails closed by design; this is a publication-window mismatch, not a negotiation
 or fallback case. The user remedy is to install the matching coupled shared,
 server, and client versions from the coordinated release rather than retrying
 `latest`. Do not describe this window as eliminated or promise an atomic
-multi-package publication until all three release workflows support that shape.
+multi-package publication until npm supports atomic multi-package approval.
 
-The workflow publishes only `./release/<tarball>`. It never publishes from the
+The workflow stages only `./release/<tarball>`. It never stages from the
 repository directory, a package name, a URL, a prior workflow artifact, or a
 locally rebuilt replacement.
 
 ## Stop And Recovery
 
-Stop before publication when source identity, tag ancestry, repository
+Stop before staging when source identity, tag ancestry, repository
 visibility, environment protection, expected owner, target-version absence,
 tests, build output, tarball policy, clean-consumer imports, or Trusted Publishing
 configuration cannot be verified.
 
-If a first-attempt tag run fails before npm accepts the version, preserve the tag
+Before any stage approval, approve none if any coupled stage or its evidence is
+missing or wrong. If the coupled candidate is abandoned, reject all three stages
+with 2FA. Treat every rejected or unusable tagged version as burned: never reuse,
+move, or rerun its tag; prepare newly reviewed versions.
+
+After shared approval but before server approval, stopping preserves live
+client/server compatibility, though the shared version is immutable and any
+replacement needs a new version. After server approval, prioritize the already
+verified client approval because the public mismatch window is open. If that
+client cannot be approved, preserve the failed evidence and prepare newly
+reviewed matching server/client recovery versions; do not reject, rerun, or
+silently substitute the tagged client.
+
+If a first-attempt tag run fails before npm accepts the stage, preserve the tag
 and run as immutable evidence. Fix the source and begin a separately reviewed and
 authorized version/tag plan. Never move, reuse, rerun, or force-update the failed
 tag.
 
-Once npm accepts the version, the immutable release has occurred. Never rerun,
-republish, overwrite, unpublish, or silently substitute a replacement because a
-later registry read is delayed or unavailable.
+Once npm accepts a stage, the tag run and candidate version are consumed under
+this project's attempt-1 rule. Once the operator approves it, the immutable live
+release has occurred. Never rerun, republish, overwrite, unpublish, or silently
+substitute a replacement because a later registry read is delayed or unavailable.
 
 ## Failed-Superseded Recovery
 
 The tag-triggered workflow is single-job and first-attempt-only. If attempt 1
 fails before the tarball is built, the tarball is verified, the clean consumer
-is exercised, or `npm publish` runs, preserve the failed tag and run as immutable
+is exercised, or `npm stage publish` runs, preserve the failed tag and run as immutable
 evidence. The failed version is not an install target and must not be rerun.
 
 Record the failure and prepare a newer version only from a clean tree:
@@ -135,7 +209,7 @@ npm run release:prepare -- <next-version> \
 
 The release identity verifier binds the record to the annotated tag, the exact
 workflow run and commit, the completed failed `publish` job, and the skipped
-tarball, clean-consumer, and publish steps. It independently checks the npm
+tarball, clean-consumer, and staging steps. It independently checks the npm
 version list for registry absence. An attempt-2 run, a failure after packaging
 or publication, an artifact integrity value on a failed record, or a version
 present in npm is rejected. The generated record is `failed-superseded`; the
@@ -145,6 +219,13 @@ next release uses a new version and a new annotated tag.
 
 These records remain evidence, not reusable release inputs:
 
+Eight published versions from 0.2.2 through 0.6.2, excluding the isolated 0.4.0
+baseline, are the pre-convention boundary. Their workflow runs ended in failure
+despite registry publication, which the canonical record schema cannot represent,
+so the incident prose remains their record rather than force-fitting them into
+`docs/release-records.json`. The 0.4.2 publication additionally came from a
+`workflow_dispatch` run on `main`; 0.4.0 is also excluded from reconstruction.
+
 - `v0.2.0` run `29353763609` and `v0.2.1` run `29355823822` failed before
   artifact creation or publication.
 - Protected-main proof runs `29356980492` and `29357632667` diagnosed and then

package/docs/template-lifecycle.md

@@ -0,0 +1,66 @@
+# Built-in template lifecycle
+
+Built-in templates are versioned package data. `src/templates.ts` is the source of truth for their names, presentation copy, cube directives, message taxonomies, roles, flags, short descriptions, and detailed playbooks. A running cube is not a writable upstream for that source.
+
+## Supported lifecycle
+
+### Edit one cube locally
+
+A client with live manage authority for the cube may use the role and cube mutation operations to create or update roles, patch one plain-label role section, or update the cube directive or message taxonomy. Prefer a one-section role patch when one section changes; it preserves every other byte. Local edits affect only that cube. They neither mutate `src/templates.ts` nor create a built-in variant.
+
+Read the canonical role or cube state before editing and read it back after the mutation. The server's canonical state is the result to verify. The package does not provide an automatic local-change-to-template audit ledger or promotion path.
+
+### Promote a trusted local improvement
+
+Promotion is a normal reviewed repository change, not a runtime copy operation:
+
+1. Compare the local text with the current built-in source and identify the behavior and failure it addresses.
+2. Generalize only what applies to new cubes across supported implementations and hosts. Remove repository-host, operator-machine, project, and live-cube details.
+3. Edit `src/templates.ts` and the focused existing tests that pin the affected invariant. Preserve plain-label sections and the role-section round-trip contract.
+4. Review the complete source change through the repository's protected change mechanism. The change history and review are the built-in template's durable audit record.
+5. Publish the reviewed package through the normal immutable shared-package release workflow.
+6. Update client and server to the same exact `borgmcp-shared` version as a matched pair. The client update path rejects a published pair whose exact shared pins differ.
+
+There is no direct promotion from server state, no package write from a running cube, and no unreviewed operator override of a built-in template.
+
+### Apply a released template
+
+New cubes created through an updated client/server pair receive the template data shipped by that exact shared package. An existing non-empty cube remains locally owned: template application does not overwrite its directive (`resolveCubeDirectiveForApply` returns `null`). A release does not rewrite existing roles, directives, or taxonomies. An operator who wants a released improvement in an existing cube applies that specific local edit deliberately and verifies canonical readback.
+
+## Authority and audit
+
+Cube-local authority and package authority are separate:
+
+- A cube-local edit requires the cube's live manage authority and is verified against canonical server readback. It is not evidence that a built-in changed.
+- A built-in edit requires repository change authority, review of the source diff, and the package release gates. Git history, review, immutable tag, and package artifact are its audit chain.
+- A shared release alone is not delivery to users. Client and server must both pin the same exact shared version; neither a range nor one-sided pin movement is supported.
+- Merge, tag, publication, and consumer pin changes remain separate authorized actions. Editing a local cube grants none of them.
+
+## Compatibility, versions, and migration
+
+Built-in templates have no independent runtime version or negotiation protocol. Their version is the `borgmcp-shared` package version that contains them.
+
+A role-text, directive, or taxonomy change ships in a new shared package version. Client and server consume the same exact version. If a change also alters a wire-visible template name or closed protocol acceptance set, follow the protocol change policy: update the exact protocol tag and implementation-neutral conformance vectors, then coordinate both consumers. Text-only playbook improvements do not invent a protocol migration.
+
+Existing cubes are snapshots with local ownership, not replicas. They do not auto-migrate or auto-synchronize. This no-clobber rule avoids erasing operator edits and avoids making package upgrades mutate active coordination policy. Migration, when desired, is an explicit cube-local edit of named fields or sections.
+
+## Validation and conformance
+
+Use the existing focused controls; do not add a second template lifecycle mechanism:
+
+- `test/templates.test.ts` pins the built-in set, expected software-development roles and flags, host-neutral presentation copy, authority/scope language, role-size budgets, Builder minimum-sufficient-change ordering, taxonomy routing, generated/source equality, and no-clobber resolution.
+- `test/role-section.test.ts` pins plain-label parsing, byte-identical parse/serialize for real template roles, and single-section replacement/insertion/deletion without clobbering unrelated text.
+- `test/packed-artifact.test.ts` installs the packed package and verifies the public named-template creation contract and shipped role text from the consumer surface.
+- `CUBE_TEMPLATE_ACCEPTANCE_CONFORMANCE` pins the closed accepted template-name set and invalid-name rejection. Stateful create vectors pin template identity to retry behavior.
+
+Review remains the host-neutrality control: role text must avoid a specific repository host, CI vendor, operating system adapter, local path, or project-only workflow unless the template's documented scope requires it. This is a semantic review question, not a keyword validator. Validate both source and the built/packed consumer artifact because built-ins are delivered through the package.
+
+## Rejected alternatives
+
+- Runtime-editable built-ins: rejected because package source and running server state would become competing authorities without one review or release history.
+- Automatic promotion from a local cube: rejected because live text may contain project-specific policy, host assumptions, temporary experiments, or unreviewed mistakes.
+- Automatic synchronization into existing cubes: rejected because it would clobber local policy and role edits. Existing cubes remain unchanged unless an operator applies a named edit.
+- Separate template versions or compatibility negotiation: rejected because package identity and exact matched consumer pins already provide the delivery boundary; another version axis would add ambiguity without preserving any supported behavior.
+- A new lifecycle validator or audit service: rejected because current behavioral tests, role-section round trips, protected review, and artifact gates already cover the enforceable invariants. Host-neutrality and promotion judgment remain review responsibilities.
+
+Boundary: this document describes current mechanisms and the supported promotion path; it does not itself authorize a release, a local cube mutation, or a consumer pin change.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "borgmcp-shared",
-  "version": "0.10.1",
+  "version": "0.12.0",
   "description": "Shared protocol, domain, templates, and conformance contracts for Borg MCP implementations.",
   "type": "module",
   "main": "./dist/index.js",
@@ -64,7 +64,7 @@
     "verify:sbom": "node scripts/verify-release-sbom.mjs",
     "release:prepare": "node scripts/release-identity.mjs prepare",
     "verify:release-identity": "node scripts/release-identity.mjs verify",
-    "prepack": "npm run check && npm test && npm run build"
+    "prepack": "npm run build && npm run check && npm test"
   },
   "keywords": [
     "borgmcp",

package/src/conformance/adapter.ts

@@ -37,6 +37,7 @@ import {
   type DroneRuntimeMetadata,
 } from '../protocol/index.js';
 import {
+  APPEND_LOG_IDEMPOTENCY_CONFORMANCE,
   CREATE_CUBE_ASSOCIATION_CONFORMANCE,
   CREATE_CUBE_RETRY_CONFORMANCE,
   INVITATION_ARTIFACT_CONFORMANCE,
@@ -361,6 +362,7 @@ export const ADAPTER_CONFORMANCE_FIXTURES = [
   { id: 'security.adapter-boundary-injection', area: 'security' },
   { id: 'security.oversize-request', area: 'security' },
   { id: 'security.cross-cube-isolation', area: 'security' },
+  { id: 'log.append-idempotency', area: 'log' },
   { id: 'log.read-cursor-tuple', area: 'cursor' },
   { id: 'sse.replay-live-transition', area: 'sse' },
   { id: 'cursor.explicit-expiry', area: 'cursor' },
@@ -1323,7 +1325,10 @@ export async function runAdapterConformance(
   await record('security.adapter-boundary-injection', async () => {
     const injectedMessage = "'); DROP TABLE log_entries; --\r\ndata: forged-sse-frame";
     const injectedBody = JSON.stringify(
-      createProtocolEnvelope('inject-b1', { message: injectedMessage }),
+      createProtocolEnvelope('inject-b1', {
+        post_id: '00000000-0000-4000-8000-000000000301',
+        message: injectedMessage,
+      }),
     );
     invariant(
       utf8ByteLength(injectedBody) <= PROTOCOL_LIMIT_CEILINGS.max_request_bytes &&
@@ -1342,7 +1347,10 @@ export async function runAdapterConformance(
     const sentinel = await environment.operations.append(
       credentialB,
       cubeB,
-      createProtocolEnvelope('inject-b2', { message: 'post-injection-sentinel' }),
+      createProtocolEnvelope('inject-b2', {
+        post_id: '00000000-0000-4000-8000-000000000302',
+        message: 'post-injection-sentinel',
+      }),
     );
     expectStatus(sentinel, 201, 'Post-injection sentinel append');
     const read = await environment.operations.read(
@@ -1389,7 +1397,10 @@ export async function runAdapterConformance(
 
   await record('security.oversize-request', async () => {
     const baseBody = JSON.stringify(
-      createProtocolEnvelope('oversize-a1', { message: 'must-not-persist' }),
+      createProtocolEnvelope('oversize-a1', {
+        post_id: '00000000-0000-4000-8000-000000000303',
+        message: 'must-not-persist',
+      }),
     );
     const oversizedBody = baseBody + ' '.repeat(
       Math.max(0, PROTOCOL_LIMIT_CEILINGS.max_request_bytes - utf8ByteLength(baseBody) + 1),
@@ -1417,7 +1428,10 @@ export async function runAdapterConformance(
     const secretAppend = await environment.operations.append(
       credentialB,
       cubeB,
-      createProtocolEnvelope('append-b1', { message: 'principal-b-secret' }),
+      createProtocolEnvelope('append-b1', {
+        post_id: '00000000-0000-4000-8000-000000000304',
+        message: 'principal-b-secret',
+      }),
     );
     expectStatus(secretAppend, 201, 'Principal B append');
     const denied = await environment.operations.read(
@@ -1429,6 +1443,77 @@ export async function runAdapterConformance(
     return { status: 404, code: ErrorCode.NOT_FOUND };
   });
 
+  await record('log.append-idempotency', async () => {
+    const principal = await environment.admin.createPrincipal('append-idempotency');
+    const otherPrincipal = await environment.admin.createPrincipal('append-idempotency-other');
+    const cube = await environment.admin.createCube('append-idempotency');
+    await environment.admin.grantCube(principal, cube);
+    await environment.admin.grantCube(otherPrincipal, cube);
+    const credential = await environment.admin.issueDroneSession(principal);
+    const otherCredential = await environment.admin.issueDroneSession(otherPrincipal);
+    const role = await environment.admin.createRole(cube, {
+      roleClass: 'worker',
+      isHumanSeat: false,
+    });
+    const firstRecipient = await environment.admin.createDrone(principal, cube, role);
+    const secondRecipient = await environment.admin.createDrone(principal, cube, role);
+    const postId = '00000000-0000-4000-8000-000000000313';
+    const initialPayload = {
+      post_id: postId,
+      message: 'once',
+      visibility: 'direct' as const,
+      recipientDroneIds: [firstRecipient.id],
+      class: 'review',
+      to: ['Coordinator'],
+    };
+    const first = await environment.operations.append(
+      credential,
+      cube,
+      createProtocolEnvelope('append-idempotency-first', initialPayload),
+    );
+    expectStatus(first, 201, 'Initial idempotent append');
+    const firstResult = decodeAppendLogResultEnvelope(first.body).payload;
+    invariant(!firstResult.deduplicated, 'Initial append was reported as deduplicated.');
+    for (const [index, vector] of APPEND_LOG_IDEMPOTENCY_CONFORMANCE.entries()) {
+      const payload = {
+        ...initialPayload,
+        ...(vector.mutation === 'message' ? { message: 'changed' } : {}),
+        ...(vector.mutation === 'visibility' ? { visibility: 'broadcast' as const } : {}),
+        ...(vector.mutation === 'recipient_set' ? { recipientDroneIds: [secondRecipient.id] } : {}),
+        ...(vector.mutation === 'resolved_class_routing' ? { class: 'security', to: ['Security Auditor'] } : {}),
+      };
+      const response = await environment.operations.append(
+        vector.actor === 'same' ? credential : otherCredential,
+        cube,
+        createProtocolEnvelope(`append-idempotency-${index}`, payload),
+      );
+      if (vector.expected === 'POST_ID_CONFLICT') {
+        expectError(response, 409, ErrorCode.POST_ID_CONFLICT, vector.name);
+        continue;
+      }
+      expectStatus(response, 201, vector.name);
+      const result = decodeAppendLogResultEnvelope(response.body).payload;
+      invariant(result.deduplicated === (vector.expected === 'deduplicated'), `${vector.name} returned the wrong deduplicated flag.`);
+      invariant(
+        vector.expected === 'deduplicated'
+          ? result.entry.id === firstResult.entry.id
+          : result.entry.id !== firstResult.entry.id,
+        `${vector.name} returned the wrong entry identity.`,
+      );
+    }
+    const read = await environment.operations.read(
+      credential,
+      cube,
+      createProtocolEnvelope('append-idempotency-read', { cursor: null, limit: 10 }),
+    );
+    expectStatus(read, 200, 'Idempotent append read');
+    invariant(
+      decodeReadLogResultEnvelope(read.body).payload.entries.length === 2,
+      'Append collision controls persisted the wrong number of entries.',
+    );
+    return { persisted_entries: 2, stable_entry: true, deduplicated: true, conflicts: 4, cross_author_created: true };
+  });
+
   const entries: Array<{ id: string; created_at: string; message: string }> = [];
   let readCursor: LogCursor | null = null;
   await record('log.read-cursor-tuple', async () => {
@@ -1436,7 +1521,10 @@ export async function runAdapterConformance(
       const response = await environment.operations.append(
         credentialA,
         cubeA,
-        createProtocolEnvelope(`append-a${index + 1}`, { message }),
+        createProtocolEnvelope(`append-a${index + 1}`, {
+          post_id: `00000000-0000-4000-8000-${String(305 + index).padStart(12, '0')}`,
+          message,
+        }),
       );
       expectStatus(response, 201, `Append ${message}`);
       const entry = decodeAppendLogResultEnvelope(response.body).payload.entry;
@@ -1470,7 +1558,10 @@ export async function runAdapterConformance(
       const appendDelta = environment.operations.append(
         credentialA,
         cubeA,
-        createProtocolEnvelope('append-a4', { message: 'delta' }),
+        createProtocolEnvelope('append-a4', {
+          post_id: '00000000-0000-4000-8000-000000000308',
+          message: 'delta',
+        }),
       );
       expectStatus(await appendDelta, 201, 'Transition append');
     } finally {
@@ -1494,7 +1585,10 @@ export async function runAdapterConformance(
       const epsilonResponse = await environment.operations.append(
         credentialA,
         cubeA,
-        createProtocolEnvelope('append-a5', { message: 'epsilon' }),
+        createProtocolEnvelope('append-a5', {
+          post_id: '00000000-0000-4000-8000-000000000309',
+          message: 'epsilon',
+        }),
       );
       expectStatus(epsilonResponse, 201, 'Live append');
       const epsilon = logEvent(await within(noDuplicate, 'Live epsilon event', streamDeadlineMs), 'Live append');
@@ -2014,6 +2108,7 @@ export async function runAdapterConformance(
         cubeA,
         createProtocolEnvelope('evict-direct-target', {
           message: 'must-not-fan-out',
+          post_id: '00000000-0000-4000-8000-000000000310',
           visibility: 'direct',
           recipientDroneIds: [evictedDrone.id],
         }),
@@ -2203,7 +2298,10 @@ export async function runAdapterConformance(
     const attributed = await environment.operations.append(
       evictedSession,
       roleContractCube,
-      createProtocolEnvelope('role-delete-attribution', { message: 'attribution survives' }),
+      createProtocolEnvelope('role-delete-attribution', {
+        post_id: '00000000-0000-4000-8000-000000000311',
+        message: 'attribution survives',
+      }),
     );
     expectStatus(attributed, 201, 'Pre-delete attributed log');
     const attributedEntry = decodeAppendLogResultEnvelope(attributed.body).payload.entry;
@@ -2867,7 +2965,10 @@ export async function runAdapterConformance(
     const append = await environment.operations.append(
       creator.credential,
       cube,
-      createProtocolEnvelope('delete-log', { message: 'deleted with cube' }),
+      createProtocolEnvelope('delete-log', {
+        post_id: '00000000-0000-4000-8000-000000000312',
+        message: 'deleted with cube',
+      }),
     );
     expectStatus(append, 201, 'Deletion fixture log');
     const entry = decodeAppendLogResultEnvelope(append.body).payload.entry;