mesh.handover.publish

{
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "path": {
      "type": [
        "string",
        "null"
      ],
      "description": "The record, relative to the repository root and inside\n`.ai/local/state/handovers/`; the newest record when omitted. Nothing outside that\ndirectory is ever read by this command."
    },
    "issue": {
      "type": [
        "string",
        "null"
      ],
      "description": "The issue the handover belongs to."
    },
    "milestone": {
      "type": [
        "string",
        "null"
      ],
      "description": "The milestone it belongs to."
    }
  },
  "description": "The input of `mesh.handover.publish`.",
  "title": "HandoverPublishInput"
}

{
  "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```"
    }
  }
}