@microck/raft 0.5.0 → 0.7.0

package/docs/reviews/performance-audit-2026-10-29.md

@@ -0,0 +1,90 @@
+# Performance and discovery audit, 2026-10-29
+
+## Scope and execution
+
+The user approved performance fixes, confirmed dead-code removal, documentation
+corrections, a discovery-driven Raft skill, current Boat parity research, and
+verification in disposable task-owned workspaces. The follow-up request
+authorizes committing, pushing, opening a ready-for-review PR and addressing
+review feedback until ready. Production deployment, merging, releases and paid
+provisioning remain outside scope.
+Paid provisioning/research spending: not authorized.
+
+Initial checkout was clean at `1fd6d62f`; Jujutsu was initialized colocated.
+Primary agent: gpt-6-astra, high reasoning effort. Three read-only simplification
+reviewers used gpt-6.1-sol with default reasoning. All reviewer jobs are complete.
+
+## Delivered changes
+
+- List and capacity collect their data in one SSH connection per host. Doctor
+  runs its sequential checks in one connection and retains the worker lock.
+  Existing lifecycle and archive safety checks remain in place.
+- Config and doctor accept a location filter, so an unrelated offline host does
+  not prevent inspection. Location-filtered default edits are refused.
+- Command help explains behavior and operational constraints. All 38 command
+  help paths ran without configuration or writes to an empty controller home.
+- The skill teaches version/help discovery, source lookup, host inspection,
+  ownership and cleanup rather than maintaining a command/software catalog.
+  The installed skill symlink now targets this repository's canonical skill;
+  the old openboat checkout was not edited. Discovery found run in the checkout
+  while the installed 0.6.0 command tree correctly omitted it.
+- README examples select persistence explicitly and provide ownership notes.
+  Sizing, release notice timing and unreleased run status are corrected.
+- The Boat comparison was refreshed from current official documentation,
+  including team sharing, environment versions, AI proxying, telemetry,
+  automatic snapshots and retained command history.
+
+## Measurements and verification
+
+[Raw timings](../benchmarks/read-latency-2026-10-29.json) record five samples per
+command/version on the same ARM64 Incus 6.0.6 host. Median reductions were 44%
+for list, 43% for capacity and 76% for doctor. These are controller-visible read
+latencies, not boot or guest workload speedups. Update checks were disabled.
+
+Passed in the disposable workspace:
+
+- Ruff lint and format checks across all Python sources and deployment scripts.
+- Limits, image fixtures, CI orchestration and feature verifiers.
+- Self-update verification through real temporary npm and uv installations.
+- Source, wheel and npm packaging and isolated installation checks.
+- Website Oxlint, Next.js build including TypeScript, search tests, and 37-page
+  export/link/search/download verification with 52 local links.
+
+Real host checks also passed: batched versus independent native inventory and
+policy reads; doctor and config scoped away from an unreachable inventory entry;
+refusal of location-scoped controller-default edits without creating a file.
+The discovery-guided one-shot job returned exit 7, collected its result file and
+confirmed cleanup. No new mocks were introduced.
+
+The initial test source archive omitted images and Git checkout metadata.
+Correcting that disposable fixture fixed packaging and checkout-detection tests;
+no assertions were weakened. A self-update HTTP timeout fixture logged an
+expected broken pipe after its client disconnected; the verifier passed.
+
+## Cleanup and review
+
+Task-owned workspaces `paris:rf-bf5bab8180464898` and
+`paris:rf-61cc02e89fc54677` are confirmed absent. Paris inventory was empty after
+cleanup. No background verification jobs or delegates remain active.
+
+The reuse and efficiency reviewers reported no actionable findings. The quality
+reviewer found two duplicated-constant sites; both now use the existing project
+and storage constants. Superseded per-call SSH code was removed. Ruff and a
+structural/reference scan found no additional safely removable Python functions;
+graph candidates were parser callbacks, tests or framework entry points.
+
+The passive update notice still has its documented bounded wait. Removing it
+would change whether short commands display release notices. Metadata checks
+before mutations remain because they establish ownership and eligibility.
+
+## Evidence limits
+
+- Timings are a five-sample exploratory result from one host and network path.
+- Boat capabilities were checked against official documentation, not its live
+  infrastructure. Dedicated organization docs describe sharing that older
+  overview/API text still describes as creator-private; the comparison notes it.
+- Authenticated GitHub inspection confirmed v0.6.0 remains the latest published
+  release. These changes and run are development-branch work, not deployed.
+- The shared fff index returned stale and unrelated results. Exact local reads
+  and the freshly built home-ubuntu-raft graph supplied code evidence instead.
+- An unrelated configured host was unreachable; no configuration was changed.

package/docs/site-development.md

@@ -1,5 +1,6 @@
 ---
 title: Documentation site
+description: Edit, build and test the Fumadocs site without touching workspace hosts.
 ---
 
 # Documentation site

package/docs/verification.mdx

@@ -1,16 +1,18 @@
 ---
 title: Verification
+description: Read test evidence and run dedicated verification suites with explicit limits.
 ---
 
 # Verification
 
