Package com.tnsai.rag

Class KnowledgeScope

java.lang.Object
com.tnsai.rag.KnowledgeScope
All Implemented Interfaces:
AutoCloseable
public final class KnowledgeScope extends Object implements AutoCloseable
Explicit lifetime for source snapshots shared by retrieval and ordered knowledge consumption.

A scope is opened by its host, attached to the agents or bridges that should see the same snapshot, and closed when that host is replaced. An operation that can outlive the host must hold a KnowledgeScope.Lease for its full turn. Closing the scope rejects new turns immediately but releases its resources only after the last previously acquired lease ends. Nested work on the same thread may acquire another lease after close; work on a new thread must have acquired its own lease before close.

This controls knowledge-source lifetime only. It does not grant access to a source or replace retrieval tenant identity, authorization, or path confinement.

Since:
0.17.4

  • Method Details

    • open

      public static KnowledgeScope open()
      Opens a new, independent knowledge-source lifetime.

    • acquire

      public KnowledgeScope.Lease acquire()
      Begins one turn or operation. Close the returned lease on the same thread, including on exceptional exits.
      Throws:
      IllegalStateException - if the scope is closed and this thread does not already hold a lease acquired before close

    • current

      public static Optional<KnowledgeScope> current()
      Scope held by the innermost lease on this thread, if any. Framework helpers use this only for calls made from an action body; dispatch across threads must still carry its scope explicitly.

    • currentLease

      public static Optional<KnowledgeScope.Lease> currentLease()
      Active lease on this thread for explicit worker propagation.

    • isClosed

      public boolean isClosed()
      Whether this scope has received a close request.

    • state

      public <T extends AutoCloseable> T state(Class<T> type, Supplier<? extends T> factory)
      Returns a lazily created resource owned by this scope. Framework modules use distinct state classes so their source caches and cursors are released together when this scope's final lease ends.
      Throws:
      IllegalStateException - if the scope is closed outside an already active lease

    • close

      public void close()
      Rejects new turns and releases resources after all existing leases end. Repeated close calls have no effect.
      Specified by:
      close in interface AutoCloseable