Summary

aprender-contracts is the canonical provable-contracts kernel in the paiml sovereign AI stack, but 6 aprender sub-crates still depend on the deprecated provable-contracts crate (crates.io 0.2 / 0.3). The workspace root also pulls it. Goal of this ticket: migrate every internal dependency to aprender-contracts so /home/noah/src/provable-contracts (and the crates.io provable-contracts crate) can be frozen read-only.

This is a prerequisite for unblocking ~8 downstream paiml repos (bashrs, forjar, batuta, entrenar, copia, manzana, organizational-intelligence-plugin, plus pmat's ecosystem) that are also on the legacy crate.

Evidence (scan run 2026-04-18)

crates/aprender-core/Cargo.toml:166:          provable-contracts = "0.3"  # Contract enforcement (dev-only)
crates/aprender-orchestrate/Cargo.toml:156:   provable-contracts = { version = "0.2", optional = true }
crates/aprender-present-lib/Cargo.toml:39:    provable-contracts = "0.3"
crates/aprender-serve/Cargo.toml:160:         provable-contracts = { version = "0.2" }
crates/aprender-simulate/Cargo.toml:96:       provable-contracts = { version = "0.2" }
crates/aprender-train/Cargo.toml:144:         provable-contracts = { version = "0.2" }
Cargo.toml:170:                               provable-contracts = "0.3"
Cargo.toml:171:                               provable-contracts-macros = "0.3"

The two crate source trees have identical top-level file layouts — both contain audit/, kani_gen/, lean_gen/, coq_gen/, flux_gen.rs, mirai_gen.rs, tla_gen.rs, probar_gen/, explain.rs, binding.rs, codegen.rs, etc. API surface should be compatible.

aprender-contracts itself already uses this exact migration pattern at crates/aprender-contracts/Cargo.toml:22:

provable-contracts-macros = { path = "../aprender-contracts-macros", version = "0.31.0", package = "aprender-contracts-macros" }

Proposed fix — Cargo.toml-only, zero source edits

Use Cargo's package-rename feature. All Rust source continues to say use provable_contracts::... but the actual package pulled is aprender-contracts:

# Before
provable-contracts = "0.3"

# After — zero source code changes
provable-contracts = { version = "0.30", package = "aprender-contracts" }

Or prefer the direct form if you want the names to line up and are willing to edit use statements:

aprender-contracts = "0.30"

plus rg -l '\buse provable_contracts\b' | xargs sed -i 's/provable_contracts/aprender_contracts/g'

Recommendation: package-rename first (ship fast, zero churn); follow up with a cleanup PR that drops the rename and uses aprender_contracts directly once the migration is stable.

Affected files

Acceptance criteria

• grep -rn "provable-contracts" crates/ Cargo.toml returns only the package = "aprender-contracts*" rename form (or zero hits).
• cargo check --workspace --all-targets passes.
• cargo test --workspace passes.
• cargo tree -p aprender-core --duplicates shows no provable-contracts and no aprender-contracts appearing twice at different versions.
• CHANGELOG.md notes the migration.
• Optional: once stable, a follow-up PR removes package-renames and uses use aprender_contracts::... directly.

Risk and rollback

• Low risk if package-rename path is taken — zero source code changes; only Cargo.toml edits.
• The two crates share structure but may have drifted behaviorally. Verify by running the workspace test suite after migration.
• Rollback: revert the 8 Cargo.toml edits (single-commit revert).

Cross-ref

• This is KAIZEN-0091 from the paiml-mcp-agent-toolkit R10 dogfood round (fix(P2): chat server silently degrades to byte-level decode on tokenizer error #337 comment-4274155634).
• Downstream repos blocked on this: bashrs, forjar, batuta, entrenar, copia, manzana, organizational-intelligence-plugin. Each has its own provable-contracts = "0.x" to migrate once aprender's internal use is cleaned up.
• Goal state: /home/noah/src/provable-contracts and crates.io provable-contracts are both frozen (no new versions); all paiml tooling consumes aprender-contracts.
• Scan evidence and detailed migration analysis: paiml-mcp-agent-toolkit /tmp/pmat-dogfood/round10/org-patterns-r10.md.

Effort estimate

~1 engineering day. Mostly Cargo.toml edits + a full workspace cargo check/test pass.