mesh.claim

{
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "session": {
      "type": [
        "string",
        "null"
      ],
      "description": "The claiming session; the calling MCP session's own when omitted. Opened when new."
    },
    "client": {
      "type": [
        "string",
        "null"
      ],
      "description": "The client, for a session this opens; `cli` when omitted."
    },
    "scope": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Repository-relative paths."
    },
    "intent": {
      "type": [
        "string",
        "null"
      ],
      "description": "What the claim is for."
    },
    "mode": {
      "anyOf": [
        {
          "$ref": "#/$defs/ClaimMode"
        },
        {
          "type": "null"
        }
      ],
      "description": "`exclusive` (the default) or `advisory`."
    },
    "issue": {
      "type": [
        "string",
        "null"
      ],
      "description": "The issue the claim is for."
    },
    "task": {
      "type": [
        "string",
        "null"
      ],
      "description": "The task, for a session this opens."
    }
  },
  "required": [
    "scope"
  ],
  "description": "The input of `mesh.claim`.",
  "title": "ClaimInput",
  "$defs": {
    "ClaimMode": {
      "oneOf": [
        {
          "type": "string",
          "const": "exclusive",
          "description": "Exclusive: a second exclusive claim meeting this scope is refused while this one\nlives, on every runtime that knows of it."
        },
        {
          "type": "string",
          "const": "advisory",
          "description": "Advisory: an announcement, like the peer board's. Overlaps are reported, never\nrefused."
        }
      ],
      "description": "Whether a claim excludes others or only tells them. Both are useful and they answer\ndifferent questions: an exclusive claim is a worker saying \"do not edit this while I\nam\", an advisory one is saying \"I am here\". Exclusive is the default because a claim\ntaken without a thought about the mode is a claim somebody expects to be respected.\n\n```\nuse majordomus_cli::mesh::journal::ClaimMode;\n\nassert_eq!(ClaimMode::default(), ClaimMode::Exclusive);\nassert_eq!(serde_json::to_value(ClaimMode::Advisory).unwrap(), serde_json::json!(\"advisory\"));\n```"
    }
  }
}

{
  "type": "object",
  "properties": {
    "key": {
      "type": "string",
      "description": "`<stream>/<local id>` of what was created or changed."
    },
    "event": {
      "type": "string",
      "description": "`<stream>/<seq>` of the event that says so."
    },
    "lamport": {
      "type": "integer",
      "format": "uint64",
      "minimum": 0,
      "description": "The event's Lamport stamp."
    },
    "durability": {
      "$ref": "#/$defs/Durability",
      "description": "Whether the event reached this machine's disk: `synced`, `memory` (a journal with no\nfile, by configuration), or `not_durable` — held and replicated to peers, not on disk\nhere, and not acknowledged as durable. `unknown` from an executable that predates it.",
      "default": "unknown"
    }
  },
  "required": [
    "key",
    "event",
    "lamport"
  ],
  "description": "What an operation wrote, as its answer to the caller. Every mesh operation is an event\nappended to this runtime's journal, and the caller is handed the three facts it cannot\nwork out for itself: the mesh-wide key of the thing it created, the event that says so,\nand the Lamport stamp that places it against everyone else's events.\n\nThe key is what a later operation is addressed by — a claim is released by the key its\nacquisition returned, never by the local name it was given — and the stamp is what a\ncaller waiting for a peer to catch up compares against.\n\n```\n# use std::sync::Arc;\n# use majordomus_cli::mesh::config::{CooperationConfig, TrustConfig};\n# use majordomus_cli::mesh::cooperation::{CheckoutFacts, Cooperation, CooperationSetup};\n# use majordomus_cli::mesh::identity::NodeIdentity;\n# use majordomus_cli::mesh::link::HttpTransport;\n# use majordomus_cli::mesh::registry::MeshRegistry;\n# use majordomus_cli::mesh::repository::of_root_commits;\n# let cooperation = Cooperation::new(CooperationSetup {\n#     identity: Arc::new(NodeIdentity::ephemeral().unwrap()), runtime: \"0000000000000001\".into(),\n#     repository: of_root_commits(&[\"root\".into()]), endpoints: vec![\"127.0.0.1:9\".into()],\n#     version: \"doc\".into(), config: CooperationConfig::default(), trust: TrustConfig::default(),\n#     journal_path: None, registry: Arc::new(MeshRegistry::new()),\n#     transport: Arc::new(HttpTransport), board: None, checkout: CheckoutFacts::default(),\n# }).unwrap();\nuse majordomus_cli::mesh::cooperation::Written;\nuse majordomus_cli::mesh::journal::{ClaimMode, Durability, SessionInfo};\n\nlet session = SessionInfo::named(\"s1\", \"cli\");\nlet written: Written = cooperation\n    .claim(&session, vec![\"docs\".into()], None, ClaimMode::Advisory, None)\n    .unwrap();\nassert!(written.lamport > 0, \"placed against every other runtime's events\");\nassert_eq!(written.durability, Durability::Memory, \"this journal has no file\");\n\n// and the key it returned is how the claim is addressed from here on\ncooperation.release(&written.key).unwrap();\n```",
  "title": "Written",
  "$defs": {
    "Durability": {
      "oneOf": [
        {
          "type": "string",
          "const": "synced",
          "description": "Appended to the journal file and synced (`fsync` of its data) before the append\nreturned."
        },
        {
          "type": "string",
          "const": "memory",
          "description": "The journal has no file: it lives in memory and its peers, by configuration."
        },
        {
          "type": "string",
          "const": "not_durable",
          "description": "The write to the journal file failed. The event is held in memory and replicated to\npeers, and is lost to this machine when the runtime restarts unless a peer still holds\nit. It is not acknowledged as durable."
        },
        {
          "type": "string",
          "const": "unknown",
          "description": "Not reported: an answer from an executable that predates this field."
        }
      ],
      "description": "Whether an event this runtime wrote reached this machine's disk: what an append\nacknowledges, and the only thing a caller may say about it.\n\n```\nuse majordomus_cli::mesh::journal::Durability;\nassert_eq!(serde_json::to_value(Durability::NotDurable).unwrap(), \"not_durable\");\nassert_eq!(Durability::default(), Durability::Unknown, \"an answer that did not say\");\nassert!(Durability::Synced.is_on_disk() && !Durability::NotDurable.is_on_disk());\n```"
    }
  }
}