tools-imp-control — IMP FORGE

Administration for the imp_control database: apply its registered schema through the module migration runner, and register a repository -- the row a context switch resolves into a mirror corpus, a record corpus, a tree and an executor. The sanctioned writer for a registry that routes between repositories and therefore cannot live inside one of them.

Tier	tools
Role	tooling
Path	`crates/tools/imp-control`
Edition	2021
Targets	imp-control, tools_imp_control
Public items	24 across 0 modules
Tests	15

What it is for

imp_control's administration: apply its schema, and register a repository.

Why a writer rather than an INSERT: tools-shell-guard refuses a hand-written statement against a live database, and it is right to. A repository row is what a context switch resolves — the corpus that holds what was read, the corpus that holds what was decided, the tree, the executor. A typo in it does not fail loudly; it silently routes work to the wrong place.

The validation here is pure, so every refusal is a unit test rather than a live-database experiment.

Capabilities

`crate root`

imp_control's administration: apply its schema, and register a repository.

Item
`pub const MAX_SHORT_NAME: usize`
`fn validate(r : & Registration) -> Result <(), RegisterError>`
`fn weigh(tables : & (String, i64), side_of : & std::collections::BTreeMap <String, Side>,) -> Weight`
`fn reconcile(estate : & ConnectionRow, host : & ConnectionRow) -> Vec <Divergence>`

`ConnectionRow`

imp_control's administration: apply its schema, and register a repository.

Item
`pub struct ConnectionRow`

`Crossing`

imp_control's administration: apply its schema, and register a repository.

Item
`pub struct Crossing`
`Crossing :: fn is_internal(& self) -> bool`
`Crossing :: fn is_forward(& self) -> bool`

`Divergence`

imp_control's administration: apply its schema, and register a repository.

Item
`pub enum Divergence`
`fn contradicts(divergences : & Divergence) -> bool`

`Edges`

imp_control's administration: apply its schema, and register a repository.

Item
`pub struct Edges`
`fn classify_edges(edges : & (String, String), side_of : & std::collections::BTreeMap <String, Side>,) -> Edges`

`RegisterError`

imp_control's administration: apply its schema, and register a repository.

Item
`pub enum RegisterError`
`fn validate_short_name(short : & str) -> Result <(), RegisterError>`

`Registration`

imp_control's administration: apply its schema, and register a repository.

Item
`pub struct Registration`

`Side`

imp_control's administration: apply its schema, and register a repository.

Item
`pub enum Side`
`Side :: fn parse(s : & str) -> Option <Self>`
`Side :: fn as_str(self) -> & 'static str`
`fn parse_classification(text : & str) -> Result <Vec <(String, Side)>, String>`

`SiteKind`

imp_control's administration: apply its schema, and register a repository.

Item
`pub enum SiteKind`
`fn classify_line(line : & str) -> SiteKind`

`Weight`

imp_control's administration: apply its schema, and register a repository.

Item
`pub struct Weight`

`Wiring`

imp_control's administration: apply its schema, and register a repository.

Item
`pub struct Wiring`
`pub const WIRING: & Wiring`

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

No public modules: the crate root is its whole surface.

Public surface

`crate root`

Item	What it is
`pub const MAX_SHORT_NAME: usize`	The longest a handle may be
`pub enum RegisterError`	—
`pub struct Registration`	What a repository registration says.
`fn validate(r : & Registration) -> Result <(), RegisterError>`	Check a registration before it reaches the database
`fn validate_short_name(short : & str) -> Result <(), RegisterError>`	The handle rule, separately so a caller can check one before asking
`pub enum Side`	Which of the three authorities a table belongs to
`Side :: fn parse(s : & str) -> Option <Self>`	Parse the word the classification file uses.
`Side :: fn as_str(self) -> & 'static str`	—
`fn parse_classification(text : & str) -> Result <Vec <(String, Side)>, String>`	Read the classification file: `table<TAB>side<TAB>rows<TAB>reason`, with `#` comments and blank lines ignored
`pub struct Crossing`	One foreign key, by the sides it connects.
`Crossing :: fn is_internal(& self) -> bool`	Does this edge stay inside one authority?
`Crossing :: fn is_forward(& self) -> bool`	Does it point the way dependency is allowed to run — the specific depending on the general? record -> upstream, record -> control and upstream -> control are forward: they become stable-UUID references
`pub struct Weight`	What each authority would weigh, and what nobody has classified.
`fn weigh(tables : & (String, i64), side_of : & std::collections::BTreeMap <String, Side>,) -> Weight`	Weigh every live table against the classification.
`pub struct Edges`	Every foreign key, sorted into what the cut would do to it.
`fn classify_edges(edges : & (String, String), side_of : & std::collections::BTreeMap <String, Side>,) -> Edges`	Sort the foreign keys by what the decomposition would do to each.
`pub enum SiteKind`	What one line does with a connection identifier
`fn classify_line(line : & str) -> SiteKind`	Classify one line by what it does with the identifier
`pub struct Wiring`	A connection identifier hardcoded somewhere in the tree, and the setting that should replace it
`pub const WIRING: & Wiring`	Every connection identifier this estate currently hardcodes
`pub struct ConnectionRow`	One registry's statement about how something is reached
`pub enum Divergence`	What two registries disagree about, or what only one of them knows.
`fn reconcile(estate : & ConnectionRow, host : & ConnectionRow) -> Vec <Divergence>`	Compare the estate's `datasource` registry with the host's `connections`
`fn contradicts(divergences : & Divergence) -> bool`	True when the two registries contradict each other about something both name

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

