# kcode-rust-libs-v2 1.1.0 Specification
## Boundary
The crate owns persistent managed-library source generations, complete in-memory UTF-8 source, optimistic complete replacement, migration from the legacy flat repository, disposable validation, and crates.io publication. The integrating server owns transport, authorization, configured roots, private token retrieval, model-facing schemas, timeouts, deployment, and adoption.
The only public operations are free `create`, `open`, and `docs`, plus `Lib::write`, `Lib::check`, and `Lib::publish`. `File`, `Lib`, `Error`, and `Result` carry those operations but add no public lifecycle controls.
## Source
A library name starts with an ASCII alphanumeric character and then contains only ASCII alphanumerics, `-`, or `_`. A file path is nonempty, relative, slash-separated UTF-8 with no empty, `.`, `..`, backslash, colon, or NUL component. Files are regular UTF-8 files, sorted by path. Symlinks and special files are rejected.
Root `Cargo.toml` and `Documentation.md` are mandatory. `[package].name` must equal the managed name. `[package].version` is a literal canonical stable `major.minor.patch` with no leading zeros, prerelease, build metadata, escape, or workspace inheritance. Root `Cargo.lock` is omitted on read and rejected on write.
`create` initializes `Cargo.toml`, `Documentation.md`, and `src/lib.rs`. `open` loads the complete useful source. `docs` returns the root manifest version and documentation.
## Migration
`open` and `docs` recognize a legacy repository only when `HEAD`, `.lock`, `generations`, and the migration marker are absent. The complete legacy tree is read and validated before mutation, with root `Cargo.lock` omitted. Ambiguous partial V2 layouts are rejected.
Migration is serialized by the managed-root lock. It stages the first immutable generation, records recoverable migration identity, installs `generations` and `.lock`, and atomically installs `HEAD` last. Ordinary pre-commit failure rolls back only migration metadata. An interrupted recorded migration is either completed from its committed `HEAD` or rolled back before retry. The original flat files remain as noncanonical recovery material; V2 reads only the generation named by `HEAD`.
## Mutation
Persistent source uses private immutable generations and an atomically replaced head. A `Lib` retains its expected head privately. `write` validates the entire proposed source before mutation, takes a filesystem lock only for the call, rejects a mismatched head as stale, stages a new complete generation, and advances the head atomically. Omitted files therefore disappear. Success refreshes the handle; failure never reports a partially staged generation as committed. Process exit releases the filesystem lock.
## Validation
A check materializes exactly the current in-memory source in a disposable directory. Rootless Podman runs fixed commands in a Rust 1.97 Bookworm image with a read-only container root, dropped capabilities, `no-new-privileges`, caller user mapping, private writable source/Cargo/target mounts, and writable `/tmp`.
The fixed fail-fast sequence is networked `cargo fetch`; network-disabled `cargo fmt --all -- --check`; then network-disabled locked/offline all-target build, Clippy with `-D warnings`, all-target tests, and doc tests. The generated lockfile and all work are discarded. Success is `()`; a failure is one bounded category and diagnostic excerpt.
## Publication
Publication first performs the complete check, then materializes the same source afresh and runs fixed `cargo publish --registry=crates-io --no-verify`. The already completed token-free check is the verification run. The private token is inherited by environment-variable name only while Cargo publishes, never appears in command arguments or source, and is exactly redacted from returned errors.
The package makes no promise of arbitrary commands, host paths, binary files, persistent build caches, historical dependency resolution, repository listing, Git behavior, adapter adoption, deployment, or registry verification.