lean_ctx/core/

contracts.rs

// SPDX-License-Identifier: Apache-2.0

use std::collections::BTreeMap;

// Machine-verified contract versions.
pub const MCP_MANIFEST_SCHEMA_VERSION: u32 = 1;
pub const CONTEXT_PROOF_V1_SCHEMA_VERSION: u32 = 1;
pub const CONTEXT_IR_V1_SCHEMA_VERSION: u32 = 1;
pub const ATTENTION_LAYOUT_DRIVER_V1_SCHEMA_VERSION: u32 = 1;
pub const VERIFICATION_OBSERVABILITY_V1_SCHEMA_VERSION: u32 = 1;
pub const HANDOFF_LEDGER_V1_SCHEMA_VERSION: u32 = 1;
pub const HANDOFF_TRANSFER_BUNDLE_V1_SCHEMA_VERSION: u32 = 1;
pub const CCP_SESSION_BUNDLE_V1_SCHEMA_VERSION: u32 = 1;
pub const KNOWLEDGE_POLICY_V1_SCHEMA_VERSION: u32 = 1;
pub const GRAPH_REPRODUCIBILITY_V1_SCHEMA_VERSION: u32 = 1;
pub const A2A_SNAPSHOT_V1_SCHEMA_VERSION: u32 = 1;
pub const MEMORY_BOUNDARY_V1_SCHEMA_VERSION: u32 = 1;
pub const GOTCHAS_REMINDERS_V1_SCHEMA_VERSION: u32 = 1;
pub const PROVIDER_FRAMEWORK_V1_SCHEMA_VERSION: u32 = 1;
pub const CONTEXT_PACKAGE_V1_SCHEMA_VERSION: u32 = 1;
pub const CONTEXT_PACKAGE_V2_SCHEMA_VERSION: u32 = 2;
pub const CONTEXT_SNAPSHOT_V1_SCHEMA_VERSION: u32 = 1;
pub const TEAM_SEAT_VALUE_V1_SCHEMA_VERSION: u32 = 1;

pub const PACKAGE_EXTENSION: &str = "ctxpkg";
pub const LEGACY_PACKAGE_EXTENSION: &str = "lctxpkg";
pub const MAX_PACKAGE_FILE_BYTES: u64 = 10 * 1024 * 1024; // 10 MB

pub fn is_package_file(path: &std::path::Path) -> bool {
    path.extension()
        .and_then(|e| e.to_str())
        .is_some_and(|ext| ext == PACKAGE_EXTENSION || ext == LEGACY_PACKAGE_EXTENSION)
}

pub fn default_package_filename(name: &str, version: &str) -> String {
    format!("{name}-{version}.{PACKAGE_EXTENSION}")
}

// Documentation-level contracts (do not have a schema field in payloads).
pub const HTTP_MCP_CONTRACT_VERSION: u32 = 2;
pub const TEAM_SERVER_CONTRACT_VERSION: u32 = 1;
pub const CAPABILITIES_CONTRACT_VERSION: u32 = 1;

/// Stability classification of a contract document (GL #394).
///
/// The classification is normative — `tests/contracts_frozen.rs` enforces it:
/// * `Frozen` — the normative surface is immutable. Any change to the doc file
///   fails CI; semantic evolution requires a new `-v2.md` file (the v1 file
///   stays in place for existing integrations).
/// * `Stable` — additive evolution allowed (new optional fields, new sections);
///   breaking changes still require a version bump per CONTRACTS.md rules.
/// * `Experimental` — may change or disappear without notice; not covered by
///   the deprecation policy.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum ContractStatus {
    Frozen,
    Stable,
    Experimental,
}

impl ContractStatus {
    pub fn as_str(self) -> &'static str {
        match self {
            ContractStatus::Frozen => "frozen",
            ContractStatus::Stable => "stable",
            ContractStatus::Experimental => "experimental",
        }
    }
}

/// One contract document under `docs/contracts/`, classified for the
/// stability matrix in CONTRACTS.md and the `/v1/capabilities` response.
pub struct ContractDoc {
    /// Short stable identifier (used in capabilities `contract_status`).
    pub id: &'static str,
    /// File name inside `docs/contracts/` (the normative artifact).
    pub doc_file: &'static str,
    pub version: u32,
    pub status: ContractStatus,
}