Boundary

Reaches into application, operations.

Shares tier tools with 90 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, … (90 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)	`tooling`
Location	`crates/tools/imp-control`
Vocabulary in force (lexicon)	`current`

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

flowchart LR
  n_tools["tools"] --> n_application["application"]
  n_tools["tools"] --> n_operations["operations"]

Dependencies

Runtime, in this workspace.

Crate	Tier	Optional	Only on
`application-core`	application	no	always
`operations-control-plane`	operations	no	always
`tools-packet-apply`	tools	no	always

Runtime, from outside the workspace.

Crate	Requirement	Features	Optional	Only on
`clap`	`^4`	`derive`	no	always
`serde_json`	`^1`	—	no	always
`sqlx`	`^0.8`	`runtime-tokio`, `postgres`, `chrono`, `uuid`, `json`	no	always
`thiserror`	`^2`	—	no	always
`tokio`	`^1`	`full`, `macros`, `rt-multi-thread`	no	always
`uuid`	`^1`	`v4`, `v7`, `serde`, `js`, `v7`	no	always

Development, in this workspace.

Crate	Tier	Optional	Only on
`tools-cli-conformance`	tools	no	always

Build. None.

Depended on by. Nothing in this workspace.

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

flowchart LR
  SELF["tools-imp-control"]
  SELF -->|development| n_tools_cli_conformance["tools-cli-conformance"]
  SELF -->|runtime| n_application_core["application-core"]
  SELF -->|runtime| n_operations_control_plane["operations-control-plane"]
  SELF -->|runtime| n_tools_packet_apply["tools-packet-apply"]
  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	`imp-control`	`src/main.rs`
lib	`tools_imp_control`	`src/lib.rs`

Error model

Error type	Named by
`RegisterError`	`validate`, `validate_short_name`

Operational characteristics

Property	Evidence
async public surface	none detected
async runtime	yes
database access	yes
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
`CORPUS_HOST_DB`	`src/main.rs`
`CORPUS_SOURCECODE_APP_DB`	`src/main.rs`
`IMP_CONTROL_DB`	`src/main.rs`

No workspace crate depends on this one.

Verification

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

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

Module	Tests	Examples	Consumers
`crate root`	20	0	0

What the tests establish, by name:

a_contradiction_names_the_field_and_both_answers — src/lib.rs
a_handle_is_spelled_like_a_handle — src/lib.rs
a_line_that_reads_the_variable_is_never_treated_as_prose — src/lib.rs
a_name_carries_no_whitespace — src/lib.rs
a_registration_says_who_made_it — src/lib.rs
a_source_root_must_be_absolute — src/lib.rs
a_table_the_classification_does_not_name_is_reported_not_counted — src/lib.rs
a_well_formed_registration_passes — src/lib.rs
agreement_is_silence — src/lib.rs
dependency_may_run_from_the_specific_to_the_general_only — src/lib.rs
every_edge_lands_in_exactly_one_bucket — src/lib.rs
scope_is_not_conflict — src/lib.rs
the_classification_file_parses_and_a_typo_does_not_vanish — src/lib.rs
the_earlier_spelling_of_the_record_side_still_reads — src/lib.rs
cli_definition_conforms — src/main.rs

Documentation coverage

Measure	Documented	Total
Public items with rustdoc	22	24
Public modules with a `//!` block	0	0

pie showData
    title Public items with rustdoc
    "Documented" : 22
    "No rustdoc detected" : 2

Metrics

Metric	Value
Rust source files	2
Source lines	1717
Code lines	1376
Public API items	24
Public modules	0
Tests	15
Examples	0
Cargo features	0
Direct runtime dependencies	9
Workspace reverse dependencies	0

pie showData
    title Public API by kind
    "constant" : 2
    "enum" : 4
    "function" : 8
    "method" : 4
    "struct" : 6

pie showData
    title Rust source composition
    "Code" : 1376
    "Blank or comment" : 341

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

crate root

ConnectionRow

Crossing

Divergence

Edges

RegisterError

Registration

Side

SiteKind

Weight

Wiring

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

`crate root`

`ConnectionRow`

`Crossing`

`Divergence`

`Edges`

`RegisterError`

`Registration`

`Side`

`SiteKind`

`Weight`

`Wiring`