# kcode-rust-libs-v2 Specification
## 1. Purpose and boundary
`kcode-rust-libs-v2` is imported by an agent-tool server. It owns persistent UTF-8 Rust-library trees, complete in-memory snapshots, complete-file writes, standardized disposable validation, and crates.io publication. It does not define transport, authentication, discovery, sessions, concurrency control, a secrets database, deployment, or consumer migration.
Its public vocabulary is `KcodeRustLibs`, `OpenedRustLib`, `RustLibFile`, `RustLibPath`, `CheckResult`, `CheckStageResult`, `CheckStage`, and `Error`.
## 2. Ownership and concurrency
The integrating server must allow at most one active user of a managed library. This crate has no lock, lease, close operation, or stale-session recovery because the server owns session lifecycle. External modification while an `OpenedRustLib` exists is unsupported. Dropping a handle has no persistent-library side effect.
## 3. Persistent roots and credentials
The constructor receives a Rust-libraries root and a crates.io token. It trims the token and rejects an empty value before creating filesystem roots. The root's direct children are managed-library directories. The token is held in a private shared redacted value and is never discovered from, written to, or read from a credential file.
Validation workspaces, Cargo homes, targets, package output, and image-build files live under a process-specific temporary work root. Persistent source is copied into a fresh run and is never mounted directly into a container. Generated state is not copied back.
## 4. Names, paths, and files
A library name is non-empty, begins with an ASCII letter or digit, and otherwise contains only ASCII letters, digits, hyphens, and underscores.
`RustLibPath` is a canonical UTF-8 relative path using `/`. It rejects leading or trailing `/`, empty components, `.`, `..`, backslashes, colons, and NUL. Managed libraries contain only ordinary directories and UTF-8 regular files. Opening rejects symlinks, special files, non-UTF-8 names, and non-UTF-8 bodies. Files are sorted lexicographically by `RustLibPath`.
## 5. Creation and opening
Creation fails if the destination already exists. A new library contains root `Cargo.toml`, root `Documentation.md`, and `src/lib.rs`; its package name is the requested library name, edition is 2024, and version is `0.1.0`. Partial creation is removed when possible after failure.
Opening recursively loads every file. No file is ignored. The returned handle exposes:
- `name()`: the library name;
- `version()`: the canonical root-package version;
- `files()`: every file exactly once.
Root `Cargo.toml` and `Documentation.md` are mandatory. The manifest must contain a direct basic-string `version = "major.minor.patch"` assignment in `[package]`. The version must be canonical stable SemVer with no prefix, leading zero, prerelease, build metadata, or workspace inheritance.
`Documentation.md` has no special duplicate representation. Its complete contents appear once, in its `RustLibFile` entry. The API has no `RustLibDocs` and no `docs()` operation.
## 6. Complete-file writes
`write(files)` accepts complete path/content pairs. It rejects duplicate paths and validates the projected required metadata and version before writing anything. It creates missing parent directories and creates or truncates each supplied file. Omitted files remain. Symlink traversal is rejected. Operating-system failures can occur after an earlier file in the same batch was replaced, so writes are not transactional. After success the handle reloads the complete snapshot and version.
## 7. Validation
`check()` uses a fresh copied source tree and executes these stages in order, stopping after the first nonzero source-quality result:
1. `cargo fetch --color never`
2. `cargo fmt --all -- --check`
3. `cargo build --workspace --all-targets --all-features --locked --offline --color never`
4. `cargo clippy --workspace --all-targets --all-features --locked --offline --color never -- -D warnings`
5. `cargo test --workspace --all-targets --all-features --locked --offline --no-fail-fast --color never`
6. `cargo test --workspace --all-features --doc --locked --offline --no-fail-fast --color never`
Fetch has container networking. Later stages use `--network=none`. Every stage uses a new foreground rootless Podman container with a read-only root, all capabilities dropped, `no-new-privileges`, caller user mapping, no TTY, writable `/tmp`, and writable mounts limited to that run's copied source, Cargo home, and target. The crate imposes no timeout, CPU, memory, or output limit; the server may supervise the synchronous call.
A completed source-quality failure is `Ok(CheckResult)` with `passed() == false`. Podman, copying, image, workspace, or process failures are `Err(Error)`.
## 8. Publication
`publish()` first performs the complete token-free check. If it passes, publication uses another fresh copied source tree and runs `cargo publish --registry=crates-io --no-verify` from `/tmp` with an explicit manifest path. Starting outside the source prevents a library-local Cargo configuration from selecting the registry or credential provider. The initialization token is inherited by environment-variable name, is absent from command arguments and copied Cargo homes, and is exactly redacted from returned publication errors.
`--no-verify` is deliberate because the full source-controlled build and tests already ran without the token; agent-authored build scripts or tests do not execute while the credential is present. Crates.io still validates ownership, names, metadata, and duplicate versions.
## 9. Self-hosting and non-goals
This package is itself an ordinary conforming managed library and can be maintained through the same API. Generated output and binary editor artifacts remain outside its managed directory.
There is no server, protocol schema, Serde model, credential store, on-disk credential discovery, repository listing, patching, deletion, rename, Git operation, binary-file support, arbitrary command, persistent build cache, timeout, deployment, or automatic migration from `kcode-rust-libs`.