hemx/docs/v1-product-evidence.md

Hemx v1 product evidence

This document records external evidence used to sharpen the hemx v1 requirements. It is not authority over REQUIREMENTS.md, and precedent does not prove demand. The product decision remains: checked hypermedia for Rust, with server-first as the simple default and client-local/offline execution as explicit opt-in layers over the same generated-resource and effect contract.

Research checked on 2026-07-13.

User job and alternatives

The target user is a Rust team building an interaction-heavy web application that wants server-rendered HTML and ordinary Rust domain logic without accepting a second selector/string contract or a component/VDOM runtime. Today that team can:

• use server-only hypermedia and accept round-trip latency;
• add handwritten JavaScript and own two state/effect models;
• adopt React/Vue or another client framework for local interaction;
• use LiveView/Turbo-style server-driven interaction; or
• build a local-first sync engine directly.

Those alternatives work. Hemx v1 is justified only if execution location can be an opt-in handler choice while generated resources, EffectBatch, failure semantics, and server authority stay coherent.

Evidence and decisions

Linear: local responsiveness requires a real sync architecture

Sources:

• Scaling the Linear Sync Engine
• Linear Method
• Linear Security
• How Linear uses Google Cloud databases

Linear materializes fast local interaction with a client-side data model and a server replication/sync system rather than hiding latency behind cosmetic loading states. Its published architecture discusses initial synchronization, real-time updates, database change capture, and scaling work; its product method also values deliberate, opinionated workflows. Its security page treats access, encryption, backups, monitoring, incident handling, and independent assurance as operational systems rather than UI features.

Use in hemx: client-local work must be genuinely local; offline/sync must have durable identities, bounded queues, resumable acknowledgement, migration, conflict/rejection behavior, and observable recovery. Production proof must cover operations and failures, not only the happy-path API.

Do not copy: hemx is a framework, not Linear's product. It must not grow issue tracking, workspace policy, SSO/SCIM, a hosted database, or a mandatory global client graph. Authentication, authorization, encryption policy, backups, and retention remain application/platform concerns; hemx integrations must expose boundaries that let applications enforce and test them.

Local-first: offline is a data-ownership and recovery promise

Source: Local-first software: You own your data, in spite of the cloud.

The local-first work identifies availability without a network, multi-device coordination, ownership, longevity, and collaboration as distinct properties. A cache or optimistic DOM patch does not establish them.

Use in hemx: persisted commands/domain events are truth; DOM effects are projections. Queue durability, export/deletion, schema upgrades, conflict policy, and recovery from corruption/quota failure must be explicit. “Offline capable” cannot mean only that a shell loads.

Do not copy: CRDTs are not the default. Hemx v1 keeps the server authoritative and requires explicit opt-in policy where collaboration semantics differ.

Hypermedia and live-server systems: preserve browser and deploy semantics

Sources:

• HTMX documentation
• Phoenix LiveView deployments
• Turbo Handbook

These systems demonstrate progressive enhancement, history-aware navigation, request synchronization, server-driven DOM updates, reconnect/deployment concerns, and the value of preserving ordinary links and forms.

Use in hemx: real href/form fallback, back/forward correctness, stale-request suppression, deploy fingerprint refusal, reconnect behavior, and clear full-page recovery are release requirements.

Do not copy: selector mini-languages, implicit component lifecycles, and a router owned by core remain outside hemx.

Platform primitives: use the browser's durable and accessible contracts

Sources:

• IndexedDB API
• Using Service Workers
• WCAG 2.2 quick reference
• RAIL performance model

IndexedDB provides transactional browser storage; service workers provide an HTTPS-bound offline/network interception lifecycle. WCAG 2.2 makes keyboard operation, visible focus, status/error communication, and programmatic name/role/value release concerns. RAIL treats roughly 100 ms as the response window in which direct manipulation feels immediate.

Use in hemx: optional adapters reuse platform storage/service-worker primitives; storage failures and upgrades are recoverable. Generated interaction must preserve semantic HTML, keyboard operation, focus, status/error announcements, and reduced-motion preferences. Client-local interaction gets an observable latency/frame budget rather than a “fast” adjective.

Do not copy: hemx core does not mandate IndexedDB, a service worker, or an application cache policy.

Security and release discipline: framework controls need testable boundaries

Sources:

• OWASP Application Security Verification Standard 5.0
• Cargo SemVer compatibility
• cargo-audit

ASVS provides a test-oriented baseline for web controls such as encoding, injection prevention, session/access boundaries, validation, and logging. Cargo's SemVer guidance shows that public Rust items, traits, features, MSRV, and runtime behavior all carry compatibility risk. cargo-audit checks the committed lockfile against RustSec advisories.

Use in hemx: unsafe HTML stays type-gated; integrations make origin/CSRF, authorization, limits, and security logging testable; replay never bypasses current authorization. v1 has an explicit public/generated/wire/runtime compatibility policy, migration evidence, MSRV/browser support, and a pinned lockfile advisory audit before release approval.

Do not copy: hemx does not claim application-level ASVS compliance. It proves only controls and boundaries it owns. Publishing remains a separate explicit human decision.

Product thesis

Hemx v1 should feel like boring server-rendered HTML with typed, selectorless partial swaps, while letting a team opt one handler into local WASM or durable sync without changing the resource/effect language. The smallest coherent mechanism is:

1. hemplate Surface facts and generated resources;
2. one handler shape with explicit execution placement;
3. one versioned EffectBatch application contract;
4. server-first by default;
5. explicit local state ownership;
6. optional durable command-log/reconciliation adapters; and
7. fail-closed versioning plus native-browser recovery.

Kill tests

Reshape or drop client-local/sync work if any slice requires:

• a second effect protocol or selector target language;
• hidden global state or a component lifecycle;
• bespoke JavaScript per application handler;
• persisted DOM/effect payloads as domain truth;
• a mandatory browser database, service worker, CRDT, or conflict policy;
• authorization decisions cached across replay without server revalidation; or
• inaccessible interaction or failure states that cannot preserve native HTML fallback.