mesh.handover.consume

{
  "additionalProperties": false,
  "description": "The input of `mesh.handover.consume`.",
  "properties": {
    "handover": {
      "description": "The handover's id (its content digest).",
      "type": "string"
    },
    "materialize": {
      "description": "Whether to write it as a local handover record `majordomus handover --resolve`\nfinds (default true).",
      "type": [
        "boolean",
        "null"
      ]
    },
    "session": {
      "description": "The consuming session; the calling MCP session's own when omitted.",
      "type": [
        "string",
        "null"
      ]
    }
  },
  "required": [
    "handover"
  ],
  "title": "HandoverConsumeInput",
  "type": "object"
}

{
  "$defs": {
    "Durability": {
      "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```",
      "oneOf": [
        {
          "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.",
          "type": "string"
        }
      ]
    },
    "HandoverBody": {
      "description": "A handover as the mesh carries it: the record's facts and its body, bounded.\n\nWhat travels is the writing, plus the few facts that let a receiver file it — the task,\nthe issue, the branch, the commit. No path of the author's disk is among them, because\nthe checkout that reads this is somewhere else and a path from another machine is at\nbest noise. Identity is the digest of the body, so a handover published twice by a\nretry or by two runtimes is one handover everywhere.\n\n```\nuse majordomus_cli::mesh::journal::HandoverBody;\n\nlet body = \"# Objective\\nship the mesh\\n\".to_string();\nlet handover = HandoverBody {\n    id: HandoverBody::digest_of(&body),\n    task: Some(\"t-1\".into()),\n    issue: Some(\"#184\".into()),\n    milestone: None,\n    branch: Some(\"feature/mesh-cooperation\".into()),\n    head: None,\n    created_at: None,\n    name: None,\n    body,\n};\nassert_eq!(handover.id, HandoverBody::digest_of(&handover.body));\n\nlet wire = serde_json::to_value(&handover).unwrap();\nassert!(wire.get(\"milestone\").is_none(), \"what it does not say is omitted\");\n```",
      "properties": {
        "body": {
          "description": "The Markdown body (`# Objective`, `# Current State`, `# Next Action`, ...).",
          "type": "string"
        },
        "branch": {
          "description": "The branch it was written on.",
          "type": [
            "string",
            "null"
          ]
        },
        "created_at": {
          "description": "When it was written, RFC 3339, as its author's clock said.",
          "type": [
            "string",
            "null"
          ]
        },
        "head": {
          "description": "The commit it was written at.",
          "type": [
            "string",
            "null"
          ]
        },
        "id": {
          "description": "The content digest (32 hex): the same handover published twice is one handover.",
          "type": "string"
        },
        "issue": {
          "description": "The issue it belongs to.",
          "type": [
            "string",
            "null"
          ]
        },
        "milestone": {
          "description": "The milestone it belongs to.",
          "type": [
            "string",
            "null"
          ]
        },
        "name": {
          "description": "The record's file name at its origin, informational.",
          "type": [
            "string",
            "null"
          ]
        },
        "task": {
          "description": "The task the handover closes or continues.",
          "type": [
            "string",
            "null"
          ]
        }
      },
      "required": [
        "id",
        "body"
      ],
      "type": "object"
    },
    "HandoverView": {
      "description": "A handover anywhere in the mesh, with everyone who has taken it. The id is the digest\nof the body, so the same handover published twice — by a retry, or by two runtimes that\nboth saw it — is one handover here; and `consumed_by` is what keeps two workers from\nsilently picking up the same continuity, since the list is folded from events every\nruntime holds.\n\n```\nuse std::sync::Arc;\nuse majordomus_cli::mesh::identity::NodeIdentity;\nuse majordomus_cli::mesh::journal::{EventBody, HandoverBody, Journal, StreamLiveness};\nuse majordomus_cli::mesh::state::{fold, HandoverView};\n\nlet j = Journal::open(Arc::new(NodeIdentity::ephemeral().unwrap()), \"0000000000000001\",\n    \"repo\".into(), None).unwrap();\nlet body = \"# Objective\\nship\\n\".to_string();\nlet handover = HandoverBody { id: HandoverBody::digest_of(&body), task: None, issue: None,\n    milestone: None, branch: Some(\"feature/x\".into()), head: None, created_at: None,\n    name: None, body };\nlet id = handover.id.clone();\nj.append_own(EventBody::HandoverPublished { handover }).unwrap();\nj.append_own(EventBody::HandoverConsumed { handover: id.clone(), session: \"s1\".into() })\n    .unwrap();\n\nlet state = fold(&j.events(), &|_| StreamLiveness::Own);\nlet view: &HandoverView = &state.handovers[0];\nassert_eq!(view.id, id, \"identified by what it says, not by who said it\");\nassert_eq!(view.consumed_by.len(), 1, \"somebody has picked this one up\");\n```",
      "properties": {
        "consumed_by": {
          "description": "Every session that consumed it, by key, in Lamport order.",
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        "handover": {
          "$ref": "#/$defs/HandoverBody",
          "description": "The record's facts and body."
        },
        "id": {
          "description": "The content digest.",
          "type": "string"
        },
        "published_lamport": {
          "description": "The Lamport stamp of the first publication.",
          "format": "uint64",
          "minimum": 0,
          "type": "integer"
        },
        "runtime": {
          "description": "`<node>-<runtime>` of the publisher.",
          "type": "string"
        },
        "stream": {
          "$ref": "#/$defs/StreamId",
          "description": "The stream that first published it."
        }
      },
      "required": [
        "id",
        "stream",
        "runtime",
        "published_lamport",
        "handover",
        "consumed_by"
      ],
      "type": "object"
    },
    "StreamId": {
      "description": "One stream: a run of one runtime of one node. `<node 32 hex>-<runtime 16 hex>-<instance\n16 hex>`. The node is the machine's key, the runtime is one checkout's server on that\nmachine, the instance is one process run of that server — so two worktrees on one\nmachine are two streams, and a restart is a new stream of the same runtime.\n\nNumbering events within a stream rather than globally is what makes replication cheap\nand unambiguous: a gap in one stream is visible without coordinating with anyone, and\n`(stream, seq)` identifies an event on every machine that holds it.\n\n```\nuse majordomus_cli::mesh::journal::StreamId;\n\nlet id = StreamId::new(&\"a\".repeat(32), &\"b\".repeat(16), &\"c\".repeat(16)).unwrap();\nassert_eq!(id.node(), \"a\".repeat(32));\nassert_eq!(id.runtime(), \"b\".repeat(16));\n\n// a restart is a new stream, and the same runtime\nlet after = StreamId::new(&\"a\".repeat(32), &\"b\".repeat(16), &\"d\".repeat(16)).unwrap();\nassert_ne!(after, id);\nassert_eq!(after.runtime_key(), id.runtime_key());\n```",
      "type": "string"
    },
    "Written": {
      "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```",
      "properties": {
        "durability": {
          "$ref": "#/$defs/Durability",
          "default": "unknown",
          "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."
        },
        "event": {
          "description": "`<stream>/<seq>` of the event that says so.",
          "type": "string"
        },
        "key": {
          "description": "`<stream>/<local id>` of what was created or changed.",
          "type": "string"
        },
        "lamport": {
          "description": "The event's Lamport stamp.",
          "format": "uint64",
          "minimum": 0,
          "type": "integer"
        }
      },
      "required": [
        "key",
        "event",
        "lamport"
      ],
      "type": "object"
    }
  },
  "description": "The answer of `mesh.handover.consume`.",
  "properties": {
    "handover": {
      "$ref": "#/$defs/HandoverView",
      "description": "The handover, as the journal holds it."
    },
    "path": {
      "description": "The local record written, relative to the repository root, when materialized.",
      "type": [
        "string",
        "null"
      ]
    },
    "written": {
      "$ref": "#/$defs/Written",
      "description": "The consumption event."
    }
  },
  "required": [
    "handover",
    "written"
  ],
  "title": "ConsumeAnswer",
  "type": "object"
}