docs: comprehensive public documentation
- docs/getting-started.md — install per distro, first use, common workflows
- docs/architecture.md — 9-crate dependency graph, design decisions, data flow
- docs/manifest-spec.md — manifest v1 specification
- docs/lock-spec.md — lock file v2 specification
- docs/store-spec.md — store format v2 specification
- docs/hash-contract.md — two-phase identity hashing algorithm
- docs/security-model.md — threat model, mount/device/env policy, privilege model
- docs/cli-stability.md — 23 stable commands, exit codes, stability guarantees
- docs/protocol-v1.md — remote protocol v1 draft
- docs/layer-limitations-v1.md — phase 1 layer limitations
- docs/api-reference.md — public API reference (Engine, D-Bus)
- docs/versioning-policy.md — semantic versioning, deprecation policy
- docs/verification.md — release artifact verification (SHA256, cosign, SBOM)
- docs/e2e-testing.md — E2E test guide with distro-specific prerequisites
- README.md — project overview, features, quick start, installation
- CONTRIBUTING.md — development setup, architecture principles, code standards
- CHANGELOG.md — full changelog for 0.1.0 and 2.0 hardening
2026-02-22 17:38:41 +00:00
# Changelog
All notable changes to Karapace will be documented in this file.
The format is based on [Keep a Changelog ](https://keepachangelog.com/en/1.1.0/ ).
docs: rewrite all documentation from source code
Delete 14 old docs files (AI-generated, riddled with Phase/M1/1.0
jargon, references to non-existent commands, stale CI snippets).
New documentation (6 files), written from repository source analysis:
- docs/architecture.md — crate graph, engine lifecycle, identity
computation, runtime backends, store design, WAL, GC, unsafe blocks
- docs/cli-reference.md — all 23 commands with syntax, args, flags,
exit codes, env vars, verified against crates/karapace-cli/src/main.rs
- docs/storage-format.md — directory layout, objects, layers, metadata,
manifest format, lock file, WAL, atomic write contract
- docs/security-model.md — mount/device/env var policies with exact
defaults from security.rs, trust assumptions, what is NOT protected
- docs/build-and-reproducibility.md — CI env vars, RUSTFLAGS, cargo
profile, reproducibility verification, toolchain pinning
- docs/contributing.md — setup, verification, project layout, code
standards, testing, CI workflows
README.md rewritten: concise, no marketing language, prerequisites
first, usage example, command table, limitations section.
CONTRIBUTING.md now points to docs/contributing.md.
CHANGELOG.md cleaned: removed M1-M8 labels, Phase refs, stale counts.
2026-02-23 00:06:42 +00:00
## [Unreleased]
docs: comprehensive public documentation
- docs/getting-started.md — install per distro, first use, common workflows
- docs/architecture.md — 9-crate dependency graph, design decisions, data flow
- docs/manifest-spec.md — manifest v1 specification
- docs/lock-spec.md — lock file v2 specification
- docs/store-spec.md — store format v2 specification
- docs/hash-contract.md — two-phase identity hashing algorithm
- docs/security-model.md — threat model, mount/device/env policy, privilege model
- docs/cli-stability.md — 23 stable commands, exit codes, stability guarantees
- docs/protocol-v1.md — remote protocol v1 draft
- docs/layer-limitations-v1.md — phase 1 layer limitations
- docs/api-reference.md — public API reference (Engine, D-Bus)
- docs/versioning-policy.md — semantic versioning, deprecation policy
- docs/verification.md — release artifact verification (SHA256, cosign, SBOM)
- docs/e2e-testing.md — E2E test guide with distro-specific prerequisites
- README.md — project overview, features, quick start, installation
- CONTRIBUTING.md — development setup, architecture principles, code standards
- CHANGELOG.md — full changelog for 0.1.0 and 2.0 hardening
2026-02-22 17:38:41 +00:00
### Breaking Changes
- **Store format v2** — `STORE_FORMAT_VERSION` bumped to 2. New `staging/` and `wal/` directories. Version 1 stores require rebuild.
- **CLI pruned to 23 commands** — removed legacy commands: `init` , `preset` , `list-presets` , `export-app` , `unexport-app` , `quick` , `validate` , `verify-lock` , `export` , `list-images` , `remove-image` , `remote-list` , `tui` .
- **Content-addressed layers** — `LayerStore::put()` now returns the blake3 content hash used as filename. Callers must use the returned hash for references.
- **`Engine::gc()` requires `&StoreLock` ** — compile-time enforcement that callers hold the store lock before garbage collection.
- **MetadataStore checksum** — `EnvMetadata` now includes an optional `checksum` field (blake3). Written on every `put()` , verified on every `get()` . Backward-compatible via `serde(default)` .
docs: rewrite all documentation from source code
Delete 14 old docs files (AI-generated, riddled with Phase/M1/1.0
jargon, references to non-existent commands, stale CI snippets).
New documentation (6 files), written from repository source analysis:
- docs/architecture.md — crate graph, engine lifecycle, identity
computation, runtime backends, store design, WAL, GC, unsafe blocks
- docs/cli-reference.md — all 23 commands with syntax, args, flags,
exit codes, env vars, verified against crates/karapace-cli/src/main.rs
- docs/storage-format.md — directory layout, objects, layers, metadata,
manifest format, lock file, WAL, atomic write contract
- docs/security-model.md — mount/device/env var policies with exact
defaults from security.rs, trust assumptions, what is NOT protected
- docs/build-and-reproducibility.md — CI env vars, RUSTFLAGS, cargo
profile, reproducibility verification, toolchain pinning
- docs/contributing.md — setup, verification, project layout, code
standards, testing, CI workflows
README.md rewritten: concise, no marketing language, prerequisites
first, usage example, command table, limitations section.
CONTRIBUTING.md now points to docs/contributing.md.
CHANGELOG.md cleaned: removed M1-M8 labels, Phase refs, stale counts.
2026-02-23 00:06:42 +00:00
### Added
docs: comprehensive public documentation
- docs/getting-started.md — install per distro, first use, common workflows
- docs/architecture.md — 9-crate dependency graph, design decisions, data flow
- docs/manifest-spec.md — manifest v1 specification
- docs/lock-spec.md — lock file v2 specification
- docs/store-spec.md — store format v2 specification
- docs/hash-contract.md — two-phase identity hashing algorithm
- docs/security-model.md — threat model, mount/device/env policy, privilege model
- docs/cli-stability.md — 23 stable commands, exit codes, stability guarantees
- docs/protocol-v1.md — remote protocol v1 draft
- docs/layer-limitations-v1.md — phase 1 layer limitations
- docs/api-reference.md — public API reference (Engine, D-Bus)
- docs/versioning-policy.md — semantic versioning, deprecation policy
- docs/verification.md — release artifact verification (SHA256, cosign, SBOM)
- docs/e2e-testing.md — E2E test guide with distro-specific prerequisites
- README.md — project overview, features, quick start, installation
- CONTRIBUTING.md — development setup, architecture principles, code standards
- CHANGELOG.md — full changelog for 0.1.0 and 2.0 hardening
2026-02-22 17:38:41 +00:00
docs: rewrite all documentation from source code
Delete 14 old docs files (AI-generated, riddled with Phase/M1/1.0
jargon, references to non-existent commands, stale CI snippets).
New documentation (6 files), written from repository source analysis:
- docs/architecture.md — crate graph, engine lifecycle, identity
computation, runtime backends, store design, WAL, GC, unsafe blocks
- docs/cli-reference.md — all 23 commands with syntax, args, flags,
exit codes, env vars, verified against crates/karapace-cli/src/main.rs
- docs/storage-format.md — directory layout, objects, layers, metadata,
manifest format, lock file, WAL, atomic write contract
- docs/security-model.md — mount/device/env var policies with exact
defaults from security.rs, trust assumptions, what is NOT protected
- docs/build-and-reproducibility.md — CI env vars, RUSTFLAGS, cargo
profile, reproducibility verification, toolchain pinning
- docs/contributing.md — setup, verification, project layout, code
standards, testing, CI workflows
README.md rewritten: concise, no marketing language, prerequisites
first, usage example, command table, limitations section.
CONTRIBUTING.md now points to docs/contributing.md.
CHANGELOG.md cleaned: removed M1-M8 labels, Phase refs, stale counts.
2026-02-23 00:06:42 +00:00
- **WAL crash safety** — Fixed race windows in `build()` and `restore()` (rollback registered before side-effects). Added WAL protection to `destroy()` , `commit()` (layer manifest rollback), and `gc()` (WAL marker).
- **Integrity hardening** — `LayerStore::get()` verifies blake3 hash on every read. `MetadataStore` embeds and verifies blake3 checksum. `verify_store_integrity()` expanded to check objects, layers, and metadata.
- **GC safety** — `Engine::gc()` now requires `&StoreLock` parameter (type-enforced). Snapshot layers whose parent is a live base layer are preserved during GC.
- **Remote protocol headers** — `X-Karapace-Protocol: 1` header sent on all HTTP backend requests (PUT, GET, HEAD). `PROTOCOL_VERSION` constant exported from `karapace-remote` .
- **unwrap() audit** — 0 `unwrap()` in production code. `Mutex::lock().unwrap()` calls in `MockBackend` replaced with proper `RuntimeError` propagation.
- **Failure mode tests** — WAL write failure, build on read-only WAL dir, stop() with SIGTERM/non-existent PID, permission denied on object read, read-only metadata dir, concurrent GC lock contention, layer/metadata corruption detection.
- **Coverage expansion** — `verify_store_integrity()` now checks objects + layers + metadata. `IntegrityReport` expanded with `layers_checked/passed` and `metadata_checked/passed` fields.
docs: comprehensive public documentation
- docs/getting-started.md — install per distro, first use, common workflows
- docs/architecture.md — 9-crate dependency graph, design decisions, data flow
- docs/manifest-spec.md — manifest v1 specification
- docs/lock-spec.md — lock file v2 specification
- docs/store-spec.md — store format v2 specification
- docs/hash-contract.md — two-phase identity hashing algorithm
- docs/security-model.md — threat model, mount/device/env policy, privilege model
- docs/cli-stability.md — 23 stable commands, exit codes, stability guarantees
- docs/protocol-v1.md — remote protocol v1 draft
- docs/layer-limitations-v1.md — phase 1 layer limitations
- docs/api-reference.md — public API reference (Engine, D-Bus)
- docs/versioning-policy.md — semantic versioning, deprecation policy
- docs/verification.md — release artifact verification (SHA256, cosign, SBOM)
- docs/e2e-testing.md — E2E test guide with distro-specific prerequisites
- README.md — project overview, features, quick start, installation
- CONTRIBUTING.md — development setup, architecture principles, code standards
- CHANGELOG.md — full changelog for 0.1.0 and 2.0 hardening
2026-02-22 17:38:41 +00:00
- **Real tar layers** — `pack_layer()` /`unpack_layer()` in karapace-store: deterministic tar creation (sorted entries, zero timestamps, owner 0:0) for regular files, directories, and symlinks. Content-addressed via blake3.
- **Snapshot system** — `Engine::commit()` captures overlay upper as a tar snapshot; `Engine::restore()` atomically unpacks a snapshot via staging directory swap; `Engine::list_snapshots()` lists snapshots for an environment.
- **CLI: `snapshots` and `restore` ** — new commands for snapshot management.
- **Write-ahead log (WAL)** — `store/wal/{op_id}.json` tracks in-flight operations with rollback steps. `Engine::new()` auto-recovers on startup. Integrated into `build()` , `commit()` , `restore()` .
- **Newtype wrappers threaded through all structs** — `EnvId` , `ShortId` , `ObjectHash` , `LayerHash` now used in `EnvMetadata` across all 8 crates. Transparent serde for backward compatibility.
- **Engine::push/pull** — transfer logic moved from `karapace-remote` to `Engine` methods. `karapace-remote` is now pure I/O.
- **CoreError::Remote** — new error variant for remote operation failures.
docs: rewrite all documentation from source code
Delete 14 old docs files (AI-generated, riddled with Phase/M1/1.0
jargon, references to non-existent commands, stale CI snippets).
New documentation (6 files), written from repository source analysis:
- docs/architecture.md — crate graph, engine lifecycle, identity
computation, runtime backends, store design, WAL, GC, unsafe blocks
- docs/cli-reference.md — all 23 commands with syntax, args, flags,
exit codes, env vars, verified against crates/karapace-cli/src/main.rs
- docs/storage-format.md — directory layout, objects, layers, metadata,
manifest format, lock file, WAL, atomic write contract
- docs/security-model.md — mount/device/env var policies with exact
defaults from security.rs, trust assumptions, what is NOT protected
- docs/build-and-reproducibility.md — CI env vars, RUSTFLAGS, cargo
profile, reproducibility verification, toolchain pinning
- docs/contributing.md — setup, verification, project layout, code
standards, testing, CI workflows
README.md rewritten: concise, no marketing language, prerequisites
first, usage example, command table, limitations section.
CONTRIBUTING.md now points to docs/contributing.md.
CHANGELOG.md cleaned: removed M1-M8 labels, Phase refs, stale counts.
2026-02-23 00:06:42 +00:00
- **CLI stability contract** — `docs/cli-stability.md` defines CLI stability expectations.
docs: comprehensive public documentation
- docs/getting-started.md — install per distro, first use, common workflows
- docs/architecture.md — 9-crate dependency graph, design decisions, data flow
- docs/manifest-spec.md — manifest v1 specification
- docs/lock-spec.md — lock file v2 specification
- docs/store-spec.md — store format v2 specification
- docs/hash-contract.md — two-phase identity hashing algorithm
- docs/security-model.md — threat model, mount/device/env policy, privilege model
- docs/cli-stability.md — 23 stable commands, exit codes, stability guarantees
- docs/protocol-v1.md — remote protocol v1 draft
- docs/layer-limitations-v1.md — phase 1 layer limitations
- docs/api-reference.md — public API reference (Engine, D-Bus)
- docs/versioning-policy.md — semantic versioning, deprecation policy
- docs/verification.md — release artifact verification (SHA256, cosign, SBOM)
- docs/e2e-testing.md — E2E test guide with distro-specific prerequisites
- README.md — project overview, features, quick start, installation
- CONTRIBUTING.md — development setup, architecture principles, code standards
- CHANGELOG.md — full changelog for 0.1.0 and 2.0 hardening
2026-02-22 17:38:41 +00:00
- **Remote protocol spec** — `docs/protocol-v1.md` (v1-draft) documents blob store routes, push/pull protocol, registry format.
docs: rewrite all documentation from source code
Delete 14 old docs files (AI-generated, riddled with Phase/M1/1.0
jargon, references to non-existent commands, stale CI snippets).
New documentation (6 files), written from repository source analysis:
- docs/architecture.md — crate graph, engine lifecycle, identity
computation, runtime backends, store design, WAL, GC, unsafe blocks
- docs/cli-reference.md — all 23 commands with syntax, args, flags,
exit codes, env vars, verified against crates/karapace-cli/src/main.rs
- docs/storage-format.md — directory layout, objects, layers, metadata,
manifest format, lock file, WAL, atomic write contract
- docs/security-model.md — mount/device/env var policies with exact
defaults from security.rs, trust assumptions, what is NOT protected
- docs/build-and-reproducibility.md — CI env vars, RUSTFLAGS, cargo
profile, reproducibility verification, toolchain pinning
- docs/contributing.md — setup, verification, project layout, code
standards, testing, CI workflows
README.md rewritten: concise, no marketing language, prerequisites
first, usage example, command table, limitations section.
CONTRIBUTING.md now points to docs/contributing.md.
CHANGELOG.md cleaned: removed M1-M8 labels, Phase refs, stale counts.
2026-02-23 00:06:42 +00:00
- **Layer limitations doc** — `docs/layer-limitations.md` documents current limits (no xattrs, device nodes, hardlinks).
docs: comprehensive public documentation
- docs/getting-started.md — install per distro, first use, common workflows
- docs/architecture.md — 9-crate dependency graph, design decisions, data flow
- docs/manifest-spec.md — manifest v1 specification
- docs/lock-spec.md — lock file v2 specification
- docs/store-spec.md — store format v2 specification
- docs/hash-contract.md — two-phase identity hashing algorithm
- docs/security-model.md — threat model, mount/device/env policy, privilege model
- docs/cli-stability.md — 23 stable commands, exit codes, stability guarantees
- docs/protocol-v1.md — remote protocol v1 draft
- docs/layer-limitations-v1.md — phase 1 layer limitations
- docs/api-reference.md — public API reference (Engine, D-Bus)
- docs/versioning-policy.md — semantic versioning, deprecation policy
- docs/verification.md — release artifact verification (SHA256, cosign, SBOM)
- docs/e2e-testing.md — E2E test guide with distro-specific prerequisites
- README.md — project overview, features, quick start, installation
- CONTRIBUTING.md — development setup, architecture principles, code standards
- CHANGELOG.md — full changelog for 0.1.0 and 2.0 hardening
2026-02-22 17:38:41 +00:00
### Changed
- **CLI monolith decomposition** — split `main.rs` into ~30 command modules under `commands/` , thin dispatcher in `main.rs` .
- **Error type cleanup** — added `StoreError::InvalidName` and `StoreError::NameConflict` variants; removed `Io(Error::other)` hacks.
- **D-Bus serialization cleanup** — replaced hand-rolled JSON with typed `serde` response structs.
- **Engine store caching** — `MetadataStore` , `ObjectStore` , and `LayerStore` cached as fields on `Engine` .
- **Remote integrity verification** — `pull_env` verifies blake3 hash of each downloaded object and layer.
- **Store spec updated** — `docs/store-spec.md` reflects v2 format with WAL, staging, tar_hash, name field.
- **README updated** — reflects 23 commands, snapshot workflow, remote push/pull examples.
## [0.1.0] — 2026-02-20
### Added
- **Deterministic environment engine** — content-addressed, hash-based environment identity from resolved lock files.
- **Manifest v1** — declarative TOML manifest with strict schema validation, deterministic normalization, and canonical serialization.
- **Lock file v2** — resolved packages with pinned versions, base image content digest (not tag), dual verification (integrity + manifest intent).
- **Content-addressable store** — blake3 hashing, atomic writes (NamedTempFile + persist), integrity verification on read, reference counting, garbage collection with signal cancellation.
- **CLI commands** — `build` , `rebuild` , `enter` , `exec` , `destroy` , `stop` , `freeze` , `archive` , `list` , `inspect` , `diff` , `snapshots` , `commit` , `restore` , `gc` , `verify-store` , `push` , `pull` , `rename` , `completions` , `man-pages` , `doctor` , `migrate` .
- **Example manifests** — `examples/minimal.toml` , `examples/dev.toml` , `examples/gui-dev.toml` , `examples/ubuntu-dev.toml` , `examples/rust-dev.toml` for common use cases.
- **Multi-distro image support** — openSUSE Tumbleweed/Leap, Ubuntu (20.04– –
- **Runtime backends** — user namespace (`unshare` + `fuse-overlayfs` + `chroot` ), OCI (`crun`/`runc`/`youki`), mock (for testing).
- **Host integration** — Wayland, X11, PipeWire, PulseAudio, D-Bus session bus, GPU (`/dev/dri`), audio (`/dev/snd`), SSH agent, fonts, themes, cursor themes, GTK/icon themes.
- **Desktop app export** — export GUI applications from environments as `.desktop` files on the host.
- **Overlay drift control** — diff, freeze, commit, export writable layer changes.
- **D-Bus desktop integration** — socket-activated `org.karapace.Manager1` service (feature-gated, opt-in).
- **Security model** — mount whitelist, device policy, environment variable allow/deny lists, resource limits, no privilege escalation.
- **Structured logging** — `log` + `env_logger` with `KARAPACE_LOG` env var and `--verbose` /`-v` CLI flag.
- **Concurrency safety** — `StoreLock` file locking on all mutating CLI and D-Bus operations, GC protects active/archived environments.
- **Automated tests** — unit tests, integration tests, crash injection tests, concurrent build safety, GC safety, reproducibility.
- **Shell completions** — `karapace completions bash|zsh|fish|elvish|powershell` for tab completion.
- **Man page generation** — `karapace man-pages <dir>` generates man pages for all commands.
- **Prerequisite detection** — early check for `unshare` , `fuse-overlayfs` , `curl` with distro-aware install instructions.
- **CI pipeline** — GitHub Actions workflow: format, clippy, test, release build with artifact upload.
### Security
- Shell injection prevention via POSIX single-quote escaping (`shell_quote`) on all sandbox script interpolation.
- Environment variable key validation (`[a-zA-Z0-9_]` only).
- Image download integrity — blake3 digest stored on download, `verify_image()` detects corruption.
- Destroy guard — cannot destroy a running environment (must stop first).
- Atomic rebuild — new environment built before old one is destroyed (no data loss on failure).
- PID cast safety — `i32::try_from()` instead of `as i32` for `libc::kill()` .
- Zero `unwrap()` in production code — all error paths handled gracefully.
- Input validation in `quick` command — image and package names validated against TOML injection.
- `Cargo.lock` committed for reproducible builds.
### Documentation
- Manifest v0.1 specification (`docs/manifest-spec.md`)
- Lock file v2 specification (`docs/lock-spec.md`)
- Store format specification (`docs/store-spec.md`)
- Hash contract (`docs/hash-contract.md`)
- Security model with threat model and attack surface (`docs/security-model.md`)
- Public API reference (`docs/api-reference.md`)
- Versioning policy (`docs/versioning-policy.md`)
- `CONTRIBUTING.md` — development workflow, architecture principles, code standards.
- `LICENSE` — European Union Public Licence v1.2 (EUPL-1.2).
