Define portable repeatable-row event semantics across official bindings #102

Agreed repeatable contract

Implement portable open-row event semantics alongside #98 across React main-thread, React worker and React Native/Hermes. Expanded lifecycle is opt-in. A row editor uses repeatable lifecycle events and never dispatches main-record lifecycle merely because it opens or changes.

Ownership: reads and writes are different

• Managed execution is bound to a complete engine construction eventScope.instancePath, rooted at [] for the main record.
• Row handlers may read current-row fields and permitted ancestor/main fields supplied by the host.
• SETVALUE writes only fields owned by the current row.
• Root handlers write root fields only.
• Sibling, descendant and unrelated branch reads/writes are rejected. Cross-row collection access is outside this delivery.
• The earlier proposal to route ancestor/main writes to other engines is superseded: such writes are explicitly rejected with structured execution issues.
• Headless row consumers provide scope explicitly; per-event application metadata cannot retarget it.
• Paths use complete repeatable schema keys and existing row IDs, with explicit positional fallback. Positional dispatch requires the observed active scopeId; no IDs are created for attribution.

Event timing and lifecycle

Opt-in rows evaluate effective values, dispatch load-repeatable, then their actual new-repeatable/edit-repeatable classification when editing. Readonly opens load only. No root load-record/edit-record hooks run for row opening.

User field edits emit contextual change after updates settle. Accepted row additions, edits and removals notify the owning repeatable definition with action and affected path. Defaults, SETVALUE and calculations do not emit further automatic changes.

Row acceptance uses the same preparation path as root actions: settle updates, built-in/custom validation, save-repeatable once when policy permits, conditional second validation if values changed, then final-snapshot row serialization. No row draft acceptance, closed-row evaluation or child-to-parent aggregation is introduced.

Confirmed cancellation emits cancel-repeatable, followed by unload-repeatable. Supported successful closes emit unload before disposal. Cancel/unload hooks are read-only notifications: reject value operations, INVALID and renderer alerts. Rerenders, resets, Strict Mode cleanup and forced disposal do not manufacture close events. Unaccepted edits and cancellation cannot mutate parent/main/sibling records.

Validation, operation completion and failures

INVALID(message) produces scope-owned findings only during synchronous validate-repeatable. Findings are separate from intrinsic field errors, calculation diagnostics, saved row values and record/media metadata. Validation handlers reject value/UI operations and promises.

Managed dispatch returns detailed findings/issues, preserves operation ordering/delegation/batching and exactly-once alerts, and awaits delegated promises/default handling. Requests are serialized; stale generations, obsolete replies, closed/deleted targets and late fallback work are rejected rather than redirected or resurrected. Preparation failures deliver no payload and keep editable/prepared values available for correction.

Applications own persistence, success notifications and closing. Save-repeatable is pre-save; there is no saved-repeatable schema event.

Revised acceptance criteria

• Written contract and four-locale documentation for timing, scope, identity, routing and ownership.
• Complete nested engine-bound scope validation; current/ancestor/main reads and rejection of sibling/descendant/unrelated reads.
• Current-row writes accepted; ancestor/main/sibling/descendant/unrelated SETVALUE writes explicitly rejected, without applying partial managed batches.
• Cancellation isolation: failed/unaccepted row edits cannot change parent/main/sibling values.
• New/load/edit/change/validate/save/cancel/unload behavior shared across both bindings, actual React workers and opt-in CLI preview; root lifecycle never runs because a row opens.
• Actual new/existing/readonly classification, settled update timing, membership notifications, save-once/conditional revalidation and final row payloads.
• Existing ID retention after sibling deletion and complete nested attribution; guarded positional fallback without ID generation.
• Exactly-once operation/alert handling, custom/delegated operation completion and stale/closed-target rejection.
• Preservation of evaluation counts, intrinsic validation, timestamps, row/record/media metadata and legacy opt-out behavior.
• Automated conformance plus fresh browser/main-thread/actual-worker and Android/Hermes acceptance. iOS deferred.

