tools-packet-compile

Compile tools-doc-truth findings into typed work packages: deterministic edits, mechanical-inference questions, and judgment packages with minimal shards. Compile only -- never mutates the repo.

Tier	tools
Role	unclassified (baselined)
Path	`crates/tools/packet-compile`
Edition	2021
Targets	tools-packet-compile, tools_packet_compile
Public items	106 across 3 modules
Tests	67

What it is for

Compile tools-doc-truth findings into typed work packages (sprint 4.3).

Compile and apply are separate stages: this crate READS a tools-doc-truth report plus injected repo facts and EMITS packets.json; it never mutates the repo. Only the Judgment class reaches a model, and each judgment package carries a minimal shard — never more than its one question needs. Every package embeds its source findings verbatim plus provenance (the Gate 1.5 round's converged risk: evidence loss at the finding→package boundary). Design: docs/research/doc-truth-cleanup-packet-plan.md; story: docs/userstories/sprint-4.3-packet-compile.md.

Capabilities

`verb:compile`

Compile tools-doc-truth findings into typed work packages (sprint 4.3).

Item
`fn compile(report : & Report, facts : & RepoFacts, provenance : Provenance) -> Packets`

`verb:compose`

Compile tools-doc-truth findings into typed work packages (sprint 4.3).

Item
`fn compose_manifest_prompt(label : & str, goal : & str, manifest : & str, model : Option <& str>,) -> Result <String, String>`

`verb:constants`

Compile tools-doc-truth findings into typed work packages (sprint 4.3).

Item
`pub const CRATE_SHARD_RULE_VERSION: & str`
`pub const FN_SHARD_RULE_VERSION: & str`
`pub const SENSE_SHARD_RULE_VERSION: & str`
`pub const D7_ANSWER_TYPE: & str`
`pub const D7_TOOL_AUTHORITY: & str`
`pub const D7_STOP_CONDITIONS: & str`
`pub const TIER_COST_ORDER: & str; 3`

`verb:crate`

Compile tools-doc-truth findings into typed work packages (sprint 4.3).

Item
`fn crate_shard_input_paths(crate_dir : & std::path::Path) -> Vec <String>`

`verb:dir`

Compile tools-doc-truth findings into typed work packages (sprint 4.3).

Item
`fn dir_rename_of(from : & str, to : & str) -> Option <(String, String)>`

`verb:follow`

Compile tools-doc-truth findings into typed work packages (sprint 4.3).

Item
`fn follow_renames(cited : & str, files : & BTreeMap <String, String>, dirs : & BTreeMap <String, String>,) -> Option <String>`

`verb:invert`

Compile tools-doc-truth findings into typed work packages (sprint 4.3).

Item
`fn invert_deps(deps : & BTreeMap <String, Vec <String>>) -> BTreeMap <String, Vec <String>>`

`verb:layer`

Compile tools-doc-truth findings into typed work packages (sprint 4.3).

Item
`fn layer_of(path : & str) -> String`

`verb:propose`

Compile tools-doc-truth findings into typed work packages (sprint 4.3).

Item
`fn propose_routing(runs : & RoutedRun, min_runs : usize) -> Vec <RoutingProposal>`

`verb:recompile`

Compile tools-doc-truth findings into typed work packages (sprint 4.3).

Item
`fn recompile_crate_shard(crate_dir : & std::path::Path, crate_name : & str, layer : & str, reverse_deps : Vec <String>,) -> anyhow::Result <String>`
`fn recompile_crate_shard_bytes(crate_dir : & std::path::Path, crate_name : & str, layer : & str, reverse_deps : Vec <String>,) -> anyhow::Result <(String, String)>`

`verb:resolve`

Compile tools-doc-truth findings into typed work packages (sprint 4.3).

Item
`fn resolve_model(override_model : Option <& str>, routing_kind : Option <& str>, seed_text : & str,) ->(Option <String>, & 'static str)`

`verb:runner`

Compile tools-doc-truth findings into typed work packages (sprint 4.3).

Item
`fn runner_bin_allowed(bin : & str) -> bool`

`verb:semantics`

Compile tools-doc-truth findings into typed work packages (sprint 4.3).

Item
`fn semantics_hash(prompt : & str) -> String`

`verb:shard`

Compile tools-doc-truth findings into typed work packages (sprint 4.3).

Item
`fn shard_hash(shard_bytes : & str) -> String`

`verb:sprint`

Compile tools-doc-truth findings into typed work packages (sprint 4.3).

Item
`fn sprint_number(filename : & str) -> Option <String>`

`verb:worker`

Compile tools-doc-truth findings into typed work packages (sprint 4.3).

Item
`fn worker_argv(model : Option <& str>) -> Vec <String>`

`Actual`

Compile tools-doc-truth findings into typed work packages (sprint 4.3).

Item
`pub struct Actual`

`Calibration`

Compile tools-doc-truth findings into typed work packages (sprint 4.3).

Item
`pub struct Calibration`
`fn calibration(est : & Estimate, act : & Actual) -> Calibration`

`CallSite`

Compile tools-doc-truth findings into typed work packages (sprint 4.3).

Item
`pub struct CallSite`

`CrateShard`

Compile tools-doc-truth findings into typed work packages (sprint 4.3).

Item
`pub struct CrateShard`
`fn crate_shard_bytes(shard : & CrateShard) -> String`
`fn extract_shard(crate_dir : & std::path::Path, crate_name : & str, layer : & str, reverse_deps : Vec <String>,) -> anyhow::Result <CrateShard>`

`DetAction`

Compile tools-doc-truth findings into typed work packages (sprint 4.3).

Item
`pub enum DetAction`
`fn renumber_sprint(number : & str, files : & (String, i64), existing : & BTreeSet <String>,) -> Vec <DetAction>`

`Estimate`

Compile tools-doc-truth findings into typed work packages (sprint 4.3).

Item
`pub struct Estimate`
`fn mechanical_estimate(pkg : & WorkPackage) -> Option <Estimate>`
`fn judgment_estimate(shard_bytes : usize) -> Estimate`

`EstimateBasis`

Compile tools-doc-truth findings into typed work packages (sprint 4.3).

Item
`pub enum EstimateBasis`

`ExecutorClass`

Compile tools-doc-truth findings into typed work packages (sprint 4.3).

Item
`pub enum ExecutorClass`

`Finding`

Compile tools-doc-truth findings into typed work packages (sprint 4.3).

Item
`pub struct Finding`

`FnShard`

Compile tools-doc-truth findings into typed work packages (sprint 4.3).

Item
`pub struct FnShard`
`fn fn_shard_bytes(shard : & FnShard) -> String`
`fn fit_fn_shard(mut shard : FnShard, max_bytes : usize) -> Option <FnShard>`

`Packets`

Compile tools-doc-truth findings into typed work packages (sprint 4.3).

Item
`pub const PACKETS_SCHEMA_VERSION: & str`
`pub struct Packets`
`fn to_canonical_json(p : & Packets) -> String`

`Provenance`

Compile tools-doc-truth findings into typed work packages (sprint 4.3).

Item
`pub struct Provenance`

`PubItem`

Compile tools-doc-truth findings into typed work packages (sprint 4.3).

Item
`pub struct PubItem`

`RepoFacts`

Compile tools-doc-truth findings into typed work packages (sprint 4.3).

Item
`pub struct RepoFacts`

`Report`

Compile tools-doc-truth findings into typed work packages (sprint 4.3).

Item
`pub struct Report`

`RoutedRun`

Compile tools-doc-truth findings into typed work packages (sprint 4.3).

Item
`pub struct RoutedRun`

`RoutingProposal`

Compile tools-doc-truth findings into typed work packages (sprint 4.3).

Item
`pub struct RoutingProposal`

`SenseOccurrence`

Compile tools-doc-truth findings into typed work packages (sprint 4.3).

Item
`pub struct SenseOccurrence`

`SenseShard`

Compile tools-doc-truth findings into typed work packages (sprint 4.3).

Item
`pub struct SenseShard`
`fn sense_shard_bytes(shard : & SenseShard) -> String`
`fn fit_sense_shard(mut shard : SenseShard, max_bytes : usize) -> Option <SenseShard>`

`WorkPackage`

Compile tools-doc-truth findings into typed work packages (sprint 4.3).

Item
`pub enum WorkPackage`
`WorkPackage :: fn executor_class(& self) -> Option <ExecutorClass>`
`WorkPackage :: fn id(& self) -> & str`
`WorkPackage :: fn shard_bytes(& self) -> String`
`fn compose_worker_prompt(pkg : & WorkPackage, model : Option <& str>) -> Result <String, String>`

`WorkerError`

Compile tools-doc-truth findings into typed work packages (sprint 4.3).

Item
`fn run_worker(model_bin : & str, prompt : & str, timeout_secs : u64, max_output_bytes : usize,) -> Result <(Vec <u8>, std::time::Duration), WorkerError>`
`fn run_worker_model(model_bin : & str, prompt : & str, timeout_secs : u64, max_output_bytes : usize, model : Option <& str>,) -> Result <(Vec <u8>, std::time::Duration), WorkerError>`
`pub enum WorkerError`
`WorkerError :: fn fmt(& self, f : & mut std::fmt::Formatter <'_>) -> std::fmt::Result`

`account (other)`

The model's own account (sprint 4.43d, US11): the ONE deliverable-contract

Item
`pub const MODEL_PROMPT_PROFILES_TSV: & str`
`fn reasoning_hash(text : & str) -> String`

`ModelAccount`

The model's own account (sprint 4.43d, US11): the ONE deliverable-contract

Item
`pub struct ModelAccount`
`fn split_model_account(text : & str) -> ModelAccount`

`PromptProfile`

The model's own account (sprint 4.43d, US11): the ONE deliverable-contract

Item
`pub struct PromptProfile`
`fn parse_prompt_profiles(tsv : & str) -> Result <Vec <(String, PromptProfile)>, String>`
`fn profile_for <'a>(profiles : & 'a (String, PromptProfile), model : Option <& str>,) -> & 'a PromptProfile`
`fn deliverable_contract(profile : & PromptProfile) -> String`

`ReasoningRequest`

The model's own account (sprint 4.43d, US11): the ONE deliverable-contract

Item
`pub enum ReasoningRequest`

`crate_walk (other)`

Whole-crate extraction: every publicly reachable module, with complete

Item
`pub const ONE_INFERENCE_ITEM_CEILING: usize`
`fn group_by_type_cohesion(m : & ModuleShard) -> Vec <ItemGroup>`
`fn inference_groups(m : & ModuleShard) -> Vec <ItemGroup>`
`fn item_name(signature : & str) -> String`
`fn source_files(dir : & Path) -> Vec <(String, String)>`
`fn test_functions(text : & str) -> Vec <(String, String)>`
`fn unsafe_sites(text : & str) -> Vec <String>`
`fn env_var_names(text : & str) -> Vec <String>`

`CrateApi`

Whole-crate extraction: every publicly reachable module, with complete

Item
`pub struct CrateApi`
`CrateApi :: fn surface(& self) -> Vec <String>`
`CrateApi :: fn item_count(& self) -> usize`
`fn mediate(api : & mut CrateApi, lexicon_tsv : & str, lexicon_version : & str)`
`fn walk_crate(crate_dir : & Path) -> CrateApi`

`EnvVisitor`

Whole-crate extraction: every publicly reachable module, with complete

Item
`EnvVisitor :: fn visit_expr_call(& mut self, i : & 'ast syn::ExprCall)`
`EnvVisitor :: fn visit_expr_macro(& mut self, i : & 'ast syn::ExprMacro)`

`ItemGroup`

Whole-crate extraction: every publicly reachable module, with complete

Item
`pub struct ItemGroup`
`fn split_by_verb(group : & ItemGroup) -> Vec <ItemGroup>`

`Mediation`

Whole-crate extraction: every publicly reachable module, with complete

Item
`pub struct Mediation`

`ModuleShard`

Whole-crate extraction: every publicly reachable module, with complete

Item
`pub struct ModuleShard`

`UnsafeVisitor`

Whole-crate extraction: every publicly reachable module, with complete

Item
`UnsafeVisitor :: fn visit_item_fn(& mut self, i : & 'ast syn::ItemFn)`
`UnsafeVisitor :: fn visit_item_impl(& mut self, i : & 'ast syn::ItemImpl)`
`UnsafeVisitor :: fn visit_item_trait(& mut self, i : & 'ast syn::ItemTrait)`
`UnsafeVisitor :: fn visit_expr_unsafe(& mut self, i : & 'ast syn::ExprUnsafe)`

`flow_pair (other)`

The J1 flow-pair shard (sprint 4.45, rule pair_emission): two flows of a browser

Item
`pub const FLOW_PAIR_SHARD_RULE_VERSION: & str`
`pub const QUESTION_SAME_CLASS: & str`
`pub const QUESTION_SHOULD_CONFORM: & str`
`fn digest(parts : & & str) -> String`
`fn flow_pair_shard(extension_dir : & str, a : FlowFacts, b : FlowFacts, repo_commit : & str,) -> FlowPairShard`

`FlowFacts`

The J1 flow-pair shard (sprint 4.45, rule pair_emission): two flows of a browser

Item
`pub struct FlowFacts`

`FlowPairShard`

The J1 flow-pair shard (sprint 4.45, rule pair_emission): two flows of a browser

Item
`pub struct FlowPairShard`
`fn flow_pair_shard_bytes(shard : & FlowPairShard) -> String`
`fn validate(bytes : & str) -> Result <FlowPairShard, String>`

`GateShape`

The J1 flow-pair shard (sprint 4.45, rule pair_emission): two flows of a browser

Item
`pub enum GateShape`

`SideEffectClass`

The J1 flow-pair shard (sprint 4.45, rule pair_emission): two flows of a browser

Item
`pub enum SideEffectClass`

How to use it

No examples/ target and no doctest in this crate's rustdoc. The tests listed under Verification are the closest executable usage.

Module structure

tools_packet_compile

account
crate_walk
flow_pair

flowchart TD
  n_tools_packet_compile["tools_packet_compile"]
  n_tools_packet_compile --> n_account["account"]
  n_tools_packet_compile --> n_crate_walk["crate_walk"]
  n_tools_packet_compile --> n_flow_pair["flow_pair"]

Public surface

`crate root`

Item	What it is
`pub const PACKETS_SCHEMA_VERSION: & str`	—
`pub struct Finding`	One tools-doc-truth finding, as deserialized from `tools-doc-truth check --json` (report schema 1.0.0)
`pub struct Report`	The tools-doc-truth report envelope.
`pub struct Provenance`	Where these packages came from — carried on the artifact, not recomputed.
`pub struct PubItem`	A public item in a crate's declared interface: signature plus its doc comment
`pub struct CrateShard`	The minimal projection a judgment package carries
`pub enum DetAction`	A deterministic edit an applier can execute with no extra context.
`pub enum WorkPackage`	Discriminated work-package types (Gate 1.5 amendment 1).
`pub enum ExecutorClass`	The ratified task-routing classes (harness-design-notes-2026-08-12 §4: `executor_class ∈ deterministic \
`pub enum EstimateBasis`	Who produced an estimate
`pub struct Estimate`	A prediction, stored at compile time so the actuals have something to be compared against
`pub struct Actual`	What a run actually cost
`pub struct Calibration`	Signed calibration error: positive means the prediction was too low
`fn calibration(est : & Estimate, act : & Actual) -> Calibration`	Compare a prediction with what happened.
`fn mechanical_estimate(pkg : & WorkPackage) -> Option <Estimate>`	A mechanical prediction for one package
`fn judgment_estimate(shard_bytes : usize) -> Estimate`	The judgment-class prediction, sized from the bytes actually handed to the model
`WorkPackage :: fn executor_class(& self) -> Option <ExecutorClass>`	The ratified routing class, or `None` for a package family that has no ratified class
`WorkPackage :: fn id(& self) -> & str`	—
`WorkPackage :: fn shard_bytes(& self) -> String`	The shard's canonical bytes, for hashing and byte accounting (sprint 4.20)
`fn shard_hash(shard_bytes : & str) -> String`	The hash of a compiled shard's bytes (sprint 4.20)
`pub const CRATE_SHARD_RULE_VERSION: & str`	The selection mechanism a crate shard is built by
`fn crate_shard_input_paths(crate_dir : & std::path::Path) -> Vec <String>`	The repo-relative inputs `extract_shard` reads for `crate_dir`, in the order it reads them
`fn crate_shard_bytes(shard : & CrateShard) -> String`	The canonical bytes of a crate shard, which is what gets hashed.
`pub struct CallSite`	One place a function is called from
`pub struct FnShard`	One function, in full, with what a judge needs around it
`pub const FN_SHARD_RULE_VERSION: & str`	The selection mechanism an `FnShard` is built by
`pub struct SenseOccurrence`	One occurrence of a governed word, as a judge is shown it (sprint 4.47 U1c).
`pub struct SenseShard`	The question "which of these occurrences mean the governed thing"
`pub const SENSE_SHARD_RULE_VERSION: & str`	The selection mechanism a `SenseShard` is built by.
`fn sense_shard_bytes(shard : & SenseShard) -> String`	The canonical bytes of a sense shard, which is what gets hashed.
`fn fit_sense_shard(mut shard : SenseShard, max_bytes : usize) -> Option <SenseShard>`	Fit a sense shard under a byte cap by dropping occurrences, never the definition
`fn fn_shard_bytes(shard : & FnShard) -> String`	The canonical bytes of a function shard, which is what gets hashed.
`fn fit_fn_shard(mut shard : FnShard, max_bytes : usize) -> Option <FnShard>`	Fit a shard under a byte cap by dropping callers, never the body
`fn recompile_crate_shard(crate_dir : & std::path::Path, crate_name : & str, layer : & str, reverse_deps : Vec <String>,) -> anyhow::Result <String>`	Re-run the crate-shard compiler and return the hash it produces now
`fn recompile_crate_shard_bytes(crate_dir : & std::path::Path, crate_name : & str, layer : & str, reverse_deps : Vec <String>,) -> anyhow::Result <(String, String)>`	Re-run the crate-shard compiler and return the canonical bytes AND their hash (4.43c populate: the payload store keeps the bytes; its CHECK re-hashes them to the key, so both must come from one mechanism)
`fn semantics_hash(prompt : & str) -> String`	The hash of the mediated semantics actually handed to a model: the composed prompt, verbatim, including any corrective note
`pub struct Packets`	The emitted artifact: one `packets.json`, canonically ordered.
`pub struct RepoFacts`	Injected repo facts — everything the pure compiler needs that is not in the report
`pub const D7_ANSWER_TYPE: & str`	—
`pub const D7_TOOL_AUTHORITY: & str`	—
`pub const D7_STOP_CONDITIONS: & str`	—
`fn renumber_sprint(number : & str, files : & (String, i64), existing : & BTreeSet <String>,) -> Vec <DetAction>`	The formalized D3 rule (Gate 1.5 amendment 2): earliest first-commit date keeps the number (path-lexicographic tiebreak); every later file gains the next FREE `.n` suffix, skipping occupied names, idempotently.
`fn compile(report : & Report, facts : & RepoFacts, provenance : Provenance) -> Packets`	Bucket findings by detector and compile the canonical package list
`fn dir_rename_of(from : & str, to : & str) -> Option <(String, String)>`	Reduce one file-level rename to the directory rename it implies, by stripping the longest common trailing path segments
`fn follow_renames(cited : & str, files : & BTreeMap <String, String>, dirs : & BTreeMap <String, String>,) -> Option <String>`	Follow git's rename record from a path as cited to the path that content sits at today
`fn sprint_number(filename : & str) -> Option <String>`	Parse the sprint number out of a userstory filename (`sprint-3.14.1-slug.md` → `3.14.1`)
`fn invert_deps(deps : & BTreeMap <String, Vec <String>>) -> BTreeMap <String, Vec <String>>`	Invert a crate→deps map into crate→reverse-deps (workspace members only).
`fn layer_of(path : & str) -> String`	Layer of a crate path: `crates/<layer>/<crate>` → layer; flat crates → `flat`.
`fn compose_worker_prompt(pkg : & WorkPackage, model : Option <& str>) -> Result <String, String>`	Canonical serialization: the artifact bytes every consumer compares
`fn compose_manifest_prompt(label : & str, goal : & str, manifest : & str, model : Option <& str>,) -> Result <String, String>`	Compose the manifest-shaped worker prompt (the work-runner / resubmit form — sprint 4.43d lifted work-runner's literal here so the resubmit path could not become a third drifting copy)
`fn worker_argv(model : Option <& str>) -> Vec <String>`	The runner's model binary allowlist (Gate 1.5.6: configurable binary path, allowlisted)
`fn run_worker(model_bin : & str, prompt : & str, timeout_secs : u64, max_output_bytes : usize,) -> Result <(Vec <u8>, std::time::Duration), WorkerError>`	—
`fn resolve_model(override_model : Option <& str>, routing_kind : Option <& str>, seed_text : & str,) ->(Option <String>, & 'static str)`	Resolve the worker model from the routing seed (sprint 4.10 AC6)
`fn run_worker_model(model_bin : & str, prompt : & str, timeout_secs : u64, max_output_bytes : usize, model : Option <& str>,) -> Result <(Vec <u8>, std::time::Duration), WorkerError>`	—
`pub struct RoutedRun`	One routed-run observation for the E-series (sprint 4.10 AC8): parsed from run_measurement rows by the caller
`pub struct RoutingProposal`	A FOR-RATIFICATION routing proposal.
`pub const TIER_COST_ORDER: & str; 3`	Cheaper-first tier order for proposal direction.
`fn propose_routing(runs : & RoutedRun, min_runs : usize) -> Vec <RoutingProposal>`	The E-series proposer (real-use data only; the operator ratifies every change)
`pub enum WorkerError`	Infra failures may consume an infra-retry; a worker's own failure consumes the single corrective retry
`WorkerError :: fn fmt(& self, f : & mut std::fmt::Formatter <'_>) -> std::fmt::Result`	—
`fn runner_bin_allowed(bin : & str) -> bool`	—
`fn to_canonical_json(p : & Packets) -> String`	—
`fn extract_shard(crate_dir : & std::path::Path, crate_name : & str, layer : & str, reverse_deps : Vec <String>,) -> anyhow::Result <CrateShard>`	Build a crate shard from a crate directory: Cargo.toml description + features, lib.rs `//!` lines, pub item signatures with their `///` docs, `mod` names

`account`

Item	What it is
`pub const MODEL_PROMPT_PROFILES_TSV: & str`	The ratified per-model prompt profiles, compiled in (one table, every producer — the model-rates precedent).
`pub enum ReasoningRequest`	How a model is asked for its account.
`pub struct PromptProfile`	One profile row: how to ask, and the recorded basis for believing it.
`fn parse_prompt_profiles(tsv : & str) -> Result <Vec <(String, PromptProfile)>, String>`	Parse the profile TSV
`fn profile_for <'a>(profiles : & 'a (String, PromptProfile), model : Option <& str>,) -> & 'a PromptProfile`	The profile for `model`: the LONGEST matching prefix wins, else `default`.
`fn deliverable_contract(profile : & PromptProfile) -> String`	The terminal contract line of every worker prompt (US11) — replaces the old "Output ONLY the deliverable" line, which forbade the very account this sprint exists to capture.
`fn reasoning_hash(text : & str) -> String`	The hash a stored reasoning payload is keyed by — the same digest the payload store's DB CHECK re-computes (`foundation-audit-log`, Gate 0.5: one definition, never hand-rolled).
`pub struct ModelAccount`	The account extracted from a deliverable, with the deliverable stripped of the trailing block (the review artifact keeps the work, the account is stored beside it).
`fn split_model_account(text : & str) -> ModelAccount`	Parse the trailing REASONING/CONFIDENCE block off a deliverable

`crate_walk`

Item	What it is
`pub struct ModuleShard`	One publicly reachable module and everything it exposes.
`pub struct Mediation`	The vocabulary state a shard is governed by, carried WITH the evidence
`pub struct CrateApi`	What one crate exposes, module by module.
`CrateApi :: fn surface(& self) -> Vec <String>`	Every public item across every module, as `module::name` keys
`CrateApi :: fn item_count(& self) -> usize`	—
`pub const ONE_INFERENCE_ITEM_CEILING: usize`	Above this, a group is not one inference
`pub struct ItemGroup`	A type-cohesive group of items: one type, its methods, and the functions that take or return it
`fn group_by_type_cohesion(m : & ModuleShard) -> Vec <ItemGroup>`	Split a module into type-cohesive groups
`fn split_by_verb(group : & ItemGroup) -> Vec <ItemGroup>`	Split an over-ceiling group by leading verb: `record_` is one inference, `parse_` is another
`fn inference_groups(m : & ModuleShard) -> Vec <ItemGroup>`	Type cohesion, then verb families for anything still too large
`fn mediate(api : & mut CrateApi, lexicon_tsv : & str, lexicon_version : & str)`	Remove retired vocabulary from a shard's evidence before any model sees it
`fn item_name(signature : & str) -> String`	The declared name in a rendered signature: the token after the keyword
`fn walk_crate(crate_dir : & Path) -> CrateApi`	Parse a crate's public API, walking from its entry point through every publicly reachable module
`fn source_files(dir : & Path) -> Vec <(String, String)>`	Every `.rs` file under `dir`, recursively, as `(path relative to` dir`, text)`, sorted by path
`fn test_functions(text : & str) -> Vec <(String, String)>`	Test functions by name, with the attribute that made each one a test
`fn unsafe_sites(text : & str) -> Vec <String>`	`unsafe fn` declarations, `unsafe impl`s, `unsafe trait`s and `unsafe {}` blocks, as human-readable kinds.
`UnsafeVisitor :: fn visit_item_fn(& mut self, i : & 'ast syn::ItemFn)`	—
`UnsafeVisitor :: fn visit_item_impl(& mut self, i : & 'ast syn::ItemImpl)`	—
`UnsafeVisitor :: fn visit_item_trait(& mut self, i : & 'ast syn::ItemTrait)`	—
`UnsafeVisitor :: fn visit_expr_unsafe(& mut self, i : & 'ast syn::ExprUnsafe)`	—
`fn env_var_names(text : & str) -> Vec <String>`	Environment-variable names read with a LITERAL argument: `std::env::var("X")`, `env!("X")`, `option_env!("X")`
`EnvVisitor :: fn visit_expr_call(& mut self, i : & 'ast syn::ExprCall)`	—
`EnvVisitor :: fn visit_expr_macro(& mut self, i : & 'ast syn::ExprMacro)`	—

`flow_pair`

Item	What it is
`pub const FLOW_PAIR_SHARD_RULE_VERSION: & str`	The selection and projection mechanism
`pub const QUESTION_SAME_CLASS: & str`	The two questions, fixed text: a seat answers these and nothing else.
`pub const QUESTION_SHOULD_CONFORM: & str`	—
`pub enum SideEffectClass`	The class of real-world side effect a flow ends in.
`pub enum GateShape`	One kind of gate on the path to the action, as a shape, not a condition.
`pub struct FlowFacts`	One flow, as structural facts only.
`pub struct FlowPairShard`	Two flows and the two questions.
`fn digest(parts : & & str) -> String`	The digest an id or location field carries: lowercase hex, 64 chars
`fn flow_pair_shard(extension_dir : & str, a : FlowFacts, b : FlowFacts, repo_commit : & str,) -> FlowPairShard`	Build the pair
`fn flow_pair_shard_bytes(shard : & FlowPairShard) -> String`	The canonical bytes, which are what gets hashed and validated
`fn validate(bytes : & str) -> Result <FlowPairShard, String>`	Hold the contract at the boundary: parse the bytes as the closed schema and refuse any field whose value is not the kind the schema names

No pub use re-exports: every item above is declared in this crate.

Boundary

Reaches into foundation.

Shares tier tools with 84 other crates: tools-advisory-reach, tools-archive-guard, tools-artifact-scaffold, tools-ask-ai-core, tools-ask-ais, tools-ask-gemini, tools-book, tools-book-report, … (84 total).

_What this crate deliberately does NOT own is a judgment. No committed registry records one for it, so none is stated here._

Where it sits

Tier (ontology)	`tools`
Architectural role (taxonomy)	`unclassified (baselined)`
Location	`crates/tools/packet-compile`
Vocabulary in force (lexicon)	`current`

Tier flow. Which tiers this crate's own edges cross.

flowchart LR
  n_tools["tools"] --> n_foundation["foundation"]

Dependencies

Runtime, in this workspace.

Crate	Tier	Optional	Only on
`foundation-audit-log`	foundation	no	always
`foundation-lexicon`	foundation	no	always

Runtime, from outside the workspace.

Crate	Requirement	Features	Optional	Only on
`anyhow`	`^1`	—	no	always
`proc-macro2`	`^1`	—	no	always
`quote`	`^1`	—	no	always
`serde`	`^1`	`derive`	no	always
`serde_json`	`^1`	—	no	always
`syn`	`^2`	`full`, `parsing`, `printing`, `clone-impls`, `visit`	no	always

Development, from outside the workspace.

Crate	Requirement	Features	Optional	Only on
`tempfile`	`^3`	—	no	always

Build. None.

Depended on by. 5 workspace crates.

Signal flow — what reaches this crate, and what it reaches.

flowchart LR
  n_tools_corpus["tools-corpus"] -->|uses| SELF
  n_tools_extension_conformance["tools-extension-conformance"] -->|uses| SELF
  n_tools_fleet_reconnect["tools-fleet-reconnect"] -->|uses| SELF
  n_tools_packet_apply["tools-packet-apply"] -->|uses| SELF
  n_tools_work_runner["tools-work-runner"] -->|uses| SELF
  SELF["tools-packet-compile"]
  SELF -->|runtime| n_foundation_audit_log["foundation-audit-log"]
  SELF -->|runtime| n_foundation_lexicon["foundation-lexicon"]
  classDef self fill:#1f883d,stroke:#1f883d,color:#fff;
  class SELF self;

Feature flags

No Cargo features are defined: every capability is unconditional, so no consumer can receive a half-wired crate.

Targets

Kind	Name	Source
bin	`tools-packet-compile`	`src/main.rs`
lib	`tools_packet_compile`	`src/lib.rs`

Error model

Error type	Named by
`WorkerError`	`run_worker`, `run_worker_model`

Operational characteristics

Property	Evidence
async public surface	none detected
async runtime	none detected
database access	none detected
network I/O	none detected
unsafe code	none detected
environment variables	yes

No unsafe block, unsafe fn, unsafe impl or unsafe trait was found by the parser anywhere in this crate's source.

Configuration

Variable	Read in
`CARGO_PKG_VERSION`	`src/main.rs`

5 workspace crates depend on this one: tools-corpus, tools-extension-conformance, tools-fleet-reconnect, tools-packet-apply, tools-work-runner.

Verification

Kind	Count
Unit tests	67
Integration tests	0
Examples	0
Doctests	0

Evidence by module. How often each public module is named by something executable.

Module	Tests	Consumers
`crate root`	59	44
`account`	9	6
`crate_walk`	15	10
`flow_pair`	11	12

What the tests establish, by name:

a_bad_confidence_is_none_not_a_guess — src/account.rs
a_deliverable_mentioning_the_words_mid_line_is_untouched — src/account.rs
a_malformed_row_is_an_error_not_a_skip — src/account.rs
absence_is_recorded_never_invented — src/account.rs
confidence_only_works_and_reasoning_only_works — src/account.rs
longest_prefix_wins_and_default_backstops — src/account.rs
split_extracts_the_trailing_block — src/account.rs
the_contract_asks_for_the_account_not_silence — src/account.rs
the_shipped_tsv_parses_and_carries_a_default — src/account.rs
a_module_splits_into_type_cohesive_groups — src/crate_walk.rs
a_path_attribute_module_is_resolved_and_walked — src/crate_walk.rs
an_item_naming_two_types_is_residual_unless_it_declares_one — src/crate_walk.rs
an_over_ceiling_residual_splits_by_verb_and_says_when_it_cannot — src/crate_walk.rs
an_oversized_group_is_reported_rather_than_arbitrarily_split — src/crate_walk.rs
an_unmediated_shard_states_no_policy — src/crate_walk.rs
an_unparseable_file_is_reported_not_skipped — src/crate_walk.rs
environment_variables_are_read_from_literal_arguments_only — src/crate_walk.rs
impl_methods_and_reexports_are_api — src/crate_walk.rs
item_name_reads_the_declared_name_or_nothing — src/crate_walk.rs
multi_line_signatures_are_captured_whole — src/crate_walk.rs
retired_vocabulary_never_leaves_the_shard — src/crate_walk.rs
shard_of_a_multi_module_crate — src/crate_walk.rs
source_files_are_recursive_and_ordered_by_path — src/crate_walk.rs
submodule_api_is_found_not_just_the_root — src/crate_walk.rs
test_functions_are_named_including_the_runner_attributes — src/crate_walk.rs
unsafe_is_detected_by_syntax_and_not_by_the_word — src/crate_walk.rs
a_packet_carrying_a_raw_source_span_is_refused — src/flow_pair.rs
the_bytes_are_canonical_and_two_pairs_differ_by_their_facts — src/flow_pair.rs
the_shard_carries_digests_enums_counts_and_the_fixed_questions_only — src/flow_pair.rs
a_body_that_will_not_fit_alone_is_refused_and_never_truncated — src/lib.rs
_… 37 more_

Documentation coverage

Measure	Documented	Total
Public items with rustdoc	88	106
Public modules with a `//!` block	3	3

pie showData
    title Public items with rustdoc
    "Documented" : 88
    "No rustdoc detected" : 18

Metrics

Metric	Value
Rust source files	5
Source lines	5432
Code lines	4169
Public API items	106
Public modules	3
Tests	67
Examples	0
Cargo features	0
Direct runtime dependencies	8
Workspace reverse dependencies	5

pie showData
    title Public API by kind
    "constant" : 13
    "enum" : 8
    "function" : 49
    "method" : 12
    "struct" : 24

pie showData
    title Rust source composition
    "Code" : 4169
    "Blank or comment" : 1263

Generation

Rendered by tools-corpus corpus readme from repository evidence alone, renderer schema 2, lexicon current. No model, network service or database was consulted. Regenerate with tools-corpus corpus readme --write; verify with --check.

What it is for

Capabilities

verb:compile

verb:compose

verb:constants

verb:crate

verb:dir

verb:follow

verb:invert

verb:layer

verb:propose

verb:recompile

verb:resolve

verb:runner

verb:semantics

verb:shard

verb:sprint

verb:worker

Actual

Calibration

CallSite

CrateShard

DetAction

Estimate

EstimateBasis

ExecutorClass

Finding

FnShard

Packets

Provenance

PubItem

RepoFacts

Report

RoutedRun

RoutingProposal

SenseOccurrence

SenseShard

WorkPackage

WorkerError

account (other)

ModelAccount

PromptProfile

ReasoningRequest

crate_walk (other)

CrateApi

EnvVisitor

ItemGroup

Mediation

ModuleShard

UnsafeVisitor

flow_pair (other)

FlowFacts

FlowPairShard

GateShape

SideEffectClass

How to use it

Module structure

Public surface

Boundary

Where it sits

Dependencies

Feature flags

Targets

Error model

Operational characteristics

Configuration

Related capabilities

Verification

Documentation coverage

Metrics

Generation

`verb:compile`

`verb:compose`

`verb:constants`

`verb:crate`

`verb:dir`

`verb:follow`

`verb:invert`

`verb:layer`

`verb:propose`

`verb:recompile`

`verb:resolve`

`verb:runner`

`verb:semantics`

`verb:shard`

`verb:sprint`

`verb:worker`

`Actual`

`Calibration`

`CallSite`

`CrateShard`

`DetAction`

`Estimate`

`EstimateBasis`

`ExecutorClass`

`Finding`

`FnShard`

`Packets`

`Provenance`

`PubItem`

`RepoFacts`

`Report`

`RoutedRun`

`RoutingProposal`

`SenseOccurrence`

`SenseShard`

`WorkPackage`

`WorkerError`

`account (other)`

`ModelAccount`

`PromptProfile`

`ReasoningRequest`

`crate_walk (other)`

`CrateApi`

`EnvVisitor`

`ItemGroup`

`Mediation`

`ModuleShard`

`UnsafeVisitor`

`flow_pair (other)`

`FlowFacts`

`FlowPairShard`

`GateShape`

`SideEffectClass`