@feltdb/core 0.8.8 → 0.9.0

package/dist/create/server-source/crates/feltdb-server/src/control_plane.rs

@@ -0,0 +1,845 @@
+//! The human control plane's server surface.
+//!
+//! FeltDB has three ways of being used, and they are not three implementations:
+//!
+//! | surface | who | interface |
+//! | --- | --- | --- |
+//! | application | code | the public API |
+//! | agent | tools | the declared/projection interface |
+//! | human | Studio | the same public API |
+//!
+//! Studio is the third of those, not a fourth implementation of the first. This
+//! module holds what the human surface needs and the other two did not already
+//! expose: the declared capability set Studio reads before it renders anything,
+//! and the JSON projections of the state model that make revisions, semantic
+//! diffs, conflict classification and reconciliation reachable over HTTP.
+//!
+//! # Why the capability set is data
+//!
+//! A control plane that draws a button for an operation its backend cannot
+//! perform is worse than one that draws nothing: the button is a claim. So the
+//! server declares what it can do, [`capabilities`] is the only source of that
+//! claim, and Studio renders an explicit *unsupported* state for everything the
+//! declaration does not mark available. Nothing in the UI may assume a
+//! capability the server did not declare, and nothing here may declare one the
+//! server does not implement — [`capabilities`] names the route that serves each
+//! entry so the claim can be checked mechanically.
+//!
+//! # Why the state projections live here
+//!
+//! [`feltdb::state_model`] is expressed in Rust types that do not survive
+//! `serde_json` unchanged. `ReconciliationPlan::path_overrides` is a
+//! `BTreeMap<Vec<PathComponent>, Value>`, and JSON has no non-string keys; a
+//! path is a sequence of *typed* components, and flattening it to `a.b.0` would
+//! lose the object-key/array-index distinction that
+//! [`feltdb::state_model::path_relation`] depends on. The projections here are
+//! therefore explicit and lossless: a path is a JSON array whose string members
+//! are object keys and whose number members are array indices.
+
+use std::collections::BTreeMap;
+
+use feltdb::state_model::{
+    ChangeKind, ConflictClass, ConflictClassification, PathComponent, ReconciliationPlan,
+    SemanticDiff, StateId, StateRevision,
+};
+use feltdb::{Operation, OperationType};
+use serde::{Deserialize, Serialize};
+use serde_json::{json, Value};
+
+// ============================================================================
+// Declared capabilities
+// ============================================================================
+
+/// Whether the instance can perform a control-plane capability.
+///
+/// `Partial` exists because the alternative is dishonest in both directions.
+/// Record history is the case that forced it: revisions are minted by some
+/// write paths and not others, so declaring the capability `Available` would
+/// promise history for records that have none, and declaring it `Unsupported`
+/// would deny history that demonstrably exists.
+#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize)]
+#[serde(rename_all = "snake_case")]
+pub enum CapabilityStatus {
+    /// The server implements this, and the named surface serves it.
+    Available,
+    /// The server implements this for some inputs only. `note` says which.
+    Partial,
+    /// No FeltDB contract performs this. Studio must render it as unavailable.
+    Unsupported,
+}
+
+/// One control-plane capability, as the server declares it.
+///
+/// Serialized outward only. The server is the sole author of this document;
+/// nothing reads one back in, and giving it a `Deserialize` would invite a
+/// caller to supply the claim the server is supposed to be making.
+#[derive(Clone, Debug, Serialize)]
+pub struct ControlPlaneCapability {
+    /// Stable identifier. Studio gates on this, never on a route string.
+    pub id: &'static str,
+    /// Studio navigation area this belongs to.
+    pub area: &'static str,
+    /// Human-readable name, used as the capability's row in the matrix.
+    pub title: &'static str,
+    /// What the instance can actually do.
+    pub status: CapabilityStatus,
+    /// The public routes that serve it. Empty exactly when nothing serves it.
+    pub surface: &'static [&'static str],
+    /// Why the status is what it is. Required for everything not `Available`.
+    pub note: &'static str,
+}
+
+/// The capabilities this server implements, in navigation order.
+///
+/// This is the whole claim. `surface` is not decoration: an `Available` or
+/// `Partial` entry names routes that exist, an `Unsupported` entry names none,
+/// and `control_plane_declaration_is_honest` in this module's tests enforces
+/// both halves.
+pub const CAPABILITIES: &[ControlPlaneCapability] = &[
+    ControlPlaneCapability {
+        id: "overview.instance",
+        area: "overview",
+        title: "Instance, authority, runtime and storage status",
+        status: CapabilityStatus::Available,
+        surface: &["GET /v1/control-plane/overview"],
+        note: "",
+    },
+    ControlPlaneCapability {
+        id: "data.collections.list",
+        area: "data",
+        title: "List collections",
+        status: CapabilityStatus::Available,
+        surface: &["GET /v1/application/schema"],
+        note: "",
+    },
+    ControlPlaneCapability {
+        id: "data.records.browse",
+        area: "data",
+        title: "Browse records",
+        status: CapabilityStatus::Available,
+        surface: &["GET /v1/data/{collection}"],
+        note: "",
+    },
+    ControlPlaneCapability {
+        id: "data.records.inspect",
+        area: "data",
+        title: "Inspect a complete record",
+        status: CapabilityStatus::Available,
+        surface: &["GET /v1/data/{collection}/{id}"],
+        note: "",
+    },
+    ControlPlaneCapability {
+        id: "data.records.create",
+        area: "data",
+        title: "Create record",
+        status: CapabilityStatus::Partial,
+        surface: &[
+            "GET /v1/control-plane/actions",
+            "POST /api/applications/{application_id}/revisions/{revision_id}/actions/{action}",
+        ],
+        note: "Only through an action the application contract declares. A collection with no declared create action cannot be written to, by Studio or by anything else.",
+    },
+    ControlPlaneCapability {
+        id: "data.records.update",
+        area: "data",
+        title: "Update record",
+        status: CapabilityStatus::Partial,
+        surface: &[
+            "GET /v1/control-plane/actions",
+            "POST /api/applications/{application_id}/revisions/{revision_id}/actions/{action}",
+        ],
+        note: "Only through a declared update action. The action accepts `if_version` for compare-and-set; a stale version is refused, not overwritten.",
+    },
+    ControlPlaneCapability {
+        id: "data.records.delete",
+        area: "data",
+        title: "Delete record",
+        status: CapabilityStatus::Partial,
+        surface: &[
+            "GET /v1/control-plane/actions",
+            "POST /api/applications/{application_id}/revisions/{revision_id}/actions/{action}",
+        ],
+        note: "Only through a declared delete action.",
+    },
+    ControlPlaneCapability {
+        id: "data.records.sort",
+        area: "data",
+        title: "Sort a browsed collection",
+        status: CapabilityStatus::Unsupported,
+        surface: &[],
+        note: "The inspection route lists records in record-key order and takes no sort parameter, so the browser cannot offer one and does not pretend to. Ordered, filtered reads do exist for applications through `POST /v1/query`; using them here would mean moving the browser to that route, which it has not been.",
+    },
+    ControlPlaneCapability {
+        id: "data.schema.inspect",
+        area: "data",
+        title: "Schema inspection",
+        status: CapabilityStatus::Available,
+        surface: &["GET /v1/application/schema", "GET /v1/application"],
+        note: "",
+    },
+    ControlPlaneCapability {
+        id: "data.indexes.inspect",
+        area: "data",
+        title: "Index inspection",
+        status: CapabilityStatus::Available,
+        surface: &["GET /v1/control-plane/indexes"],
+        note: "",
+    },
+    ControlPlaneCapability {
+        id: "data.indexes.rebuild",
+        area: "data",
+        title: "Rebuild an index",
+        status: CapabilityStatus::Available,
+        surface: &["POST /v1/control-plane/indexes/rebuild"],
+        note: "",
+    },
+    ControlPlaneCapability {
+        id: "data.records.history",
+        area: "state",
+        title: "Record version history",
+        status: CapabilityStatus::Partial,
+        surface: &["GET /v1/state/resources/{resource}/history"],
+        note: "A revision is minted by the direct-authority write path and reconstructed by replication apply. Transactions committed through declared application actions advance the authority revision without minting a state revision, so records written that way have no revision history to show.",
+    },
+    ControlPlaneCapability {
+        id: "state.resources.list",
+        area: "state",
+        title: "State resources and heads",
+        status: CapabilityStatus::Available,
+        surface: &["GET /v1/state/resources"],
+        note: "",
+    },
+    ControlPlaneCapability {
+        id: "state.history",
+        area: "state",
+        title: "State history: revisions, parents, authority, timestamps",
+        status: CapabilityStatus::Available,
+        surface: &[
+            "GET /v1/state/resources/{resource}/history",
+            "GET /v1/state/revisions/{id}",
+        ],
+        note: "",
+    },
+    ControlPlaneCapability {
+        id: "state.diff.semantic",
+        area: "state",
+        title: "Semantic state diff",
+        status: CapabilityStatus::Available,
+        surface: &["POST /v1/state/diff"],
+        note: "",
+    },
+    ControlPlaneCapability {
+        id: "state.conflict.classify",
+        area: "state",
+        title: "Conflict classification",
+        status: CapabilityStatus::Available,
+        surface: &["POST /v1/state/conflicts"],
+        note: "",
+    },
+    ControlPlaneCapability {
+        id: "state.reconciliation.plan",
+        area: "state",
+        title: "Reconciliation plan and preview",
+        status: CapabilityStatus::Available,
+        surface: &["POST /v1/state/reconciliation/plan"],
+        note: "",
+    },
+    ControlPlaneCapability {
+        id: "state.reconciliation.execute",
+        area: "state",
+        title: "Reconciliation execution",
+        status: CapabilityStatus::Available,
+        surface: &["POST /v1/state/reconciliation/execute"],
+        note: "",
+    },
+    ControlPlaneCapability {
+        id: "state.branch.heads",
+        area: "state",
+        title: "Named branches and branch heads",
+        status: CapabilityStatus::Unsupported,
+        surface: &[],
+        note: "The state model deliberately owns history, not currentness: it has no branch refs. `GET /v1/state/resources` reports a head per resource, which is the newest revision by sequence, not a named branch.",
+    },
+    ControlPlaneCapability {
+        id: "provenance.record",
+        area: "state",
+        title: "Who and what changed a record",
+        status: CapabilityStatus::Available,
+        surface: &["GET /v1/control-plane/provenance/{collection}/{id}"],
+        note: "",
+    },
+    ControlPlaneCapability {
+        id: "provenance.transactions",
+        area: "operations",
+        title: "Recent commits and the actor that made them",
+        status: CapabilityStatus::Available,
+        surface: &["GET /v1/control-plane/transactions"],
+        note: "Answered from a bounded window over recent commits; older ones are in the durable transaction log, which no route reads back. Instance-scoped: it requires `state:read` on the instance and is not filtered per application, which makes it an operator surface rather than an application-member one.",
+    },
+    ControlPlaneCapability {
+        id: "agents.list",
+        area: "agents",
+        title: "Agents registered against an application",
+        status: CapabilityStatus::Available,
+        surface: &["GET /v1/control-plane/agents"],
+        note: "",
+    },
+    ControlPlaneCapability {
+        id: "agents.identity",
+        area: "agents",
+        title: "Agent identity, access, activity and sessions",
+        status: CapabilityStatus::Available,
+        surface: &["GET /v1/control-plane/agents/{agent_id}"],
+        note: "",
+    },
+    ControlPlaneCapability {
+        id: "agents.register",
+        area: "agents",
+        title: "Register an agent and grant it capabilities",
+        status: CapabilityStatus::Available,
+        surface: &[
+            "POST /api/applications/{application_id}/principals",
+            "POST /api/principals/{principal_id}/capabilities",
+        ],
+        note: "",
+    },
+    ControlPlaneCapability {
+        id: "agents.work",
+        area: "agents",
+        title: "Give an agent bounded, durable work",
+        status: CapabilityStatus::Available,
+        surface: &[
+            "POST /v1/workloads",
+            "GET /v1/workloads",
+            "GET /v1/workloads/{id}",
+            "GET /v1/workloads/{id}/history",
+            "GET /v1/workloads/{id}/result",
+            "POST /v1/workloads/{id}/cancel",
+            "POST /v1/workloads/{id}/retry",
+        ],
+        note: "",
+    },
+    ControlPlaneCapability {
+        id: "agents.work.review_gate",
+        area: "agents",
+        title: "Review and approve an agent's proposed data changes before they apply",
+        status: CapabilityStatus::Unsupported,
+        surface: &[],
+        note: "There is no propose-then-approve step for record changes. A workload executes when a worker claims it, and an agent that may write, writes. A human can bound the work in advance (capabilities, scope, `not_before`) and can cancel it, and every change it makes is attributable afterwards — but Studio cannot stage an agent's record changes for approval, so it does not offer to. Contract changes are different: `/v1/proposals` has a real validate/preview/approve gate, and it governs the application contract rather than its data.",
+    },
+    ControlPlaneCapability {
+        id: "agents.sessions",
+        area: "agents",
+        title: "Agent sessions and the worker executing them",
+        status: CapabilityStatus::Available,
+        surface: &["GET /v1/control-plane/agents/{agent_id}", "GET /v1/workers"],
+        note: "",
+    },
+    ControlPlaneCapability {
+        id: "agents.authorization_decisions",
+        area: "agents",
+        title: "Authorization decisions taken for an agent",
+        status: CapabilityStatus::Available,
+        surface: &["GET /v1/control-plane/agents/{agent_id}"],
+        note: "",
+    },
+    ControlPlaneCapability {
+        id: "agents.task_context",
+        area: "agents",
+        title: "An agent's current task or reasoning context",
+        status: CapabilityStatus::Partial,
+        surface: &["GET /v1/workloads/{id}", "GET /v1/workloads/{id}/context"],
+        note: "A workload carries the input, capability snapshot and checkpoints its own protocol records. FeltDB stores no goal text, prompt, or model context of its own, so Studio shows the workload's declared input and nothing it did not receive.",
+    },
+    ControlPlaneCapability {
+        id: "operations.recent",
+        area: "operations",
+        title: "Recent writes and their operation records",
+        status: CapabilityStatus::Available,
+        surface: &["GET /v1/control-plane/operations"],
+        note: "Bounded by the change log the instance retains — compaction removes older operations, so this is recent activity, not an operation archive. Instance-scoped: it requires `state:read` on the instance and is not filtered per application, which makes it an operator surface rather than an application-member one.",
+    },
+    ControlPlaneCapability {
+        id: "operations.rejections",
+        area: "operations",
+        title: "Rejected operations: CAS failures and stale versions",
+        status: CapabilityStatus::Partial,
+        surface: &["POST /api/applications/{application_id}/revisions/{revision_id}/actions/{action}"],
+        note: "A refusal is returned to its caller as a structured PRECONDITION_FAILED with the expected and actual version. The instance keeps no durable log of refusals, so Studio can show the refusals it caused and cannot show refusals other callers caused.",
+    },
+    ControlPlaneCapability {
+        id: "operations.events",
+        area: "operations",
+        title: "Live state event stream",
+        status: CapabilityStatus::Available,
+        surface: &["GET /v1/events"],
+        note: "",
+    },
+    ControlPlaneCapability {
+        id: "operations.transaction_status",
+        area: "operations",
+        title: "One transaction: status, idempotency and attribution",
+        status: CapabilityStatus::Available,
+        surface: &["GET /v1/control-plane/transactions/{transaction_id}"],
+        note: "",
+    },
+    ControlPlaneCapability {
+        id: "operations.correlation_id",
+        area: "operations",
+        title: "Follow one request across operations and events",
+        status: CapabilityStatus::Unsupported,
+        surface: &[],
+        note: "A `request_id` is minted per error response and carried nowhere else: successful responses have none, and no operation, event or transaction records one. There is no id to filter a stream by, so Studio offers no correlation filter. A transaction id is the identifier that does span a commit's operations, and `GET /v1/control-plane/transactions/{transaction_id}` follows it.",
+    },
+    ControlPlaneCapability {
+        id: "operations.audit_log",
+        area: "operations",
+        title: "Searchable audit log",
+        status: CapabilityStatus::Unsupported,
+        surface: &[],
+        note: "The audit log is append-only and write-only from the server's side: it is a security artifact read out of band, and no route serves it back.",
+    },
+    ControlPlaneCapability {
+        id: "replication.health",
+        area: "replication",
+        title: "Authorities, peers, causal position and replication health",
+        status: CapabilityStatus::Available,
+        surface: &["GET /v1/control-plane/replication"],
+        note: "",
+    },
+    ControlPlaneCapability {
+        id: "applications.list",
+        area: "applications",
+        title: "Applications and runtime status",
+        status: CapabilityStatus::Available,
+        surface: &["GET /v1/control-plane/applications"],
+        note: "",
+    },
+    ControlPlaneCapability {
+        id: "monitoring.metrics",
+        area: "monitoring",
+        title: "Requests, rejections, storage and state growth",
+        status: CapabilityStatus::Available,
+        surface: &["GET /v1/control-plane/overview", "GET /metrics"],
+        note: "",
+    },
+    ControlPlaneCapability {
+        id: "monitoring.latency",
+        area: "monitoring",
+        title: "Request latency distribution",
+        status: CapabilityStatus::Unsupported,
+        surface: &[],
+        note: "The instance counts requests, sheds and deadline overruns; it records no latency histogram, and a chart drawn from counters would be invented.",
+    },
+    ControlPlaneCapability {
+        id: "settings.instance",
+        area: "settings",
+        title: "Instance identity, storage, authority and limits",
+        status: CapabilityStatus::Available,
+        surface: &["GET /v1/control-plane/overview", "GET /v1/diagnostics"],
+        note: "",
+    },
+    ControlPlaneCapability {
+        id: "settings.mutate",
+        area: "settings",
+        title: "Change instance configuration",
+        status: CapabilityStatus::Unsupported,
+        surface: &[],
+        note: "Configuration is supplied at start-up by the deployment. No route mutates it, so Studio shows configuration and does not offer to edit it.",
+    },
+    ControlPlaneCapability {
+        id: "developer.tool_projection",
+        area: "developer",
+        title: "Projected agent tool or MCP configuration",
+        status: CapabilityStatus::Unsupported,
+        surface: &[],
+        note: "FeltDB projects no agent tool manifest of its own. What it does publish is its own interface description at `/v1/openapi.json`, which an agent can read to discover what an application declares and what it may call. Emitting a tool configuration Studio invented, for a projection FeltDB does not serve, would be a claim about an interface that does not exist.",
+    },
+    ControlPlaneCapability {
+        id: "developer.access",
+        area: "developer",
+        title: "Connection details, SDK and CLI snippets",
+        status: CapabilityStatus::Available,
+        surface: &["GET /v1/control-plane/developer"],
+        note: "",
+    },
+];
+
+/// The declared capability set, as the capabilities route serves it.
+pub fn capabilities() -> Value {
+    json!({
+        "contract": "feltdb.control-plane.capabilities",
+        "version": 1,
+        "capabilities": CAPABILITIES,
+    })
+}
+
+// ============================================================================
+// State model projections
+// ============================================================================
+
+/// A semantic path as JSON: object keys are strings, array indices are numbers.
+///
+/// The distinction is preserved rather than rendered, because `path_relation`
+/// compares components structurally and `["a","0"]` is not `["a",0]`.
+pub fn path_to_json(path: &[PathComponent]) -> Value {
+    Value::Array(
+        path.iter()
+            .map(|component| match component {
+                PathComponent::Key(key) => Value::String(key.clone()),
+                PathComponent::Index(index) => json!(index),
+            })
+            .collect(),
+    )
+}
+
+/// Reads a path back. Refuses anything that is not a string or an index.
+pub fn path_from_json(value: &Value) -> Result<Vec<PathComponent>, String> {
+    let members = value
+        .as_array()
+        .ok_or_else(|| "a path must be an array".to_string())?;
+    members
+        .iter()
+        .map(|member| match member {
+            Value::String(key) => Ok(PathComponent::Key(key.clone())),
+            Value::Number(number) => number
+                .as_u64()
+                .map(|index| PathComponent::Index(index as usize))
+                .ok_or_else(|| "an array index must be a non-negative integer".to_string()),
+            _ => Err("a path component must be an object key or an array index".to_string()),
+        })
+        .collect()
+}
+
+fn change_kind_name(kind: &ChangeKind) -> &'static str {
+    match kind {
+        ChangeKind::Added => "added",
+        ChangeKind::Removed => "removed",
+        ChangeKind::Changed => "changed",
+    }
+}
+
+fn conflict_class_name(class: &ConflictClass) -> &'static str {
+    match class {
+        ConflictClass::Independent => "independent",
+        ConflictClass::Convergent => "convergent",
+        ConflictClass::Conflict => "conflict",
+    }
+}
+
+/// A semantic diff, in the order the contract produced it.
+pub fn diff_to_json(diff: &SemanticDiff) -> Value {
+    json!({
+        "contract": "feltdb.state.diff",
+        "changes": diff.changes.iter().map(|change| json!({
+            "path": path_to_json(&change.path),
+            "kind": change_kind_name(&change.kind),
+            "old_value": change.old_value,
+            "new_value": change.new_value,
+        })).collect::<Vec<_>>(),
+        "is_read_only": diff.is_read_only,
+    })
+}
+
+/// A conflict classification, per path and overall.
+pub fn classification_to_json(classification: &ConflictClassification) -> Value {
+    json!({
+        "contract": "feltdb.state.conflict",
+        "overall": conflict_class_name(&classification.overall),
+        "path_conflicts": classification.path_conflicts.iter().map(|conflict| json!({
+            "path": path_to_json(&conflict.path),
+            "classification": conflict_class_name(&conflict.classification),
+            "base_value": conflict.base_value,
+            "left_value": conflict.left_value,
+            "right_value": conflict.right_value,
+        })).collect::<Vec<_>>(),
+    })
+}
+
+/// A revision, without its content.
+///
+/// History listings use this: a resource's history is a chain of facts about
+/// *when and by whom*, and carrying every revision's full content would make
+/// listing a resource cost as much as reading all of it.
+pub fn revision_summary_to_json(revision: &StateRevision) -> Value {
+    json!({
+        "state_id": revision.id.as_hex(),
+        "resource": revision.resource,
+        "content_id": revision.content_id.as_hex(),
+        "parent_id": revision.parent_id.as_ref().map(StateId::as_hex),
+        "sequence": revision.sequence,
+        "authority": revision.authority,
+        "timestamp_ms": revision.timestamp_ms,
+        "metadata": revision.metadata,
+    })
+}
+
+/// A revision with its content, and whether it still verifies against its id.
+///
+/// `integrity_verified` is reported rather than assumed. The store checks
+/// integrity when a revision is written; a reader that shows history to a human
+/// re-checks it, because the one thing worse than no history is history that
+/// silently does not match what it claims to record.
+pub fn revision_to_json(revision: &StateRevision, content: Value) -> Value {
+    let mut document = revision_summary_to_json(revision);
+    if let Some(object) = document.as_object_mut() {
+        object.insert("content".into(), content);
+        object.insert(
+            "integrity_verified".into(),
+            json!(revision.verify_integrity()),
+        );
+    }
+    document
+}
+
+/// The plan a caller asked for.
+///
+/// `parent_choice` is a branch name rather than a boolean because `true` does
+/// not say *left* to anyone reading a request body, and choosing the wrong
+/// branch silently discards the other one's changes.
+#[derive(Clone, Debug, Deserialize)]
+pub struct ReconciliationPlanRequest {
+    pub base: String,
+    pub left: String,
+    pub right: String,
+    pub parent_choice: String,
+    #[serde(default)]
+    pub overrides: Vec<PathOverrideRequest>,
+}
+
+/// One path the caller decides explicitly, whatever the branches hold there.
+#[derive(Clone, Debug, Deserialize)]
+pub struct PathOverrideRequest {
+    pub path: Value,
+    pub value: Value,
+}
+
+impl ReconciliationPlanRequest {
+    /// Builds the plan this request names.
+    ///
+    /// Every failure here is the caller's request being unusable, never a
+    /// server fault, so each returns a message naming the part that was wrong.
+    pub fn to_plan(&self) -> Result<ReconciliationPlan, String> {
+        let parent_choice = match self.parent_choice.as_str() {
+            "left" => true,
+            "right" => false,
+            other => {
+                return Err(format!(
+                    "parent_choice must be \"left\" or \"right\", not {other:?}"
+                ))
+            }
+        };
+        let mut overrides: BTreeMap<Vec<PathComponent>, Value> = BTreeMap::new();
+        for entry in &self.overrides {
+            overrides.insert(path_from_json(&entry.path)?, entry.value.clone());
+        }
+        let mut plan = ReconciliationPlan::new(
+            StateId::from_hex(self.left.clone()),
+            StateId::from_hex(self.right.clone()),
+            StateId::from_hex(self.base.clone()),
+            parent_choice,
+        );
+        plan.path_overrides = overrides;
+        Ok(plan)
+    }
+}
+
+/// A plan, echoed back in the same shape it was requested in.
+pub fn plan_to_json(plan: &ReconciliationPlan) -> Value {
+    json!({
+        "base": plan.base_id.as_hex(),
+        "left": plan.left_id.as_hex(),
+        "right": plan.right_id.as_hex(),
+        "parent_choice": if plan.parent_choice { "left" } else { "right" },
+        "overrides": plan.path_overrides.iter().map(|(path, value)| json!({
+            "path": path_to_json(path),
+            "value": value,
+        })).collect::<Vec<_>>(),
+    })
+}
+
+// ============================================================================
+// Operation projections
+// ============================================================================
+
+fn operation_type_name(kind: &OperationType) -> &'static str {
+    match kind {
+        OperationType::Insert => "insert",
+        OperationType::Update => "update",
+        OperationType::Delete => "delete",
+    }
+}
+
+/// The collection a capability names.
+///
+/// A capability is `{state_namespace}:{collection}` for application data and a
+/// bare collection for the direct-authority routes. Splitting from the right
+/// covers both, and covers an application whose state namespace differs from
+/// the server's — which is the usual case, and the one that made an earlier
+/// left-anchored version report every application collection as unmatched.
+pub fn collection_of(capability: &str) -> &str {
+    capability
+        .rsplit_once(':')
+        .map(|(_, collection)| collection)
+        .unwrap_or(capability)
+}
+
+/// What an operation did, without what it wrote.
+///
+/// The value is deliberately dropped rather than redacted. An operations view
+/// answers *what happened, to what, by whom, in what order*; carrying record
+/// contents through it would make every write's payload readable from a second
+/// route with none of the per-record authorization that
+/// `GET /v1/data/{collection}/{id}` applies.
+pub fn operation_summary_to_json(operation: &Operation) -> Value {
+    json!({
+        "operation_id": operation.op_id,
+        "type": operation_type_name(&operation.op_type),
+        "capability": operation.capability,
+        "collection": collection_of(&operation.capability),
+        "key": operation.key,
+        "instance_id": operation.instance_id,
+        "sequence": operation.sequence,
+        "timestamp_ms": operation.timestamp_ms as u64,
+        "content_hash": operation.content_hash,
+        "vector_clock": operation.vector_clock,
+        "state_id": operation.revision.as_ref().map(|revision| revision.id.clone()),
+    })
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    /// The declaration is the product claim, so it is checked like one.
+    #[test]
+    fn control_plane_declaration_is_honest() {
+        let mut seen = std::collections::BTreeSet::new();
+        for capability in CAPABILITIES {
+            assert!(
+                seen.insert(capability.id),
+                "capability {} is declared twice",
+                capability.id
+            );
+            match capability.status {
+                CapabilityStatus::Unsupported => {
+                    assert!(
+                        capability.surface.is_empty(),
+                        "{} is unsupported and still names a surface",
+                        capability.id
+                    );
+                    assert!(
+                        !capability.note.is_empty(),
+                        "{} is unsupported without saying why",
+                        capability.id
+                    );
+                }
+                CapabilityStatus::Partial => {
+                    assert!(
+                        !capability.surface.is_empty(),
+                        "{} is partial and names no surface",
+                        capability.id
+                    );
+                    assert!(
+                        !capability.note.is_empty(),
+                        "{} is partial without saying which inputs it covers",
+                        capability.id
+                    );
+                }
+                CapabilityStatus::Available => assert!(
+                    !capability.surface.is_empty(),
+                    "{} is available and names no surface",
+                    capability.id
+                ),
+            }
+            for route in capability.surface {
+                let (method, path) = route
+                    .split_once(' ')
+                    .unwrap_or_else(|| panic!("{} names a surface without a method", capability.id));
+                assert!(
+                    ["GET", "POST", "PUT", "DELETE"].contains(&method),
+                    "{} names an unknown method {method}",
+                    capability.id
+                );
+                assert!(
+                    path.starts_with('/'),
+                    "{} names a relative path {path}",
+                    capability.id
+                );
+            }
+        }
+    }
+
+    #[test]
+    fn a_path_survives_the_round_trip_with_its_component_kinds() {
+        let path = vec![
+            PathComponent::Key("items".into()),
+            PathComponent::Index(2),
+            PathComponent::Key("0".into()),
+        ];
+        let encoded = path_to_json(&path);
+        assert_eq!(encoded, json!(["items", 2, "0"]));
+        assert_eq!(path_from_json(&encoded).unwrap(), path);
+    }
+
+    #[test]
+    fn a_path_component_that_is_neither_key_nor_index_is_refused() {
+        assert!(path_from_json(&json!(["a", true])).is_err());
+        assert!(path_from_json(&json!(["a", -1])).is_err());
+        assert!(path_from_json(&json!("a")).is_err());
+    }
+
+    #[test]
+    fn a_plan_request_names_its_branch_by_name() {
+        let request: ReconciliationPlanRequest = serde_json::from_value(json!({
+            "base": "b", "left": "l", "right": "r", "parent_choice": "right",
+            "overrides": [{"path": ["o", 0], "value": 7}],
+        }))
+        .unwrap();
+        let plan = request.to_plan().unwrap();
+        assert!(!plan.parent_choice);
+        assert_eq!(plan.path_overrides.len(), 1);
+        assert_eq!(plan_to_json(&plan)["parent_choice"], json!("right"));
+        assert_eq!(plan_to_json(&plan)["overrides"][0]["path"], json!(["o", 0]));
+    }
+
+    #[test]
+    fn a_plan_request_with_an_unnamed_branch_is_refused() {
+        let request: ReconciliationPlanRequest = serde_json::from_value(json!({
+            "base": "b", "left": "l", "right": "r", "parent_choice": "either",
+        }))
+        .unwrap();
+        assert!(request.to_plan().is_err());
+    }
+
+    #[test]
+    fn a_diff_carries_typed_paths_and_named_kinds() {
+        let diff = SemanticDiff::compute(&json!({"a": 1}), &json!({"a": 2, "b": [3]}));
+        let encoded = diff_to_json(&diff);
+        let changes = encoded["changes"].as_array().unwrap();
+        assert!(changes
+            .iter()
+            .any(|change| change["path"] == json!(["a"]) && change["kind"] == json!("changed")));
+        assert!(changes
+            .iter()
+            .any(|change| change["kind"] == json!("added") && change["path"] == json!(["b"])));
+    }
+
+    #[test]
+    fn an_operation_summary_never_carries_the_value_it_wrote() {
+        let operation = Operation::insert(
+            1,
+            "instance".into(),
+            1,
+            "User:usr_1".into(),
+            json!({"api_token": "must-not-appear"}),
+            "serde_json::Value".into(),
+            "app-namespace:User".into(),
+        );
+        let summary = operation_summary_to_json(&operation);
+        assert_eq!(summary["collection"], json!("User"));
+        assert_eq!(collection_of("Doc"), "Doc");
+        assert_eq!(summary["type"], json!("insert"));
+        assert!(!summary.to_string().contains("must-not-appear"));
+    }
+}