Skip to content

refactor(koinon): split the shared crate into stoicheion and tekmerion - #460

Merged
forkwright merged 2 commits into
mainfrom
refactor/264-split-koinon
Aug 21, 2026
Merged

refactor(koinon): split the shared crate into stoicheion and tekmerion#460
forkwright merged 2 commits into
mainfrom
refactor/264-split-koinon

Conversation

@forkwright

Copy link
Copy Markdown
Owner

Resolves the VOCAB/crate-name-collision finding 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 lint flagged crates/koinon for colliding by name with the standalone
fleet repo koinon. The issue framed the fix as a choice: add a
distinct_concepts block to kanon's fleet-wide hub-words.toml, or rename one
of the two.

Reading the crate settles which. The name collided because the concept did:
koinon ("common/shared") held two unrelated things under one label — the
vocabulary the workspace speaks in, and the evidence it produces about what was
done. A distinct_concepts entry would have declared the two names distinct
while 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 value
types: EntityId, SignalId, Timestamp, Coordinates, Power,
Confidence, the signal and hardware taxonomies.

tekmerion — evidence. ValidatedCaller and caller authority, 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. stoicheion has no dependency on tekmerion in its manifest and
no 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.rs keeps four domain separators reading koinon/...:

const GENESIS_DOMAIN: &[u8] = b"koinon/tamper-log/genesis/v1";
const SEAL_DOMAIN:    &[u8] = b"koinon/tamper-log/seal/v1";
const SIGNED_SEAL_DOMAIN: &[u8] = b"koinon/tamper-log/seal-signed/v1";
pub(super) const TIP_SIGNING_DOMAIN: &[u8] = b"koinon/tamper-log/tip/v1";

These are not names. They are keyed-hash inputs: GENESIS_DOMAIN seeds every
chain'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, so
it verified all 8 packages rather than a subset).

One check earns specific mention. crates/akroasis/tests/caller_architecture.rs
guards that domain crates consume ValidatedCaller rather than minting
principals, via a path allowlist that named crates/koinon/src/{caller,lib}.rs.
Those entries were repointed to crates/tekmerion/.... That edit is
load-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
(kanon crates/basanos/standards/fleet-repos.toml @ origin/main, 31 rows):
koinon is present — which is the finding — while stoicheion and tekmerion
are both absent. So the rename resolves the collision without minting a new one.

forkwright 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.
@forkwright
forkwright merged commit 537fcbd into main Aug 21, 2026
11 checks passed
@forkwright
forkwright deleted the refactor/264-split-koinon branch August 21, 2026 16:23
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant