# kcode-web-libs 0.2.0 Specification
## Boundary
The crate owns persistent managed-library source generations, complete
in-memory UTF-8 source, optimistic complete replacement, disposable browser
validation, and immutable local publication. The integrating server owns
transport, authorization, the distinct configured source and publication
roots, installation of `chromium` on `PATH`, model-facing schemas, production
routing, 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. File/directory path collisions are rejected before
materialization. A source contains at most 1,024 files, one file contains at
most 16 MiB, the complete tree contains at most 64 MiB, a path contains at most
4,096 UTF-8 bytes, and one path component contains at most 255 bytes.
Root `kcode-web.json` and `Documentation.md` are mandatory. The manifest name
must equal the managed name. Its version is a literal canonical stable
`major.minor.patch`. The entry and test paths must identify retained `.js` or
`.mjs` files.
`create` initializes `kcode-web.json`, `Documentation.md`, `index.js`, and
`tests.js`. `open` loads the complete source. `docs` reads only the manifest and
root documentation and returns the version and documentation. Repositories live
at `<web_libs_root>/<name>/`; reserved dot-prefixed internal directories cannot
collide with a valid library name.
## 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 and synchronizes a new complete
generation, and advances and synchronizes the head atomically. Omitted files
therefore disappear. A successful write refreshes the handle and removes the
previous generation on a best-effort basis.
## Validation
A check materializes exactly the current in-memory source in a disposable
directory. A temporary loopback HTTP server serves that candidate and immutable
already-published exact-version dependencies. Headless Chromium imports the
declared entry module, imports the declared test module, and awaits its exported
`runTests()` function. Chromium is resolved as `chromium` through `PATH`. The
result and diagnostics are bounded. All disposable source, profile, and
diagnostic files are removed after the call. Persistent trusted coordinator
assets live under `<publications_root>/.coordinator/`.
## Publication
Publication first performs the complete browser check over the current
in-memory source. It then stages and synchronizes every file and directory,
atomically installs the complete tree at
`<publications_root>/module/<name>/v<version>/`, and synchronizes the
module directory before returning success. Exact name/version destinations are
immutable and independent; publication never overwrites or deduplicates them.
The canonical source and publication roots must be disjoint; neither may
contain the other. The crate does not create or consult `.published` beneath
the source root.
The package makes no promise of arbitrary commands, binary files, persistent
browser profiles, repository listing, legacy migration, Git behavior, floating
aliases, application selection, deployment, or production HTTP routing.