Package com.tnsai.intelligence.rag.temporal

Class TemporalIndex

java.lang.Object
com.tnsai.intelligence.rag.temporal.TemporalIndex
public final class TemporalIndex extends Object
Immutable temporal document index.

The identity snapshot is computed once, on first use, and cached. Callers that select Strategy.TEMPORAL must force the full structural check with validate() before retrieval enters its failure-policy boundary: malformed temporal metadata is a configuration fault, not a transport failure, so it must not be routed through @Search.onFailure.

Since:
0.13.0

  • Constructor Details

    • TemporalIndex

      public TemporalIndex(List<RetrievedDocument> documents)
      Creates an index over documents carrying temporal metadata.
      Parameters:
      documents - source documents in declaration order

  • Method Details

    • documents

      public List<RetrievedDocument> documents()
      Returns the source documents in declaration order.
      Returns:
      immutable source document list

    • size

      public int size()
      Returns the validated number of unique documents.
      Returns:
      index size

    • validate

      public void validate()
      Checks every structural invariant this index can decide from its own documents: canonical identity, duplicate entry IDs, and the presence and ISO-8601 syntax of every declared TemporalMetadata.TIMESTAMP.

      Whether a document carries a unique entry ID and a parseable timestamp is fixed by the Role's knowledge sources and the installed SourceLoaders, never by request data, so this runs at strategy-selection time — above the @Search.onFailure guard, the same rule rerankerModel, queryExpansionModel, GraphStoreProvider resolution and hierarchy validation follow. Routing malformed temporal metadata through the guard would let CONTINUE emit a silently ungrounded action that reports success and USE_CACHE answer it from a stale entry, for what is a deployment fault.

      Clock-relative faults are deliberately excluded. Whether a timestamp exceeds the tolerated future skew depends on the retrieval instant rather than on configuration — the same index turns valid as wall-clock time advances — so that check stays a runtime concern and still reaches the guard from retrieve(). Failures raised while traversing a valid index do the same.

      Throws:
      TemporalException - when any structural invariant is violated

    • find

      public Optional<RetrievedDocument> find(String id)
      Resolves an indexed document by entry ID.
      Parameters:
      id - canonical entry ID
      Returns:
      matching document, if present

    • identifier

      public String identifier(RetrievedDocument document)
      Resolves the canonical entry ID carried by a child hit.
      Parameters:
      document - indexed document or child hit
      Returns:
      non-blank entry ID, falling back to the document source

    • timestamp

      public Optional<Instant> timestamp(String id)
      Parses the canonical timestamp for one resolved entry.
      Parameters:
      id - canonical entry ID
      Returns:
      timestamp, or empty when the document is intentionally undated

    • sourceGroup

      public String sourceGroup(RetrievedDocument document)
      Resolves the source group used for source fencing.
      Parameters:
      document - indexed document
      Returns:
      temporal source metadata, or document source as fallback