AkurAI-Build

public
Latest change 2a1193541cf008c406be9f347e44150a58a66130 - docs: preserve the architecture review, backlog, and schema policy by Olafur Bui
# `bunfork-static-v1` evolution policy

`bunfork-static-v1` manifests are strict by construction: unknown fields,
duplicate keys, and unexpected schema strings fail closed. That means any
field addition is a hard version break, so forward compatibility has to be a
written policy rather than an accident. This document is that policy
(architecture review 10, finding 8).

## Compatibility rules

1. The `schema` string is the only version signal. A binary serves a
   manifest if and only if it recognizes the exact schema string.
2. v1 is frozen. No fields will be added, removed, or reinterpreted within
   `bunfork-static-v1`. Bug fixes may tighten validation (fail more) but
   never loosen it.
3. When v2 ships, binaries will dual-read: accept `bunfork-static-v1` and
   `bunfork-static-v2` for at least one minor release line, while `admit`
   writes v2 only. `doctor` will report the manifest's schema version.
4. Downgrade is explicit: a v1-only binary rejects v2 manifests with the
   existing "unsupported static manifest schema" error; re-admit with the
   old binary to produce a v1 manifest.

## Semantics locked in v1 (decided during the 2026-07 review)

- `trailing_slash` has three distinct behaviors: `directory` canonicalizes
  to `/guide/`, `redirect` canonicalizes to `/guide`, `ignore` serves both.
- Admission and serving share one total-size bound
  (`artifact::MAX_TOTAL_BYTES`, 512 MiB), so admitted artifacts always boot.
- Precompressed `.br`/`.gz` siblings are negotiation inputs; direct requests
  for them are served as `application/octet-stream`.

## Planned for v2

| Change | Motivation |
| --- | --- |
| Per-file cache class recorded at admit time | Runtime currently hard-codes `_app/immutable/` and `_next/static/*` namespaces (review 10); framework churn silently degrades caching. Admission should classify once and the server should read the manifest. |
| Opt-in `.well-known` allowlist | The hidden-path denylist correctly fails closed but makes ACME HTTP-01, `security.txt`, and `assetlinks.json` unservable (review 5). v2 admits an explicit, enumerated allowlist under `well_known`. |
| Producer-declared SPA fallback exclusions | The framework prefix list and dot-heuristic in `is_navigation_path` will drift (review 5); producers should declare exclusion prefixes in the manifest. |
| Optional inline-script CSP hashes | `admit` already parses and hashes every file; emitting `script-src` hashes lets static mode drop `'unsafe-inline'` without a reverse proxy (review 6). |
| Explicit precompressed-sibling mapping | Replaces suffix-pairing conventions with declared relationships, enabling direct-request 404s for siblings if desired. |

Fields not listed here require a new entry in this document before
implementation.