#ADR 0004: Frontend Delivery, Source Maps, And Obfuscation

• Status: accepted; operator build/visual verification pending
• Date: 2026-08-20

#Context

k0smos has seven Vite themes. Production assets were minified, but their main entry filenames were stable (app.js and app.css), only two themes had machine-readable size gates, and templates did not resolve entry assets through the Vite manifest. The backlog also asked for frontend obfuscation without first separating performance and cache goals from security properties.

Browser-delivered source is observable. A user can inspect, save, instrument, or replace it. Minification and obfuscation cannot keep secrets, enforce authorization, protect tenant isolation, or make client-side business rules authoritative.

#Decision

All supported themes use one production policy:

• Vite production mode with tree-shaking, esbuild JavaScript minification, CSS minification, and content-hashed JS/CSS entry/chunk filenames;
• a manifest consumed by the Plates entryCss() and entryJs() helpers, with a compatibility fallback for an installation whose operator has not rebuilt assets yet;
• no version query on manifest-resolved hashed assets, so immutable cache keys are stable for their content;
• no public production source maps;
• per-theme raw/gzip budgets for the app entry, every JS chunk, and every CSS asset, plus the existing Default eager/dynamic dependency constraints;
• deterministic build-metadata.json containing no timestamp or machine path, and recording the theme, profile, minifier, source-map/obfuscation policy, package-lock SHA-256, Vite version, and emitted-file SHA-256 values;
• explicit development mode for the Vite server, where readable modules, HMR, and browser debugging are expected and no deployable bundle is produced.

The existing Default/Sober admin-shell split remains authoritative. P7 does not introduce another bootstrap or route-entry architecture; it adds delivery and verification guarantees around the P3 chunks.

Whole-bundle obfuscation is rejected. No current component has a named, non-security intellectual-property requirement that survives the observability constraint, and an obfuscator would degrade diagnostics, accessibility review, performance analysis, dependency auditing, and incident response. A future narrow exception requires a named file and owner, before/after size/startup measurements, private symbolication, browser/accessibility tests, and explicit confirmation that no security property depends on it.

#CSP And SRI Evaluation

CSP is not enabled by this increment. Current layouts contain intentional inline bootstrap/configuration scripts and some themes consume third-party font/icon resources. A meaningful CSP requires nonce generation and propagation through every inline script/style and integration, a report-only rollout, violation collection/redaction, and functional tests. A partial header would either break the product or require unsafe directives that misrepresent its protection.

SRI is also not enabled. Entrypoints and dynamic chunks are same-origin, content-addressed artifacts deployed atomically with their manifest. Adding an integrity attribute only to the entry would not establish integrity for its dynamic dependency graph. Reconsider SRI only if the asset resolver can emit and test an integrity ledger for every reachable asset, or when a necessary cross-origin static resource has a versioned immutable URL.

#Consequences

• Production deploys can apply long-lived immutable caching to hashed assets while serving the manifest/HTML with revalidation.
• Operators must publish a complete build directory and manifest atomically; deleting the previous assets before traffic switches can break open pages.
• Error symbolication uses minified runtime locations unless a future approved private source-map upload integration is implemented. Maps must never be left under public/build.
• Lockfile and file digests make build provenance inspectable without leaking source or secrets.
• The engineering increment is not fully accepted until the operator compiles all eight affected themes and completes the clean-load/visual/cache checklist in doc/public/en/architecture/frontend-delivery.md.