# Open item — substrate-proto naming violation

**Status:** Documented 2026-04-20. Not v1-blocking. CNCF-sandbox-blocking.
**Scope:** bascule-oss architectural positioning. Coordinated change with the substrate workspace.

## The finding

`bascule-oss/crates/bascule-core/Cargo.toml` depends on `substrate-proto` (via `workspace = true` in this repo's root `Cargo.toml`). `substrate-proto` is itself a facade over `substrate-common`, sourced from the sibling substrate workspace via path dependency. Both names are substrate-prefixed.

This simultaneously:

- Violates [CLAUDE.md](CLAUDE.md)'s rule *"Zero substrate/chronicle/gsap dependencies"*.
- Fails [CI contamination check](.github/workflows/ci.yml) on lines matching `substrate|chronicle|gsap|hfl|metakernel` in `Cargo.lock` — current `Cargo.lock` contains `substrate-common`, `substrate-hfl`, `substrate-proto`, `hfl-types` entries.
- Creates the optical problem of bascule-oss visibly depending on Guildhouse-substrate-named infrastructure, even though the *content* of what's depended on is legitimately neutral (SAT protocol types).

## The content is fine; the packaging is the problem

`substrate-proto` exposes proto-generated Substrate Attestation Token (SAT) types. SAT is a protocol contract between substrate (the attestation producer) and bascule (the session-composing consumer). bascule-core needs the wire format types to compose SATs that substrate-produced Keylime verifiers will accept. That's a legitimate cross-boundary architectural dependency — not a leak of substrate-internal types into a generic SSH-auth surface.

The problem is naming. `substrate-proto` is named from substrate's perspective (substrate's single import surface for SAT types). From bascule-oss's perspective, it's consuming a *protocol contract*, not a *substrate implementation detail*. A name that reflected the content (e.g. `sat-proto`, `attestation-proto`) would accurately describe what bascule-oss depends on and would cleanly pass both the CLAUDE.md rule and the CI contamination check.

## Proposed resolution (post-v1)

1. **Rename `substrate-proto` → `sat-proto`** (or `attestation-proto`). This is a substrate-side change: the crate moves to a neutral namespace while its content is unchanged.
2. **Move SAT public surface out of `substrate-common`** into a neutral location. `substrate-common` may keep substrate-internal content; the bits bascule-core needs (the generated Rust types) live behind the neutral name.
3. Update bascule-core's `Cargo.toml` to depend on the neutrally-named crate. Update bascule-oss's workspace `Cargo.toml` likewise.
4. Update the CI contamination check — the rule stands, but the grep is now true in both spirit and letter.
5. Optionally update `CLAUDE.md` to name specific allowed cross-boundary protocol crates by name, so future contributors understand the rule is about *substrate/chronicle/gsap-internal-leakage*, not about *string-prefix avoidance*.

## Why not now

- The path fix that this NOTE accompanies unblocks local 5.5c-c work without introducing or expanding the violation. The violation pre-exists this commit; we're not making it worse.
- The rename is a coordinated cross-workspace change (substrate-side rename, bascule-side update, possibly downstream consumers like Capstone if they import SAT types). Doing it correctly means touching multiple repos with coordinated PRs. Out of scope for the current Phase 5.5 foundation work.
- Timing-wise, the right moment for this is immediately before CNCF sandbox application prep, when the institutional positioning argument is most concrete and the sandbox committee's read of the project is being actively shaped.

## Why this matters for CNCF sandbox

CNCF sandbox committees evaluate whether a project is a *generic open-source substrate* or *a specific company's product with open-source framing*. Naming is a substantial signal in that evaluation, more than content in many cases:

- A sandbox application listing `substrate-proto` as a dependency reads as "bascule-oss is tightly coupled to Guildhouse-substrate; this project is Guildhouse-specific."
- A sandbox application listing `sat-proto` / `attestation-proto` reads as "bascule-oss is part of a defensible layered architecture; the protocol crate is cross-project; Guildhouse is one of several consumers."

This is the specific CNCF-sandbox-positioning work that the rename accomplishes. The architectural cleanup and the sandbox-positioning story are the same work, and should be done together with awareness that they're connected.

## For a future contributor picking this up

Read this NOTE, the current `CLAUDE.md`, and the CI workflow. Then:

1. Decide the neutral crate name (`sat-proto` is most literal; `attestation-proto` is broader and might accommodate future additions beyond SAT; pick one based on how much the crate is expected to grow).
2. Do the substrate-side rename: new crate at `substrate/crates/<new-name>/`, re-exports from `substrate-common` preserved, `substrate-proto` becomes a deprecation shim that re-exports from the new crate for one release cycle.
3. Update bascule-oss to depend on the new name.
4. Regenerate `Cargo.lock`; confirm CI contamination check passes.
5. Coordinate with other consumers (Capstone, any sandbox applicants) on the deprecation timing.

## Tracking

This NOTE is the canonical reference for the issue. If/when a more formal open-items tracking system lands in bascule-oss (a `TODO.md`, a GitHub project, an issue tracker), migrate this there and leave a pointer here.