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](https://linear.app/now/scaling-the-linear-sync-engine)
- [Linear Method](https://linear.app/method/introduction)
- [Linear Security](https://linear.app/security)
- [How Linear uses Google Cloud databases](https://cloud.google.com/blog/products/databases/product-workflow-tool-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](https://www.inkandswitch.com/essay/local-first/).

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](https://htmx.org/docs/)
- [Phoenix LiveView deployments](https://hexdocs.pm/phoenix_live_view/deployments.html)
- [Turbo Handbook](https://turbo.hotwired.dev/handbook/introduction)

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](https://developer.mozilla.org/en-US/docs/Web/API/IndexedDB_API)
- [Using Service Workers](https://developer.mozilla.org/en-US/docs/Web/API/Service_Worker_API/Using_Service_Workers)
- [WCAG 2.2 quick reference](https://www.w3.org/WAI/WCAG22/quickref/)
- [RAIL performance model](https://web.dev/articles/rail)

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](https://owasp.org/www-project-application-security-verification-standard/)
- [Cargo SemVer compatibility](https://doc.rust-lang.org/cargo/reference/semver.html)
- [cargo-audit](https://github.com/rust-secure-code/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.