Tracking issue for bitemporal temporal-graph support: an RDF 1.1 annotation-node convention plus in-core ORM support, so a caller can recover the shape of the graph as it stood at any point in time — in both the world's time (valid time) and our belief's time (transaction time). Ships as an **additive minor release**. Existing models compile byte-identically; temporal tracking is opt-in per field. ## Order of work Two gates come first. Nothing that emits a triple should merge before the namespace IRI is decided. | | Ticket | Gate | |---|---|---| | 1 | #105 — publish the design as a spec page | everything cites it | | 2 | ~~#106 — decide the `tg:` namespace IRI~~ | **DECIDED 2026-09-20: `https://w3id.org/sparqlmojo/temporal#`.** Registration and publication are #133, which still gates every triple-emitting ticket | | 3 | ~~#131 — decide what `None` means on a temporal value~~ | **DECIDED 2026-09-20: an unfetched bound raises, so `None` always means the interval is open.** No longer blocking | Then two pieces of **test infrastructure the repo does not have yet**. Both were discovered by reading the code rather than assumed, and both are prerequisites rather than nice-to-haves: - [x] #126 — a golden-SPARQL test harness. There is none today; compiled SPARQL is asserted with inline substrings, which cannot express "nothing changed" - [x] #127 — run the integration tests in CI against a real endpoint. CI has no `services:` block and skips all 99 outbound tests, so every round-trip guarantee below is currently unverified by the pipeline Then the code, in dependency order: - [x] #107 — `sparqlmojo.temporal` subpackage, `TemporalRef` / `TemporalValue[T]` *(implements #131's outcome)* - [x] #108 — temporal **edge** field types *(needs #107; decides whether a public predicate accessor exists)* - [x] #129 — temporal **literal** field types *(needs #108; should be mechanical — say so if it isn't)* - [x] #133 — register the namespace on w3id and publish the vocabulary *(gates every triple-emitting ticket)* - [x] #109 — deterministic annotation-node IRIs *(needs #133)* - [x] #110 — byte-identical current-state compilation *(needs #108, #126; land before any temporal SPARQL)* - [x] #128 — the as-of star join, compiled *(needs #108, #126)* - [x] #111 — `session.at(valid=, belief=)` view and the one-slice guarantee *(needs #128)* - [x] #112 — `session.history()` *(needs #128)* - [ ] #113 — write path: append and commit *(needs #109)* - [ ] #114 — `close_interval()` / `correct()` *(needs #113)* - [ ] #115 — coalescing on commit *(needs #114)* - [ ] #116 — `rematerialize(scope)` *(needs #113)* - [ ] #117 — correlated-subquery compilation in grouped queries *(needs #128, #115)* - [ ] #118 — property-based interval-algebra tests *(needs #114, #115; adds `hypothesis`)* - [ ] #119 — second-engine portability suite *(needs #127)* - [ ] #120 — star-join benchmark *(needs #119)* - [ ] #124 — user-facing feature guide *(last: needs the API to work)* #110 is deliberately early: "existing models compile identically" is what makes this a minor release, so it should be a passing test before there is any temporal SPARQL to break it, not a claim checked at the end. ## Sizing Every implementation ticket carries a **Repo orientation** section with the exact files, symbols and line numbers it touches, so picking one up does not start with a discovery phase. **The yardstick.** This project's largest merged change is **1,560 insertions across 14 files** (#63, CONSTRUCT support). Typical ticket-sized changes are 3–7 files and 70–250 insertions. With a 95% coverage gate, tests are not optional, so a ticket's real cost is roughly source plus two to three times that in tests — the collection-field family is 757 source lines against 2,830 test lines. Four things were found by measuring against that, each an assumption the series had made silently: 1. **No golden-test harness exists** (#126) — "byte-identical" was unstateable without one. 2. **CI runs against no SPARQL endpoint at all** (#127) — so "second engine" (#119) was two tickets wearing one hat, and every round-trip criterion below is currently unverified by the pipeline. 3. **`hypothesis` is not a dependency** (#118 adds it). 4. **The field-types ticket was roughly twice the largest change this repo has shipped.** It asked for four field classes at once; it now covers the two edge types, with the literal ones following the established pattern in #129. Two tickets were split for the same reason: **#128** (the compiled star join) out of **#111** (the view object) — one is SPARQL, the other is API — and **#129** out of **#108**. ## What a dry run found Four tickets were handed to a fresh agent with no context beyond the ticket and the repo, and asked for a plan rather than code. All four came back correctly sized, and #106 stopped and asked instead of deciding — which is what its marker is for. They also found defects that reading the tickets myself had not: - **A second corruption site.** #117 named only the polymorphic path; `select_projections()` is called just as unconditionally at `clauses.py:960` on the ordinary flattened path, so a *non*-polymorphic query mixing a temporal field with a collection field corrupts identically. The ticket's acceptance criteria would have passed with the bug still live. - **A seam owned by nobody.** Splitting the as-of work into #128 and #111 created an interface — what carries the `(valid, belief)` pair onto the `Query` — that neither ticket defined. - **`None` means two incompatible things** (#131), which is a hole in the design, not in a ticket. - **The design document's SPARQL examples used `__vf` suffixes** while the codebase reserves `·` precisely because a double underscore is a legal Python identifier. Two agents flagged it independently. Fixed in the document and the tickets. - **A wrong line reference** in #117 (`field_base.py:167` is `bind_name`; `select_projections` is at `:190`), and a misleading hydration pointer in #128. **The namespace question is closed.** `https://w3id.org/sparqlmojo/temporal#` — chosen so that the *host* stops mattering: w3id is a redirect layer, so the identifier is fixed while its target stays free to move. What remains is mechanical (#133), and nothing that emits a triple should merge until the path actually resolves. **Both human decisions are now closed.** The namespace is `https://w3id.org/sparqlmojo/temporal#` (#106 → #133 to register it), and an unfetched bound raises rather than reporting `None` (#131), so `None` has exactly one meaning across the API. **#132 remains open** — nothing enforces one value at a time for a scalar temporal field — but it constrains the write path rather than the public type, so it does not gate the field types. **Keep temporal logic out of `session.py`.** It is already 1,174 lines, the largest module in the package, and four tickets here touch the write path. The logic belongs in `sparqlmojo/temporal/` with the session wiring into it. ## Also opened along the way (non-blocking) None of these gate the dependency order above; they're gaps found while implementing an already-checked-off ticket, each opened as its own ticket rather than fixed as a drive-by or left as a comment, per this repo's own "ticket, not TODO" convention. - **From #107/#108/#129 (the value types and field types):** #143 (`TemporalRef`/`TemporalValue` construction leaks a bare `TypeError` on mismatched tz-awareness), #144 (post-construction assignment of a bare value on a temporal field fails with an opaque `AttributeError`), #148 (`model_dump_json()` raises on any model holding a `TemporalRef`/`TemporalValue`), #152 (`TemporalValue[T]`'s inner type isn't validated at construction), #153 (temporal literal fields silently drop language tags on read), #150 (`temporal_fields.py` has grown past the ~500-line split threshold). - **From #109 (annotation-node IRIs):** #155 (`mint_annotation_iri`'s `obj: IRI | Literal` parameter is a union of unrelated types, not the classes-over-unions style this repo prefers). - **From #110/#128 (compilation):** #158 (extend #110's byte-identical golden coverage to CONSTRUCT and property-path forms, not just SELECT). - **Toward the write path (#113, not yet started):** #147 (a short-form IRI inside a `TemporalRef` is not expanded against the session's prefix registry on write). - **Hydration:** #151 (`TemporalLiteralList` gives an opaque error on dirty `GROUP_CONCAT` data). - **Docs:** #145 (document the temporal-graph series's public types — narrower than #124's user-facing guide above; the two should land together). ## Deferred, on purpose Not part of this series, and not accidental omissions: temporal property paths (transitive traversal over temporal edges), Allen-algebra filter helpers beyond the two as-of filters, OWL-Time export, and time-windowed grouping ("officers per year"). ## The two things most likely to go wrong 1. **Splitting a temporal tuple across independent aggregates** pairs one interval's value with another interval's bounds — a row that never existed, returned with no error. #117 makes that shape unreachable rather than merely discouraged. 2. **Treating the direct-triple view as self-maintaining.** It is correct as of the last write, not as of now; #116 is what bounds the staleness, and the docs have to say so.