/// The complete classified inventory of `docs/contracts/*.md` — the single
/// source of truth for the stability matrix. `tests/contracts_frozen.rs`
/// asserts that every file in the directory is listed here (no contract can
/// stay unclassified) and that frozen docs never change.
pub fn contract_docs() -> Vec<ContractDoc> {
    use ContractStatus::{Experimental, Frozen, Stable};
    let doc = |id, doc_file, version, status| ContractDoc {
        id,
        doc_file,
        version,
        status,
    };
    vec![
        // ── Frozen: externally consumed platform/transport promises ────────
        doc("http-mcp", "http-mcp-contract-v1.md", 1, Frozen),
        doc("http-mcp-v2", "http-mcp-contract-v2.md", 2, Stable),
        doc("context-ir", "context-ir-v1.md", 1, Frozen),
        doc(
            "local-free-invariant",
            "local-free-invariant-v1.md",
            1,
            Frozen,
        ),
        // v2 = binding for 3.12 (LeanCTX | Hive): paid rights only through
        // Hive, plan checks only in core/hive; v1 stays the record.
        doc(
            "local-free-invariant-v2",
            "local-free-invariant-v2.md",
            2,
            Stable,
        ),
        doc(
            "oss-plane-separation",
            "oss-plane-separation-v1.md",
            1,
            Frozen,
        ),
        // v2 = Apache host + private commercial components (v4); v1 stays frozen.
        doc(
            "oss-plane-separation-v2",
            "oss-plane-separation-v2.md",
            2,
            Stable,
        ),
        doc("wasm-abi", "wasm-abi-v1.md", 1, Frozen),
        // Release promotion, offline rollback rehearsal and signing-key
        // rotation are externally consumed fail-closed supply-chain formats.
        // Their exact v1 semantics are immutable; evolution requires v2.
        doc("delivery-manifest", "delivery-manifest-v1.md", 1, Frozen),
        doc(
            "deployment-rehearsal",
            "deployment-rehearsal-v1.md",
            1,
            Frozen,
        ),
        doc(
            "release-key-rotation",
            "release-key-rotation-v1.md",
            1,
            Frozen,
        ),
        // ── Stable: additive evolution allowed ──────────────────────────────
        // capabilities is additive BY DESIGN: its drift test binds the doc's
        // key list to TOP_LEVEL_KEYS, so the doc grows with every new key —
        // freezing the file would contradict its own contract.
        doc("capabilities", "capabilities-contract-v1.md", 1, Stable),
        // v2 = v1 + storageQuotaBytes/roiWebhookUrl (GL #387/#388); v1 stays frozen.
        // v3 = v1 + sso_oidc entitlement (GL #460/#533); additive. Business merged into Team in v3.9.
        doc("evidence-bundle", "evidence-bundle-v1.md", 1, Stable),
        doc("a2a", "a2a-contract-v1.md", 1, Stable),
        doc(
            "attention-layout-driver",
            "attention-layout-driver-v1.md",
            1,
            Stable,
        ),
        doc("conformance", "conformance-v1.md", 1, Stable),
        doc(
            "context-plan-projection-digest",
            "context-plan-projection-digest-v1.md",
            1,
            Stable,
        ),
        doc(
            "ocla-cache-validator",
            "ocla-cache-validator-v1.md",
            1,
            Stable,
        ),
        doc(
            "ocla-verifier-conformance",
            "ocla-verifier-conformance-v1.md",
            1,
            Stable,
        ),
        doc("extension-trust", "extension-trust-v1.md", 1, Stable),
        doc("extractors", "extractors-v1.md", 1, Stable),
        doc("contracts-readme", "README.md", 1, Stable),
        doc("deprecation-policy", "DEPRECATION.md", 1, Stable),
        doc("audit-schedule", "audit-schedule-v1.md", 1, Stable),
        doc("branch-protection", "branch-protection-v1.md", 1, Stable),
        doc(
            "certification-levels",
            "certification-levels-v1.md",
            1,
            Stable,
        ),
        doc("release-integrity", "release-integrity-v1.md", 1, Stable),
        doc("evidence-bundle-v2", "evidence-bundle-v2.md", 2, Stable),
        doc(
            "evidence-bundle-v2-verification",
            "evidence-bundle-v2-verification-v1.md",
            1,
            Stable,
        ),
        doc(
            "public-product-claims",
            "public-product-claims-v1.md",
            1,
            Stable,
        ),
        doc(
            "gotchas-reminders",
            "gotchas-reminders-contract-v1.md",
            1,
            Stable,
        ),
        doc(
            "graph-reproducibility",
            "graph-reproducibility-contract-v1.md",
            1,
            Stable,
        ),
        doc(
            "handoff-transfer-bundle",
            "handoff-transfer-bundle-v1.md",
            1,
            Stable,
        ),
        doc(
            "knowledge-policy",
            "knowledge-policy-contract-v1.md",
            1,
            Stable,
        ),
        doc(
            "memory-boundary",
            "memory-boundary-contract-v1.md",
            1,
            Stable,
        ),
        doc("persona-spec", "persona-spec-v1.md", 1, Stable),
        doc(
            "provider-framework",
            "provider-framework-contract-v1.md",
            1,
            Stable,
        ),
        doc("wrapped-permalink", "wrapped-permalink-v1.md", 1, Stable),
        // Community addon manifest (#858): self-declared stable (v1); the format
        // evolves additively (new optional fields), so Stable, not Frozen.
        doc("addon-manifest", "addon-manifest-v1.md", 1, Stable),
        // Additive signing profile; production adoption remains a separate gate.
        doc(
            "decision-record-signature",
            "decision-record-signature-v1.md",
            1,
            Stable,
        ),
        // ── Experimental: may change without notice ─────────────────────────
        // Integration/source-pin notes are not release or protocol-stability
        // promises. Classify them explicitly; never promote a note to Frozen
        // merely to satisfy the inventory check.
        doc(
            "team-context-source",
            "team-context-v1.SOURCE-v1.md",
            1,
            Experimental,
        ),
        // W0/W1 token-intelligence foundations are locally verified but do not
        // yet claim complete hotpath adoption or externally consumed stability.
        doc(
            "context-candidate-admission",
            "context-candidate-admission-v1.md",
            1,
            Experimental,
        ),
        // Evidence tiers, eval verdicts, retention probes and the quality
        // receipt; the receipt section is still being extended additively.
        doc("context-quality", "context-quality-v1.md", 1, Experimental),
        doc(
            "multi-agent-efficiency-benchmark",
            "multi-agent-efficiency-benchmark-v1.md",
            1,
            Experimental,
        ),
        // The committed artifact is conformance-only; external deployment use
        // and governed attestor adoption remain deliberately unclaimed.
        doc(
            "test-deployment-evidence",
            "test-deployment-evidence-v1.md",
            1,
            Experimental,
        ),
        // Local Rust adapter only; external callability, authenticated approval,
        // and recovery orchestration are deliberately not claimed by v2.
        doc(
            "ocla-config-tuning",
            "ocla-config-tuning-v2.md",
            2,
            Experimental,
        ),
        doc(
            "personal-cloud-encryption",
            "personal-cloud-encryption-v1.md",
            1,
            Experimental,
        ),
        // 2026-06 org/cloud-plane wave — fresh surfaces, not yet consumed by
        // external integrations; promote to Stable deliberately, not by default.
        doc(
            "context-policy-packs",
            "context-policy-packs-v1.md",
            1,
            Experimental,
        ),
        // Quality loop (GL #494): edit-failure feedback into mode selection.
        doc("quality-loop", "quality-loop-v1.md", 1, Experimental),
        // Edit metering (GL #1144): anchored-vs-str_replace efficiency channel.
        doc("edit-metering", "edit-metering-v1.md", 1, Experimental),
        // Context Time Machine (GL #1022/#1023): git-anchored, signed temporal
        // snapshot format — fresh surface, evolving additively until stable.
        doc(
            "context-snapshot",
            "context-snapshot-v1.md",
            1,
            Experimental,
        ),
        doc(
            "team-invite-links",
            "team-invite-links-v1.md",
            1,
            Experimental,
        ),
        doc("pillar-boundaries", "pillar-boundaries-v1.md", 1, Stable),
        // Logical editor-session telemetry is an additive local-dashboard surface;
        // keep it experimental until multiple integrations implement the lifecycle.
        doc(
            "logical-session-presence",
            "logical-session-presence-v1.md",
            1,
            Experimental,
        ),
        doc(
            "tokenizer-calibration",
            "tokenizer-calibration-v1.md",
            1,
            Experimental,
        ),
        doc(
            "engine-interface-compatibility",
            "engine-interface-compatibility-v1.md",
            1,
            Stable,
        ),
        // P2 protocol artifact: a strict canonical surface with exact Rust and
        // schema conformance tests; its hash is pinned in frozen-hashes.json.
        // (`invocation-context-binding-v1` and `invocation-evidence-manifest-v1`
        // were withdrawn on 2026-10-16: nothing ever produced or consumed them.)
        doc("receipt-document", "receipt-document-v1.md", 1, Frozen),
        doc(
            "native-engine-context-proof",
            "native-engine-context-proof-v1.md",
            1,
            Experimental,
        ),
        // ── Experimental: Context Gateway, unreleased ──────────────────────
        // Canonical decision vocabulary (`lean_ctx_protocol::context_gateway`).
        doc("context-gateway", "context-gateway-v1.md", 1, Experimental),
        // v2: keyed receipt objects, additive to v1.
        doc(
            "context-gateway-v2",
            "context-gateway-v2.md",
            2,
            Experimental,
        ),
        // Egress lifecycle of the proxy (admission → bind → dispatch →
        // observation) and the Team context-outcome report: written with the
        // Context Gateway work, unreleased, not yet consumed externally.
        doc(
            "egress-lifecycle",
            "egress-lifecycle-v1.md",
            1,
            Experimental,
        ),
        doc(
            "team-context-outcome",
            "team-context-outcome-v1.md",
            1,
            Experimental,
        ),
        // ── Experimental: v4 Engine interface, unreleased ───────────────────
        // Additive local operator surfaces that ship with the v4 Engine. They
        // may still change before the release that publishes them; promote to
        // Stable/Frozen then, never before.
        doc(
            "engine-context-plan",
            "engine-context-plan-v1.md",
            1,
            Experimental,
        ),
        doc(
            "engine-context-sources",
            "engine-context-sources-v1.md",
            1,
            Experimental,
        ),
        // Presenter capability: additive to v1, first Engine release 3.11.0.
        doc(
            "engine-context-sources-v2",
            "engine-context-sources-v2.md",
            2,
            Experimental,
        ),
        doc("engine-outcome", "engine-outcome-v1.md", 1, Experimental),
        doc(
            "engine-context-store",
            "engine-context-store-v1.md",
            1,
            Experimental,
        ),
        doc("local-read", "local-read-v1.md", 1, Experimental),
        doc("client-calls", "client-calls-v1.md", 1, Experimental),
        doc("local-service", "local-service-v1.md", 1, Experimental),
        doc(
            "engine-provider-execution",
            "engine-provider-execution-v1.md",
            1,
            Experimental,
        ),
        doc(
            "engine-source-execution",
            "engine-source-execution-v1.md",
            1,
            Experimental,
        ),
        doc(
            "intelligence-runtime-install",
            "intelligence-runtime-install-v1.md",
            1,
            Experimental,
        ),
        doc(
            "reference-scheduler-estimates",
            "reference-scheduler-estimates-v1.md",
            1,
            Experimental,
        ),
        doc("change-envelope", "change-envelope-v1.md", 1, Experimental),
        doc(
            "change-attestation",
            "change-attestation-v1.md",
            1,
            Experimental,
        ),
        doc("managed-config", "managed-config-v1.md", 1, Experimental),
    ]
}

