diff --git a/Makefile b/Makefile index 36785e1..14abca8 100644 --- a/Makefile +++ b/Makefile @@ -26,3 +26,13 @@ classification-report: classification-check: python3 scripts/classification_coverage.py --check + +.PHONY: reference-generate reference-check reference-test +reference-generate: + python3 scripts/reference_preview.py + +reference-check: + python3 scripts/reference_preview.py --check + +reference-test: + PYTHONDONTWRITEBYTECODE=1 "$(BENCH_PY)" -m pytest -q -p no:cacheprovider tests/test_reference_preview.py diff --git a/README.md b/README.md index f6eb5db..c5b561b 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,10 @@ # frontend-patterns -A coherent, generative pattern language for frontend architecture and design. +An evolving research language for frontend architecture and design. + +Start with the [0.1 research preview](START.md): two decision paths, seventeen +draft hypotheses and evidence-qualified implementation mappings. Canonical admission, +independent usefulness and the M1/M2/M3 gates remain open. The project treats frontend architecture not as a choice among frameworks or named styles, but as the progressive resolution of recurring forces concerning: diff --git a/SCOPE.md b/SCOPE.md index 4ae879f..ffba37a 100644 --- a/SCOPE.md +++ b/SCOPE.md @@ -56,7 +56,8 @@ Static source mechanisms and authored runtime fixtures do not establish complete pattern recurrence, production fitness or independent human confirmation. Canonical admission, M1/M2 acceptance, demonstrated generativity, full graph export, -held-out retrieval evaluation and developed technology mappings remain open. +held-out retrieval evaluation remain open. Scoped mechanism mappings are available +in the 0.1 preview; full implementation contracts remain unverified. There is research runtime code, but no maintained frontend application or framework is offered as the product. See the [evolution report](research/evolution/EvolutionReport.md) for current counts and evidence limits; [REVIEW.md](REVIEW.md) preserves the initial @@ -86,9 +87,9 @@ held-out retrieval and real-repository applicability, subject to its recorded ga review dates and comparable-cycle measurement. Actionable work stays in workplans; this file describes boundaries, not a second backlog. -[WP-0007](workplans/FEP-WP-0007-language-v01-preview.md) proposes a finite 0.1 research +[WP-0007](workplans/FEP-WP-0007-language-v01-preview.md) packages a finite 0.1 research preview: curated candidate reference paths, two core sequences, scoped mappings and -a candidate export. This is not a declared release or a replacement for M1/M2/M3. +a candidate export. This is a bounded research preview, not a replacement for M1/M2/M3. The [2026-09-27 scope–intent assessment](history/2026-09-27T010237+0200-scope-vs-intent.md) records the current gaps and recommended priorities. Future assessments should diff --git a/START.md b/START.md new file mode 100644 index 0000000..9f19cf5 --- /dev/null +++ b/START.md @@ -0,0 +1,66 @@ +# Start with a frontend decision + +**0.1 research preview.** Seventeen candidate patterns, all hypotheses. Use them to +make assumptions and trade-offs explicit; confirm the required contracts in your +implementation. This language has not yet demonstrated improved decision quality. + +## Choose your starting problem + +| Your problem | Start here | What the sequence helps decide | +| --- | --- | --- | +| Users edit shared records; writes can conflict or lose their responses | [Transactional editing](sequences/TransactionalApplication.md) | Preserve intent, reject stale proposals, resolve uncertain outcomes, refresh views | +| Users edit notes offline and must resume after restarting | [Offline local work](sequences/LocalFirstApplication.md) | Acknowledge local save, retain pending propagation, handle divergence, plan recovery | +| You need navigation, rendering, feature or interaction guidance | [Extension candidates](reference/0.1/Catalog.md#extensions) | Explore individual hypotheses with their current evidence limits | +| You need an overview of coverage | [Classification inventory](research/catalog/ClassificationCoverage.md) | Compare families, scales, responsibilities and selected forces | + +Before choosing, state who can accept the relevant change, which state must survive +restart, and what the user is allowed to retain. A locally displayed result is not +necessarily accepted. Where a view is computed is a separate decision from authority. + +If you cannot answer those questions, clarify them first. If you require globally +exclusive approval while fully disconnected, neither sequence supplies that guarantee. +A collaborative editor, hard real-time system or complete security architecture needs +additional domain work; an unfilled catalog cell is not permission to improvise a +validated solution. + +## Read the language as decisions + +A candidate explains a problem and forces, a proposed solution, its resulting context, +alternatives and failure modes. Follow conditional links only when their assumptions +hold. The eight [core candidates](reference/0.1/Catalog.md#core) connect into the two +sequences; the other nine are extensions, not mandatory additions. + +[Transactional mappings](technologies/TransactionalRecovery.md) and +[offline mappings](technologies/OfflineRecovery.md) locate implementation mechanisms. +No listed product is certified to implement the whole proposed configuration. + +A short example: if an edit succeeds remotely but its response disappears, preserve +its operation identity and treat the outcome as unknown. Find the result or use a +verified bounded replay contract before creating another attempt. After acceptance, +refresh observations separately; a refresh failure does not undo acceptance. Follow +the [transactional sequence](sequences/TransactionalApplication.md) for assumptions +and alternatives. + +## Evidence and future versions + +The [0.1 release record](reference/0.1/README.md) pins the corpus and lists supported +contexts. [Evidence profiles](research/evolution/EvolutionReport.md) separate documents, +code inspection and runtime observations. No candidate is canonically admitted; a +source locator or passing fixture does not prove its full contract. + +For a counterexample, record the candidate ID, the context, expected versus observed +behavior, implementation revision and any reproducible evidence. Explain whether a +precondition was absent or the proposed solution failed despite it. Use the source or +learning-cycle templates under `templates/`; proposed corrections require a named +review with retained prior claims. Never paste private data or credentials into evidence. + +Later versions may revise, merge, split or retire candidates. Preserve identities and +supersession records; do not silently reinterpret an older release. The language is +intended to keep learning. + +## Agent reference + +Read [index.json](reference/0.1/index.json) for stable research identities, proposed +relations, classification, evidence and gaps. It is a candidate reference export, not +an admitted canonical graph. Read the linked contracts before making a recommendation; +do not infer inverse edges, unconditional dependencies or transitive guarantees. diff --git a/reference/0.1/Catalog.md b/reference/0.1/Catalog.md new file mode 100644 index 0000000..69f65d0 --- /dev/null +++ b/reference/0.1/Catalog.md @@ -0,0 +1,32 @@ +# Candidate reference — 0.1 + +All records are draft hypotheses. Classification is provisional; linked candidate prose contains context, alternatives and consequences. Evidence locators describe partial support, not full-contract recurrence. + +## Core + +| Candidate / decision | Families; scales | Evidence limits | +| --- | --- | --- | +| [CAND-0001 — Conflict Copy](../../research/candidates/ConflictCopy.md) — Preserve competing versions instead of silently losing one. | synchronization; L2, L6 | Authorized retention and export are separate decisions. Complete contract recurrence and fault-tested deployed behavior remain unverified. | +| [CAND-0002 — Local Commit Boundary](../../research/candidates/LocalCommitBoundary.md) — Define when a local change is durably accepted. | mutation, authority; L2, L6 | No executed storage crash or backup test. Local acceptance is not off-device recovery. | +| [CAND-0003 — Pending Synchronization](../../research/candidates/PendingSynchronization.md) — Keep accepted local intent visible until synchronization resolves. | synchronization; L2, L6 | Atomic supersession and retry contract proposed, not storage-tested. | +| [CAND-0004 — Explicit Reconciliation](../../research/candidates/ExplicitReconciliation.md) — Resolve divergent content while retaining provenance. | synchronization, affordance; L2, L6 | Atomic resolution/provenance UI not executed. Overlap with Conflict Copy remains an open merge question. | +| [CAND-0005 — Local Draft State](../../research/candidates/LocalDraftState.md) — Separate unfinished intent from refreshed authoritative data. | affordance, mutation; L6 | No native-unload, crash, multiple-tab or access-revocation guarantee. Full base/draft/current merge contract is not verified in deployed frontends. | +| [CAND-0006 — Version-Checked Mutation](../../research/candidates/VersionCheckedMutation.md) — Reject an operation whose observed base is stale. | mutation, authority; L2, L6 | Distributed atomicity and complete frontend recurrence remain unverified. Refetch does not authorize overwriting conflicting intent. | +| [CAND-0007 — Mutation Outcome Tracking](../../research/candidates/MutationOutcomeTracking.md) — Retain operation identity when transport outcome is uncertain. | mutation, synchronization; L2, L6 | No production server deduplication or complete retention-window guarantee. Cancelling local UI is not remote compensation. | +| [CAND-0008 — Invalidate and Reproject](../../research/candidates/InvalidateAndReproject.md) — Refresh a projection after mutation without equating acceptance and visibility. | projection, synchronization; L3, L6 | Read-your-write and acceptance/refresh distinction still proposed. No independent deployed full-contract observation. | + +## Extensions + +| Candidate / decision | Families; scales | Evidence limits | +| --- | --- | --- | +| [CAND-0009 — URL-addressable State](../../research/candidates/URLAddressableState.md) — Make a navigable state reconstructible from its URL. | address, projection; L3 | Independent application recurrence and human/AT validation remain unverified. Pending history disclosure, multiple history misses, redirects, nonzero swap delays, bfcache, lifecycle cleanup, interrupted/late enhancement and offline availability remain open. Zulip auxiliary target/anchor callbacks, deferred editing focus and search callback wiring remain unverified; static guards do not prove whole-application ownership. | +| [CAND-0010 — Progressive Enhancement](../../research/candidates/ProgressiveEnhancement.md) — Keep essential actions usable when enhancement is unavailable. | quality, execution, affordance; L3, L6 | Independent application recurrence and human/AT validation remain unverified. Pending history disclosure, multiple history misses, redirects, nonzero swap delays, bfcache, lifecycle cleanup, interrupted/late enhancement and offline availability remain open. Zulip auxiliary target/anchor callbacks, deferred editing focus and search callback wiring remain unverified; static guards do not prove whole-application ownership. | +| [CAND-0011 — Presentation Model](../../research/candidates/PresentationModel.md) — Separate presentation decisions from view mechanisms. | composition, affordance; L4, L6 | No executed model/view integration or independently reviewed full-contract use. | +| [CAND-0012 — Derived State](../../research/candidates/DerivedState.md) — Compute a result from explicit authoritative inputs. | projection, affordance; L3, L6 | Snapshot coherence and changed-locale cache test still planned. | +| [CAND-0013 — Vertical Feature Slice](../../research/candidates/VerticalFeatureSlice.md) — Group a capability across UI, state and behavior with explicit interfaces. | composition; L4 | Build/import enforcement not executed. Feature organization does not establish independent activation. | +| [CAND-0014 — Islands of Interactivity](../../research/candidates/IslandsOfInteractivity.md) — Activate selected interactive regions within a document. | projection, execution; L3, L5 | No executed island fixture, performance comparison or complete recurrence study. | +| [CAND-0015 — Failure Boundary](../../research/candidates/FailureBoundary.md) — Contain specified failure classes while preserving useful neighboring work. | quality, composition; L5, L6 | Synthetic host, not full application recurrence. Boundary cannot imply containment for all asynchronous failures. | +| [CAND-0016 — Focus Return](../../research/candidates/FocusReturn.md) — Restore meaningful focus after a temporary interaction ends. | quality, affordance; L6 | One implementation family; repeated trials are not independent uses. Animated exits and competing owners remain untested; no production repair claim. Route ownership is a contrast, not independent modal recurrence; AT speech and broader history/lifecycle cases remain unverified. Zulip auxiliary target/anchor callbacks, deferred editing focus and search callback wiring remain unverified; static guards do not prove whole-application ownership. | +| [CAND-0017 — Independent Feature Boundary](../../research/candidates/IndependentFeatureBoundary.md) — Separate feature release, activation and session transition contracts. | composition, execution; L1, L4 | No upstream deployment or real team/release-independence validation. Distributed atomicity, retention authorization and native-unload/crash behavior remain open. | + +Extensions are optional research leads. VC-03/06 remain provisional; other planned cases are unsupported. Follow the [starting guide](../../START.md) for the two core contexts. diff --git a/reference/0.1/DevelopmentChecks.md b/reference/0.1/DevelopmentChecks.md new file mode 100644 index 0000000..2683f5a --- /dev/null +++ b/reference/0.1/DevelopmentChecks.md @@ -0,0 +1,99 @@ +# Disclosed development navigation checks + +Author-model review; scenarios and answers were authored together. These checks validate navigation and stated boundaries, not measured retrieval or independent usefulness. + +## D01 — My shared record changed while I was editing. + +[transactional](../../sequences/TransactionalApplication.md) → CAND-0005, CAND-0006. + +Preserve the proposal, inspect the current record and reconsider after a stale-base rejection. + +Boundary: The endpoint must atomically enforce the expected-version contract. + +Reject: Blind retry against a new version or overwriting input. + +Editorial disposition: pass-with-stated-limits. + +## D02 — The write timed out. Can I retry with a new ID? + +[transactional](../../sequences/TransactionalApplication.md) → CAND-0007. + +Keep outcome unknown; look up the original operation or replay only within its verified identity/retention contract. + +Boundary: Without lookup/deduplication evidence, stop automatic retry and reconcile. + +Reject: Inferring rejection from timeout or declaring a fresh identity safe. + +Editorial disposition: pass-with-stated-limits. + +## D03 — The write was accepted but refreshing the list failed. + +[transactional](../../sequences/TransactionalApplication.md) → CAND-0007, CAND-0008. + +Keep acceptance established and show stale-view recovery separately. + +Boundary: The receipt must refer to this operation, and obsolete observations cannot erase newer work. + +Reject: Retrying the mutation because the refresh failed. + +Editorial disposition: pass-with-stated-limits. + +## D04 — I need notes to survive an offline restart and synchronize later. + +[offline](../../sequences/LocalFirstApplication.md) → CAND-0002, CAND-0003. + +Define a recoverable local commit and persistent pending propagation; verify storage and receiver semantics. + +Boundary: This preview supplies a proposed contract, not tested storage guarantees. + +Reject: Equating a cache or visible typing with a durable save. + +Editorial disposition: pass-with-stated-limits. + +## D05 — Two offline versions disagree, but our revision store already retains both. + +[offline](../../sequences/LocalFirstApplication.md) → CAND-0004. + +Consider explicit comparison using the existing revision store; a separate conflict file is optional. + +Boundary: The store must provide authorized, recoverable alternatives and provenance. + +Reject: Making Conflict Copy an unconditional dependency of reconciliation. + +Editorial disposition: pass-with-stated-limits. + +## D06 — Can I approve a globally exclusive reservation while disconnected from every authority? + +[start](../../START.md) → clarify / abstain. + +Identify the incompatible acceptance requirement; neither supported sequence provides that guarantee. + +Boundary: Clarify/change the domain contract or require connectivity; no pattern recommendation establishes it. + +Reject: Treating locally saved data or replica convergence as global exclusivity. + +Editorial disposition: pass-with-stated-limits. + +## D07 — Which state-management pattern should I use? + +[start](../../START.md) → clarify / abstain. + +Ask who accepts changes, what must survive restart, whether writers can conflict and what may be retained. + +Boundary: Underspecified; do not infer that either core sequence applies. + +Reject: Picking a universal state architecture without context. + +Editorial disposition: pass-with-stated-limits. + +## D08 — Give me a complete secure collaborative editor with guaranteed real-time latency. + +[start](../../START.md) → clarify / abstain. + +State that full collaborative/security/latency design is outside the supported core and identify the missing domain evidence. + +Boundary: Unsupported need; request a narrower brief and additional evidence. + +Reject: Assembling extension names into a certified complete architecture. + +Editorial disposition: pass-with-stated-limits. diff --git a/reference/0.1/README.md b/reference/0.1/README.md new file mode 100644 index 0000000..e22df8e --- /dev/null +++ b/reference/0.1/README.md @@ -0,0 +1,31 @@ +# Frontend pattern language 0.1 — research preview + +Start with the [decision guide](../../START.md), then choose +[transactional editing](../../sequences/TransactionalApplication.md) or +[offline local work](../../sequences/LocalFirstApplication.md). + +This version packages **17 draft hypotheses**, with **8 connected core candidates** +and **9 extensions**. Publication version 0.1 does not mean canonical maturity, +PatternSchema compliance, completed M1/M2/M3 or demonstrated usefulness. + +- [Candidate catalog](Catalog.md): decisions, context, evidence and extension limits. +- [Machine-readable reference](index.json): stable CAND identities, proposed edges + and qualified evidence. Conditions are part of each edge; do not infer transitivity. +- [Manifest](manifest.json): selected corpus, input digests, reference paths and scope. +- [Release review](ReleaseReview.md) and [release notes](ReleaseNotes.md): acceptance + evidence, reviewer role, remaining work and update policy. +- [Development navigation checks](DevelopmentChecks.md): disclosed scenarios and + manual reasoning review, not independent human or held-out evaluation. +- [Evidence evolution](../../research/evolution/EvolutionReport.md): transparent + learning and evidence profiles, with immutable historical snapshots. + +Candidate bodies and evidence are pinned by the manifest to a recorded Git revision. +Relative links in a later checkout may show newer files; use that revision for the +recorded corpus. The index includes the pinned hashes and profile/classification +information for this preview. Future incompatible changes require a new version; +errata must explain the correction and preserve prior records in Git. + +Unsupported promises include offline global exclusivity, universal crash-safe storage, +permanent deduplication, accessibility conformance, automatic merge correctness and +production release independence. The extension list is a research surface, not a +complete guide to every frontend architecture. diff --git a/reference/0.1/ReleaseNotes.md b/reference/0.1/ReleaseNotes.md new file mode 100644 index 0000000..700c4e6 --- /dev/null +++ b/reference/0.1/ReleaseNotes.md @@ -0,0 +1,26 @@ +# 0.1 research preview notes + +2026-09-27. This is a versioned research reference, with no canonical admission or +production certification. Candidate corpus revision: +`8cc7016e1fbcb08b670091a174672fcdd8d07640`. + +The preview provides a starting guide, transactional and offline decision sequences, +eight connected core candidates, nine optional extensions, scoped mechanism mappings, +a candidate JSON export and eight disclosed development navigation checks. Existing +candidate contracts and evidence maturity are unchanged by packaging. + +Source traceability passes its bounded documentary review. M1 remains revise/defer; +M2/M3 and independent human usefulness remain open. Conflict Copy and Explicit +Reconciliation retain separate identities with a conditional relationship. No new +external source verification or live inference was performed for this packaging. + +Storage/receiver validation transferred from WP-0002 T02 to WP-0003 T04. Existing +research owners are listed in the manifest. No additional release-blocking residual +was identified in the bounded review. + +Later corrections must retain prior claims in Git, name the affected identities and +context, and explain the evidence and changed decision. An incompatible corpus or +classification change requires a new version and reviewed manifest; never refresh +hashes as a substitute for review. Preserve supersession links when splitting, +merging or retiring candidates. Documentation errata must identify the corrected +preview and remain distinguishable from new empirical evidence. diff --git a/reference/0.1/ReleaseReview.md b/reference/0.1/ReleaseReview.md new file mode 100644 index 0000000..4324635 --- /dev/null +++ b/reference/0.1/ReleaseReview.md @@ -0,0 +1,32 @@ +# 0.1 preview acceptance review + +2026-09-27 · Reviewer: Codex, author-model editorial and deterministic review. +No independent human reviewer participated. **Disposition: ready as a bounded +research preview.** This does not pass M1/M2/M3 or canonical admission. + +| Requirement | Evidence and disposition | +| --- | --- | +| Core selection and source readiness | [Source readiness](../../research/reviews/SourceReadiness-0.1.md) and [M1 review](../../research/reviews/M1-SeedReview.md); eight core contracts qualified, empirical gates deferred | +| Ontology disposition | [Ontology review](../../research/reviews/PreviewOntology-0.1.md); conditional proposals, separate preservation and resolution | +| Human reference paths | [Start](../../START.md), two sequences, two scoped mappings and catalog; alternatives and unsupported needs explicit | +| Machine reference | Export checks candidate digests against the pinned Git corpus, input hashes, identities, vocabulary, endpoints, evidence paths and live residual references | +| Development navigation | Eight disclosed [cases](DevelopmentChecks.md), including incompatible, underspecified and unsupported requests; editorial review only | +| Failure checks | Tests reject bad endpoints/types, missing evidence, empty conditions, duplicate selection, modified candidates, escaping paths and missing relation fields | +| Claim boundary | All seventeen records remain hypotheses; no empirical benefit, full-contract recurrence, accessibility conformance or production guarantees claimed | + +Validation commands: `make reference-test reference-check schema-test bench-test +bench-plan evolution-check classification-check` and `git diff --check`. The review +also checks relative file links in the changed and new Markdown reference surface. +The development cases are authored answers with deterministic reference checks; +there is no search engine, live model retrieval result or held-out score. + +The manifest pins existing candidate contracts to `8cc7016` and hashes profile, +classification and vocabulary inputs. Packaging files are versioned by the commit +containing this review; the baseline revision does not contain this new guide. +Relative links resolve against the checkout, so use the corpus revision to recover +original candidate content after future changes. + +Research residuals remain live under WP-0002 T03; WP-0003 T01–T04; WP-0004 +T01–T03; and WP-0006 T03, with paths in the manifest. WP-0003 T04 explicitly +records the source-review handoff origin. Finishing packaging closes none of those +gates. No tag or external release publication is part of this review. diff --git a/reference/0.1/development-cases.json b/reference/0.1/development-cases.json new file mode 100644 index 0000000..5876be9 --- /dev/null +++ b/reference/0.1/development-cases.json @@ -0,0 +1,115 @@ +{ + "kind": "disclosed-development-checks", + "method": "Author-model editorial navigation and reasoning review plus deterministic reference checks. Cases and answers are authored together; not a retrieval engine result, held-out comparison or independent human validation.", + "cases": [ + { + "id": "D01", + "query": "My shared record changed while I was editing.", + "entrypoint": "transactional", + "expected_candidates": [ + "CAND-0005", + "CAND-0006" + ], + "reviewed_answer": "Preserve the proposal, inspect the current record and reconsider after a stale-base rejection.", + "prohibited_claim": "Blind retry against a new version or overwriting input.", + "boundary": "The endpoint must atomically enforce the expected-version contract.", + "review_result": "pass-with-stated-limits", + "reviewer": "Codex author-model", + "independent_human": false + }, + { + "id": "D02", + "query": "The write timed out. Can I retry with a new ID?", + "entrypoint": "transactional", + "expected_candidates": [ + "CAND-0007" + ], + "reviewed_answer": "Keep outcome unknown; look up the original operation or replay only within its verified identity/retention contract.", + "prohibited_claim": "Inferring rejection from timeout or declaring a fresh identity safe.", + "boundary": "Without lookup/deduplication evidence, stop automatic retry and reconcile.", + "review_result": "pass-with-stated-limits", + "reviewer": "Codex author-model", + "independent_human": false + }, + { + "id": "D03", + "query": "The write was accepted but refreshing the list failed.", + "entrypoint": "transactional", + "expected_candidates": [ + "CAND-0007", + "CAND-0008" + ], + "reviewed_answer": "Keep acceptance established and show stale-view recovery separately.", + "prohibited_claim": "Retrying the mutation because the refresh failed.", + "boundary": "The receipt must refer to this operation, and obsolete observations cannot erase newer work.", + "review_result": "pass-with-stated-limits", + "reviewer": "Codex author-model", + "independent_human": false + }, + { + "id": "D04", + "query": "I need notes to survive an offline restart and synchronize later.", + "entrypoint": "offline", + "expected_candidates": [ + "CAND-0002", + "CAND-0003" + ], + "reviewed_answer": "Define a recoverable local commit and persistent pending propagation; verify storage and receiver semantics.", + "prohibited_claim": "Equating a cache or visible typing with a durable save.", + "boundary": "This preview supplies a proposed contract, not tested storage guarantees.", + "review_result": "pass-with-stated-limits", + "reviewer": "Codex author-model", + "independent_human": false + }, + { + "id": "D05", + "query": "Two offline versions disagree, but our revision store already retains both.", + "entrypoint": "offline", + "expected_candidates": [ + "CAND-0004" + ], + "reviewed_answer": "Consider explicit comparison using the existing revision store; a separate conflict file is optional.", + "prohibited_claim": "Making Conflict Copy an unconditional dependency of reconciliation.", + "boundary": "The store must provide authorized, recoverable alternatives and provenance.", + "review_result": "pass-with-stated-limits", + "reviewer": "Codex author-model", + "independent_human": false + }, + { + "id": "D06", + "query": "Can I approve a globally exclusive reservation while disconnected from every authority?", + "entrypoint": "start", + "expected_candidates": [], + "reviewed_answer": "Identify the incompatible acceptance requirement; neither supported sequence provides that guarantee.", + "prohibited_claim": "Treating locally saved data or replica convergence as global exclusivity.", + "boundary": "Clarify/change the domain contract or require connectivity; no pattern recommendation establishes it.", + "review_result": "pass-with-stated-limits", + "reviewer": "Codex author-model", + "independent_human": false + }, + { + "id": "D07", + "query": "Which state-management pattern should I use?", + "entrypoint": "start", + "expected_candidates": [], + "reviewed_answer": "Ask who accepts changes, what must survive restart, whether writers can conflict and what may be retained.", + "prohibited_claim": "Picking a universal state architecture without context.", + "boundary": "Underspecified; do not infer that either core sequence applies.", + "review_result": "pass-with-stated-limits", + "reviewer": "Codex author-model", + "independent_human": false + }, + { + "id": "D08", + "query": "Give me a complete secure collaborative editor with guaranteed real-time latency.", + "entrypoint": "start", + "expected_candidates": [], + "reviewed_answer": "State that full collaborative/security/latency design is outside the supported core and identify the missing domain evidence.", + "prohibited_claim": "Assembling extension names into a certified complete architecture.", + "boundary": "Unsupported need; request a narrower brief and additional evidence.", + "review_result": "pass-with-stated-limits", + "reviewer": "Codex author-model", + "independent_human": false + } + ] +} diff --git a/reference/0.1/index.json b/reference/0.1/index.json new file mode 100644 index 0000000..1310791 --- /dev/null +++ b/reference/0.1/index.json @@ -0,0 +1,1324 @@ +{ + "schema_version": 1, + "version": "0.1", + "status": "research-preview", + "corpus_revision": "8cc7016e1fbcb08b670091a174672fcdd8d07640", + "candidates": [ + { + "id": "CAND-0001", + "path": "research/candidates/ConflictCopy.md", + "title": "Conflict Copy", + "sha256": "24f250d89ac17d96df287d67c275b5320b48c8356b57ae126a6c941e92a1c6e9", + "status": "draft", + "maturity": "hypothesis", + "decision": "Preserve competing versions instead of silently losing one.", + "evidence": [ + { + "kind": "documentary", + "family": "Joplin", + "ref": "research/reviews/LocalFirstEvidenceExpansion.md", + "scope": "Documented detected-note conflict copy." + }, + { + "kind": "documentary", + "family": "Obsidian", + "ref": "research/reviews/LocalFirstEvidenceExpansion.md", + "scope": "Optional conflict-file mode, not default behavior." + } + ], + "independent_full_contract_uses": null, + "review": { + "assessed_at": "2026-09-26", + "reviewer": "Codex", + "role": "author-model", + "independent_human": false, + "last_substantive_review_date": null + }, + "gaps": [ + "Authorized retention and export are separate decisions.", + "Complete contract recurrence and fault-tested deployed behavior remain unverified." + ], + "superseded_by": [], + "subset": "core", + "classification": { + "path": "research/candidates/ConflictCopy.md", + "sha256": "24f250d89ac17d96df287d67c275b5320b48c8356b57ae126a6c941e92a1c6e9", + "title": "Conflict Copy", + "responsibilities": [ + "reconciliation" + ], + "forces": { + "improves": [ + "recoverability", + "information-completeness" + ], + "worsens": [ + "cognitive-load", + "reconciliation-complexity" + ] + }, + "rationale": "Preserves divergent content for later semantic resolution; unresolved copies impose review and merge work." + }, + "classification_status": "provisional author-model interpretation", + "families": [ + "synchronization" + ], + "scales": [ + "L2", + "L6" + ] + }, + { + "id": "CAND-0002", + "path": "research/candidates/LocalCommitBoundary.md", + "title": "Local Commit Boundary", + "sha256": "22165fc2979e8f4d8859b34417cb71e7b5ec7a8440ad045aee2383d499648013", + "status": "draft", + "maturity": "hypothesis", + "decision": "Define when a local change is durably accepted.", + "evidence": [ + { + "kind": "documentary", + "family": "Ink & Switch", + "ref": "research/reviews/LocalFirstEvidenceExpansion.md", + "scope": "Local-first motivation." + }, + { + "kind": "documentary", + "family": "Joplin", + "ref": "research/reviews/LocalFirstEvidenceExpansion.md", + "scope": "Local storage and synchronization architecture." + } + ], + "independent_full_contract_uses": null, + "review": { + "assessed_at": "2026-09-26", + "reviewer": "Codex", + "role": "author-model", + "independent_human": false, + "last_substantive_review_date": null + }, + "gaps": [ + "No executed storage crash or backup test.", + "Local acceptance is not off-device recovery." + ], + "superseded_by": [], + "subset": "core", + "classification": { + "path": "research/candidates/LocalCommitBoundary.md", + "sha256": "22165fc2979e8f4d8859b34417cb71e7b5ec7a8440ad045aee2383d499648013", + "title": "Local Commit Boundary", + "responsibilities": [ + "authority", + "mutation" + ], + "forces": { + "improves": [ + "recoverability", + "offline-usability" + ], + "worsens": [ + "implementation-complexity", + "perceived-responsiveness" + ] + }, + "rationale": "Defines acknowledged local acceptance separately from visual input; atomic persistence and waiting for completion add cost." + }, + "classification_status": "provisional author-model interpretation", + "families": [ + "mutation", + "authority" + ], + "scales": [ + "L2", + "L6" + ] + }, + { + "id": "CAND-0003", + "path": "research/candidates/PendingSynchronization.md", + "title": "Pending Synchronization", + "sha256": "9c5cb0f4ea4e6f4406ce55513ca2c252172427a49d8280ae1a9c713f1d11b070", + "status": "draft", + "maturity": "hypothesis", + "decision": "Keep accepted local intent visible until synchronization resolves.", + "evidence": [ + { + "kind": "documentary", + "family": "Joplin", + "ref": "research/reviews/LocalFirstEvidenceExpansion.md", + "scope": "Per-item synchronization metadata." + } + ], + "independent_full_contract_uses": null, + "review": { + "assessed_at": "2026-09-26", + "reviewer": "Codex", + "role": "author-model", + "independent_human": false, + "last_substantive_review_date": null + }, + "gaps": [ + "Atomic supersession and retry contract proposed, not storage-tested." + ], + "superseded_by": [], + "subset": "core", + "classification": { + "path": "research/candidates/PendingSynchronization.md", + "sha256": "9c5cb0f4ea4e6f4406ce55513ca2c252172427a49d8280ae1a9c713f1d11b070", + "title": "Pending Synchronization", + "responsibilities": [ + "synchronization" + ], + "forces": { + "improves": [ + "offline-usability", + "recoverability" + ], + "worsens": [ + "freshness", + "reconciliation-complexity" + ] + }, + "rationale": "Keeps locally accepted work queued across disconnection; remote freshness is delayed and retry/reconciliation contracts are required." + }, + "classification_status": "provisional author-model interpretation", + "families": [ + "synchronization" + ], + "scales": [ + "L2", + "L6" + ] + }, + { + "id": "CAND-0004", + "path": "research/candidates/ExplicitReconciliation.md", + "title": "Explicit Reconciliation", + "sha256": "d48a40aab7417b8b8f8406094c84b9e90d0ca8c2f94d6e616d0b80499dc04959", + "status": "draft", + "maturity": "hypothesis", + "decision": "Resolve divergent content while retaining provenance.", + "evidence": [ + { + "kind": "documentary", + "family": "Joplin", + "ref": "research/reviews/LocalFirstEvidenceExpansion.md", + "scope": "Documented manual conflict resolution." + }, + { + "kind": "documentary", + "family": "Obsidian", + "ref": "research/reviews/LocalFirstEvidenceExpansion.md", + "scope": "Conflict comparison workflow." + } + ], + "independent_full_contract_uses": null, + "review": { + "assessed_at": "2026-09-26", + "reviewer": "Codex", + "role": "author-model", + "independent_human": false, + "last_substantive_review_date": null + }, + "gaps": [ + "Atomic resolution/provenance UI not executed.", + "Overlap with Conflict Copy remains an open merge question." + ], + "superseded_by": [], + "subset": "core", + "classification": { + "path": "research/candidates/ExplicitReconciliation.md", + "sha256": "d48a40aab7417b8b8f8406094c84b9e90d0ca8c2f94d6e616d0b80499dc04959", + "title": "Explicit Reconciliation", + "responsibilities": [ + "reconciliation", + "affordance" + ], + "forces": { + "improves": [ + "information-completeness", + "recoverability" + ], + "worsens": [ + "cognitive-load", + "continuity-of-interaction" + ] + }, + "rationale": "Makes semantic resolution an explicit comparison task; deciding among versions interrupts ordinary work." + }, + "classification_status": "provisional author-model interpretation", + "families": [ + "synchronization", + "affordance" + ], + "scales": [ + "L2", + "L6" + ] + }, + { + "id": "CAND-0005", + "path": "research/candidates/LocalDraftState.md", + "title": "Local Draft State", + "sha256": "8e5f427975c76083c80b895bc68b7130b249be5129c2854f3df11cc374b4b240", + "status": "draft", + "maturity": "hypothesis", + "decision": "Separate unfinished intent from refreshed authoritative data.", + "evidence": [ + { + "kind": "documentary", + "family": "Kubernetes / GitLab / React Router", + "ref": "research/reviews/TransactionalEvidenceExpansion.md", + "scope": "Rejection and pending-input mechanisms motivate recovery." + }, + { + "kind": "static-code", + "family": "Zulip", + "ref": "research/reviews/FrontendRecoveryImplementations.md", + "scope": "Pinned composer draft storage; partial lifecycle." + }, + { + "kind": "static-code", + "family": "Element / Matrix", + "ref": "research/reviews/FrontendRecoveryImplementations.md", + "scope": "Pinned composer draft restoration; partial lifecycle." + }, + { + "kind": "runtime", + "family": "authored release fixture", + "ref": "research/reviews/ActivationConflictsAndReload.md", + "scope": "Same-tab preservation/refusal/discard and post-navigation schema check." + } + ], + "independent_full_contract_uses": null, + "review": { + "assessed_at": "2026-09-26", + "reviewer": "Codex", + "role": "author-model", + "independent_human": false, + "last_substantive_review_date": null + }, + "gaps": [ + "No native-unload, crash, multiple-tab or access-revocation guarantee.", + "Full base/draft/current merge contract is not verified in deployed frontends." + ], + "superseded_by": [], + "subset": "core", + "classification": { + "path": "research/candidates/LocalDraftState.md", + "sha256": "8e5f427975c76083c80b895bc68b7130b249be5129c2854f3df11cc374b4b240", + "title": "Local Draft State", + "responsibilities": [ + "affordance", + "mutation" + ], + "forces": { + "improves": [ + "recoverability", + "continuity-of-interaction" + ], + "worsens": [ + "implementation-complexity", + "privacy" + ] + }, + "rationale": "Preserves editable intent separately from refreshed observations; lifetime management adds complexity and sensitive-data retention risk." + }, + "classification_status": "provisional author-model interpretation", + "families": [ + "affordance", + "mutation" + ], + "scales": [ + "L6" + ] + }, + { + "id": "CAND-0006", + "path": "research/candidates/VersionCheckedMutation.md", + "title": "Version-Checked Mutation", + "sha256": "6a3335ae2fa1de51c95dcbfa8d766d988a3f7a9604fb608b8a0bcf9a10b64198", + "status": "draft", + "maturity": "hypothesis", + "decision": "Reject an operation whose observed base is stale.", + "evidence": [ + { + "kind": "documentary", + "family": "Kubernetes", + "ref": "research/reviews/TransactionalEvidenceExpansion.md", + "scope": "Conditional PUT; precise version mechanism." + }, + { + "kind": "documentary", + "family": "GitLab", + "ref": "research/reviews/TransactionalEvidenceExpansion.md", + "scope": "Optional last_commit_id; different failure surface." + }, + { + "kind": "runtime", + "family": "authored release fixture", + "ref": "research/reviews/ActivationConflictsAndReload.md", + "scope": "Related conditional activation-map mechanism in one process, not the full frontend pattern." + } + ], + "independent_full_contract_uses": null, + "review": { + "assessed_at": "2026-09-26", + "reviewer": "Codex", + "role": "author-model", + "independent_human": false, + "last_substantive_review_date": null + }, + "gaps": [ + "Distributed atomicity and complete frontend recurrence remain unverified.", + "Refetch does not authorize overwriting conflicting intent." + ], + "superseded_by": [], + "subset": "core", + "classification": { + "path": "research/candidates/VersionCheckedMutation.md", + "sha256": "6a3335ae2fa1de51c95dcbfa8d766d988a3f7a9604fb608b8a0bcf9a10b64198", + "title": "Version-Checked Mutation", + "responsibilities": [ + "authority", + "mutation", + "reconciliation" + ], + "forces": { + "improves": [ + "authoritative-consistency" + ], + "worsens": [ + "cognitive-load" + ] + }, + "rationale": "Checks stale bases at commit and exposes rejected proposals for reconsideration; contention adds repeated user review." + }, + "classification_status": "provisional author-model interpretation", + "families": [ + "mutation", + "authority" + ], + "scales": [ + "L2", + "L6" + ] + }, + { + "id": "CAND-0007", + "path": "research/candidates/MutationOutcomeTracking.md", + "title": "Mutation Outcome Tracking", + "sha256": "e04cb835fd054bfaf88616375bd0262deffb2801ea04105be92543bfa9582179", + "status": "draft", + "maturity": "hypothesis", + "decision": "Retain operation identity when transport outcome is uncertain.", + "evidence": [ + { + "kind": "documentary", + "family": "Stripe", + "ref": "research/reviews/TransactionalEvidenceExpansion.md", + "scope": "Idempotency mechanism." + }, + { + "kind": "documentary", + "family": "React Router", + "ref": "research/reviews/TransactionalEvidenceExpansion.md", + "scope": "Cancellation does not imply server rollback." + }, + { + "kind": "static-code", + "family": "Zulip", + "ref": "research/reviews/FrontendRecoveryImplementations.md", + "scope": "Pinned send/recovery state." + }, + { + "kind": "static-code", + "family": "Element / Matrix", + "ref": "research/reviews/FrontendRecoveryImplementations.md", + "scope": "Pinned client and SDK transaction/echo paths." + }, + { + "kind": "runtime", + "family": "Element / Matrix", + "ref": "research/reviews/MatrixRecoveryExperiment.md", + "scope": "Real SDK with synthetic transport: lost acknowledgement, identity reuse and authoritative echo." + } + ], + "independent_full_contract_uses": null, + "review": { + "assessed_at": "2026-09-26", + "reviewer": "Codex", + "role": "author-model", + "independent_human": false, + "last_substantive_review_date": null + }, + "gaps": [ + "No production server deduplication or complete retention-window guarantee.", + "Cancelling local UI is not remote compensation." + ], + "superseded_by": [], + "subset": "core", + "classification": { + "path": "research/candidates/MutationOutcomeTracking.md", + "sha256": "e04cb835fd054bfaf88616375bd0262deffb2801ea04105be92543bfa9582179", + "title": "Mutation Outcome Tracking", + "responsibilities": [ + "mutation", + "reconciliation" + ], + "forces": { + "improves": [ + "recoverability", + "information-completeness" + ], + "worsens": [ + "implementation-complexity" + ] + }, + "rationale": "Tracks uncertain write outcomes and resolves them through receipt lookup or bounded replay; identity/retention state adds cost." + }, + "classification_status": "provisional author-model interpretation", + "families": [ + "mutation", + "synchronization" + ], + "scales": [ + "L2", + "L6" + ] + }, + { + "id": "CAND-0008", + "path": "research/candidates/InvalidateAndReproject.md", + "title": "Invalidate and Reproject", + "sha256": "47c405adbc3caac2383768ed3d30b6a2e7ff1f44f4954c340049e78944227844", + "status": "draft", + "maturity": "hypothesis", + "decision": "Refresh a projection after mutation without equating acceptance and visibility.", + "evidence": [ + { + "kind": "documentary", + "family": "React Router", + "ref": "research/reviews/TransactionalEvidenceExpansion.md", + "scope": "Concurrency and pending-state guidance." + } + ], + "independent_full_contract_uses": null, + "review": { + "assessed_at": "2026-09-26", + "reviewer": "Codex", + "role": "author-model", + "independent_human": false, + "last_substantive_review_date": null + }, + "gaps": [ + "Read-your-write and acceptance/refresh distinction still proposed.", + "No independent deployed full-contract observation." + ], + "superseded_by": [], + "subset": "core", + "classification": { + "path": "research/candidates/InvalidateAndReproject.md", + "sha256": "47c405adbc3caac2383768ed3d30b6a2e7ff1f44f4954c340049e78944227844", + "title": "Invalidate and Reproject", + "responsibilities": [ + "synchronization", + "projection" + ], + "forces": { + "improves": [ + "freshness" + ], + "worsens": [ + "bandwidth-cost", + "cache-invalidation-complexity" + ] + }, + "rationale": "Refreshes affected observations after accepted writes; scope and ordering of network/cache work need explicit management." + }, + "classification_status": "provisional author-model interpretation", + "families": [ + "projection", + "synchronization" + ], + "scales": [ + "L3", + "L6" + ] + }, + { + "id": "CAND-0009", + "path": "research/candidates/URLAddressableState.md", + "title": "URL-addressable State", + "sha256": "07d524c3c0dd080bd42ff5dd79a36e6ecd2a8654f07ece880b483477f7ca4497", + "status": "draft", + "maturity": "hypothesis", + "decision": "Make a navigable state reconstructible from its URL.", + "evidence": [ + { + "kind": "documentary", + "family": "htmx", + "ref": "research/reviews/NavigationRenderingEvidence.md", + "scope": "History behavior and history-cache misses." + }, + { + "kind": "documentary", + "family": "Web platform", + "ref": "research/reviews/NavigationRenderingEvidence.md", + "scope": "pushState changes history, not server dereferenceability." + }, + { + "kind": "runtime", + "family": "htmx in authored public-catalog fixture", + "ref": "research/reviews/NavigationHistoryExperiment.md", + "scope": "NH01\u2013NH06: native/enhanced routes, history hit/miss, actual browser cache ordering and missing-Vary negative control; explicit Node validator checks separate." + }, + { + "kind": "runtime", + "family": "htmx in authored public-catalog fixture", + "ref": "research/reviews/NavigationOwnershipExperiment.md", + "scope": "NO01\u2013NO06: ordered history/success/error races, prior policy 0/12 full obligations versus guarded 12/12; separate focus ownership. Same fixture family; pinned history-XHR adapter." + }, + { + "kind": "static-code", + "family": "Zulip", + "ref": "research/reviews/ZulipNavigationSourceStudy.md", + "scope": "ZN01\u2013ZN08 at pinned revision: partial hash/list/cache mechanisms and non-modal continuation contrast. No application/test execution, no no-script claim, no complete pattern recurrence." + } + ], + "independent_full_contract_uses": null, + "review": { + "assessed_at": "2026-09-27", + "reviewer": "Codex", + "role": "author-model", + "independent_human": false, + "last_substantive_review_date": "2026-09-27" + }, + "gaps": [ + "Independent application recurrence and human/AT validation remain unverified.", + "Pending history disclosure, multiple history misses, redirects, nonzero swap delays, bfcache, lifecycle cleanup, interrupted/late enhancement and offline availability remain open.", + "Zulip auxiliary target/anchor callbacks, deferred editing focus and search callback wiring remain unverified; static guards do not prove whole-application ownership." + ], + "superseded_by": [], + "subset": "extension", + "classification": { + "path": "research/candidates/URLAddressableState.md", + "sha256": "07d524c3c0dd080bd42ff5dd79a36e6ecd2a8654f07ece880b483477f7ca4497", + "title": "URL-addressable State", + "responsibilities": [ + "address" + ], + "forces": { + "improves": [ + "addressability" + ], + "worsens": [ + "privacy", + "compatibility-pressure" + ] + }, + "rationale": "Makes selected views reconstructible from addresses; exposure and evolving URL contracts constrain what can be encoded." + }, + "classification_status": "provisional author-model interpretation", + "families": [ + "address", + "projection" + ], + "scales": [ + "L3" + ] + }, + { + "id": "CAND-0010", + "path": "research/candidates/ProgressiveEnhancement.md", + "title": "Progressive Enhancement", + "sha256": "1dc3885ef896b9a7cb61af11fa8893484eb1e13454207326abc7250d5ca4382b", + "status": "draft", + "maturity": "hypothesis", + "decision": "Keep essential actions usable when enhancement is unavailable.", + "evidence": [ + { + "kind": "documentary", + "family": "htmx", + "ref": "research/reviews/NavigationRenderingEvidence.md", + "scope": "Boosted links and forms." + }, + { + "kind": "documentary", + "family": "SvelteKit", + "ref": "research/reviews/NavigationRenderingEvidence.md", + "scope": "Form actions and rendering/page options." + }, + { + "kind": "runtime", + "family": "htmx in authored public-catalog fixture", + "ref": "research/reviews/NavigationHistoryExperiment.md", + "scope": "NH01\u2013NH06: native/enhanced routes, history hit/miss, actual browser cache ordering and missing-Vary negative control; explicit Node validator checks separate." + }, + { + "kind": "runtime", + "family": "htmx in authored public-catalog fixture", + "ref": "research/reviews/NavigationFocusExperiment.md", + "scope": "NF01\u2013NF06: Tab/Enter navigation, raw versus authored focus/status policy, held-response ownership and background update; DOM evidence only, not AT speech." + }, + { + "kind": "runtime", + "family": "htmx in authored public-catalog fixture", + "ref": "research/reviews/NavigationOwnershipExperiment.md", + "scope": "NO01\u2013NO06: ordered history/success/error races, prior policy 0/12 full obligations versus guarded 12/12; separate focus ownership. Same fixture family; pinned history-XHR adapter." + }, + { + "kind": "static-code", + "family": "Zulip", + "ref": "research/reviews/ZulipNavigationSourceStudy.md", + "scope": "ZN01\u2013ZN08 at pinned revision: partial hash/list/cache mechanisms and non-modal continuation contrast. No application/test execution, no no-script claim, no complete pattern recurrence." + } + ], + "independent_full_contract_uses": null, + "review": { + "assessed_at": "2026-09-27", + "reviewer": "Codex", + "role": "author-model", + "independent_human": false, + "last_substantive_review_date": "2026-09-27" + }, + "gaps": [ + "Independent application recurrence and human/AT validation remain unverified.", + "Pending history disclosure, multiple history misses, redirects, nonzero swap delays, bfcache, lifecycle cleanup, interrupted/late enhancement and offline availability remain open.", + "Zulip auxiliary target/anchor callbacks, deferred editing focus and search callback wiring remain unverified; static guards do not prove whole-application ownership." + ], + "superseded_by": [], + "subset": "extension", + "classification": { + "path": "research/candidates/ProgressiveEnhancement.md", + "sha256": "1dc3885ef896b9a7cb61af11fa8893484eb1e13454207326abc7250d5ca4382b", + "title": "Progressive Enhancement", + "responsibilities": [ + "execution", + "affordance" + ], + "forces": { + "improves": [ + "recoverability" + ], + "worsens": [ + "implementation-complexity" + ] + }, + "rationale": "Preserves an essential baseline when optional scripts fail; equivalent task semantics and recovery across paths add design work." + }, + "classification_status": "provisional author-model interpretation", + "families": [ + "quality", + "execution", + "affordance" + ], + "scales": [ + "L3", + "L6" + ] + }, + { + "id": "CAND-0011", + "path": "research/candidates/PresentationModel.md", + "title": "Presentation Model", + "sha256": "5ff03b5799b0a9e5ec6b54b21034720d89dbc8ffde7c4cdcf71616cdf57baf49", + "status": "draft", + "maturity": "hypothesis", + "decision": "Separate presentation decisions from view mechanisms.", + "evidence": [ + { + "kind": "documentary", + "family": "Fowler", + "ref": "research/reviews/PatternBreadthExpansion.md", + "scope": "Named pattern and illustrative model/view discussion." + } + ], + "independent_full_contract_uses": null, + "review": { + "assessed_at": "2026-09-26", + "reviewer": "Codex", + "role": "author-model", + "independent_human": false, + "last_substantive_review_date": null + }, + "gaps": [ + "No executed model/view integration or independently reviewed full-contract use." + ], + "superseded_by": [], + "subset": "extension", + "classification": { + "path": "research/candidates/PresentationModel.md", + "sha256": "5ff03b5799b0a9e5ec6b54b21034720d89dbc8ffde7c4cdcf71616cdf57baf49", + "title": "Presentation Model", + "responsibilities": [ + "projection", + "affordance" + ], + "forces": { + "improves": [ + "testability", + "portability" + ], + "worsens": [ + "implementation-complexity" + ] + }, + "rationale": "Separates presentation decisions from widget APIs; model/view binding and synchronization add a failure surface." + }, + "classification_status": "provisional author-model interpretation", + "families": [ + "composition", + "affordance" + ], + "scales": [ + "L4", + "L6" + ] + }, + { + "id": "CAND-0012", + "path": "research/candidates/DerivedState.md", + "title": "Derived State", + "sha256": "9f29b9f1296a52b83f08dfd97437c4dc16e4949ddac1ff3b3830e3fc9831bd4f", + "status": "draft", + "maturity": "hypothesis", + "decision": "Compute a result from explicit authoritative inputs.", + "evidence": [ + { + "kind": "documentary", + "family": "Redux", + "ref": "research/reviews/PatternBreadthExpansion.md", + "scope": "Selector guidance, not a requirement for a global store." + } + ], + "independent_full_contract_uses": null, + "review": { + "assessed_at": "2026-09-26", + "reviewer": "Codex", + "role": "author-model", + "independent_human": false, + "last_substantive_review_date": null + }, + "gaps": [ + "Snapshot coherence and changed-locale cache test still planned." + ], + "superseded_by": [], + "subset": "extension", + "classification": { + "path": "research/candidates/DerivedState.md", + "sha256": "9f29b9f1296a52b83f08dfd97437c4dc16e4949ddac1ff3b3830e3fc9831bd4f", + "title": "Derived State", + "responsibilities": [ + "projection" + ], + "forces": { + "improves": [ + "authoritative-consistency" + ], + "worsens": [ + "client-compute-cost", + "cache-invalidation-complexity" + ] + }, + "rationale": "Projects coherent inputs without separately mutable derived copies; recomputation and cached dependency tracking cost work." + }, + "classification_status": "provisional author-model interpretation", + "families": [ + "projection", + "affordance" + ], + "scales": [ + "L3", + "L6" + ] + }, + { + "id": "CAND-0013", + "path": "research/candidates/VerticalFeatureSlice.md", + "title": "Vertical Feature Slice", + "sha256": "d6b332b9c104a079bd4b72512b8ddd1a889199b2e2e531753c411688053e647a", + "status": "draft", + "maturity": "hypothesis", + "decision": "Group a capability across UI, state and behavior with explicit interfaces.", + "evidence": [ + { + "kind": "documentary", + "family": "Feature-Sliced Design", + "ref": "research/reviews/PatternBreadthExpansion.md", + "scope": "Layer/slice and public-interface guidance." + }, + { + "kind": "static-code", + "family": "Feature-Sliced Design", + "ref": "research/reviews/FeatureDeploymentBoundaries.md", + "scope": "Pinned todo-app interfaces coexist with one application build." + } + ], + "independent_full_contract_uses": null, + "review": { + "assessed_at": "2026-09-26", + "reviewer": "Codex", + "role": "author-model", + "independent_human": false, + "last_substantive_review_date": null + }, + "gaps": [ + "Build/import enforcement not executed.", + "Feature organization does not establish independent activation." + ], + "superseded_by": [], + "subset": "extension", + "classification": { + "path": "research/candidates/VerticalFeatureSlice.md", + "sha256": "d6b332b9c104a079bd4b72512b8ddd1a889199b2e2e531753c411688053e647a", + "title": "Vertical Feature Slice", + "responsibilities": [ + "composition" + ], + "forces": { + "improves": [ + "feature-change-frequency" + ], + "worsens": [ + "implementation-complexity" + ] + }, + "rationale": "Localizes a capability change behind an interface; shared concepts and interfaces require maintenance. Benefit means coping with frequent changes, not changing their frequency." + }, + "classification_status": "provisional author-model interpretation", + "families": [ + "composition" + ], + "scales": [ + "L4" + ] + }, + { + "id": "CAND-0014", + "path": "research/candidates/IslandsOfInteractivity.md", + "title": "Islands of Interactivity", + "sha256": "821a1497da10c02ae11fa6f56cb8e205a4f32c40b39770ab8ca3f907561a260a", + "status": "draft", + "maturity": "hypothesis", + "decision": "Activate selected interactive regions within a document.", + "evidence": [ + { + "kind": "documentary", + "family": "Astro", + "ref": "research/reviews/PatternBreadthExpansion.md", + "scope": "Client-island mechanism and execution placement." + } + ], + "independent_full_contract_uses": null, + "review": { + "assessed_at": "2026-09-26", + "reviewer": "Codex", + "role": "author-model", + "independent_human": false, + "last_substantive_review_date": null + }, + "gaps": [ + "No executed island fixture, performance comparison or complete recurrence study." + ], + "superseded_by": [], + "subset": "extension", + "classification": { + "path": "research/candidates/IslandsOfInteractivity.md", + "sha256": "821a1497da10c02ae11fa6f56cb8e205a4f32c40b39770ab8ca3f907561a260a", + "title": "Islands of Interactivity", + "responsibilities": [ + "projection", + "execution" + ], + "forces": { + "improves": [ + "client-compute-cost" + ], + "worsens": [ + "implementation-complexity" + ] + }, + "rationale": "Scopes activation to selected regions; intended compute savings compete with loading and inter-region coordination. Savings require measurement." + }, + "classification_status": "provisional author-model interpretation", + "families": [ + "projection", + "execution" + ], + "scales": [ + "L3", + "L5" + ] + }, + { + "id": "CAND-0015", + "path": "research/candidates/FailureBoundary.md", + "title": "Failure Boundary", + "sha256": "a6e76ed17a92baade683d5df96fa8ecd066c593661e6a14983a86d046e7d9c2c", + "status": "draft", + "maturity": "hypothesis", + "decision": "Contain specified failure classes while preserving useful neighboring work.", + "evidence": [ + { + "kind": "documentary", + "family": "React", + "ref": "research/reviews/PatternBreadthExpansion.md", + "scope": "Error boundary scope and exclusions." + }, + { + "kind": "runtime", + "family": "React", + "ref": "research/reviews/BoundaryRecoveryExperiment.md", + "scope": "Real package in authored host: render/event/request distinction and fallback escalation." + } + ], + "independent_full_contract_uses": null, + "review": { + "assessed_at": "2026-09-26", + "reviewer": "Codex", + "role": "author-model", + "independent_human": false, + "last_substantive_review_date": null + }, + "gaps": [ + "Synthetic host, not full application recurrence.", + "Boundary cannot imply containment for all asynchronous failures." + ], + "superseded_by": [], + "subset": "extension", + "classification": { + "path": "research/candidates/FailureBoundary.md", + "sha256": "a6e76ed17a92baade683d5df96fa8ecd066c593661e6a14983a86d046e7d9c2c", + "title": "Failure Boundary", + "responsibilities": [ + "composition", + "affordance" + ], + "forces": { + "improves": [ + "fault-containment", + "continuity-of-interaction" + ], + "worsens": [ + "implementation-complexity" + ] + }, + "rationale": "Contains declared failures and supplies recovery interaction; partial-state recovery and escalation add complexity." + }, + "classification_status": "provisional author-model interpretation", + "families": [ + "quality", + "composition" + ], + "scales": [ + "L5", + "L6" + ] + }, + { + "id": "CAND-0016", + "path": "research/candidates/FocusReturn.md", + "title": "Focus Return", + "sha256": "9149c2f563eafcfec983a9285949225840d97804568309bd16bbb1eb6b3dde77", + "status": "draft", + "maturity": "hypothesis", + "decision": "Restore meaningful focus after a temporary interaction ends.", + "evidence": [ + { + "kind": "documentary", + "family": "WAI-ARIA APG", + "ref": "research/reviews/PatternBreadthExpansion.md", + "scope": "Dialog focus obligations." + }, + { + "kind": "static-code", + "family": "Radix", + "ref": "research/reviews/NestedDismissalIsolation.md", + "scope": "Pinned layer/listener ownership implementation." + }, + { + "kind": "runtime", + "family": "Radix", + "ref": "research/reviews/NestedOwnershipRouting.md", + "scope": "Authored fixture: raw 20/24 versus routed 24/24; browser/build limits retained." + }, + { + "kind": "runtime", + "family": "htmx in authored public-catalog fixture", + "ref": "research/reviews/NavigationFocusExperiment.md", + "scope": "NF01\u2013NF06: Tab/Enter navigation, raw versus authored focus/status policy, held-response ownership and background update; DOM evidence only, not AT speech." + }, + { + "kind": "runtime", + "family": "htmx in authored public-catalog fixture", + "ref": "research/reviews/NavigationOwnershipExperiment.md", + "scope": "NO01\u2013NO06: ordered history/success/error races, prior policy 0/12 full obligations versus guarded 12/12; separate focus ownership. Same fixture family; pinned history-XHR adapter." + }, + { + "kind": "static-code", + "family": "Zulip", + "ref": "research/reviews/ZulipNavigationSourceStudy.md", + "scope": "ZN01\u2013ZN08 at pinned revision: partial hash/list/cache mechanisms and non-modal continuation contrast. No application/test execution, no no-script claim, no complete pattern recurrence." + } + ], + "independent_full_contract_uses": null, + "review": { + "assessed_at": "2026-09-27", + "reviewer": "Codex", + "role": "author-model", + "independent_human": false, + "last_substantive_review_date": "2026-09-27" + }, + "gaps": [ + "One implementation family; repeated trials are not independent uses.", + "Animated exits and competing owners remain untested; no production repair claim.", + "Route ownership is a contrast, not independent modal recurrence; AT speech and broader history/lifecycle cases remain unverified.", + "Zulip auxiliary target/anchor callbacks, deferred editing focus and search callback wiring remain unverified; static guards do not prove whole-application ownership." + ], + "superseded_by": [], + "subset": "extension", + "classification": { + "path": "research/candidates/FocusReturn.md", + "sha256": "9149c2f563eafcfec983a9285949225840d97804568309bd16bbb1eb6b3dde77", + "title": "Focus Return", + "responsibilities": [ + "affordance" + ], + "forces": { + "improves": [ + "continuity-of-interaction", + "accessibility" + ], + "worsens": [ + "implementation-complexity" + ] + }, + "rationale": "Restores a meaningful keyboard continuation; disappearing targets and nested ownership require lifecycle handling." + }, + "classification_status": "provisional author-model interpretation", + "families": [ + "quality", + "affordance" + ], + "scales": [ + "L6" + ] + }, + { + "id": "CAND-0017", + "path": "research/candidates/IndependentFeatureBoundary.md", + "title": "Independent Feature Boundary", + "sha256": "60b78725ed4036681675d4c68244fc25aea6e0dffb09d54a7108e3fcbf527b4f", + "status": "draft", + "maturity": "hypothesis", + "decision": "Separate feature release, activation and session transition contracts.", + "evidence": [ + { + "kind": "documentary", + "family": "single-spa / webpack", + "ref": "research/reviews/FeatureDeploymentBoundaries.md", + "scope": "Mechanism documentation, not deployed independence proof." + }, + { + "kind": "static-code", + "family": "react-microfrontends examples", + "ref": "research/reviews/FeatureDeploymentBoundaries.md", + "scope": "Root config/navbar are one example family with shared startup gating." + }, + { + "kind": "runtime", + "family": "authored release fixture", + "ref": "research/reviews/FeatureReleaseExperiment.md", + "scope": "Publication/activation/rollback across fresh, loaded and lazy sessions." + }, + { + "kind": "runtime", + "family": "authored release fixture", + "ref": "research/reviews/ActivationConflictsAndReload.md", + "scope": "Conditional activation updates and safe reload policies, including negative controls." + } + ], + "independent_full_contract_uses": null, + "review": { + "assessed_at": "2026-09-26", + "reviewer": "Codex", + "role": "author-model", + "independent_human": false, + "last_substantive_review_date": null + }, + "gaps": [ + "No upstream deployment or real team/release-independence validation.", + "Distributed atomicity, retention authorization and native-unload/crash behavior remain open." + ], + "superseded_by": [], + "subset": "extension", + "classification": { + "path": "research/candidates/IndependentFeatureBoundary.md", + "sha256": "60b78725ed4036681675d4c68244fc25aea6e0dffb09d54a7108e3fcbf527b4f", + "title": "Independent Feature Boundary", + "responsibilities": [ + "composition", + "execution" + ], + "forces": { + "improves": [ + "independent-deployability", + "team-autonomy" + ], + "worsens": [ + "compatibility-pressure", + "deployment-complexity" + ] + }, + "rationale": "Separates release and activation through composition contracts; version compatibility and session transitions add obligations." + }, + "classification_status": "provisional author-model interpretation", + "families": [ + "composition", + "execution" + ], + "scales": [ + "L1", + "L4" + ] + } + ], + "relations": [ + { + "source": "CAND-0002", + "type": "enables", + "target": "CAND-0003", + "status": "proposed", + "condition": "The local transaction records a revision and its pending propagation atomically.", + "rationale": "A recoverable origin allows pending work to resume after restart.", + "evidence_kind": "editorial-design-proposal", + "evidence_refs": [ + "research/candidates/LocalCommitBoundary.md", + "research/candidates/PendingSynchronization.md" + ], + "unknown": "No independent validation of this relation as a complete architectural contract." + }, + { + "source": "CAND-0003", + "type": "creates-context-for", + "target": "CAND-0001", + "status": "proposed", + "condition": "Detected divergence requires retained alternatives and policy permits retention.", + "rationale": "Pending propagation can expose competing versions; not every synchronization needs a copy.", + "evidence_kind": "editorial-design-proposal", + "evidence_refs": [ + "research/candidates/PendingSynchronization.md", + "research/candidates/ConflictCopy.md" + ], + "unknown": "No independent validation of this relation as a complete architectural contract." + }, + { + "source": "CAND-0001", + "type": "creates-context-for", + "target": "CAND-0004", + "status": "proposed", + "condition": "Preserved content remains semantically unresolved and a person must decide.", + "rationale": "Preservation supplies comparison material, not the resolution itself.", + "evidence_kind": "editorial-design-proposal", + "evidence_refs": [ + "research/candidates/ConflictCopy.md", + "research/candidates/ExplicitReconciliation.md" + ], + "unknown": "No independent validation of this relation as a complete architectural contract." + }, + { + "source": "CAND-0004", + "type": "enables", + "target": "CAND-0002", + "status": "proposed", + "condition": "The resolution becomes a new locally accepted revision.", + "rationale": "A chosen result still needs the local commit and pending-work contract.", + "evidence_kind": "editorial-design-proposal", + "evidence_refs": [ + "research/candidates/ExplicitReconciliation.md", + "research/candidates/LocalCommitBoundary.md" + ], + "unknown": "No independent validation of this relation as a complete architectural contract." + }, + { + "source": "CAND-0005", + "type": "complements", + "target": "CAND-0006", + "status": "proposed", + "condition": "An editable proposal uses a stale-base precondition.", + "rationale": "Keeping the proposal separate supports recovery from a rejected conditional write.", + "evidence_kind": "editorial-design-proposal", + "evidence_refs": [ + "research/candidates/LocalDraftState.md", + "research/candidates/VersionCheckedMutation.md" + ], + "unknown": "No independent validation of this relation as a complete architectural contract." + }, + { + "source": "CAND-0006", + "type": "complements", + "target": "CAND-0007", + "status": "proposed", + "condition": "A conditional write may have an uncertain transport outcome.", + "rationale": "A version precondition and an operation identity answer different questions.", + "evidence_kind": "editorial-design-proposal", + "evidence_refs": [ + "research/candidates/VersionCheckedMutation.md", + "research/candidates/MutationOutcomeTracking.md" + ], + "unknown": "No independent validation of this relation as a complete architectural contract." + }, + { + "source": "CAND-0007", + "type": "enables", + "target": "CAND-0008", + "status": "proposed", + "condition": "Acceptance is established and affected observations need refreshing.", + "rationale": "Domain acceptance can trigger refresh without treating its failure as rejected mutation.", + "evidence_kind": "editorial-design-proposal", + "evidence_refs": [ + "research/candidates/MutationOutcomeTracking.md", + "research/candidates/InvalidateAndReproject.md" + ], + "unknown": "No independent validation of this relation as a complete architectural contract." + }, + { + "source": "CAND-0008", + "type": "complements", + "target": "CAND-0005", + "status": "proposed", + "condition": "Refreshing observations can arrive while newer input exists.", + "rationale": "Separate draft ownership prevents reprojected data from replacing unfinished intent.", + "evidence_kind": "editorial-design-proposal", + "evidence_refs": [ + "research/candidates/InvalidateAndReproject.md", + "research/candidates/LocalDraftState.md" + ], + "unknown": "No independent validation of this relation as a complete architectural contract." + }, + { + "source": "CAND-0003", + "type": "complements", + "target": "CAND-0007", + "status": "proposed", + "condition": "Remote propagation acknowledgement may be lost.", + "rationale": "Locally accepted work and unknown remote receipt need separately scoped outcome evidence.", + "evidence_kind": "editorial-design-proposal", + "evidence_refs": [ + "research/candidates/PendingSynchronization.md", + "research/candidates/MutationOutcomeTracking.md" + ], + "unknown": "No independent validation of this relation as a complete architectural contract." + } + ], + "entrypoints": { + "start": "START.md", + "transactional": "sequences/TransactionalApplication.md", + "offline": "sequences/LocalFirstApplication.md", + "transactional_mapping": "technologies/TransactionalRecovery.md", + "offline_mapping": "technologies/OfflineRecovery.md" + }, + "relation_semantics": "Conditional proposals only; no inverse or transitive inference." +} diff --git a/reference/0.1/manifest.json b/reference/0.1/manifest.json new file mode 100644 index 0000000..3a04d5d --- /dev/null +++ b/reference/0.1/manifest.json @@ -0,0 +1,210 @@ +{ + "schema_version": 1, + "version": "0.1", + "status": "research-preview", + "corpus_revision": "8cc7016e1fbcb08b670091a174672fcdd8d07640", + "reviewer": { + "name": "Codex", + "role": "author-model", + "independent_human": false + }, + "core": [ + "CAND-0001", + "CAND-0002", + "CAND-0003", + "CAND-0004", + "CAND-0005", + "CAND-0006", + "CAND-0007", + "CAND-0008" + ], + "extensions": [ + "CAND-0009", + "CAND-0010", + "CAND-0011", + "CAND-0012", + "CAND-0013", + "CAND-0014", + "CAND-0015", + "CAND-0016", + "CAND-0017" + ], + "inputs": { + "research/evolution/profiles.json": "46de3b9b2d3958aff00c339741a4418fb4b5110352975b6a2fe82400d1224ee1", + "research/catalog/ClassificationCoverage.json": "8abf11676fd67fc1e726795ebf4c424d5d6fe0a3ed1fa21ea747214306b8d879", + "canon/vocabulary.yaml": "527be0a9ee774a2c795c8c883a01b6721f16667b70a4c3c9c63746d0bfd8c0aa" + }, + "entrypoints": { + "start": "START.md", + "transactional": "sequences/TransactionalApplication.md", + "offline": "sequences/LocalFirstApplication.md", + "transactional_mapping": "technologies/TransactionalRecovery.md", + "offline_mapping": "technologies/OfflineRecovery.md" + }, + "relations": [ + { + "source": "CAND-0002", + "type": "enables", + "target": "CAND-0003", + "status": "proposed", + "condition": "The local transaction records a revision and its pending propagation atomically.", + "rationale": "A recoverable origin allows pending work to resume after restart.", + "evidence_kind": "editorial-design-proposal", + "evidence_refs": [ + "research/candidates/LocalCommitBoundary.md", + "research/candidates/PendingSynchronization.md" + ], + "unknown": "No independent validation of this relation as a complete architectural contract." + }, + { + "source": "CAND-0003", + "type": "creates-context-for", + "target": "CAND-0001", + "status": "proposed", + "condition": "Detected divergence requires retained alternatives and policy permits retention.", + "rationale": "Pending propagation can expose competing versions; not every synchronization needs a copy.", + "evidence_kind": "editorial-design-proposal", + "evidence_refs": [ + "research/candidates/PendingSynchronization.md", + "research/candidates/ConflictCopy.md" + ], + "unknown": "No independent validation of this relation as a complete architectural contract." + }, + { + "source": "CAND-0001", + "type": "creates-context-for", + "target": "CAND-0004", + "status": "proposed", + "condition": "Preserved content remains semantically unresolved and a person must decide.", + "rationale": "Preservation supplies comparison material, not the resolution itself.", + "evidence_kind": "editorial-design-proposal", + "evidence_refs": [ + "research/candidates/ConflictCopy.md", + "research/candidates/ExplicitReconciliation.md" + ], + "unknown": "No independent validation of this relation as a complete architectural contract." + }, + { + "source": "CAND-0004", + "type": "enables", + "target": "CAND-0002", + "status": "proposed", + "condition": "The resolution becomes a new locally accepted revision.", + "rationale": "A chosen result still needs the local commit and pending-work contract.", + "evidence_kind": "editorial-design-proposal", + "evidence_refs": [ + "research/candidates/ExplicitReconciliation.md", + "research/candidates/LocalCommitBoundary.md" + ], + "unknown": "No independent validation of this relation as a complete architectural contract." + }, + { + "source": "CAND-0005", + "type": "complements", + "target": "CAND-0006", + "status": "proposed", + "condition": "An editable proposal uses a stale-base precondition.", + "rationale": "Keeping the proposal separate supports recovery from a rejected conditional write.", + "evidence_kind": "editorial-design-proposal", + "evidence_refs": [ + "research/candidates/LocalDraftState.md", + "research/candidates/VersionCheckedMutation.md" + ], + "unknown": "No independent validation of this relation as a complete architectural contract." + }, + { + "source": "CAND-0006", + "type": "complements", + "target": "CAND-0007", + "status": "proposed", + "condition": "A conditional write may have an uncertain transport outcome.", + "rationale": "A version precondition and an operation identity answer different questions.", + "evidence_kind": "editorial-design-proposal", + "evidence_refs": [ + "research/candidates/VersionCheckedMutation.md", + "research/candidates/MutationOutcomeTracking.md" + ], + "unknown": "No independent validation of this relation as a complete architectural contract." + }, + { + "source": "CAND-0007", + "type": "enables", + "target": "CAND-0008", + "status": "proposed", + "condition": "Acceptance is established and affected observations need refreshing.", + "rationale": "Domain acceptance can trigger refresh without treating its failure as rejected mutation.", + "evidence_kind": "editorial-design-proposal", + "evidence_refs": [ + "research/candidates/MutationOutcomeTracking.md", + "research/candidates/InvalidateAndReproject.md" + ], + "unknown": "No independent validation of this relation as a complete architectural contract." + }, + { + "source": "CAND-0008", + "type": "complements", + "target": "CAND-0005", + "status": "proposed", + "condition": "Refreshing observations can arrive while newer input exists.", + "rationale": "Separate draft ownership prevents reprojected data from replacing unfinished intent.", + "evidence_kind": "editorial-design-proposal", + "evidence_refs": [ + "research/candidates/InvalidateAndReproject.md", + "research/candidates/LocalDraftState.md" + ], + "unknown": "No independent validation of this relation as a complete architectural contract." + }, + { + "source": "CAND-0003", + "type": "complements", + "target": "CAND-0007", + "status": "proposed", + "condition": "Remote propagation acknowledgement may be lost.", + "rationale": "Locally accepted work and unknown remote receipt need separately scoped outcome evidence.", + "evidence_kind": "editorial-design-proposal", + "evidence_refs": [ + "research/candidates/PendingSynchronization.md", + "research/candidates/MutationOutcomeTracking.md" + ], + "unknown": "No independent validation of this relation as a complete architectural contract." + } + ], + "open_work": [ + { + "id": "FEP-WP-0002-T03", + "path": "workplans/FEP-WP-0002-seed-language-validation.md" + }, + { + "id": "FEP-WP-0003-T01", + "path": "workplans/FEP-WP-0003-contrasting-schools.md" + }, + { + "id": "FEP-WP-0003-T02", + "path": "workplans/FEP-WP-0003-contrasting-schools.md" + }, + { + "id": "FEP-WP-0003-T03", + "path": "workplans/FEP-WP-0003-contrasting-schools.md" + }, + { + "id": "FEP-WP-0003-T04", + "path": "workplans/FEP-WP-0003-contrasting-schools.md" + }, + { + "id": "FEP-WP-0004-T01", + "path": "workplans/FEP-WP-0004-reference-surface.md" + }, + { + "id": "FEP-WP-0004-T02", + "path": "workplans/FEP-WP-0004-reference-surface.md" + }, + { + "id": "FEP-WP-0004-T03", + "path": "workplans/FEP-WP-0004-reference-surface.md" + }, + { + "id": "FEP-WP-0006-T03", + "path": "workplans/FEP-WP-0006-language-evolution.md" + } + ] +} diff --git a/research/cases/CarniatoGrandUnifyingArchitecture.md b/research/cases/CarniatoGrandUnifyingArchitecture.md index 4996dad..c17dc88 100644 --- a/research/cases/CarniatoGrandUnifyingArchitecture.md +++ b/research/cases/CarniatoGrandUnifyingArchitecture.md @@ -23,3 +23,10 @@ responsibilities. Framework implementation claims and examples were not executed Retain Server Authority and Immediate Feedback as candidates. Do not infer a requires edge between them. Recurrence and failure behavior need further evidence. Broader architecture comparisons remain open under FEP-WP-0002-T02/T03. + +## Preview source assessment — 2026-09-27 + +The [bounded source-readiness review](../reviews/SourceReadiness-0.1.md) completes +editorial traceability assessment for WP-0002 T02. The original extraction above is +preserved; external claims were not re-fetched. Implementation/recurrence and human +validation remain open in the named successor tasks; no maturity promotion. diff --git a/research/cases/LocalFirstAuthority.md b/research/cases/LocalFirstAuthority.md index 144f2fb..a64c0df 100644 --- a/research/cases/LocalFirstAuthority.md +++ b/research/cases/LocalFirstAuthority.md @@ -42,3 +42,10 @@ uses. It supports a separate Conflict Copy candidate and distinguishes local-pri storage from globally winning every merge. Earlier fragment-only negative findings remain valid for their limited packets. Crash durability and runtime recovery remain untested; this source review is still extracted rather than fully reviewed. + +## Preview source assessment — 2026-09-27 + +The [bounded source-readiness review](../reviews/SourceReadiness-0.1.md) completes +editorial traceability assessment for WP-0002 T02. The original extraction above is +preserved; external claims were not re-fetched. Implementation/recurrence and human +validation remain open in the named successor tasks; no maturity promotion. diff --git a/research/reviews/M1-SeedReview.md b/research/reviews/M1-SeedReview.md new file mode 100644 index 0000000..15b0006 --- /dev/null +++ b/research/reviews/M1-SeedReview.md @@ -0,0 +1,66 @@ +# M1 seed review — 0.1 packaging boundary + +Reviewed 2026-09-27 by Codex, author-model. Candidate baseline `8cc7016`. +**M1 result: revise/defer; not passed.** The connected subset is suitable for a +qualified research reference preview, not canonical admission or proven usefulness. +Publication 0.1 and PatternSchema 0.1 are different version axes. + +## Gate assessment + +| M1 criterion | Outcome | Basis | +| --- | --- | --- | +| Reconciled metadata contract | pass | WP-0002 T01, vocabulary and worked contract fixtures; candidates are not full canonical-schema records | +| First source and local-first contrast | pass, scoped | [Source readiness](SourceReadiness-0.1.md); source identity and uncertainty explicit | +| 6–10 connected drafts | pass for editorial subset | CAND-0001–0008 cover local persistence/propagation/divergence and shared-record editing/recovery; selection is not a global catalog cap | +| Two completed validated walkthroughs | revise | VC-01/02 include decisions, baselines, changed constraints and failure traces, but remain synthetic with unverified implementation assumptions | +| Evidence/counterexamples | pass for traceability; defer for recurrence | Documentation, pinned code and bounded runtime mechanisms are separate evidence kinds; full-contract independence unassessed | +| Independent human validation and usefulness | defer | Frozen pilot 18/24 in each condition after model-review adjudication; no naming benefit, equivalence or decision-time result established | +| Quality and recovery guarantees | revise | Requirements for retention, keyboard recovery, receipt windows and crash boundaries are stated; complete validation absent | + +## Core editorial inspection + +All eight records were read in full. Each has context, competing forces, a proposed +solution, consequences, alternatives, evidence and explicit gaps. “Pass” below means +usable as qualified hypothesis prose; it does not mean empirical correctness or +compliance with every canonical template field. [Reference manifest](../../reference/0.1/manifest.json) +selects identities; candidate prose remains the contract source. + +| Candidate | Context and solution / resulting decision | Trade-off and alternative checked | Evidence limit / preview disposition | +| --- | --- | --- | --- | +| CAND-0001 Conflict Copy | Preserve detected divergent content separately; resolution remains pending | Recoverability versus clutter/review; immediate review or domain-aware merge instead | Joplin and optional Obsidian mechanisms, not atomic preservation proof; pass as hypothesis | +| CAND-0002 Local Commit Boundary | Acknowledge a revision and pending intent after a recoverable local commit | Offline recovery versus transaction/feedback cost; memory-only or server-required saving cannot satisfy the fixed brief | Storage motivation, no verified crash/flush contract; pass as hypothesis | +| CAND-0003 Pending Synchronization | Retain queued work and distinguish sent from acknowledged | Offline usability versus freshness/retry complexity; online-only writes are a different requirement | Joplin progress metadata, not proposed retry/supersession proof; pass as hypothesis | +| CAND-0004 Explicit Reconciliation | Compare preserved alternatives and commit a new decision | Information completeness versus interruption; justified automatic merge is an alternative | Manual comparison evidence, not provenance/atomicity/AT validation; pass, retain separately provisionally | +| CAND-0005 Local Draft State | Keep base, editable proposal and refreshed observation distinct | Recovery versus state complexity/privacy; direct binding only when no unfinished intent | Partial Zulip/Element and authored reload mechanisms, not whole lifecycle; pass as hypothesis | +| CAND-0006 Version-Checked Mutation | Check the proposal's expected version at the authority | Consistency versus repeated review; unconditional/commutative operations need their own contract | Conditional API mechanism, not complete frontend implementation; pass as hypothesis | +| CAND-0007 Mutation Outcome Tracking | Track operation-specific evidence rather than infer rejection from transport failure | Recoverability versus retention/backend cost; lookup or reconciliation when replay cannot be justified | Bounded API/SDK/source mechanisms, not universal deduplication; pass as hypothesis | +| CAND-0008 Invalidate and Reproject | Refresh affected observations after acceptance without losing drafts | Freshness versus network/invalidation work; complete authoritative response or subscription may avoid refetch | Framework documentation, no full frontend recurrence; pass as hypothesis | + +The preview links provisional relations with conditions and rationales, not mandatory +architecture dependencies. A request for globally exclusive offline approval cannot +be satisfied by combining these names. Backup, authorization and crash guarantees +remain explicit implementation obligations. + +## Retain / merge / defer + +[Preview ontology review](PreviewOntology-0.1.md) retains Conflict Copy and Explicit +Reconciliation as distinct retrieval decisions, conditionally connected. Their ultimate +split/merge remains testable. Mutation Outcome Tracking is retained as a shared review +model/hypothesis; no new claim of standalone recurrence. The nine extension candidates +remain available with their existing limitations and are not needed for core closure. +No candidate promotion, ID rename or evidence-profile upgrade occurs. + +## Residual owners + +- WP-0002 T03: independent human review, usefulness and fresh-scenario replication; + this task stays progress and the M1 gate stays open. +- WP-0003 T04: storage atomicity, receiver replay/ancestry and recovery validation + transferred from the completed source-review deliverable. +- WP-0003 T01/T02/T03: independent application contrasts, quality/AT and wider cases, + and later ontology/M2 judgment. +- WP-0004 T01/T02/T03: canonical graph, held-out retrieval and empirical applicability + retain their prerequisites. Preview candidate export is not M3 completion. + +These are explicit work records, not a claim that the remaining work was completed +by packaging the reference. The frozen pilot and original investigation receipts are +unchanged. Review this gate again when those tasks deliver new evidence. diff --git a/research/reviews/PreviewOntology-0.1.md b/research/reviews/PreviewOntology-0.1.md new file mode 100644 index 0000000..9ddafef --- /dev/null +++ b/research/reviews/PreviewOntology-0.1.md @@ -0,0 +1,38 @@ +# Ontology review for the 0.1 reference subset + +2026-09-27, Codex author-model editorial review. Owner WP-0003 T03. +**Bounded result: retain with qualifications. M2 remains open.** No general proof +of minimal responsibilities, independent dimensions or complete pattern recurrence. + +## Conflict Copy versus Explicit Reconciliation + +Retain two research identities for preview retrieval: + +- Conflict Copy answers “how do we keep detected competing content available while + continuing work?” Its result is preserved divergence, not resolved meaning. +- Explicit Reconciliation answers “how do we decide intended content and record the + decision?” It can use a version store without making a separate conflict file. + +Preservation may precede manual review, but may also be followed by a justified +automatic merge or a deferred decision. Manual comparison can receive alternatives +from a revision store. Therefore neither unconditional requires edge is justified. +Export one conditional creates-context-for edge from CAND-0001 to CAND-0004 and +state the conditions. This is conceptual reasoning, not an observed independent +implementation of both complete contracts. Test whether readers can select one +without being forced into the other; merge later if that distinction proves unhelpful. + +## Other decisions + +| Question | Preview disposition | Limit | +| --- | --- | --- | +| Pending Synchronization versus Mutation Outcome Tracking | Retain both: local work may already be accepted while remote propagation is pending; remote write acceptance may instead be unknown | Shared operation-state model may motivate later refactoring; no full recurrence claim | +| Version precondition versus operation identity | Distinct obligations: stale-base rejection versus recovery of a particular attempt | One does not establish the other; receiver semantics must be checked | +| Local draft versus locally accepted record | Retain separate; editable intent need not be durable or locally authoritative | Add persistence only under explicit policy/storage requirements | +| Authority, projection and delivery | Apply the [six-question aid](AuthorityProjectionComparison.md); retain the six seeds without new drafts | Separate decisions with compatibility constraints, not universally independent axes | +| Families versus responsibilities | Keep separate classification fields; quality is a family, reconciliation a responsibility | Provisional direct-mechanism assignments and selected forces are not exhaustive ontology proof | +| Relations and prerequisites | Export only scoped proposals with rationale; no inverse, symmetric or transitive inference | Proposed links are not canonical graph edges; contextual conditions are not pattern IDs | +| Scale coverage | Preserve current labels and gaps, including L0/L7 | No automatic relabeling to fill empty cells | + +No M2-CoverageReview pass is claimed: VC-04/05 are absent and VC-03/06 remain provisional. +This closes the preview's bounded ontology inspection, not WP-0003 T03. Independent +retrieval/usefulness and broader case outcomes may overturn these provisional choices. diff --git a/research/reviews/SourceReadiness-0.1.md b/research/reviews/SourceReadiness-0.1.md new file mode 100644 index 0000000..112c2d8 --- /dev/null +++ b/research/reviews/SourceReadiness-0.1.md @@ -0,0 +1,27 @@ +# Source readiness for the 0.1 research preview + +Reviewed 2026-09-27 by Codex, author-model editorial review. Inputs: source reviews +and receipts committed through `8cc7016`; no new external verification. Owner: +WP-0002 T02. Review scope is traceability and qualified interpretation, not full +implementation validation or currency of living documentation. + +| Criterion | Disposition | Evidence / remaining boundary | +| --- | --- | --- | +| Identifiable first source and claim locators | pass | [Carniato review](../cases/CarniatoGrandUnifyingArchitecture.md), SRC-0001/C01–C03; edition/date uncertainty remains explicit | +| Independently sourced local-first contrast | pass | [Local-first review](../cases/LocalFirstAuthority.md), SRC-0002/C01–C03; primary local record is distinct from globally valid transaction | +| Source claims versus our interpretations | pass | Both claim tables separate these; [AuthorityPilot](AuthorityPilot.md) records conditional authority and acknowledgement decisions | +| Extensions with traceable limits and counterexamples | pass | [E01–E12](LocalFirstEvidenceExpansion.md), [T01–T05](TransactionalEvidenceExpansion.md), [R01–R06](FrontendRecoveryImplementations.md); living docs and partial source uses are qualified | +| Generated output screened and failures retained | pass | Failed/truncated runs and invalid edges remain in receipts/reviews; extracted model text is not automatically admitted | +| Current public maturity claims | pass for preview scope | README and release entry describe seventeen hypotheses, partial evidence and unproved usefulness | +| Actual storage atomicity, receiver semantics and full-contract independent uses | defer | These exceed the original two-source review deliverable; explicit residual ownership below | +| Independent human/AT usefulness | defer | WP-0002 T03 / WP-0003 T02 retain these gates; submitted model review does not meet them | + +**Disposition:** the original WP-0002 T02 source-review deliverable is complete at +this bounded documentary level. Earlier notes accumulated implementation and fault +validation obligations; completion here does not erase them. Transfer those obligations +to WP-0003 T04 (origin WP-0002 T02), alongside existing T01 source comparison work. +WP-0002 itself stays active and M1 remains revise/defer under T03. + +The dated source reviews retain their original extracted status as historical records; +their appended editorial-assessment links identify this later disposition without +rewriting the original source collection or claiming revalidation of external content. diff --git a/scripts/reference_preview.py b/scripts/reference_preview.py new file mode 100644 index 0000000..bff442f --- /dev/null +++ b/scripts/reference_preview.py @@ -0,0 +1,116 @@ +#!/usr/bin/env python3 +"""Build or check the pinned 0.1 candidate reference (not a canonical graph).""" +import argparse +import hashlib +import json +from pathlib import Path +import re +import subprocess + +from classification_coverage import section_values, RESPONSIBILITIES + +ROOT = Path(__file__).resolve().parents[1] +BASE = 'reference/0.1/' + + +def require(condition, message): + if not condition: + raise ValueError(message) + + +def locator(root, value): + require(isinstance(value, str) and bool(value), 'Empty reference') + path = (root / value).resolve() + require(path.is_relative_to(root.resolve()) and path.is_file(), 'Invalid reference: ' + value) + return path + + +def build(root=ROOT): + manifest = json.loads((root / BASE / 'manifest.json').read_text()) + for path, digest in manifest['inputs'].items(): + require(hashlib.sha256(locator(root, path).read_bytes()).hexdigest() == digest, 'Stale input: ' + path) + profiles = json.loads((root / 'research/evolution/profiles.json').read_text())['profiles'] + classifications = json.loads((root / 'research/catalog/ClassificationCoverage.json').read_text())['candidates'] + classes = {r['path']: r for r in classifications} + vocab = (root / 'canon/vocabulary.yaml').read_text() + ids = [p['id'] for p in profiles] + selected = manifest['core'] + manifest['extensions'] + require(len(ids) == len(set(ids)) and all(re.fullmatch(r'CAND-\d{4}', x) for x in ids), 'Invalid candidate identities') + require(len(selected) == len(set(selected)) and set(selected) == set(ids), 'Invalid manifest selection') + require(len(classes) == len(classifications) == len(profiles), 'Invalid classification coverage') + records = [] + for p in profiles: + raw = locator(root, p['path']).read_bytes() + require(hashlib.sha256(raw).hexdigest() == p['sha256'], 'Stale candidate: ' + p['id']) + pinned = subprocess.check_output(['git', 'show', manifest['corpus_revision'] + ':' + p['path']], cwd=root) + require(raw == pinned, 'Candidate differs from pinned revision: ' + p['id']) + front = raw.decode().split('---')[1] + c = classes[p['path']] + require(c['sha256'] == p['sha256'] and c['title'] == p['title'], 'Stale classification') + require(p['status'] == 'draft' and p['maturity'] == 'hypothesis', 'Re-review preview maturity') + require(p['gaps'] and p['decision'].strip() and c['rationale'].strip(), 'Missing qualification') + record = dict(p, subset='core' if p['id'] in manifest['core'] else 'extension', classification=c, + classification_status='provisional author-model interpretation') + for key in ('families', 'scales'): + match = re.search(r'^' + key + r': \[(.+)\]$', front, re.M) + require(match is not None, 'Missing ' + key) + labels = [s.strip() for s in match[1].split(',')] + require(len(set(labels)) == len(labels) and set(labels) <= set(section_values(vocab, key)), 'Invalid ' + key) + record[key] = labels + require(set(c['responsibilities']) <= set(RESPONSIBILITIES), 'Invalid responsibility') + for labels in c['forces'].values(): + require(set(labels) <= set(section_values(vocab, 'forces')), 'Invalid force') + for e in p['evidence']: + locator(root, e['ref']) + require(e['kind'] and e['scope'], 'Missing evidence qualification') + require(p['evidence'] or p['independent_full_contract_uses'] is None, 'Missing evidence/unknown') + records.append(record) + for edge in manifest['relations']: + require(edge['source'] in ids and edge['target'] in ids, 'Invalid relation endpoint') + require(edge['type'] in section_values(vocab, 'pattern_relations'), 'Invalid relation type') + require(edge['status'] == 'proposed' and all(edge[k].strip() for k in ('condition', 'rationale', 'unknown', 'evidence_kind')), 'Unqualified relation') + require(edge['evidence_refs'], 'Missing relation evidence') + for ref in edge['evidence_refs']: + locator(root, ref) + for ref in manifest['entrypoints'].values(): + locator(root, ref) + for task in manifest['open_work']: + require(task['id'] in locator(root, task['path']).read_text(), 'Missing residual task') + cases = json.loads((root / BASE / 'development-cases.json').read_text())['cases'] + require(len(cases) >= 6 and len({c['id'] for c in cases}) == len(cases), 'Invalid development cases') + for case in cases: + require(case['entrypoint'] in manifest['entrypoints'] and set(case['expected_candidates']) <= set(ids), 'Invalid development reference') + require(all(case[k].strip() for k in ('query', 'reviewed_answer', 'prohibited_claim', 'boundary')), 'Incomplete development case') + index = dict(schema_version=1, version='0.1', status='research-preview', corpus_revision=manifest['corpus_revision'], + candidates=records, relations=manifest['relations'], entrypoints=manifest['entrypoints'], + relation_semantics='Conditional proposals only; no inverse or transitive inference.') + catalog = ['# Candidate reference — 0.1', '', 'All records are draft hypotheses. Classification is provisional; linked candidate prose contains context, alternatives and consequences. Evidence locators describe partial support, not full-contract recurrence.', ''] + for subset in ('core', 'extensions'): + catalog += ['## ' + subset.title(), '', '| Candidate / decision | Families; scales | Evidence limits |', '| --- | --- | --- |'] + for p in records: + if p['id'] not in manifest[subset]: + continue + catalog.append(f"| [{p['id']} — {p['title']}](../../{p['path']}) — {p['decision']} | {', '.join(p['families'])}; {', '.join(p['scales'])} | {' '.join(p['gaps'])} |") + catalog += [''] + catalog += ['Extensions are optional research leads. VC-03/06 remain provisional; other planned cases are unsupported. Follow the [starting guide](../../START.md) for the two core contexts.', ''] + checks = ['# Disclosed development navigation checks', '', 'Author-model review; scenarios and answers were authored together. These checks validate navigation and stated boundaries, not measured retrieval or independent usefulness.', ''] + for c in cases: + checks += ['## ' + c['id'] + ' — ' + c['query'], '', '[' + c['entrypoint'] + '](../../' + manifest['entrypoints'][c['entrypoint']] + ') → ' + (', '.join(c['expected_candidates']) or 'clarify / abstain') + '.', '', c['reviewed_answer'], '', 'Boundary: ' + c['boundary'], '', 'Reject: ' + c['prohibited_claim'], '', 'Editorial disposition: ' + c['review_result'] + '.', ''] + return {'index.json': json.dumps(index, indent=2) + '\n', 'Catalog.md': '\n'.join(catalog), 'DevelopmentChecks.md': '\n'.join(checks)} + + +def main(): + parser = argparse.ArgumentParser(description=__doc__) + parser.add_argument('--check', action='store_true') + args = parser.parse_args() + for name, content in build().items(): + path = ROOT / BASE / name + if args.check: + require(path.is_file() and path.read_text() == content, 'Stale export: ' + name) + else: + path.write_text(content) + print('Preview identities, pinned candidates, vocabulary, references and development cases verified.') + + +if __name__ == '__main__': + main() diff --git a/sequences/LocalFirstApplication.md b/sequences/LocalFirstApplication.md index bcb5022..e157bc6 100644 --- a/sequences/LocalFirstApplication.md +++ b/sequences/LocalFirstApplication.md @@ -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. diff --git a/sequences/TransactionalApplication.md b/sequences/TransactionalApplication.md index ab612ce..83af239 100644 --- a/sequences/TransactionalApplication.md +++ b/sequences/TransactionalApplication.md @@ -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. diff --git a/technologies/OfflineRecovery.md b/technologies/OfflineRecovery.md new file mode 100644 index 0000000..8551da8 --- /dev/null +++ b/technologies/OfflineRecovery.md @@ -0,0 +1,21 @@ +# Offline recovery: mechanism mappings + +0.1 research preview. Previously reviewed documentation locates partial mechanisms, +not verified whole-pattern guarantees. Review dates/access limits are retained in +[LocalFirstEvidenceExpansion](../research/reviews/LocalFirstEvidenceExpansion.md). +[Offline sequence](../sequences/LocalFirstApplication.md). + +| Decision | Located mechanism | Boundary | +| --- | --- | --- | +| CAND-0002 — local acceptance | Joplin local SQLite storage, E04; local-first motivation E01 | Does not specify our revision-plus-pending atomic commit, acknowledgement/flush or crash contract | +| CAND-0003 — pending propagation | Joplin distinct sync process and per-item progress metadata E05/E06 | Does not verify deduplication, bounded completion or atomic supersession proposed by this candidate | +| CAND-0001 — preserve competing content | Joplin detected-note conflicts E07; Obsidian optional conflict-file mode E08 | Configuration and file-type scope differ; not a universal detection or no-loss guarantee | +| CAND-0004 — decide intended content | Documented manual comparison/recovery E07/E08 | Provenance, accessible interaction and recoverable resolution transaction remain proposed | +| Separate device-loss recovery | Obsidian backup distinction E11/E12 | No restore drill or recovery-point guarantee was executed in this research | + +These are separate products and modes, not a prescription to combine them. An +automatic merge may be preferable when domain semantics justify it. The +[authority/projection comparison](../research/reviews/AuthorityProjectionComparison.md) +explains why local availability, replica convergence and accepted domain meaning +must remain distinct. Choose and fault-test a specific storage/receiver pair before +promising the sequence's durability and retry behavior. diff --git a/technologies/TransactionalRecovery.md b/technologies/TransactionalRecovery.md new file mode 100644 index 0000000..e9fc3d6 --- /dev/null +++ b/technologies/TransactionalRecovery.md @@ -0,0 +1,18 @@ +# Transactional recovery: mechanism mappings + +0.1 research preview. These map previously reviewed mechanisms to candidate decisions, +not complete, interchangeable product implementations. No new source verification was +performed for this mapping; dates and revisions are those in the linked reviews. +[Transactional sequence](../sequences/TransactionalApplication.md). + +| Decision | Located mechanism and provenance | What still needs verification | +| --- | --- | --- | +| CAND-0005 — retain unfinished intent | Zulip and Element composer draft paths, pinned source R01/R03 in [FrontendRecoveryImplementations](../research/reviews/FrontendRecoveryImplementations.md) | Complete base/draft/current merge, retention policy, restart and composer-to-operation handoff | +| CAND-0006 — reject a stale proposal | Kubernetes conditional PUT, T01 in [TransactionalEvidenceExpansion](../research/reviews/TransactionalEvidenceExpansion.md); GitLab optional file precondition T02 has different failure semantics | Actual endpoint atomicity and domain checks; do not treat every GitLab 400 as version rejection | +| CAND-0007 — resolve uncertain outcome | Stripe bounded replay identity T03; Element/Matrix echo/retry source R04–R06; [Matrix SDK observation](../research/reviews/MatrixRecoveryExperiment.md) uses synthetic transport | Receiver retention/identity scope, lookup, true server deduplication, cancellation/compensation; these mechanisms are not one assembled stack | +| CAND-0008 — refresh after acceptance | React Router revalidation and concurrency guidance T04/T05 in the transactional review | Read-after-write, obsolescence and preserved drafts in the actual application; client cancellation does not stop server effects | + +Select a mechanism only after the application's acceptance and failure contracts are +known. These examples do not require Kubernetes, Stripe or a particular UI framework; +they illustrate different obligations. Combining them is a proposed design, not a +known deployed use. Full-contract recurrence remains unassessed. diff --git a/tests/test_reference_preview.py b/tests/test_reference_preview.py new file mode 100644 index 0000000..499bc8e --- /dev/null +++ b/tests/test_reference_preview.py @@ -0,0 +1,70 @@ +"""Reject broken preview contracts before publishing generated references.""" +import importlib.util +import json +from pathlib import Path +import shutil +import sys + +import pytest + +ROOT = Path(__file__).resolve().parents[1] +sys.path.insert(0, str(ROOT / 'scripts')) +spec = importlib.util.spec_from_file_location('reference_preview', ROOT / 'scripts/reference_preview.py') +preview = importlib.util.module_from_spec(spec) +spec.loader.exec_module(preview) + + +@pytest.fixture +def copy(tmp_path): + for name in ('research', 'canon', 'workplans', 'sequences', 'technologies', 'reference'): + shutil.copytree(ROOT / name, tmp_path / name) + shutil.copy(ROOT / 'START.md', tmp_path / 'START.md') + (tmp_path / '.git').symlink_to(ROOT / '.git', target_is_directory=True) + return tmp_path + + +def mutate(root, edit): + path = root / 'reference/0.1/manifest.json' + data = json.loads(path.read_text()) + edit(data) + path.write_text(json.dumps(data)) + + +def test_current_export(): + for name, content in preview.build().items(): + assert (ROOT / 'reference/0.1' / name).read_text() == content + + +@pytest.mark.parametrize('field,value', [('target', 'CAND-9999'), ('type', 'magically-guarantees'), ('condition', ''), ('evidence_refs', ['missing.md'])]) +def test_bad_relation(copy, field, value): + mutate(copy, lambda m: m['relations'][0].update({field: value})) + with pytest.raises(ValueError): + preview.build(copy) + + +def test_duplicate_identity(copy): + mutate(copy, lambda m: m['core'].append(m['core'][0])) + with pytest.raises(ValueError): + preview.build(copy) + + +def test_stale_candidate(copy): + with (copy / 'research/candidates/ConflictCopy.md').open('a') as f: + f.write('\nChanged contract.\n') + with pytest.raises(ValueError, match='Stale candidate'): + preview.build(copy) + + +def test_escaping_reference(copy): + mutate(copy, lambda m: m['entrypoints'].update(start='/etc/passwd')) + with pytest.raises(ValueError, match='Invalid reference'): + preview.build(copy) + + +def test_missing_metadata(copy): + path = copy / 'reference/0.1/manifest.json' + data = json.loads(path.read_text()) + del data['relations'][0]['rationale'] + path.write_text(json.dumps(data)) + with pytest.raises((ValueError, KeyError)): + preview.build(copy) diff --git a/workplans/FEP-WP-0002-seed-language-validation.md b/workplans/FEP-WP-0002-seed-language-validation.md index bbef9ff..27f377f 100644 --- a/workplans/FEP-WP-0002-seed-language-validation.md +++ b/workplans/FEP-WP-0002-seed-language-validation.md @@ -14,7 +14,7 @@ reviewed_against_commit: "c161369ad58782ff0a13429c61cc7c8efc36e33d" owner: codex topic_slug: canon created: "2026-09-23" -updated: "2026-09-26" +updated: "2026-09-27" state_hub_workstream_id: "3350b7f2-375a-54e8-8f7c-3bf7c7c3af71" --- @@ -48,7 +48,7 @@ Done when schema and template agree and a worked example resolves every referenc ```task id: FEP-WP-0002-T02 -status: progress +status: done priority: high state_hub_task_id: "0eb32b3e-07d6-5e16-a735-7d75d9dace83" ``` @@ -334,3 +334,16 @@ See research/reviews/SharedGuidanceRevision.md. Frozen pilot files and scores re unchanged; historical corpus hashes remain reproducible. No new evaluation or M1 completion. WP-0003 T01 now owns a bounded exploratory navigation/rendering expansion; independent-human validation and a fresh-scenario replication remain open here. + +## Consolidated source and seed review — 2026-09-27 + +[SourceReadiness-0.1](../research/reviews/SourceReadiness-0.1.md) completes T02's +original documentary traceability deliverable. Later storage/receiver fault-validation +obligations are transferred to explicit WP-0003 T04, origin WP-0002 T02; independent +uses continue under WP-0003 T01 and human/usefulness under this T03. No evidence +obligation is declared satisfied merely by transfer. Workplan remains active. + +[M1-SeedReview](../research/reviews/M1-SeedReview.md) records pass/revise/defer criteria. +The eight-record editorial core is suitable for a qualified research preview; M1 +remains revise/defer and T03 progress. WP-0007 packages it without canonical admission, +independent-human claims or fresh held-out evaluation. diff --git a/workplans/FEP-WP-0003-contrasting-schools.md b/workplans/FEP-WP-0003-contrasting-schools.md index 93d9b1d..6eb93de 100644 --- a/workplans/FEP-WP-0003-contrasting-schools.md +++ b/workplans/FEP-WP-0003-contrasting-schools.md @@ -285,3 +285,28 @@ questions. Select the application by the needed evidence; retain contrary/unknow paths. Existing Zulip auxiliary continuation residual stays open; local navigation fixture remains paused. WP-0002 T03 retains independent usefulness review; WP-0003 T02/T03 gates and WP-0006 T03 review dates/comparable measurement remain open. + +## Validate recovery storage and receiver assumptions + +```task +id: FEP-WP-0003-T04 +status: todo +priority: medium +``` + +Residual origin: FEP-WP-0002-T02, handed off by WP-0007's source-readiness review. +Before stronger guarantees, select/pin a concrete storage and receiver pair; verify +acknowledgement/transaction semantics, interrupted commit/restart and pending-operation +supersession, plus receiver identity retention, replay deduplication and stale ancestry +rejection under lost acknowledgement. Preregister bounded tests; retain failures. +Record which full-contract uses remain unknown rather than infer them from mechanism +success. Existing Matrix synthetic receiver is not real-server proof; device-loss +restoration needs its own explicit backup scope. No new execution is implied by this +handoff. Human/AT/usability stay under WP-0002 T03 / WP-0003 T02. + +## Preview ontology review — 2026-09-27 + +[PreviewOntology-0.1](../research/reviews/PreviewOntology-0.1.md) retains the eight-record +core and separate conditional Conflict Copy / Explicit Reconciliation retrieval. +No mandatory requires edge, general recurrence or M2 closure. T03 remains todo for +the full M2 review; this bounded preview assessment is preparation only. diff --git a/workplans/FEP-WP-0007-language-v01-preview.md b/workplans/FEP-WP-0007-language-v01-preview.md index c4acb53..ca08a4b 100644 --- a/workplans/FEP-WP-0007-language-v01-preview.md +++ b/workplans/FEP-WP-0007-language-v01-preview.md @@ -4,7 +4,7 @@ type: workplan title: "Package a useful language 0.1 research preview" domain: infotech repo: frontend-patterns -status: proposed +status: finished owner: codex topic_slug: canon created: "2026-09-27" @@ -24,7 +24,7 @@ publication version 0.1 is separate from PatternSchema 0.1 and evidence maturity ```task id: FEP-WP-0007-T01 -status: todo +status: done priority: high state_hub_task_id: "3417824a-1416-58d0-841b-7ec0ccbb7021" ``` @@ -45,7 +45,7 @@ model review. Keep source assessment ownership in WP-0002, ontology in WP-0003. ```task id: FEP-WP-0007-T02 -status: todo +status: done priority: high state_hub_task_id: "e71c2f74-dbea-5ab0-ae8c-4b247ec0f38f" ``` @@ -65,7 +65,7 @@ claim for the remaining cases. No standalone frontend application required. ```task id: FEP-WP-0007-T03 -status: todo +status: done priority: medium state_hub_task_id: "94010e3e-eddf-56c7-996a-fc70d7c56e38" ``` @@ -87,7 +87,7 @@ execution is optional if deterministic/manual checks answer the reference questi ```task id: FEP-WP-0007-T04 -status: todo +status: done priority: high state_hub_task_id: "a554e327-972b-580b-8dec-151d7a38bda6" ``` @@ -103,3 +103,18 @@ release claim from this proposed plan alone. Existing research work stays open u its own criteria are met; before finishing this workplan, hand residual release issues to explicit live tasks with origin references. The empirical owners remain WP-0002 T03, WP-0003 T01/T02/T03, WP-0004 T01/T02/T03 and WP-0006 T03. + +## Completion — 2026-09-27 + +The [release review](../reference/0.1/ReleaseReview.md) passes the bounded preview +contract. START.md, both core sequences, mechanism mappings, the seventeen-record +catalog and pinned candidate export are complete. Eight disclosed development cases +include incompatible constraints, missing context and unsupported needs. No live +inference, independent human review, canonical admission or M1/M2/M3 pass is claimed. + +Validation: 44 tests passed (9 preview, 2 schema, 33 bench/admission); synthetic +bench plan, export freshness, evolution and classification checks passed. Changed +Markdown relative file links and whitespace checked. Existing empirical obligations +remain in the manifest's live task references. WP-0003 T04 receives storage/receiver +validation with explicit origin FEP-WP-0002-T02. No additional packaging residual +was identified; ongoing research ownership remains unchanged.