coulomb/frontend-patterns
5
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Complete the bounded language 0.1 research preview

Browse source 
Assistant: codex
Assistant-Model: gpt-6-astra
Assistant-Session: 01a0e241-8285-7a63-8c0c-51c9cb824dc3
This commit is contained in:
tegwick 2026-09-27 11:49:48 +02:00
parent 8cc7016e1f
commit 53bb65e7a6
26 changed files with 2497 additions and 33 deletions
Download patch file Download diff file Expand all files Collapse all files

70
sequences/LocalFirstApplication.md
View file

@ -1,15 +1,63 @@
# LocalFirstApplication
# Offline local-work sequence
Status: research stub
0.1 research preview · synthetic VC-02 guidance · all linked candidates are hypotheses.
[Start](../START.md) · [Core and extensions](../reference/0.1/Catalog.md)
A generative sequence for applications in which local state remains usable and authoritative interaction continues despite network loss.
## Starting context
## Research tasks
People create/edit notes without connectivity, restart without losing acknowledged
work, then synchronize. Multiple writers may produce incompatible changes. Notes do
not make globally exclusive reservations or approvals. Access/retention policy and
separate device-loss recovery must be explicit.
- identify dominant forces,
- establish authority assumptions,
- determine suitable projection patterns,
- determine synchronization model,
- identify failure modes,
- derive candidate sequence,
- test against known implementations.
Offline usability, recoverability and completeness compete with freshness, storage
complexity and reconciliation effort. Decide what “saved” means before choosing sync
or rendering tools. An evictable cache is not automatically the required local record.
## Decisions and resulting contexts
| Decision | Candidate and resulting context | Alternative / boundary |
| --- | --- | --- |
| Acknowledge only a recoverable local commit | [CAND-0002 Local Commit Boundary](../research/candidates/LocalCommitBoundary.md): accepted local revision and pending propagation survive the specified restart | Memory-only feedback cannot satisfy restart; server-only saving cannot satisfy offline acceptance. Verify transaction and failure boundaries |
| Keep propagation visible and restartable | [CAND-0003 Pending Synchronization](../research/candidates/PendingSynchronization.md): distinguish queued, sent and receiver-acknowledged | Online-only writes change the brief. Untracked upload cannot prove completion; receiver receipt does not mean every device received the change |
| Preserve detected competing content when permitted | [CAND-0001 Conflict Copy](../research/candidates/ConflictCopy.md): working version selected, divergent intent still available | Immediate comparison or justified semantic merge may be preferable; a copy cannot detect all conflicts or guarantee no loss |
| Make semantic resolution an explicit decision | [CAND-0004 Explicit Reconciliation](../research/candidates/ExplicitReconciliation.md): comparison produces a new revision and pending work | A version store can supply alternatives without conflict files; domain-appropriate automatic merge may avoid manual review |
Local projection must reconstruct required offline work from locally available inputs.
Initial online server rendering may coexist with that path; it cannot be the only
way to display new offline edits. Choosing a CRDT or sync transport does not by itself
establish persistence, access or acceptable domain outcomes.
## Follow the failure
A and B edit a common revision while disconnected. A acknowledges local save only
after the specified durable transaction. Restart reconstructs that work and its pending
identity. When divergence is detected, preserve alternatives subject to policy and
block obsolete retry work. Selecting a working version does not settle intended content.
When the user resolves it, atomically record the new revision/pending operation and
supersede the old one. An already transmitted operation still needs receiver-side
ancestry/precondition handling. Late receipts must not clear newer pending work.
A lost acknowledgement remains unresolved propagation, not proof of rejection. Retry
only within the receiver contract; expired identity or access needs explicit handling.
Backup must survive the failure you promise to recover from. Another local copy or
synchronized deletion is not an independent restore path.
## Change a constraint
If only A may edit and that restriction actually holds, omit the concurrent-version
branch. Local commit and pending propagation remain. If another writer, external tool
or restored revision violates the assumption, reassess divergence handling.
If the user instead needs offline globally exclusive checkout or approval, stop:
this note-oriented configuration does not provide global exclusivity. Clarify the
acceptance requirement or choose a separately justified domain protocol.
## Implementation and evidence
[Offline mechanism mappings](../technologies/OfflineRecovery.md) locate local storage,
sync metadata and documented conflict-handling options. They do not establish our
atomic storage or retry contracts. The full [VC-02 trace](../research/walkthroughs/VC02-OfflineFieldNotes.md)
records its baseline and assumptions. [M1 review](../research/reviews/M1-SeedReview.md)
remains revise/defer; crash recovery, receiver semantics, human/AT and independent
usefulness evidence are still open.

