AkurAI-Build

public

Latest change 2a1193541cf008c406be9f347e44150a58a66130 - docs: preserve the architecture review, backlog, and schema policy by Olafur Bui

# Architect Review 10/10 — Maintainability, Modularity & Positioning

## What is already good (verified)
- **Doc accuracy is high.** Spot-checked README claims against code: artifact bounds (50k/256MiB/1GiB, `src/artifact.rs:14-17`), 512 MiB preload (`src/server.rs:36`), vector bounds (`src/db.rs:22-26`), `bunfork-deployment-v2` (`src/main.rs:764`), protected deploy outputs list (`src/main.rs:825-832` matches README exactly), 4xx `ApiError` classification (`src/server.rs:129-173`). Earlier adversarial P0s (destructive `--force`, hex-string secret comparison) are demonstrably fixed: digest ownership at `src/main.rs:835-897`; `secrets_equal` decodes bytes (`src/db.rs:468`).
- **Scope discipline is exemplary.** Rejected scope is stated as product policy in README ("rejected scope, not partially emulated features") and docs/adversarial/10 no-go lists.
- **Black-box tests exist.** `tests/static_http.rs` spawns the real binary and asserts listener-level HTTP contracts — exactly what pass 01 demanded.
- **Deploy bundle design is sound.** Complete inventory excluding only `bunfork.json`, exclusive-create staging, fsync, atomic rename, preserved previous release.

## Prioritized findings

1. **P0 — Repository has zero commits.** `git log` fails; every authored file is untracked. Pass 01 flagged this ("evidence base is not yet reproducible") and it remains unfixed. Provenance for the entire adversarial audit trail, THIRD_PARTY_NOTICES, and e2e evidence is unverifiable, and any editing accident is unrecoverable. Commit the tree before anything else.

2. **P1 — Digest-ownership check strands bundles across upgrades.** `validate_owned_deployment` requires `bunfork_version == CARGO_PKG_VERSION` and `listen == DEFAULT_ADDRESS` (`src/main.rs:869-878`). Bumping 0.1.0→0.2.0 makes every existing deployment "unowned or incompatible," forcing users into manual `rm -rf` — the exact hazard digest ownership was built to eliminate. Accept any verified v2 manifest whose inventory matches, regardless of producing version/address.

3. **P1 — Positioning inconsistency: "full-stack".** Cargo.toml description and `--help` say "Rust-first full-stack runtime" (`Cargo.toml:6`, `src/main.rs:30`), yet docs/adversarial/01 §1.5 concludes "full-stack framework remains false" and the README deliberately avoids the term. Align crate metadata/help text with README language. On the name: "bunfork" is defensible only because README ¶2 immediately disclaims Bun compatibility; the name alone (crates.io search, `ps`, systemd unit) will mislead. Add "not a fork of Bun" to the one-line crate description so every discovery surface carries the disclaimer.

4. **P1 — Framework namespace churn is hard-coded at runtime.** `has_immutable_namespace` (`src/server.rs:584-597`) pins `_app/immutable/` and seven `_next/static/*` names; Next canary and future SvelteKit majors will drift, silently degrading caching. Move the cache-class decision to admit time (per-file record in the manifest), making runtime framework-agnostic and giving schema v2 an obvious motivation.

5. **P2 — Module decomposition.** ~5,000 lines in four files. `server.rs` (1,699) mixes five concerns: static negotiation, route grammar, MiniJinja env, vector API, auth/origin. `main.rs` embeds a ~390-line deploy engine (`deploy`/`validate_owned_deployment`/`sync_tree`/`copy_tree`, lines 610-994). Extract `src/deploy.rs` and `src/router.rs` before adding features. The 1-line `lib.rs` is a legitimate minimal-API choice, but the asymmetry (artifact in lib; db/server bin-private, with bin modules importing `bunfork::artifact`) is unexplained — document or normalize.

6. **P2 — Duplicated security-critical fs helpers.** `artifact.rs:448/461` (`open_nofollow`/`ensure_path_identity`) duplicate `db.rs:1055/991` (`open_existing_nofollow`/`ensure_path_matches_file`). Consolidate into one hardened fsutil module so future fixes cannot diverge.

7. **P2 — Previous-release accumulation.** `bunfork-dist.previous-<pid>` siblings already number two; retention is unbounded and pid-suffixed (not sortable by time). Behavior matches README, but add a documented prune procedure or timestamped suffixes.

8. **P2 — No forward-compat story for `bunfork-static-v1`.** `deny_unknown_fields` (`src/artifact.rs:20`) is correctly fail-closed, but no v2 negotiation/dual-read policy exists. Write it down now, before external manifests exist in the wild.

No files were modified.