/// Contract-id → stability status, exported through `/v1/capabilities` so
/// clients can verify compatibility before relying on a surface (GL #394).
pub fn status_kv() -> BTreeMap<&'static str, &'static str> {
    contract_docs()
        .into_iter()
        .map(|d| (d.id, d.status.as_str()))
        .collect()
}

pub fn versions_kv() -> BTreeMap<&'static str, u32> {
    BTreeMap::from([
        (
            "leanctx.contract.mcp_manifest.schema_version",
            MCP_MANIFEST_SCHEMA_VERSION,
        ),
        (
            "leanctx.contract.context_proof_v1.schema_version",
            CONTEXT_PROOF_V1_SCHEMA_VERSION,
        ),
        (
            "leanctx.contract.context_ir_v1.schema_version",
            CONTEXT_IR_V1_SCHEMA_VERSION,
        ),
        (
            "leanctx.contract.attention_layout_driver_v1.schema_version",
            ATTENTION_LAYOUT_DRIVER_V1_SCHEMA_VERSION,
        ),
        (
            "leanctx.contract.verification_observability_v1.schema_version",
            VERIFICATION_OBSERVABILITY_V1_SCHEMA_VERSION,
        ),
        (
            "leanctx.contract.handoff_ledger_v1.schema_version",
            HANDOFF_LEDGER_V1_SCHEMA_VERSION,
        ),
        (
            "leanctx.contract.handoff_transfer_bundle_v1.schema_version",
            HANDOFF_TRANSFER_BUNDLE_V1_SCHEMA_VERSION,
        ),
        (
            "leanctx.contract.ccp_session_bundle_v1.schema_version",
            CCP_SESSION_BUNDLE_V1_SCHEMA_VERSION,
        ),
        (
            "leanctx.contract.knowledge_policy_v1.schema_version",
            KNOWLEDGE_POLICY_V1_SCHEMA_VERSION,
        ),
        (
            "leanctx.contract.graph_reproducibility_v1.schema_version",
            GRAPH_REPRODUCIBILITY_V1_SCHEMA_VERSION,
        ),
        (
            "leanctx.contract.a2a_snapshot_v1.schema_version",
            A2A_SNAPSHOT_V1_SCHEMA_VERSION,
        ),
        (
            "leanctx.contract.memory_boundary_v1.schema_version",
            MEMORY_BOUNDARY_V1_SCHEMA_VERSION,
        ),
        (
            "leanctx.contract.gotchas_reminders_v1.schema_version",
            GOTCHAS_REMINDERS_V1_SCHEMA_VERSION,
        ),
        (
            "leanctx.contract.provider_framework_v1.schema_version",
            PROVIDER_FRAMEWORK_V1_SCHEMA_VERSION,
        ),
        (
            "leanctx.contract.context_package_v1.schema_version",
            CONTEXT_PACKAGE_V1_SCHEMA_VERSION,
        ),
        (
            "leanctx.contract.context_package_v2.schema_version",
            CONTEXT_PACKAGE_V2_SCHEMA_VERSION,
        ),
        (
            "leanctx.contract.context_snapshot_v1.schema_version",
            CONTEXT_SNAPSHOT_V1_SCHEMA_VERSION,
        ),
        (
            "leanctx.contract.http_mcp.contract_version",
            HTTP_MCP_CONTRACT_VERSION,
        ),
        (
            "leanctx.contract.team_server.contract_version",
            TEAM_SERVER_CONTRACT_VERSION,
        ),
        (
            "leanctx.contract.capabilities.contract_version",
            CAPABILITIES_CONTRACT_VERSION,
        ),
        (
            "leanctx.contract.team_seat_value_v1.schema_version",
            TEAM_SEAT_VALUE_V1_SCHEMA_VERSION,
        ),
    ])
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn contract_docs_have_unique_ids_and_files() {
        let docs = contract_docs();
        let mut ids: Vec<_> = docs.iter().map(|d| d.id).collect();
        let mut files: Vec<_> = docs.iter().map(|d| d.doc_file).collect();
        ids.sort_unstable();
        files.sort_unstable();
        let unique_ids: std::collections::BTreeSet<_> = ids.iter().collect();
        let unique_files: std::collections::BTreeSet<_> = files.iter().collect();
        assert_eq!(unique_ids.len(), docs.len(), "duplicate contract id");
        assert_eq!(unique_files.len(), docs.len(), "duplicate doc file");
    }

    #[test]
    fn frozen_set_covers_the_platform_promises() {
        // The freeze (GL #394) is only meaningful if the externally consumed
        // surfaces are actually in it. Removing one of these from `Frozen`
        // is itself a breaking policy change.
        let docs = contract_docs();
        for id in [
            "http-mcp",
            "context-ir",
            "local-free-invariant",
            "oss-plane-separation",
            "wasm-abi",
            "delivery-manifest",
            "deployment-rehearsal",
            "release-key-rotation",
        ] {
            let entry = docs.iter().find(|d| d.id == id).expect("listed");
            assert_eq!(
                entry.status,
                ContractStatus::Frozen,
                "{id} must stay frozen"
            );
        }
    }

    #[test]
    fn status_kv_matches_docs() {
        let kv = status_kv();
        assert_eq!(kv.len(), contract_docs().len());
        assert_eq!(kv["http-mcp"], "frozen");
        assert_eq!(kv["personal-cloud-encryption"], "experimental");
        assert_eq!(kv["context-candidate-admission"], "experimental");
        assert_eq!(kv["multi-agent-efficiency-benchmark"], "experimental");
        assert_eq!(kv["test-deployment-evidence"], "experimental");
    }

    #[test]
    fn doc_files_follow_versioned_naming() {
        // v1→v2 rule: every doc file carries its version suffix so a breaking
        // change lands as a NEW file instead of mutating the old one.
        // Governance metadata (README, DEPRECATION) are exempt.
        for d in contract_docs() {
            if d.doc_file == "README.md"
                || d.doc_file == "DEPRECATION.md"
                || d.doc_file.starts_with("v4-")
            {
                continue;
            }
            assert!(
                d.doc_file.ends_with(&format!("-v{}.md", d.version)),
                "{} must end in -v{}.md",
                d.doc_file,
                d.version
            );
        }
    }
}