pack.plan

What a profile of share/archive.yaml would pack: the files carried and their bytes and o200k_base tokens, every file left out by reason (worktree, link, artifact, binary, derived, excluded; derived counted, the rest listed), the shards it is cut into within the profile's token budget and file count, and every finding that refuses the build — a file over the budget, too many shards, a machine path or credential in a selected file, an empty selection, a profile without limits. Reads git's index and blobs only; writes nothing.

query
behaviorally_verified
module pack
#pack
#archive
#review
#privacy

Exposure

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

surface	as
MCP	tool majordomus_pack_plan
HTTP	GET /api/v1/pack/plan operationId pack.plan
command line	majordomus pack plan

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 · PackPlanInput

The input of pack.plan: which profile of share/archive.yaml to plan, or the distribution's default one when none is named.

use majordomus_cli::capability::builtin::pack::PackPlanInput;
let input = PackPlanInput { profile: Some("chatgpt".into()) };
assert_eq!(input.profile.as_deref(), Some("chatgpt"));

property	type	required	description
profile	string \| null	no	A profile of `share/archive.yaml`; its `default` when absent. default null

JSON Schema

{
  "additionalProperties": false,
  "description": "The input of `pack.plan`: which profile of `share/archive.yaml` to plan, or the\ndistribution's default one when none is named.\n\n```\nuse majordomus_cli::capability::builtin::pack::PackPlanInput;\nlet input = PackPlanInput { profile: Some(\"chatgpt\".into()) };\nassert_eq!(input.profile.as_deref(), Some(\"chatgpt\"));\n```",
  "properties": {
    "profile": {
      "default": null,
      "description": "A profile of `share/archive.yaml`; its `default` when absent.",
      "type": [
        "string",
        "null"
      ]
    }
  },
  "title": "PackPlanInput",
  "type": "object"
}

output · PackPlan

The plan of one pack: what it carries, what it leaves out and why, how it is cut into shards, and whether it may be built.

The examples below plan a repository holding main.rs and a logo.png whose content is binary, with a distribution whose chat profile has limits and whose bare one has none.

use majordomus_cli::pack::{plan, PackPlan};
#### use std::process::Command;
#### let dir = tempfile::tempdir().unwrap();
#### let (root, share) = (dir.path().join("repo"), dir.path().join("share"));
#### std::fs::create_dir_all(&root).unwrap();
#### std::fs::create_dir_all(&share).unwrap();
#### std::fs::write(share.join("archive.yaml"), "default: chat\nprofiles:\n  - id: chat\n    binary: drop\n    artifacts: drop\n    shards:\n      max_count: 5\n      max_tokens: 4000\n  - id: bare\n    binary: drop\n").unwrap();
#### let git = |a: &[&str]| assert!(Command::new("git").arg("-C").arg(&root)
####     .args(["-c", "user.email=t@example.com", "-c", "user.name=t"]).args(a)
####     .status().unwrap().success());
#### git(&["init", "-q"]);
#### std::fs::write(root.join("main.rs"), "fn main() {}\n").unwrap();
#### std::fs::write(root.join("logo.png"), b"\x89PNG\0\x01").unwrap();
#### git(&["add", "-A"]);
#### git(&["commit", "-q", "-m", "one"]);
let p: PackPlan = plan(&root, &share, None).plan;
assert!(p.measured && p.passes && p.index_matches_head);
assert_eq!((p.tracked, p.selected), (2, 1));
assert_eq!(p.dropped["binary"], 1);
// an unknown profile is not measured, and not measured is never a pass
let p: PackPlan = plan(&root, &share, Some("nope")).plan;
assert!(!p.measured && !p.passes);