65
sequences/TransactionalApplication.md
View file

@ -1,15 +1,58 @@
# TransactionalApplication
# Transactional editing sequence
Status: research stub
0.1 research preview · synthetic VC-01 guidance · all linked candidates are hypotheses.
[Start](../START.md) · [Core and extensions](../reference/0.1/Catalog.md)
A generative sequence for applications dominated by forms, workflows, commands, validation and authoritative transactions.
## Starting context
## Research tasks
People edit shared records. A designated service must validate and accept writes;
other people or in-flight operations can change a record. Preserve unfinished intent
while the page remains open. Restart persistence is an additional policy/storage choice.
- identify dominant forces,
- establish authority assumptions,
- determine suitable projection patterns,
- determine synchronization model,
- identify failure modes,
- derive candidate sequence,
- test against known implementations.
The main forces are consistency, recoverability and continuity versus complexity,
latency and user review effort. First verify the endpoint's version, authorization,
business-rule and receipt contracts; the names below cannot supply missing guarantees.
## Decisions and resulting contexts
| Decision | Candidate and resulting context | Alternative / boundary |
| --- | --- | --- |
| Keep typing separate from the last received record | [CAND-0005 Local Draft State](../research/candidates/LocalDraftState.md): base, proposal and current observation can be compared | Directly bind a cache only where there is no unfinished work; retention/export still follow access policy |
| Reject proposals based on stale assumptions | [CAND-0006 Version-Checked Mutation](../research/candidates/VersionCheckedMutation.md): authority checks expected version with the write; rejection creates a review decision | Commutative or unconditional operations need their own domain contract; do not blindly resend against a newer version |
| Distinguish transport failure from the result of the operation | [CAND-0007 Mutation Outcome Tracking](../research/candidates/MutationOutcomeTracking.md): keep pending, accepted, rejected or unknown evidence for that attempt | Without result lookup or valid deduplication scope/window, stop automatic replay and reconcile; a fresh ID is not a recovery guarantee |
| Refresh affected views after acceptance | [CAND-0008 Invalidate and Reproject](../research/candidates/InvalidateAndReproject.md): acceptance and view freshness remain separate | A complete authoritative result or suitable subscription may avoid refetch; obsolete responses must not replace newer observations or drafts |
These decisions are conditional, not a mandatory dependency chain. Keep shared
acceptance separate from local display. Server and client projection are alternatives
only after their input availability, performance and recovery needs are understood.
## Follow the failure
A reads a record and edits it; B changes that record. A's stale write is rejected:
keep A's draft and compare it with the current record. After the user reconsiders,
a new proposal may be sent. If its response disappears, retain its identity and show
unknown outcome. Resolve that attempt through its verified receipt/replay contract.
Once acceptance is established, refresh affected observations without erasing newer
input. If refreshing fails, show accepted with a stale view, not failed mutation.
Opaque versions are not sortable numbers without an ordering contract. Stopping a
local wait does not reverse a remote effect; compensation is a separate authorized
operation. Invalid access may prohibit retaining the draft. Keyboard/error recovery
must be implemented and checked; this sequence is not accessibility certification.
## Change a constraint
With one authorized writer, cross-user contention disappears, but that writer's
in-flight operations can still race. Outcome uncertainty and refresh remain; version
checks do not automatically become unnecessary. With required offline final approval,
this fixed server-acceptance brief is incompatible: change the domain acceptance
contract or require connectivity. Do not substitute the offline-note sequence silently.
## Implementation and evidence
Use [transactional mechanism mappings](../technologies/TransactionalRecovery.md) to
find API and frontend examples, then verify your actual contracts. The full
[VC-01 trace](../research/walkthroughs/VC01-TransactionalAdministration.md) includes the
plain-language baseline, assumptions and counterfactual. It is development reasoning,
not empirical validation. [M1 review](../research/reviews/M1-SeedReview.md) remains
revise/defer. Independent human usefulness and complete application recurrence are open.