trainlog/docs/reviews/training_knowledge_v1_temporal_contract.md

Training Knowledge V1 — temporal contract and correction

Date: 2026-09-09. Contract analysis: advisor / Terra-high, completed. Temporal implementation and executable validation: PASS. Independent temporal delta review: TEMPORAL_DELTA_REVIEW=PASS, with no findings or repairs. The initial full-tranche audit found non-temporal defects and its authorized repair chain completed. Independent bounded verification and fresh final validation subsequently passed; TRAINING_KNOWLEDGE_V1=PASS. This record preserves the temporal contract and does not expand scientific scope or declare a frozen format decision.

Authority and compatibility

The frozen exchange timestamp rule requires RFC 3339 / ISO 8601 date-time text with an explicit UTC offset. The V1 schema declares format: date-time. The operational reader profile is:

YYYY-MM-DD[Tt]HH:MM[:SS[.digits]](Z|z|±HH:MM)

It uses extended Gregorian dates in years 0001–9999, valid calendar days, hours 00–23, minutes 00–59 and ordinary seconds 00–59. Fractions require seconds and at least one ASCII digit after a dot. Every fractional digit participates in comparison; trailing zeros do not change an instant.

Numeric offsets range through ±23:59. Lowercase t/z and the offset grammar follow RFC 3339 §5.6. -00:00 compares as a zero UTC offset while its distinct source spelling is preserved. Omitted seconds are an application compatibility requirement: Android persists OffsetDateTime.now().toString(), which can omit seconds when seconds and fractional seconds are both zero.

Basic dates, ISO week dates, spaces instead of T/t, comma fractions, compact offsets and hour-only offsets are NOT CONTRACTUALLY REQUIRED. They are rejected by the selected profile. The observed acceptance of these forms by Python datetime.fromisoformat() is not normative evidence: this environment's jsonschema 4.26.0 has no registered default date-time checker. No Trainlog writer, pre-existing fixture or inspected real session establishes a need for those extensions. All three real session timestamps match the selected profile and fit the existing C result fields.

Years outside 0001–9999 and :60 remain outside the established operational admission. Supporting real leap seconds would require a verified shared leap-event schedule and matching validator behavior; the repair does not guess a conversion or collapse a leap second into the following minute. RFC 3339 §5.7

Root cause and implementation

The old cursor guard, SQLite julianday(), Java OffsetDateTime.parse() and Python's ISO parser had different languages and precision. A +14:30 source produced a rejected cursor. SQLite returned NULL for valid +15:00 and lowercase-t values, allowing records to disappear. Floating-point Julian days also did not preserve arbitrary fractional precision.

The C and Kotlin readers now parse source text into an integer UTC second and an exact fractional digit sequence. Both occurrence pagination and the new latest-explicit-MAX reader order descending by:

(represented UTC instant, session_id bytes, entry_id bytes)

The cursor applies the same comparison exclusively. Equal instants with different offsets or fractional trailing zeros use identity tie breakers, never timestamp-text tie breakers. Cursor emission preserves the source timestamp and both IDs. C supports aliasing the input and output cursor.

Each read scans all matching metadata candidates and retains at most limit + 1 occurrence candidates, or one MAX candidate. Only selected rows are hydrated. It does not use a timestamp SQL predicate, SQL temporal order or SQL limit before comparison. Scan work is O(N) for the exercise history; retained candidate count is O(limit), with no global dataset-size cap. Each read has a snapshot covering selection and hydration. Separate page calls retain the existing current-data semantics, without a cross-call snapshot.

Malformed caller cursors fail before the scan. Malformed matching stored timestamps cause an explicit database/consistency error; they are not silently skipped. Source timestamps are never rewritten or normalized in persistent storage.

The C public timestamp fields retain their existing 40-character capacity. Longer valid SQLite text is compared with full precision; if selected for output, it produces DATABASE_ERROR. It is never truncated or silently omitted. Android can return longer strings. This is an existing C API representation limit, not a new wire precision bound. Arbitrary-length C output would require a separate ownership/length API change.

The Python validator uses the same grammar and exact chronology. It overrides only date-time on a fresh per-validation format-checker instance, preserving other checks and caller/global state. The document path therefore admits Android's no-seconds form even when an optional strict RFC checker is present.

Regression and validation evidence

Production C and Android tests cover mixed representations, page size one, emitted cursors, continuation, exhaustion, no duplicates, chronological order, equal-instant session/entry ties, near-equal fractions, malformed cursors and stored values, and latest-MAX selection. C also checks selected and unselected timestamps beyond its fixed output capacity. Python tests cover grammar, exact chronology, date/offset bounds and missing/strict/permissive optional format checkers through actual document validation.

An independent C production-API probe exercises twelve admitted spellings: +02:00, +14:30, +15:00, lowercase t, Z, lowercase t/z, omitted seconds, +23:59, -23:59, -00:00, and two long fractional forms. Each case uses two sessions in a temporary database, page size one, exact source/cursor equality checks and traversal through exhaustion. It passes normally and under ASan/UBSan.

Full validation passes: 42 desktop tests; eight knowledge Python tests; four timestamp Python tests; JSON/import/catalog validators; three standalone C17 headers; Android unit tests and debug assembly (56 tests, zero failures or errors, one pre-existing missing-fixture skip); two targeted C sanitizer tests plus the timestamp Python test; project skill validation; git diff --check. Logs and reusable runner: /tmp/trainlog-temporal-validation/.

The independent temporal reviewer covered grammar, calendar validity, offset ranges, exact fractions, bytewise ties, cursor aliasing and exclusivity, source capacity, snapshot behavior, and Android/Python parity. It ran the targeted Meson training_context and timestamp_validation tests and all four Python temporal tests. It reported no temporal defect, repair, or unresolved temporal boundary.

Preserved boundaries and remaining scope

Desktop schema v11, Android schema v10, stable IDs, real database logical contents and counts, BODY ZONES, equipment and all scientific catalog bytes remain unchanged. Scientific review stays valid without a scientific delta. No staging, commit, push, database deletion, migration, device installation, uninstall, keystore change or history rewrite occurred.

Older general history/export/MAX-list readers with lexical timestamp ordering are outside this bounded new-reader repair. Leap-event support, arbitrary- length C output and manual device/MTP/visual checks remain explicit future or manual work. The previously recorded secondary-zone-ID TUI presentation inconsistency remains nonblocking. Final-review repair verification and fresh final validation completed with TRAINING_KNOWLEDGE_V1=PASS.