-Raft is verified using real disposable Incus workspaces, guest processes, files, Docker builds, and network connections. Tests contain no mocked services and verify Raft behavior rather than conformance with the hosted Boat service.
+Raft is verified using real disposable Incus workspaces, guest processes, files, Docker builds, and network connections. Native suites exercise real services and verify Raft behavior rather than conformance with the hosted Boat service. Separate local worker and CI-orchestration fault fixtures are labeled below; they do not establish native-host behavior.
 
 ## Verification boundaries
 
 Tests do not certify arbitrary long-running workloads, host loss, multi-tenant security boundaries, or exact Boat image/version parity. ARM64 host reboot and physical storage capacity are not certified by the AMD64 VM test. Containers share the host kernel and do not offer VM isolation.
 
-Storage accounting covers shared pools rather than per-box quotas. Large backup transfers hold the host lifecycle lock, which delays expiration checks.
+Shared-pool boxes have no per-box quota. Own-disk boxes have enforced ext4 limits
+and reservation accounting; the coverage matrix distinguishes both modes. Large backup transfers hold the host lifecycle lock, which delays expiration checks.
 
 ## Coverage matrix
 
@@ -34,7 +36,7 @@ Storage accounting covers shared pools rather than per-box quotas. Large backup
 | Development image | Real developer-user tool checks, immutable selection and credential-path archive rejection |
 | Deployment/firewall | Repeat deployment removes stale rules without restarting Incus; failed filtering blocks normal and socket startup; boot timestamps prove filtering precedes Incus |
 | Storage contract | Disposable oversized pool is rejected without automatic resizing |
-| CLI options and errors | Help for all 34 commands and `host add`; default location, TTL and desktop port; all eight sizing profiles; global and per-location reports; invalid TTLs, sizes, required arguments, handles, paths, snapshot names, jobs and ports |
+| CLI options and errors | Command help, including `run` and `host add`; default location, TTL and desktop port; all eight sizing profiles; global and per-location reports; invalid TTLs, sizes, required arguments, handles, paths, snapshot names, jobs and ports |
 
 ## Command and option audit (2026-10-06)
 
@@ -58,7 +60,7 @@ The [final runtime validation](https://github.com/Microck/raft/actions/runs/3754
 
 ## New workspace controls
 
-`python3 deploy/verify-features.py --location lab` verifies `doctor` readiness against the installed worker, recursive trees and unsafe-archive rejection, templates from a running source, snapshot deletion, CPU/RAM overrides, disposable timer deletion, retention preview/apply, and host note policies for `new`, `fork`, `note` and `recover` (it sets a policy on the host and clears it at the end). It uses only its own fixtures. Run the archive, controller-default and policy-message checks without `--location` to avoid allocating boxes.
+`python3 deploy/verify-features.py --location lab` verifies `doctor` readiness against the installed worker, recursive trees and unsafe-archive rejection, templates from a running source, snapshot deletion, CPU/RAM overrides, disposable timer deletion, prune preview/apply, host note policies for `new`, `fork`, `note` and `recover`, and stopped-box retention: it sets a 1-hour policy, backdates one stopped box and the policy start, and checks that the next timer run deletes only that box, records the stop time of a box stopped natively and logs to the journal. It sets policies on the host and clears them at the end, and uses only its own fixtures. Every live suite runs the CLI in a private `HOME` holding only `incus.json`, so controller defaults such as `disposable true` never change their boxes. Run the archive, controller-default, policy-message and host worker retention checks without `--location` to avoid allocating boxes; the worker check runs the real worker against a fake `incus` on `PATH`.
 
 The live suite also holds a controller stdin pipe open while running real remote
 readers through both captured and streamed lifecycle transactions. Both must
@@ -241,3 +243,19 @@ On 2026-10-06, `raft limits` (since renamed `raft capacity`, with the admission
 Allocation fixtures validated mixed sizing budgets, frozen containers, low RAM and disk conditions, host reserves, and admission limits. The four-stopped-box admission test verified that creation, forking, and recovery reject a fifth container when slots are exhausted. These are conservative allocation checks, not workload saturation benchmarks.
 
 </details>
+
+## Disposable CI command verification
+
+`python3 deploy/verify-run.py` runs explicit orchestration fault-injection tests,
+real Linux signal/deadline handling, real Git filtering and safe archive traversal,
+and the actual ownership-check cleanup program against an isolated fake Incus
+executable. These are not native-host evidence. They cover failed/uncertain
+creation, upload failures, nonzero payload preservation, artifacts, cleanup
+failures, cancellation, timeouts, existing destinations and ignored credentials.
+
+`python3 deploy/verify-run.py --location lab` additionally creates real temporary
+boxes on the explicitly selected host, uploads a source tree, executes successful
+and failing commands, retrieves result directories, checks timeout cleanup and
+compares the host inventory before/after. Native AMD64 and ARM64 image CI runs
+this suite. A new PR must have those actual runs pass before claiming native
+verification; local fault-injection success alone does not establish it.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@microck/raft",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "description": "Self-hosted Linux workspaces powered by Incus, an open-source alternative to boat.dev",
   "license": "MIT",
   "repository": {
@@ -20,6 +20,8 @@
   "files": [
     "raft.py",
     "raft_files.py",
+    "raft_run.py",
+    "raft_jobs.py", "raft_output.py",
     "deploy/*.py",
     "deploy/*.sh",
     "deploy/*.conf",