# kcode-rust-libs-v2 1.0.0 Specification
## Boundary
The crate owns persistent managed-library source generations, complete in-memory UTF-8 source, optimistic complete replacement, 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` reads only the two root files needed for version and documentation.
## 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, migration, Git behavior, adapter adoption, deployment, or registry verification.