Temporal persistence grammar v2 — implementation contract#

This replaces the open choices of v1 for the implementation requested by the user. Source: e21c280f3; user decisions: native reconstruction is required, existing persisted data may be replaced, and the existing SQL/residual pipeline is the integration point. V1 and its hostile readings remain historical evidence.

Frozen model#

M1 Value: support Instant and PlainDate, the two reported kinds. Resolve their constructors from globalThis.Temporal, as the offline serializer does. Require them on encode and decode; prototype toString performs the brand check. Reject other genuine Temporal kinds explicitly. Do not silently stringify or flatten them. Preserve existing Date/BigInt/scalar behavior. No pluggable codec API.

M2 Carrier: rows, nested records/arrays, row/collection metadata, replay and tombstones use the same native encoding. Wrapper index specifications use that encoding too. Plain records containing the reserved marker are escaped on new writes, so decoding cannot promote them to native values.

M3 Representation: each native tag stores canonical text and a sortable key. Instant uses an offset, zero-padded decimal epoch-nanosecond integer; PlainDate uses its ISO-calendar year/month/day with an offset, padded year. Neither uses floating point or Date conversion. Canonical kind/text is equality identity; the sortable key is ordering identity. PlainDates with different calendar IDs can have the same order but different equality identity.

M4 SQL: extend the shared runtime/index reference expression to select native sort keys. Temporal literals use the same sort key. Equality and IN add a kind/text identity check when required, retaining the indexed key restriction. Coalesce propagates both representations. Boolean composition operates on exact predicates in this declared domain, including NOT; preserve the existing unsupported-expression and binding-cap fallbacks. Runtime and persisted index SQL must remain syntactically aligned. The existing residual evaluator and local sort remain authoritative, with native Temporal comparison in local sort and pagination after cleanup. No new query execution pipeline.

M5 Query domain: native scalar refs/literals, nested refs, coalesce, equality, IN, same-kind ordered comparisons, Boolean composition, ordered windows and cursor predicates. Ordered operands must have compatible declared types; cross-kind native ordering is invalid, not an invented total order. Native calendar annotations and nanosecond precision remain observable. Arbitrary Temporal arithmetic/date extraction, other native kinds and custom classes are not introduced by this repair.

M6 Histories: extend current owner grammars with native values. Preserve action order, validation of superseded actions, full durable rollback, replay positions, wrapper receipts/FIFO and existing publication-before-durability. Immutable Temporal values may be retained by the model; observations must compare native kind and text instead of relying on structuredClone or empty-object equality.

M7 Boundaries: direct shared core and wrapper index serialization are included. Existing coordinator wire contracts remain narrower: reject invalid wire input before remote-demand retry admission; do not transport native instances through structuredClone. Native host/multiprocess receiving support is not claimed.

M8 Upgrade: new readers retain existing supported encodings and rebuild changed index SQL through the existing path. Already-corrupted empty objects remain plain data; an application can replace the cache using the existing schema version/reset options. No automatic reset or irreversible data action is needed to implement this additive repair. Downgrade readers are not promised support for the new format. New accepted data still has the M1/M2 preservation contract.

Case := value family × carrier × operation × existing legal history × boundary. The active overlaps are storage/equality/order, runtime/index literals, serialization/action folding, and public admission/transport. These dimensions are model annotations, not proposed production classes or lifecycle states.

Evidence and executable owners#

E1 sqlite-temporal-value-oracle: file reopen, nested values, metadata, replay, boundaries in precision/year/calendar, marker escaping and constructor failure. E2 expression-index-oracle: raw SQL keys before cleanup, native equality/order, IN/NOT/coalesce, and actual index use. Add a wrapper-produced specification path. E3 ordinary-transaction-work-oracle: independent native kind/text observations for repeated actions, rollback and invalid superseded native values; keep work bounds and current models. E4 persisted-oracle: preserve existing receipt/FIFO laws and reject permanent wire admission failures before they enter retry. Reuse its current owner paths.

Selected transformations and overlaps#

The user selected F1 and F2 together and accepted the stated F3 receiving limit in the implementation plan. These are adjacent transformation paths from the same existing subsystem, not competing performance/correctness products. Storage and queries overlap at representation; queries and index metadata overlap at native literals; action folding and serialization overlap at validation; public demand and transport overlap at admission. Splitting these into independent codecs or models would lose those obligations.

The case dimensions are finite test annotations. Dynamics are value encoding, query compilation and existing action histories; constraints are M1–M8; boundary conditions are the two supported kinds, one registered constructor provider, real Node SQLite and the declared shared-core/local-wrapper routes.

Post-freeze implementation discoveries — 2026-10-05#

D1 (M2/E2): Collection.getIndexMetadata was an additional receiving entrance. Its JSON clone erased native literals and its signature collapsed them to empty records. Copy expression structure while retaining immutable values, and include kind/text in the signature. Six wrapper witnesses failed before this repair.

D2 (M2/M4/E1): IN must match correlated (order, identity) pairs. Two ordinary string literals must not combine to impersonate one native value under NOT IN. Escape only an ordinary record's marker field so its other nested JSON paths remain queryable. Both distinctions have pre-fix public-result failures.

D3 (M7/E4): a leader without a local subset owner can become a follower while hydration waits. Validate at entry for an already-remote request, and after hydration inside the existing admission cleanup boundary for a newly remote request. Remove the redundant hydration-time ensure path; dispatch owns the remote request. String controls dispatch exactly once; unsupported native input never reaches dispatch or retry. No new lifecycle or retry state is added.

D4 (M4/E2): SQLite forbids membership subqueries in index definitions. Runtime IN uses paired membership; index expressions use equivalent balanced OR clauses. Balancing preserves large membership definitions without exceeding expression depth. Two and 1,025-value string-index witnesses check final keys, raw SQL and named-index use. This preserves an existing scalar index route affected by F2.

These addenda refine the receiving paths and SQL forms. They do not replace the frozen native-value law or revise existing publication/durability contracts.

See evidence for executed controls and remaining owner gaps, and process for reconstruction and projection provenance.

Current-main integration and review repairs — 2026-10-05#

The branch now includes main cfb03f201, including the safe candidate contract from #1997. M4's exact native examples retain their raw-key/index checks. Classification admits native raw-ref equality, native membership, same-kind ranges and raw-ref NOT leaves. Range candidates retain SQL NULL projections because core NaN orders above native values. NOT uses the original leaf, never an approximate candidate. Mixed native/scalar field pairs fall back outside the native pair. Positive native coalesce equality remains selective; NOT/coalesce and unsupported Boolean shapes keep residual filtering. NaN is not nullish in the core evaluator, so SQL coalesce cannot certify negation for that domain.

D4's scalar membership DDL law still holds. Its original exact raw-key and plan claim preceded #1997: eq(in(ref, strings), true) now deliberately reads a candidate superset. The two and 1,025-value witnesses retain successful DDL and exact final keys, with full candidate reads as the current contract. Native plan assertions remain unchanged.

M7 also covers an ownerless leader that completes local loading before it becomes a follower. Sequence-gap recovery validates retained demand at the existing remote queue admission. Invalid native input reaches the existing terminal error path without a coordinator call; a valid string dispatches once. Transient transport retry keeps its prior law. No second lifecycle or transport codec is added.

M8 does not claim lossless migration for old ordinary objects whose reserved marker now names a recognized encoding. A receiving old-writer/new-reader probe confirms that ambiguity. The user permits replacing old data; the guide now states the rebuild requirement. New accepted records retain M2 preservation.