Documentation
¶
Overview ¶
Package session owns cumulative short-term execution memory. Serving and embedding share its admission, checkpoint, journal and historical projection implementation. It persists through StateStore and resolves result references through ArtifactStore; it does not own another transcript or long-term memory.
The package is below runtime composition so memory inspection and mutation can use the same owner without importing run-context assembly. Planner policy and governed compaction remain outside this package. Historical evidence never grants authority to repeat an action, and recovery refuses unknown outcomes.
Index ¶
- Variables
- func Delete(ctx context.Context, store state.StateStore, id identity.Quadruple, key string, ...) (int, error)
- func Put(ctx context.Context, store state.StateStore, redactor audit.Redactor, ...) (string, error)
- func ReconcileRetainedRun(ctx context.Context, store state.StateStore, redactor audit.Redactor, ...) error
- func ValidateRetainedInputs(requested []string, resolved []planner.InputArtifactView) error
- type Inspection
- type Item
- type RetainedRun
- func (r *RetainedRun) AfterDispatch(ctx context.Context, rc planner.RunContext, step planner.Step) (err error)
- func (r *RetainedRun) Apply(base *planner.RunContext) error
- func (r *RetainedRun) BeforeDispatch(ctx context.Context, rc planner.RunContext, step planner.Step) (err error)
- func (r *RetainedRun) CompactionRequired() bool
- func (r *RetainedRun) Finish(ctx context.Context, tr *planner.Trajectory, query, answer, status string) error
- func (r *RetainedRun) GuardPlanner(inner planner.Planner, store artifacts.ArtifactStore) planner.Planner
- func (r *RetainedRun) RecordContext(ctx context.Context, rc planner.RunContext, step planner.Step) (err error)
- func (r *RetainedRun) Start(ctx context.Context, base planner.RunContext) (err error)
Constants ¶
This section is empty.
Variables ¶
var ( // continuity to a fresh or partially restored conversation. ErrRetainedContextUnavailable = errors.New("run context: retained execution context unavailable") // ErrRetainedContextCapacity means evidence cannot fit the bounded window. // A caller must not blindly repeat writes after an execution-time failure. ErrRetainedContextCapacity = errors.New("run context: retained execution context capacity exceeded") )
var ErrItemNotFound = errors.New("session memory: item not found")
ErrItemNotFound does not distinguish an absent key from a foreign one.
var ErrRetainedContextUnsettled = fmt.Errorf("%w: external dispatch outcome is unknown", ErrRetainedContextUnavailable)
ErrRetainedContextUnsettled refuses recovery while an external action may be in flight or its outcome was never committed. Reconcile with the owning service; neither this error nor a restart is permission to repeat the action.
Functions ¶
func Delete ¶
func Delete(ctx context.Context, store state.StateStore, id identity.Quadruple, key string, now func() time.Time) (int, error)
Delete removes one currently visible source/checkpoint with a conditional write. A derived checkpoint is invalidated wholesale when affected: an opaque summary cannot prove selective forgetting. All frozen admissions are fenced, so inference/dispatch/late settlement cannot reintroduce erased material. Other sessions and their admissions are untouched. No external action runs.
func Put ¶
func Put(ctx context.Context, store state.StateStore, redactor audit.Redactor, id identity.Quadruple, query, answer string, turns int, ttl time.Duration, now func() time.Time) (string, error)
Put records an administrator-supplied conversation note, not a tool result or execution authority. It has no inference or side effects. Capacity is checked before publication; it never drops unsummarized turns to make a note fit.
func ReconcileRetainedRun ¶
func ReconcileRetainedRun(ctx context.Context, store state.StateStore, redactor audit.Redactor, q identity.Quadruple, turns int, now func() time.Time) error
ReconcileRetainedRun explicitly seals an abandoned, fully settled journal as interrupted context. The caller must own the full identity triple. The atomic terminal write fences the source admission before any future dispatch can commit intent. No historical action, model request, or completion hook runs. Pending actions are refused; this is not a cold-run resume operation.
func ValidateRetainedInputs ¶
func ValidateRetainedInputs(requested []string, resolved []planner.InputArtifactView) error
ValidateRetainedInputs prevents opt-in continuity from silently accepting an input that the legacy best-effort materializer omitted. Non-retained callers keep their existing input policy. The guard separately verifies current scope and lifetime before inference and dependent dispatch.
Types ¶
type Inspection ¶
Inspection is one bounded read of the same state used for execution. It is not another persisted transcript. Active runs expose no uncommitted content.
type Item ¶
Item is a read projection of committed memory, never an admission or journal. Value is already redacted at the execution boundary. It must still use the consumer's ordinary heavy-value and identity protections.
type RetainedRun ¶
type RetainedRun struct {
// contains filtered or unexported fields
}
RetainedRun is a run-local handle on a bounded, identity-scoped execution window. It is not long-term memory, a transcript API, or an execution-relaunch capability. Different handles share only the existing conditional StateStore. Start and dispatch callbacks persist query/intent/settlement in a bounded private run journal. Cold action replay or automatic reacquisition is not authorized by this handle or by a retained admission.
func BeginRetainedRun ¶
func BeginRetainedRun(ctx context.Context, store state.StateStore, redactor audit.Redactor, q identity.Quadruple, turns int, ttl time.Duration, now func() time.Time) (*RetainedRun, error)
BeginRetainedRun explicitly opts one run into retained execution-context retention. Admission freezes the preceding terminal window and establishes a conditional erasure fence before any model/tool work. Zero is not an enable value: callers leave this helper unwired when retention is disabled.
func (*RetainedRun) AfterDispatch ¶
func (r *RetainedRun) AfterDispatch(ctx context.Context, rc planner.RunContext, step planner.Step) (err error)
AfterDispatch commits the entire permitted result/error before a dependent model decision. Its context may be a bounded post-cancellation persistence context, but it can never start or retry an external action.
func (*RetainedRun) Apply ¶
func (r *RetainedRun) Apply(base *planner.RunContext) error
Apply supplies history as non-executable, lower-trust evidence entries. Tagged historical exchanges reuse native rendering; legacy entries remain inert text. The same compactor may summarize older history. The caller must omit legacy conversation-memory projection for this retained-context run.
func (*RetainedRun) BeforeDispatch ¶
func (r *RetainedRun) BeforeDispatch(ctx context.Context, rc planner.RunContext, step planner.Step) (err error)
BeforeDispatch commits intent before any external invocation. A frame without a settlement means outcome unknown, not failed. A parallel decision is one complete exchange: partial branch execution remains unknown after a crash.
func (*RetainedRun) CompactionRequired ¶
func (r *RetainedRun) CompactionRequired() bool
CompactionRequired reports admission-time turn pressure on the detailed history. It does not compact or renew retention. The run loop uses its ordinary compactor before the first decision, outside persistence deadlines and locks. Token pressure is governed by the configured working-input budget, not the byte size of retained exact evidence.
func (*RetainedRun) Finish ¶
func (r *RetainedRun) Finish(ctx context.Context, tr *planner.Trajectory, query, answer, status string) error
Finish stores exactly this run's terminal evidence, never the inherited window. Incomplete executions are labeled as possibly having unrecorded outcomes; no stored action is replayed. It must be called only after the active execution has returned and any final answer has been validated. A failed required write remains an error even when side effects succeeded.
func (*RetainedRun) GuardPlanner ¶
func (r *RetainedRun) GuardPlanner(inner planner.Planner, store artifacts.ArtifactStore) planner.Planner
GuardPlanner keeps retained evidence behind its current admission and erasure checks at decision boundaries. It preserves the planner's existing request- context marker rather than selecting a different compaction path.
func (*RetainedRun) RecordContext ¶
func (r *RetainedRun) RecordContext(ctx context.Context, rc planner.RunContext, step planner.Step) (err error)
RecordContext commits one applied, non-executable context update. It shares the ordered bounded journal with dispatches; a failed write cannot be repaired by continuing with forgotten instructions. The caller appends the same step to the live trajectory only after this write succeeds.
func (*RetainedRun) Start ¶
func (r *RetainedRun) Start(ctx context.Context, base planner.RunContext) (err error)
Start commits the admitted query before model or tool work. It creates a private run-local journal, not another public transcript. Each later dispatch writes only one bounded frame plus this small head through SaveBatchIf.
Source Files