Delivery boundaries

Core first, then binding adoption after maintainer publication of the core contract. Core alone does not complete this issue or #98. Preserve development → main; no direct issue/card closure.

Open row editors only. Closed-row submission freshness remains paqu-io/form0-react#73. Broader validation policy #99/#104, asynchronous validation #96, setter normalization #101, conditional scope #103 and styling remain separate. No cross-row collection access, cross-scope writes, persistence implementation or saved-* event is included.

Implementation checkpoint — 14 October 2026

• Core 0.5.0 is published and downstream manifests adopt it. Binding controller, opt-in lifecycle, custom summary, scoped operations and save preparation are implemented locally; React main-thread/worker conformance and Native tests pass. CLI builtin-recognition checks retain their original evidence; expanded browser adoption is tracked below.
• Media preservation exposed File/Blob rejection in the new managed core copy path. Core PR #117, commit fbd0d5d, corrects this with defensive native-media copies. Full 24-script core gate passes. A maintainer patch publication (recommended 0.5.1) is required before the final binding minimum is adopted.
• Candidate binding gates pass against an explicitly unpublished core patch: React 64 tests, Native 54 tests; CLI 106 tests pass against registry core 0.5.0. Native's original Metro audit exception and expiry remain unchanged; task-cache policy passes with nine approved entries, production audits zero. Four-locale documentation source checks pass.
• Fresh actual browser/main-thread/worker and Android/Hermes acceptance remains pending; iOS deferred. Core PR fix(events): preserve native media in managed event copies #117 has seven passing checks and zero findings in both actual head CodeQL analyses; binding new-code scans follow their PR delivery. No version bump, publication, merge or direct issue/card closure was performed by the agent. Closed-row freshness, cross-row collections, broader validation policy and other related packages remain separate.

CLI preview scope expansion — 14 October 2026

At the maintainer's direction, CLI browser preview now joins the portable event delivery; the earlier dependency-only boundary is superseded for the built-in browser renderer. Standalone CLI reporting/outcomes and serve --app ownership remain unchanged.

Local implementation adds opt-in settings with explicit record classification, server-owned scoped engines, promise dispatch/preparation, synchronous custom validation, staged inline row acceptance/cancellation, local-only writes and current preference/timestamp serialization. Collapse is presentation only; forced reload is retirement. Draft preparation is a raw development snapshot with no connector persistence; connectors receive only eligible final records. Root/row IDs and metadata are preserved, and stale/duplicate/positional/ambiguous targets are guarded.

Automated evidence: CLI full sequential 142 tests, focused 36 conformance/HTTP/client checks, real packed HTTP, one simulated-DOM scenario, 93 exact installed files and zero production audits. Actual baseline/current legacy HTTP state/maps/operations/diagnostics match with 16 evaluations each. Four-locale docs source gates pass. The independently installed unpublished CLI candidate and three browser steps are USER PENDING, separate from active binding acceptance. No earlier browser/device acceptance transfers; new-code CLI CodeQL follows its PR. No agent publication/merge or direct issue/card closure.

Cross-package delivery checkpoint — 21 October 2026

