refactor(koinon): split the shared crate into stoicheion and tekmerion - #460
Merged
Conversation
added 2 commits
August 21, 2026 11:13
The `koinon` crate collided by name with the standalone fleet repo of the same name, and the collision was not incidental: the crate held two unrelated things under one "common types" label. Splitting it resolves the collision and the conflation in the same move. `stoicheion` carries the workspace vocabulary — the identifiers, units, and value types every crate speaks in. `tekmerion` carries evidence: callers, effect receipts, and the tamper log that attests to them. The dependency runs one way, tekmerion on stoicheion, because evidence is stated in the vocabulary while the vocabulary knows nothing about being attested. The tamper-log domain separators keep their original `koinon/...` strings. They are keyed-hash inputs rather than names, so changing one re-roots every existing chain and makes logs already on disk verify as broken — which is indistinguishable from the tampering they exist to detect. `tamper_log_seal.rs` carries that constraint at the constants themselves.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Resolves the
VOCAB/crate-name-collisionfinding recorded in the "Note —separate finding, same lint pass" section of issue 264. It does not touch
that issue's main body — the 7 unwired-dead-code sites are untouched and issue
264 stays open on them.
What the collision actually was
kanon lintflaggedcrates/koinonfor colliding by name with the standalonefleet repo
koinon. The issue framed the fix as a choice: add adistinct_conceptsblock to kanon's fleet-widehub-words.toml, or rename oneof the two.
Reading the crate settles which. The name collided because the concept did:
koinon("common/shared") held two unrelated things under one label — thevocabulary the workspace speaks in, and the evidence it produces about what was
done. A
distinct_conceptsentry would have declared the two names distinctwhile leaving one crate genuinely holding two concepts, which is the condition
the lint is pointing at rather than the naming accident on its surface.
The split
stoicheion— the workspace vocabulary. Identifiers, units, and valuetypes:
EntityId,SignalId,Timestamp,Coordinates,Power,Confidence, the signal and hardware taxonomies.tekmerion— evidence.ValidatedCallerand caller authority, effectreceipts, and the tamper log that attests to them.
The dependency runs one way —
tekmeriononstoicheion— because evidence isstated in the vocabulary, while the vocabulary knows nothing about being
attested.
stoicheionhas no dependency ontekmerionin its manifest andno code reference to it; its module doc names the crate once, to state which
way the edge runs.
The one thing deliberately not renamed
tamper_log_seal.rskeeps four domain separators readingkoinon/...:These are not names. They are keyed-hash inputs:
GENESIS_DOMAINseeds everychain's root hash and the seal domains key every MAC. Changing one byte re-roots
the chain, so every tamper log already on disk would verify as broken — and
a broken verification is indistinguishable from the tampering the log exists to
detect. A search-and-replace that "finished the rename" here would be a silent,
unrecoverable break in the one component whose entire purpose is detecting
silent breaks.
The constraint is now written at the constants themselves, so the next person
holding a rename script reads it before running one.
Verification
utilities/pre-push-verify.sh, whole workspace (the root manifest changed, soit verified all 8 packages rather than a subset).
One check earns specific mention.
crates/akroasis/tests/caller_architecture.rsguards that domain crates consume
ValidatedCallerrather than mintingprincipals, via a path allowlist that named
crates/koinon/src/{caller,lib}.rs.Those entries were repointed to
crates/tekmerion/.... That edit isload-bearing rather than cosmetic: both files genuinely contain 5 of the 6
restricted identifiers, so leaving the allowlist stale would have made the guard
fail on tekmerion — the safe direction, but still a break. Repointing keeps
the guard meaning exactly what it meant before.
The new names were checked against the collision they are meant to resolve
rather than assumed clear. Against the canonical registry
(
kanoncrates/basanos/standards/fleet-repos.toml@origin/main, 31 rows):koinonis present — which is the finding — whilestoicheionandtekmerionare both absent. So the rename resolves the collision without minting a new one.