mesh.build_cache.ensure

For one lockfile the repository tracks (npm node_modules, mix deps, or the cargo build directory), skip an install whose key is already in place; otherwise restore it from this machine's local archive level (~/.cache/majordomus/build-cache) and then from the store this node declares when its own probe finds it healthy and a credential file is present, each only after the archive's SHA-256 matches the digest recorded when it was saved and every entry is judged safe (no absolute name, no `..`, no link leaving the target). On a miss the command runs, and when it succeeds what it left is archived to the local level and the store. A failure of any level is a miss: the command runs exactly as without the cache. npm's command is not run on a hit; mix's is; a cargo build directory is restored only when cold, under cargo's own lock, without incremental state, and never saved above one PUT. A restore and a save respect the build's free-space floor (MAJORDOMUS_MIN_FREE_MB); the local level is held under the policy's build_cache.local_max_gib, oldest first. MAJORDOMUS_BUILD_CACHE=off bypasses every level. Offered on the command line only: it runs a command (ADR 0157, I3952).

command
experimental
module mesh
#mesh
#build
#cache

Exposure

Where this one definition is reachable. Absence is explicit: a surface not listed does not carry it.

surface	as
MCP	—
HTTP	—
command line	majordomus mesh build-cache ensure

Schemas

The canonical input and output, from the Rust types; the MCP tool schema and the OpenAPI parameters and responses are derived from these.

input · BuildCacheEnsureInput

The input of mesh.build_cache.ensure.

property	type	required	description
command	array	no	The install or build command, run in that directory on a miss; required for npm and mix, optional for a cargo build directory. default []
dir	string \| null	no	The directory holding the lockfile, relative to the repository; absent names the only one the repository tracks, or the one the command was started in.
kind	reference	yes	What is cached: `npm-modules`, `mix-deps` or `cargo-build-dir`.

JSON Schema

{
  "$defs": {
    "Kind": {
      "description": "What is cached: the thing a lockfile makes reusable, named by the directory an install or\na build fills. The word is part of every key, so two kinds never share an entry.\n\n```\nuse majordomus_cli::mesh::build_cache::key::Kind;\nassert_eq!(Kind::NpmModules.as_str(), \"npm-modules\");\nassert_eq!(Kind::parse(\"mix-deps\"), Some(Kind::MixDeps));\n```",
      "oneOf": [
        {
          "const": "cargo-build-dir",
          "description": "The cargo build directory of a workspace: the dependencies compiled on the way, without\nincremental state. Restored only into a directory that is cold.",
          "type": "string"
        },
        {
          "const": "mix-deps",
          "description": "The `deps/` directory `mix deps.get` fills.",
          "type": "string"
        },
        {
          "const": "npm-modules",
          "description": "The `node_modules/` directory `npm ci` fills.",
          "type": "string"
        }
      ]
    }
  },
  "additionalProperties": false,
  "description": "The input of `mesh.build_cache.ensure`.",
  "properties": {
    "command": {
      "default": [],
      "description": "The install or build command, run in that directory on a miss; required for npm and\nmix, optional for a cargo build directory.",
      "items": {
        "type": "string"
      },
      "type": "array"
    },
    "dir": {
      "description": "The directory holding the lockfile, relative to the repository; absent names the only\none the repository tracks, or the one the command was started in.",
      "type": [
        "string",
        "null"
      ]
    },
    "kind": {
      "$ref": "#/$defs/Kind",
      "description": "What is cached: `npm-modules`, `mix-deps` or `cargo-build-dir`."
    }
  },
  "required": [
    "kind"
  ],
  "title": "BuildCacheEnsureInput",
  "type": "object"
}

output · BuildCacheEnsureReport

What mesh build-cache ensure did.

property	type	required	description
command	one of 2	no	The command, when it ran.
dir	string	yes	The directory holding the lockfile, relative to the repository.
key	string \| null	no	The key, when one could be derived.
kind	reference	yes	What is cached.
local	reference	yes	The local level after this run.
notes	array	yes	Every miss, refusal and skip, in the order they happened.
saved	array	yes	The levels a new archive was saved to.
source	reference	yes	Where the content came from.
target	string	yes	Where the content lives.

JSON Schema