• The maintainer published core 0.5.1 (including the media correction) and reports CLI 0.7.0 published. CLI portable preview was delivered through CLI PR #79, with 161 full tests, 37 focused checks and nine actual browser scenarios against registry core 0.5.1; its seven PR checks and actual-head CodeQL passed before promotion.
• Both bindings now use published core ^0.5.1 on their existing development branches: React PR #82, head bf1c0a3; Native PR #50, head 0b88039. Each targets main, is mergeable, and has all seven checks passing, including Node 22/24. Actual-head CodeQL reports zero findings across 87 JS/TS and 17 Actions rules per repository, no errors/warnings or open PR alerts.
• Fresh independent release verification: React 64/64, Native 54/54; 32 actual Chromium main-thread/worker event scenarios + four media scenarios, 27 Native renderer adapter scenarios, strict public Native declarations, web worker build and Android/Hermes export all pass. Package inventories are 14 React / 61 Native files. Maintainer browser and corrected Android acceptance for exercised flows is retained at its original artifacts; final runtime/type bytes are identical to those accepted candidates. This does not claim an exhaustive device matrix or a new device run; iOS remains deferred.
• Both production audits report zero. React all-dependency audit is clean after a targeted development-only Vite 8.3.3 security patch and required Rolldown subtree. Native's original nine Metro/braces peer-chain entries and 7 November expiry remain unchanged under the existing audit policy. Maintained dependency trees were not installed into or replaced.
• Four-locale event/binding documentation source checks pass. Docs promotion/rendered checks, binding merges, proposed minor bumps React 0.4.0 / Native 0.5.0, npm publication and issue closure remain maintainer steps. This issue remains open; these PRs contain references without closing keywords. No unrelated closed-row freshness, conditional scope, setters or broader validation-policy scope was added.

Published delivery and closure review — 21 October 2026

Core 0.5.1, CLI 0.7.0, React 0.4.0 and React Native 0.5.0 are now published. React PR #82 and Native PR #50 are merged. Fresh installed registry binding runtime/type files match the previously accepted candidates (10 React distribution files / 57 Native source/type/font files), preserving the original browser/worker and exercised Android acceptance provenance.

The implementation, save-preparation, scope/cancellation, operation, legacy-preservation, automated acceptance and code-scanning criteria are complete for this agreed contract. The remaining delivery item is the maintainer-owned documentation promotion and its production/rendered CI. Four-locale docs source gates pass: formatting, i18n, navigation, 128-document parity across four locales, 20 tests and lint. Documentation now identifies the actual released minimums and no longer describes CLI/binding adoption as a future release. iOS device acceptance remains explicitly deferred; no exhaustive device matrix is claimed.

Template updates are supplementary maintenance: web PR #31 patches Vite on its existing major; mobile PR #24 aligns SDK 57 patches and narrowly re-reviews the version-specific audit graph. These do not expand this event contract. Connector core 0.5.1 checks pass: PostgreSQL 13 tests with one unconfigured live-DB skip, SQLite all five tests, formatting/package inventories and zero production audits. Connector runtime source and the maintainer's local commits/edits are preserved.

Closure guidance: after documentation delivery checks pass and the maintainer confirms the revised criteria, this issue is eligible for closure. It does not need to remain open for the next feature package. Broader submission validation #99/#104, closed-row freshness paqu-io/form0-react#73, conditional scope, setters and unresolved dependency advisories retain their separate scope. No automatic closing reference or direct issue/card closure is performed here.

Documentation PR ready — 21 October 2026

The remaining docs are committed and pushed on development as 29a6c77 (core/INVALID), 3f78c80 (bindings) and ac6078b (CLI preview). Docs PR #24 targets main and covers all 50 prepared files in four locales.

All four validation checks pass on that exact head, including the full production build, rendered-output validation and production audit. Actual-head CodeQL reports zero findings with no errors/warnings or open PR alerts. Deployment is correctly skipped on a PR and runs through the existing workflow after merge to main.

The maintainer's merge/deployment and final closure review remain. Documentation delivery is not marked complete before that promotion; this issue stays open and no automatic closing reference was added. The next feature package (#99/#104, with React #73 ownership separate) does not extend this issue's acceptance scope. Earlier acceptance evidence retains its original artifacts and platform limits.

Event delivery complete — 21 October 2026

Documentation PR #24 is merged as fa051d0. Its main-branch validation and deployment workflow completed successfully, including production deployment. The maintainer also confirms publication and deployment are complete.

The remaining documentation-delivery criterion is now complete, alongside the previously recorded implementation, package, browser/worker, exercised Android and CodeQL acceptance. All revised criteria are checked. This issue is closure-eligible now; issue/card closure remains with the maintainer. It does not wait for core #99/#104, React #73, or independent template dependency maintenance. iOS device acceptance remains explicitly deferred and earlier evidence retains its original artifact/platform scope.