Add time travel capability using @ syntax in query URIs

[bplatz]

Time travel queries via @ syntax in FQL graph URIs

Sits on top of: #1087 (branch name consistency)
Prerequisite of: #1096 (branch implementation)
Prerequisite of: #1095 (brach merge, rebase, reset)

Summary

Adds time travel to database queries using @ in from and from-named to select historical states by transaction number, ISO-8601 timestamp, or commit SHA.

Motivation

• Clear, URL/IRI-friendly syntax for time travel queries with a concrete resource name (not requiring query params)
• Consistent with reserved @ semantics and upcoming branching support.

Supported formats

• @t:<tx>: transaction number
  • Example: my-ledger@t:42
• @iso:<timestamp>: ISO-8601 wall-clock time
  • Example: my-ledger@iso:2025-07-01T00:00:00Z
• @sha:<commit>: commit SHA (base32 SHA-256 with leading b)
  • Examples: my-ledger@sha:bb6rql... (full), my-ledger@sha:bb6rql (prefix, ≥6 chars)

Works with branches:

• my-ledger:main@t:42

Works with federated datasets:

• from-named: ["g1@t:10", "g2"]

Behavior

• SHA handling:
  • Accepts full base32 SHA-256 with leading b (51–52 chars).
  • Partial prefixes allowed (minimum 6 chars).
  • Ambiguous prefixes return 400 :db/ambiguous-commit-sha.
  • Not found returns 400 :db/invalid-commit-sha.
• Missing values (e.g., @t:, @iso:, @sha:) return 400 :db/invalid-time-travel.
• ISO lookup returns the most recent commit at or before the provided time; if none exists, returns 400 “no data as of …”.
• Federated queries:
  • Top-level t must be ISO-8601 wall-clock time.
  • Per-graph time travel via @ on each alias.

Implementation details

• Time travel protocol extended:
  • sha->t for SHA-based lookups.
• Parsing:
  • extract-query-string-t in fluree.db.query.api parses @ syntax on from/from-named.
• SHA normalization:
  • Supports only fluree:commit:sha256:b prefix form (when present) or a value starting with b.
  • Full SHAs use a direct query; prefixes use an index range scan.
  • Enforces minimum 6-char prefix.
• Creation-time validation:
  • Ledger names reject : and @ to avoid ambiguity and reserve @ for time travel.

Testing

• Coverage for all three formats: @t, @iso, @sha.
• Controlled ISO tests to ensure stable comparisons.
• SHA tests include full hashes and prefix matching.
• Negative cases: missing spec values, invalid formats, not found, and ambiguous prefixes.

Backward compatibility

• Existing queries continue to work. @-based time travel is additive; legacy ?t= remains supported but is superseded when @ is present.

[dpetran]

Could you expound a bit on why we need the new syntax instead of query params? I think we can still support sha t and iso via that syntax, and having two ways to do it makes users have to decide which to use, and I'm not clear that there's a technical benefit of one over the other.

[bplatz]

Could you expound a bit on why we need the new syntax instead of query params? I think we can still support sha t and iso via that syntax, and having two ways to do it makes users have to decide which to use, and I'm not clear that there's a technical benefit of one over the other.

I think the difference is probably bigger than it is, but query params are for queries... this is a concrete resource (a db), so using query parameters I think breaks the semantics of URLs and resources.

With this change we can represent a db resource as a full IRI/URL when combined with a host... not that query params couldn't be used as well but I don't think that is the right way of doing it.

I think we can use query params for lots of things... like some of the items we currently support in 'opts' could be great candidates and I think that would be a correct use of query params. But at least I don't believe it was a good use to identify a concrete resource.

[zonotope]

🏷️

[zonotope]

another nitpick, but i think this comment should end with :branch instead of @branch.