{
  "$defs": {
    "CommandRun": {
      "description": "The command, and how it ended.",
      "properties": {
        "argv": {
          "description": "What ran.",
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        "exit": {
          "description": "Its exit code; absent when it could not start or a signal ended it.",
          "format": "int32",
          "type": [
            "integer",
            "null"
          ]
        }
      },
      "required": [
        "argv"
      ],
      "type": "object"
    },
    "Kind": {
      "description": "What is cached: the thing a lockfile makes reusable, named by the directory an install or\na build fills. The word is part of every key, so two kinds never share an entry.\n\n```\nuse majordomus_cli::mesh::build_cache::key::Kind;\nassert_eq!(Kind::NpmModules.as_str(), \"npm-modules\");\nassert_eq!(Kind::parse(\"mix-deps\"), Some(Kind::MixDeps));\n```",
      "oneOf": [
        {
          "const": "cargo-build-dir",
          "description": "The cargo build directory of a workspace: the dependencies compiled on the way, without\nincremental state. Restored only into a directory that is cold.",
          "type": "string"
        },
        {
          "const": "mix-deps",
          "description": "The `deps/` directory `mix deps.get` fills.",
          "type": "string"
        },
        {
          "const": "npm-modules",
          "description": "The `node_modules/` directory `npm ci` fills.",
          "type": "string"
        }
      ]
    },
    "Level": {
      "description": "A level an archive was saved to.",
      "oneOf": [
        {
          "const": "local",
          "description": "`~/.cache/majordomus/build-cache`.",
          "type": "string"
        },
        {
          "const": "store",
          "description": "The selected store.",
          "type": "string"
        }
      ]
    },
    "LocalLevel": {
      "description": "The local level, measured after this run.",
      "properties": {
        "bound_bytes": {
          "description": "What it may hold.",
          "format": "uint64",
          "minimum": 0,
          "type": "integer"
        },
        "bytes": {
          "description": "What it holds, in bytes.",
          "format": "uint64",
          "minimum": 0,
          "type": "integer"
        },
        "dir": {
          "description": "Where it is.",
          "type": "string"
        },
        "pruned": {
          "description": "Archives removed by this run to stay under the bound, oldest first.",
          "format": "uint64",
          "minimum": 0,
          "type": "integer"
        }
      },
      "required": [
        "dir",
        "bytes",
        "bound_bytes",
        "pruned"
      ],
      "type": "object"
    },
    "Source": {
      "description": "Where the target's content came from.",
      "oneOf": [
        {
          "const": "bypassed",
          "description": "`MAJORDOMUS_BUILD_CACHE=off`: no level was asked, the command ran.",
          "type": "string"
        },
        {
          "const": "uncached",
          "description": "No key could be derived (a toolchain did not answer): the command ran uncached.",
          "type": "string"
        },
        {
          "const": "in_place",
          "description": "The marker already named this key: nothing was done.",
          "type": "string"
        },
        {
          "const": "local",
          "description": "Restored from this machine's local level.",
          "type": "string"
        },
        {
          "const": "store",
          "description": "Restored from the store.",
          "type": "string"
        },
        {
          "const": "command",
          "description": "Every level missed: the command made it.",
          "type": "string"
        },
        {
          "const": "nothing",
          "description": "Nothing was restored and no command was given.",
          "type": "string"
        }
      ]
    }
  },
  "description": "What `mesh build-cache ensure` did.",
  "properties": {
    "command": {
      "anyOf": [
        {
          "$ref": "#/$defs/CommandRun"
        },
        {
          "type": "null"
        }
      ],
      "description": "The command, when it ran."
    },
    "dir": {
      "description": "The directory holding the lockfile, relative to the repository.",
      "type": "string"
    },
    "key": {
      "description": "The key, when one could be derived.",
      "type": [
        "string",
        "null"
      ]
    },
    "kind": {
      "$ref": "#/$defs/Kind",
      "description": "What is cached."
    },
    "local": {
      "$ref": "#/$defs/LocalLevel",
      "description": "The local level after this run."
    },
    "notes": {
      "description": "Every miss, refusal and skip, in the order they happened.",
      "items": {
        "type": "string"
      },
      "type": "array"
    },
    "saved": {
      "description": "The levels a new archive was saved to.",
      "items": {
        "$ref": "#/$defs/Level"
      },
      "type": "array"
    },
    "source": {
      "$ref": "#/$defs/Source",
      "description": "Where the content came from."
    },
    "target": {
      "description": "Where the content lives.",
      "type": "string"
    }
  },
  "required": [
    "kind",
    "dir",
    "target",
    "source",
    "saved",
    "notes",
    "local"
  ],
  "title": "BuildCacheEnsureReport",
  "type": "object"
}

Policies

benchmark: waived — waived: destructive
cache: disabled — every call runs the handler

Benchmark targets

Derived from the registry for this repository: one requirement per transport, and the cases the input type provides. The whole matrix is on the benchmarks page.

transport	state	cases	targets
direct	waived (destructive)	0