property	type	required	description
bytes	integer	yes	The bytes of the content carried.
commit	string \| null	no	The commit `HEAD` names; the content is the index's, which equals it when `index_matches_head` is true.
dropped	object	yes	How many files were left out, by reason.
dropped_files	array	yes	Every file left out for a reason other than `derived`.
findings	array	yes	Every reason the pack cannot be built. Empty is the passing answer.
index_matches_head	boolean	yes	Whether the index holds exactly what `HEAD` holds. `false` means staged changes travel with the pack under a commit id that does not contain them.
limits	one of 2	no	The limits applied.
measured	boolean	yes	Whether the tree could be read at all. `false` is not a pass.
passes	boolean	yes	`true` when the tree was measured and nothing was found.
profile	string	yes	The profile planned.
reason	string \| null	no	Why it could not, when it could not.
selected	integer	yes	How many the pack carries.
shards	array	yes	The shards, in order; the index is not one of them.
tokenizer	string	yes	The tokenizer the counts are in.
tokens	integer	yes	The tokens of the content carried, in `o200k_base`.
tracked	integer	yes	How many files the index tracks.

JSON Schema

{
  "$defs": {
    "DropReason": {
      "description": "Why a tracked file is not in the pack. Every reason but `derived` and `excluded` is\nfinal: no `include` of a profile re-admits a link, a gitlink, an artifact or a binary.\n\n```\nuse majordomus_cli::pack::DropReason;\nassert_eq!(DropReason::Binary.as_str(), \"binary\");\nlet json = serde_json::to_string(&DropReason::Artifact).unwrap();\nassert_eq!(json, \"\\\"artifact\\\"\");\n```",
      "oneOf": [
        {
          "const": "worktree",
          "description": "A gitlink: a nested repository or worktree whose content is not in this index.",
          "type": "string"
        },
        {
          "const": "link",
          "description": "A symbolic link, whose content is a path on the machine that committed it.",
          "type": "string"
        },
        {
          "const": "artifact",
          "description": "A path the distribution names as build output, a cache or a worktree container.",
          "type": "string"
        },
        {
          "const": "binary",
          "description": "Not text: a NUL byte, content that is not UTF-8, or an extension on the binary list.",
          "type": "string"
        },
        {
          "const": "derived",
          "description": "Marked `merge=derived` in `.gitattributes`: a projection of a file that is here.",
          "type": "string"
        },
        {
          "const": "excluded",
          "description": "Matched by the profile's `exclude`.",
          "type": "string"
        }
      ]
    },
    "DroppedFile": {
      "description": "One dropped file the report names. Derived files are counted, not listed: they are a\nfunction of files that are in the pack.\n\nThe examples below plan a repository holding `main.rs` and a `logo.png` whose content is\nbinary, with a distribution whose `chat` profile has limits and whose `bare` one has none.\n\n```\nuse majordomus_cli::pack::{plan, DropReason, DroppedFile};\n# use std::process::Command;\n# let dir = tempfile::tempdir().unwrap();\n# let (root, share) = (dir.path().join(\"repo\"), dir.path().join(\"share\"));\n# std::fs::create_dir_all(&root).unwrap();\n# std::fs::create_dir_all(&share).unwrap();\n# std::fs::write(share.join(\"archive.yaml\"), \"default: chat\\nprofiles:\\n  - id: chat\\n    binary: drop\\n    artifacts: drop\\n    shards:\\n      max_count: 5\\n      max_tokens: 4000\\n  - id: bare\\n    binary: drop\\n\").unwrap();\n# let git = |a: &[&str]| assert!(Command::new(\"git\").arg(\"-C\").arg(&root)\n#     .args([\"-c\", \"user.email=t@example.com\", \"-c\", \"user.name=t\"]).args(a)\n#     .status().unwrap().success());\n# git(&[\"init\", \"-q\"]);\n# std::fs::write(root.join(\"main.rs\"), \"fn main() {}\\n\").unwrap();\n# std::fs::write(root.join(\"logo.png\"), b\"\\x89PNG\\0\\x01\").unwrap();\n# git(&[\"add\", \"-A\"]);\n# git(&[\"commit\", \"-q\", \"-m\", \"one\"]);\nlet dropped = plan(&root, &share, None).plan.dropped_files;\nlet want = DroppedFile { path: \"logo.png\".into(), reason: DropReason::Binary };\nassert_eq!(dropped, [want]);\n```",
      "properties": {
        "path": {
          "description": "The path.",
          "type": "string"
        },
        "reason": {
          "$ref": "#/$defs/DropReason",
          "description": "Why."
        }
      },
      "required": [
        "path",
        "reason"
      ],
      "type": "object"
    },
    "PackFinding": {
      "description": "A reason the pack cannot be built as planned, or a written pack is not what its\nmanifest says: a stable code, the path when there is one, and the remedy.\n\nThe examples below plan a repository holding `main.rs` and a `logo.png` whose content is\nbinary, with a distribution whose `chat` profile has limits and whose `bare` one has none.\n\n```\nuse majordomus_cli::pack::{plan, PackFinding};\n# use std::process::Command;\n# let dir = tempfile::tempdir().unwrap();\n# let (root, share) = (dir.path().join(\"repo\"), dir.path().join(\"share\"));\n# std::fs::create_dir_all(&root).unwrap();\n# std::fs::create_dir_all(&share).unwrap();\n# std::fs::write(share.join(\"archive.yaml\"), \"default: chat\\nprofiles:\\n  - id: chat\\n    binary: drop\\n    artifacts: drop\\n    shards:\\n      max_count: 5\\n      max_tokens: 4000\\n  - id: bare\\n    binary: drop\\n\").unwrap();\n# let git = |a: &[&str]| assert!(Command::new(\"git\").arg(\"-C\").arg(&root)\n#     .args([\"-c\", \"user.email=t@example.com\", \"-c\", \"user.name=t\"]).args(a)\n#     .status().unwrap().success());\n# git(&[\"init\", \"-q\"]);\n# std::fs::write(root.join(\"main.rs\"), \"fn main() {}\\n\").unwrap();\n# std::fs::write(root.join(\"logo.png\"), b\"\\x89PNG\\0\\x01\").unwrap();\n# git(&[\"add\", \"-A\"]);\n# git(&[\"commit\", \"-q\", \"-m\", \"one\"]);\nlet findings: Vec<PackFinding> = plan(&root, &share, Some(\"bare\")).plan.findings;\nassert_eq!(findings[0].code, \"pack.no_limits\");\nassert!(findings[0].path.is_none() && !findings[0].remedy.is_empty());\n```",
      "properties": {
        "code": {
          "description": "A stable code: `pack.file_too_large`, `pack.too_many_shards`, `pack.index_too_large`, `pack.leak`,\n`pack.empty`, `pack.no_limits`, and from verification `pack.tampered`,\n`pack.not_text`, `pack.forbidden_path`, `pack.missing`, `pack.stray`,\n`pack.over_budget`, `pack.manifest`.",
          "type": "string"
        },
        "message": {
          "description": "What is wrong.",
          "type": "string"
        },
        "path": {
          "description": "The path the finding is about, when it is about one.",
          "type": [
            "string",
            "null"
          ]
        },
        "remedy": {
          "description": "What settles it.",
          "type": "string"
        }
      },
      "required": [
        "code",
        "message",
        "remedy"
      ],
      "type": "object"
    },
    "ShardLimits": {
      "description": "The shard limits of a profile: the reader's own limits on what it can index, the file\ncount of a project and the tokens one file of it may hold.\n\n```\nuse majordomus_cli::pack::{Profiles, ShardLimits};\nlet p = Profiles::parse(\n    \"default: a\\nprofiles:\\n  - id: a\\n    shards:\\n      max_count: 20\\n      max_tokens: 900\\n\",\n)\n.unwrap();\nlet want = ShardLimits { max_count: 20, max_tokens: 900 };\nassert_eq!(p.profile(None).unwrap().shards, Some(want));\n```",
      "properties": {
        "max_count": {
          "description": "The most files the pack may hold, the index included.",
          "format": "uint",
          "minimum": 0,
          "type": "integer"
        },
        "max_tokens": {
          "description": "The most tokens one file of the pack may hold, counted with `o200k_base`.",
          "format": "uint64",
          "minimum": 0,
          "type": "integer"
        }
      },
      "required": [
        "max_count",
        "max_tokens"
      ],
      "type": "object"
    },
    "ShardPlan": {
      "description": "One planned shard: a Markdown file of the pack, the paths it carries from first to last,\nand what it weighs in bytes and in tokens.\n\nThe examples below plan a repository holding `main.rs` and a `logo.png` whose content is\nbinary, with a distribution whose `chat` profile has limits and whose `bare` one has none.\n\n```\nuse majordomus_cli::pack::{plan, ShardPlan};\n# use std::process::Command;\n# let dir = tempfile::tempdir().unwrap();\n# let (root, share) = (dir.path().join(\"repo\"), dir.path().join(\"share\"));\n# std::fs::create_dir_all(&root).unwrap();\n# std::fs::create_dir_all(&share).unwrap();\n# std::fs::write(share.join(\"archive.yaml\"), \"default: chat\\nprofiles:\\n  - id: chat\\n    binary: drop\\n    artifacts: drop\\n    shards:\\n      max_count: 5\\n      max_tokens: 4000\\n  - id: bare\\n    binary: drop\\n\").unwrap();\n# let git = |a: &[&str]| assert!(Command::new(\"git\").arg(\"-C\").arg(&root)\n#     .args([\"-c\", \"user.email=t@example.com\", \"-c\", \"user.name=t\"]).args(a)\n#     .status().unwrap().success());\n# git(&[\"init\", \"-q\"]);\n# std::fs::write(root.join(\"main.rs\"), \"fn main() {}\\n\").unwrap();\n# std::fs::write(root.join(\"logo.png\"), b\"\\x89PNG\\0\\x01\").unwrap();\n# git(&[\"add\", \"-A\"]);\n# git(&[\"commit\", \"-q\", \"-m\", \"one\"]);\nlet planned = plan(&root, &share, None);\nlet first: &ShardPlan = &planned.plan.shards[0];\nassert_eq!((first.files, first.first.as_str(), first.last.as_str()), (1, \"main.rs\", \"main.rs\"));\nassert!(first.file.ends_with(\".md\") && first.tokens > 0);\n```",
      "properties": {
        "bytes": {
          "description": "The bytes of the content it carries.",
          "format": "uint64",
          "minimum": 0,
          "type": "integer"
        },
        "file": {
          "description": "The file name inside the pack.",
          "type": "string"
        },
        "files": {
          "description": "How many files it carries.",
          "format": "uint",
          "minimum": 0,
          "type": "integer"
        },
        "first": {
          "description": "The first path it carries.",
          "type": "string"
        },
        "last": {
          "description": "The last path it carries.",
          "type": "string"
        },
        "tokens": {
          "description": "The tokens of the blocks it carries.",
          "format": "uint64",
          "minimum": 0,
          "type": "integer"
        }
      },
      "required": [
        "file",
        "files",
        "first",
        "last",
        "bytes",
        "tokens"
      ],
      "type": "object"
    }
  },
  "description": "The plan of one pack: what it carries, what it leaves out and why, how it is cut into\nshards, and whether it may be built.\n\nThe examples below plan a repository holding `main.rs` and a `logo.png` whose content is\nbinary, with a distribution whose `chat` profile has limits and whose `bare` one has none.\n\n```\nuse majordomus_cli::pack::{plan, PackPlan};\n# use std::process::Command;\n# let dir = tempfile::tempdir().unwrap();\n# let (root, share) = (dir.path().join(\"repo\"), dir.path().join(\"share\"));\n# std::fs::create_dir_all(&root).unwrap();\n# std::fs::create_dir_all(&share).unwrap();\n# std::fs::write(share.join(\"archive.yaml\"), \"default: chat\\nprofiles:\\n  - id: chat\\n    binary: drop\\n    artifacts: drop\\n    shards:\\n      max_count: 5\\n      max_tokens: 4000\\n  - id: bare\\n    binary: drop\\n\").unwrap();\n# let git = |a: &[&str]| assert!(Command::new(\"git\").arg(\"-C\").arg(&root)\n#     .args([\"-c\", \"user.email=t@example.com\", \"-c\", \"user.name=t\"]).args(a)\n#     .status().unwrap().success());\n# git(&[\"init\", \"-q\"]);\n# std::fs::write(root.join(\"main.rs\"), \"fn main() {}\\n\").unwrap();\n# std::fs::write(root.join(\"logo.png\"), b\"\\x89PNG\\0\\x01\").unwrap();\n# git(&[\"add\", \"-A\"]);\n# git(&[\"commit\", \"-q\", \"-m\", \"one\"]);\nlet p: PackPlan = plan(&root, &share, None).plan;\nassert!(p.measured && p.passes && p.index_matches_head);\nassert_eq!((p.tracked, p.selected), (2, 1));\nassert_eq!(p.dropped[\"binary\"], 1);\n// an unknown profile is not measured, and not measured is never a pass\nlet p: PackPlan = plan(&root, &share, Some(\"nope\")).plan;\nassert!(!p.measured && !p.passes);\n```",
  "properties": {
    "bytes": {
      "description": "The bytes of the content carried.",
      "format": "uint64",
      "minimum": 0,
      "type": "integer"
    },
    "commit": {
      "description": "The commit `HEAD` names; the content is the index's, which equals it when\n`index_matches_head` is true.",
      "type": [
        "string",
        "null"
      ]
    },
    "dropped": {
      "additionalProperties": {
        "format": "uint",
        "minimum": 0,
        "type": "integer"
      },
      "description": "How many files were left out, by reason.",
      "type": "object"
    },
    "dropped_files": {
      "description": "Every file left out for a reason other than `derived`.",
      "items": {
        "$ref": "#/$defs/DroppedFile"
      },
      "type": "array"
    },
    "findings": {
      "description": "Every reason the pack cannot be built. Empty is the passing answer.",
      "items": {
        "$ref": "#/$defs/PackFinding"
      },
      "type": "array"
    },
    "index_matches_head": {
      "description": "Whether the index holds exactly what `HEAD` holds. `false` means staged changes\ntravel with the pack under a commit id that does not contain them.",
      "type": "boolean"
    },
    "limits": {
      "anyOf": [
        {
          "$ref": "#/$defs/ShardLimits"
        },
        {
          "type": "null"
        }
      ],
      "description": "The limits applied."
    },
    "measured": {
      "description": "Whether the tree could be read at all. `false` is not a pass.",
      "type": "boolean"
    },
    "passes": {
      "description": "`true` when the tree was measured and nothing was found.",
      "type": "boolean"
    },
    "profile": {
      "description": "The profile planned.",
      "type": "string"
    },
    "reason": {
      "description": "Why it could not, when it could not.",
      "type": [
        "string",
        "null"
      ]
    },
    "selected": {
      "description": "How many the pack carries.",
      "format": "uint",
      "minimum": 0,
      "type": "integer"
    },
    "shards": {
      "description": "The shards, in order; the index is not one of them.",
      "items": {
        "$ref": "#/$defs/ShardPlan"
      },
      "type": "array"
    },
    "tokenizer": {
      "description": "The tokenizer the counts are in.",
      "type": "string"
    },
    "tokens": {
      "description": "The tokens of the content carried, in `o200k_base`.",
      "format": "uint64",
      "minimum": 0,
      "type": "integer"
    },
    "tracked": {
      "description": "How many files the index tracks.",
      "format": "uint",
      "minimum": 0,
      "type": "integer"
    }
  },
  "required": [
    "measured",
    "profile",
    "index_matches_head",
    "tracked",
    "selected",
    "bytes",
    "tokens",
    "tokenizer",
    "dropped",
    "dropped_files",
    "shards",
    "findings",
    "passes"
  ],
  "title": "PackPlan",
  "type": "object"
}

Policies

benchmark: required — a target on every transport the exposure declares; the cases are the input type's
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	covered	2	default-profile chatgpt
mcp	covered	2	default-profile chatgpt
http	covered	2	default-profile chatgpt