Initial libmcp 1.0.0

1 files changed, 235 insertions, 0 deletions

diff --git a/docs/spec.md b/docs/spec.md
new file mode 100644
index 0000000..e31d073
--- /dev/null
+++ b/docs/spec.md
@@ -0,0 +1,235 @@
+# libmcp Spec
+
+## Status
+
+This document is the normative specification for `libmcp` `1.0.0`.
+
+`libmcp` is the reusable operational spine for hardened MCP servers. It is not
+an application framework, a domain schema repository, or a mandate that every
+MCP use one transport topology.
+
+## Problem Statement
+
+Several MCPs now share the same operational posture:
+
+- stable public host
+- disposable worker
+- explicit replay contracts
+- blue/green rollout and hot reinstall
+- health and telemetry as first-class operational surfaces
+- recovery tests for process churn and replay safety
+- model-facing porcelain output instead of backend dumps
+
+This library exists to make that posture reusable and versioned.
+
+## Scope
+
+`libmcp` owns the shared control plane:
+
+- replay contract vocabulary
+- typed fault taxonomy
+- request identity and JSON-RPC frame helpers
+- health and telemetry base schemas
+- JSONL telemetry support
+- model UX doctrine primitives
+- normalization helpers
+- hardening test support
+- canonical `$mcp-bootstrap` skill
+
+`libmcp` explicitly does not own:
+
+- domain tools
+- backend-specific request routing
+- backend-specific warm-up heuristics
+- a mandatory public transport shape
+- an obligation that every tool batch or support preview modes
+
+## Supported Topologies
+
+The library must support both of these shapes:
+
+1. stable host owning the public MCP session and talking to a private worker RPC
+2. stable host owning the public MCP session and proxying to a worker MCP server
+
+The invariants are standard. The wire shape is not.
+
+## Core Contracts
+
+### Replay
+
+Every request surface must carry an explicit replay contract.
+
+The shared vocabulary is:
+
+- `Convergent`
+- `ProbeRequired`
+- `NeverReplay`
+
+`Convergent` means repeated execution is safe because it converges on the same
+observable result.
+
+`ProbeRequired` means the host may only replay after proving that a previous
+attempt did not already take effect or after reconstructing enough state to make
+the replay safe.
+
+`NeverReplay` means the request must fail rather than run again automatically.
+
+### Faults
+
+Failures must be represented as typed operational faults, not merely as text.
+
+The baseline taxonomy must distinguish at least:
+
+- transport failure
+- process failure
+- protocol failure
+- timeout
+- downstream response failure
+- resource exhaustion
+- replay exhaustion
+- rollout disruption
+- invariant breach
+
+Each fault must carry enough structure to drive:
+
+- retry or restart policy
+- health reporting
+- telemetry aggregation
+- model-facing shaping
+
+### Health
+
+Every `libmcp` consumer should be able to expose a common operational health
+core.
+
+The base health payload includes:
+
+- lifecycle state
+- generation
+- uptime
+- consecutive failures
+- restart count
+- rollout state
+- last fault
+
+Consumers may extend it with domain-specific fields.
+
+### Telemetry
+
+Every `libmcp` consumer should be able to expose a common operational telemetry
+core and emit append-only event telemetry.
+
+The base telemetry payload includes:
+
+- request counts
+- success and error counts
+- retry counts
+- per-method aggregates
+- last method error
+- recent restart-triggering fault
+
+The JSONL event path is part of the support surface because postmortem analysis
+of hot paths and error concentrations is a first-class operational need.
+
+## Model UX Doctrine
+
+The library contract includes model-facing behavior.
+
+### Porcelain by Default
+
+Nontrivial tools should default to `render=porcelain`.
+
+Structured `render=json` must remain available, but it is opt-in unless a tool
+is intrinsically structured and tiny.
+
+Porcelain output should be:
+
+- line-oriented
+- deterministic
+- bounded
+- summary-first
+- suitable for long-running agent loops
+
+The library should therefore provide reusable primitives for:
+
+- render mode selection
+- bounded/truncated text shaping
+- stable note emission
+- path rendering
+- common porcelain patterns
+
+`libmcp` does not require a universal detail taxonomy like
+`summary|compact|full`. Consumers may add extra detail controls when their tool
+surface actually needs them.
+
+### Normalization
+
+The library should reduce trivial model-facing friction where the semantics are
+still unambiguous.
+
+Examples:
+
+- field aliases
+- integer-like strings
+- `file://` URIs
+- consistent path-style normalization
+- method-token normalization where tools have canonical names and common aliases
+
+### Failure Shaping
+
+Transient operational failures should be surfaced in a way that helps a model
+recover:
+
+- concise message
+- typed category underneath
+- retry hint when retry is plausible
+- no raw backend spew by default
+
+### Optional Nice-to-Haves
+
+These are good patterns but are not part of the minimum contract:
+
+- `dry_run` or preview modes
+- batching for tools that do not naturally batch
+- backend-specific uncertainty notes
+
+## Canonical Skill Ownership
+
+This repository is the canonical owner of `$mcp-bootstrap`.
+
+The skill is versioned library collateral, not an external convenience file.
+Maintaining it is part of the `libmcp` contract.
+
+The rule is:
+
+- the source of truth lives in this repository
+- local Codex installation should point at it by symlink
+- the skill must stay aligned with the current public doctrine of the library
+
+## Versioning
+
+`libmcp` `1.0.0` is defined by the first steady integration into
+`adequate_rust_mcp`.
+
+The `1.0.0` contract means:
+
+- the extracted seam proved real in `adequate_rust_mcp`
+- the skill and spec align with the implementation
+- the model UX doctrine is embodied in helpers and tests, not just prose
+- the core contracts are stable enough to be depended on directly
+
+`fidget_spinner` is explicitly out of scope for `1.0.0`.
+
+## Immediate Implementation Sequence
+
+1. Create the library workspace and migrate the design note into this spec.
+2. Implement the MVP core:
+   - replay contracts
+   - fault taxonomy
+   - request identity and JSON-RPC helpers
+   - health and telemetry base types
+   - telemetry log support
+   - render and normalization helpers
+3. Port `adequate_rust_mcp` onto the shared pieces and stabilize.
+4. Lock `libmcp` to `1.0.0`.
+5. Revisit deeper runtime lifting only after the first consumer is truly clean.