- commit
- fc2fbf946aa3bdf5bba922f57f11e7a3ca5fd2d2
- parent
- d2086652673d2784c6f56dfd4a45cf612d26d73e
- author
- Dami <dami.etoile@gmail.com>
| M | docs/ | 2 | +- |
| M | docs/ | 51 | +++++++++++++++++++++--------- |
| A | docs/ | 19 | +++++++++++ |
@@ -26,7 +26,7 @@ indicative floor rather than an equivalent-UI bundle claim.
2626 2727 ## Consequences2828 29-- Jazz alpha churn is isolated to `apps/prototype/src/runtime` and schema/config files.29+- Jazz alpha churn is isolated to `apps/reference/src/_lofi` and schema/config files.3030 - Component authors get context-free hooks that work across independent Astro islands.3131 - The adapter owns query snapshot identity, cleanup, mutation error mapping, and HMR lifecycle.3232 - Deferred asynchronous subscription failures remain limited by Jazz's public API and must not be@@ -1,7 +1,7 @@
11 # lofi developer-experience contract22 3-Status: **v0 proposed**\4-Scope: **M0 contract and M1 feasibility**\3+Status: **v0 validated through M1; M2 implementation in progress**\4+Scope: **M0 contract, M1 feasibility, and M2 DevX graduation**\55 Last reviewed: **2026-07-15**66 77 This is the product contract for lofi. Implementation choices are provisional until they satisfy@@ -18,9 +18,9 @@ The older `init.md` is research input, not an authoritative description of Jazz
1818 - **deferred** — valuable but intentionally owned by a later milestone.1919 - **rejected** — disproved or incompatible with the product direction.2020 21-The promises marked **M1 gate: yes** must be validated, revised, or rejected before M1 merges. A21+The promises marked **M1 gate: yes** were validated, revised, or rejected before M1 merged. A2222 post-M1 promise may remain proposed only when it has a named milestone and does not affect the23-honesty of the graduated prototype.23+honesty of the graduated reference application.2424 2525 ## Two distinct journeys2626 @@ -49,11 +49,11 @@ cd lofi
4949 deno task dev5050 ```5151 52-The graduated `apps/prototype` must then support a local write, reload, offline cold-start and edit,53-check, test, build, and preview. It does not claim observable transport reconnection or convergence54-because the pinned Jazz API exposes neither signal; that remains a later test contract. Git is a55-contributor prerequisite for this repository journey; Deno remains the only required global runtime56-for a generated application.52+The graduated M1 application, now retained as `apps/reference`, must support a local write, reload,53+offline cold-start and edit, check, test, build, and preview. It does not claim observable transport54+reconnection or convergence because the pinned Jazz API exposes neither signal; that remains a later55+test contract. Git is a contributor prerequisite for this repository journey; Deno remains the only56+required global runtime for a generated application.5757 5858 ## End-to-end journey contract5959 @@ -155,14 +155,17 @@ my-app/
155155 ├── public/156156 ├── src/157157 │ ├── schema.ts158+│ ├── permissions.ts158159 │ ├── app.ts159160 │ ├── pages/160-│ └── islands/161+│ ├── islands/162+│ ├── styles/163+│ └── _lofi/ # generated; not author-edited161164 └── tests/162165 ```163166 164-The exact layout may change during M1 only when verified toolchain behavior requires it or the165-change removes an author-facing concept.167+The exact layout may change only when verified toolchain behavior requires it or the change removes168+an author-facing concept. `src/_lofi/` is generated machinery, not an author-editing surface.166169 167170 ## Author boundary168171 @@ -170,6 +173,7 @@ change removes an author-facing concept.
170173 | -------------------------- | ------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |171174 | Product UI/pages/islands | lofi components/hooks and application types only. | Raw Jazz, worker, transport, Workbox, and capability branching are forbidden. |172175 | `schema.ts` | Application schema declarations. | Direct pinned Jazz 2 schema declarations are allowed in the M1 prototype until #7 determines whether a lofi-owned schema facade is honest and affordable. |176+| `permissions.ts` | Application access policy next to the schema. | Direct pinned Jazz 2 permission declarations are allowed; Jazz tooling watches this location. |173177 | `app.ts` | Named lofi configuration and composition. | Raw vendor setup is allowed only inside spike controls, not the graduated prototype. |174178 | Generated/internal runtime | Vendor clients, workers, storage, sync, auth, and PWA wiring. | May change across alpha pins without changing product UI. |175179 | Escape-hatch module | Explicitly isolated unsupported vendor access. | Never generated by default; no compatibility promise before framework extraction. |@@ -268,9 +272,26 @@ generator gets its own fixture inspection.
268272 269273 ## Graduation rule270274 271-M1 graduates exactly one integrated `apps/prototype` containing the approved Jazz version, Preact272-strategy, Astro/Deno path, durability policy, and identity model. Rejected runtime alternatives are273-removed from the final tree; their evidence remains in decisions and merge-commit history.275+M1 graduated exactly one integrated application, now named `apps/reference`, containing the approved276+Jazz version, Preact strategy, Astro/Deno path, durability policy, and identity model. Rejected277+runtime alternatives are removed from the final tree; their evidence remains in decisions and278+merge-commit history.274279 275280 Package extraction, the generator, full inspector/testing SDK, and production PWA hardening remain276281 M2 or later work.282+283+## M2 layered graduation284+285+M2 integrates into the `m2` branch as three separately reviewed layers. Each layer must pass its own286+checks and independent pull-request review before merge. The combined branch is re-reviewed before287+it may merge into `dev`.288+289+| Layer | Issues | Contract result |290+| ---------------------------------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------- |291+| 1 — reference and checkout journey | #9; tracks #11 | Honest checklist CRUD, explicit author/generated boundary, and reusable checkout-mode golden-path evidence. |292+| 2 — public command path | #13, #14; completes #11 | Non-interactive creation plus actionable `dev`/`doctor`; the same journey runs against generated output. |293+| 3 — testing and inspection | #12, #10 | Reusable offline/convergence controls and truthful developer diagnostics without leaking machinery into product UI. |294+295+Layer 1 does not close #11: checkout-mode evidence is necessary, but the generated-project journey296+cannot pass until Layer 2 implements the public create command. Remaining abstraction leaks are297+tracked in `docs/m2-abstraction-leaks.md` rather than hidden behind premature package APIs.@@ -0,0 +1,19 @@
1+# M2 abstraction-leak ledger2+3+Status: active during M2\4+Last reviewed: 2026-07-155+6+This ledger keeps the Layer 1 reference application honest. A listed leak is not a supported lofi7+API; it is a concrete input to the layer that owns removing or productizing it.8+9+| Leak retained in Layer 1 | Why it remains | Owning issue | Graduation evidence |10+| -------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | ----------------------------- | ---------------------------------------------------------------------------------------------------------------------- |11+| Repository-root wrappers own `dev`, `build`, preview, environment loading, and secret scans. | Extracting commands before the reference journey is executable would freeze an untested project shape. | #13, #14 | A generated directory runs its own documented tasks without repository-relative paths. |12+| `schema.ts` and `permissions.ts` import the pinned Jazz schema DSL directly. | M1 rejected inventing a second schema language without a proven ergonomic gain. | Later API extraction after M2 | A second real application demonstrates a smaller stable facade, or the direct DSL is accepted explicitly. |13+| `app.ts` uses a provisional plain configuration object and the Jazz schema value. | Layer 1 needs configuration-as-data but does not yet have two consumers that justify a public factory or exported type. | #13 | The generator emits the approved configuration without raw client, transport, or environment plumbing. |14+| Runtime cardinality and lifecycle evidence use a development-only global probe. | Product UI must stay clean while the browser journey still needs deterministic evidence. | #10 | The inspector exposes the same truthful signals through a supported development surface and is absent from production. |15+| The checkout golden path owns process/browser orchestration at repository scope. | Layer 1 proves the journey before defining a reusable testing package. | #12 | Offline and multi-client helpers are callable from generated-project tests with readiness-based APIs. |16+| Cloud/global settlement is observable per write, but live socket state is not. | Jazz alpha.53 exposes mutation durability but no supported connection-state signal. | #10, #12 | Inspector/tests distinguish configured mode, local durability, global durability, and unavailable live detail. |17+18+Deleting an entry requires retained evidence in the owning issue or a decision record accepting the19+behavior as an intentional public boundary.