From 1a02928c3d0d25a96b0b893c9baa0bf16f8aa6da Mon Sep 17 00:00:00 2001
From: Ethan <ethanj@gmail.com>
Date: Sat, 30 May 2026 15:27:43 -0700
Subject: [PATCH] docs: add validation-boundary map and clarify MCP as a thin
 adapter

Two documentation additions that make implicit contracts explicit for
public readers, in response to external review feedback.

README "Validation boundary" section: maps what this public repository's
CI proves on its own (the per-PR jobs plus package/release-context checks)
versus what is validated in separate internal repositories and what is not
yet public. Public-safe: describes external validation by role without
naming non-public repositories, per the docs public-safety policy. The
intent is a map, not a ranking.

mcp-server README "Authoritative contract" section: states that the REST
API and SDK type surface are the authoritative memory contract, and that
this MCP server is a thin callable-tool adapter over it. JSON-stringified
tool-result text is a transport convenience, not a separate audit surface;
consumers should read the REST/SDK projection for evidence/audit purposes.

Gates: docs-contract, repo-hygiene, security-compliance all pass;
git diff --check clean.
---
 README.md                     | 48 +++++++++++++++++++++++++++++++++++
 packages/mcp-server/README.md | 14 ++++++++++
 2 files changed, 62 insertions(+)

diff --git a/README.md b/README.md
index 2babe55..bc95dc6 100644
--- a/README.md
+++ b/README.md
@@ -117,6 +117,54 @@ Until latency benchmarks are linked from the docs, treat the engine as
 "designed for single-digit-ms local retrieval on a developer laptop at typical
 agent corpus sizes" — a design target, not a guarantee.
 
+## Validation boundary
+
+Different kinds of proof live in different places. This map states what this
+public repository's CI proves on its own and what is validated elsewhere, so
+readers do not assume the public repo independently proves every product claim.
+
+**Proven in this repository's public CI (every pull request):**
+
+- repo hygiene
+- package metadata checks
+- affected build, typecheck, lint, and self-contained package tests (Node 22
+  and 24)
+- code-health gates
+- package `pack` dry-run plus tarball-shape verification
+- docs contract (install commands, package status labels, and smoke rows stay
+  in sync)
+- public integration smoke
+- security compliance
+
+**Also in this repository, run in package or release contexts (not the per-PR
+affected lane):**
+
+- Core OpenAPI generation and drift check (`generate:openapi` / `check:openapi`)
+- Core API schema tests (Schemathesis)
+- Core Docker image smoke (runs in the Docker image publish workflow)
+- DB-backed Core tests, which require Postgres/pgvector provisioning
+
+**Validated outside this repository:**
+
+- hosted-service behavior
+- release orchestration and marketplace operations
+- full benchmark and evaluation harnesses, including performance and cost
+  reproduction
+- global, end-to-end product behavior
+
+These run in separate internal repositories and surface as public artifacts when
+they are ready to publish.
+
+**Not yet public (planned):**
+
+- reproducible benchmark artifacts and raw evaluation harnesses, including the
+  BEAM and LoCoMo suites referenced in the headline results
+- any global lifecycle fixtures not currently published
+
+This is a map, not a ranking: external or not-yet-public validation is not
+presented as equivalent to public CI from a reader-trust standpoint. It simply
+lives in a different place.
+
 ## Quickstart
 
 For the full walkthrough, see the
diff --git a/packages/mcp-server/README.md b/packages/mcp-server/README.md
index c5d2e84..10bc408 100644
--- a/packages/mcp-server/README.md
+++ b/packages/mcp-server/README.md
@@ -7,6 +7,20 @@ MCP server that exposes [AtomicMemory core](../../packages/core) as four tools t
 - `memory_package` — token-budgeted context package
 - `memory_list` — list recent scoped memories
 
+## Authoritative contract
+
+The REST API and the [`@atomicmemory/sdk`](../../packages/sdk) type surface are
+the authoritative memory contract — provenance, scope, mutation decisions,
+lineage, retrieval scores, and context-package metadata are defined there. This
+MCP server is a thin callable-tool adapter over that contract.
+
+Tool results are returned as JSON-stringified text for host compatibility, so
+the text payload is a transport convenience, not a separate audit surface. For
+evidence or audit purposes — inspecting why a memory exists, what it replaced,
+or what shaped a retrieval — read the REST/SDK projection rather than parsing
+MCP tool text. New memory semantics land in Core and the SDK first; this adapter
+exposes them, it does not define them.
+
 ## Status: package entrypoint
 
 This package is intended to publish as `@atomicmemory/mcp-server`. Cursor and