Help us shape the future of Go! Take the 2026 Go Developer Survey

protocol

package
v1.33.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 23, 2026 License: Apache-2.0 Imports: 13 Imported by: 0

Documentation

Overview

Administrative memory mutations use the same owner as inspection and execution. The transport validates identity and admin authority; the owner validates source identity and atomically fences stale context publication.

Package protocol projects the memory owner's authoritative inspection through the existing admin-scoped memory routes. Cumulative checkpoints, recent execution and retained evidence are one bounded read, never a second stored transcript. The owner supplies stable keys and performs conditional mutations. Heavy values remain subject to the Protocol's existing artifact boundary.

Index

Constants

This section is empty.

Variables

View Source
var ErrContextLeak = errors.New("memory/protocol: heavy memory value reached the response path as raw inline bytes")

ErrContextLeak — Get materialised a memory record value whose byte length meets or exceeds the heavy-content threshold but the value reached the response path as raw inline bytes rather than an ArtifactStub. Mirrors `llm.ErrContextLeak` (CLAUDE.md §13): a heavy value MUST route through the bounded artifact read by reference; an inline heavy value is a leak and is failed loudly, never truncated.

View Source
var ErrInvalidFilter = errors.New("memory/protocol: invalid memory.list filter")

ErrInvalidFilter — a memory.list filter carried a structurally invalid value: an unknown scope / driver / strategy enum, or a negative page / page-size. The caller maps this onto `CodeInvalidRequest`. Fails loudly — a malformed filter is never a silently-dropped facet (CLAUDE.md §13).

View Source
var ErrPageOutOfRange = errors.New("memory/protocol: page/page_size out of range")

ErrPageOutOfRange — a memory.list request asked for a page-size above the documented maximum (or a negative page / page-size). Distinct from ErrInvalidFilter so the caller can render a precise message; both map onto `CodeInvalidRequest`.

Functions

func Delete added in v1.3.0

Delete removes the named source through the owner. Cumulative deletion invalidates an affected checkpoint and fences frozen admissions; it never blindly restores a stale snapshot or claims selective summary forgetting.

func Get

Get answers the `memory.get` Protocol method: it resolves a single memory record by key within the caller's identity scope and returns the full detail — metadata + post-redaction value (below the heavy-content threshold) OR a `MemoryArtifactRef` (at or above it).

Identity is mandatory. Heavy values return a source-bound reference resolved by artifacts.get against current memory, without making a separately retained artifact copy. EXACTLY ONE of Value / ValueArtifact is populated on success.

A key that resolves to no record returns `memory.ErrNotFound` — the caller maps it onto `CodeNotFound`.

func Health

Health answers the `memory.health` Protocol method: it returns the aggregate memory-health counters (total records / identity-rejected-24h / recovery-dropped-24h) plus the per-scope driver mapping.

Identity is mandatory: an incomplete triple on id fails loudly with `memory.ErrIdentityRequired`. The record counters derive from the caller's per-identity inspection; the 24-hour event counters derive from the events Aggregator (when wired); the driver mapping derives from the configured per-scope driver split.

func List

List answers the `memory.list` Protocol method: it projects the caller's per-identity memory inspection into the Console-page row shape, applies the request's facet filters, paginates, and attaches the aggregate counters.

Identity is mandatory: an incomplete triple on id fails loudly with `memory.ErrIdentityRequired`. The cross-tenant scope gate is the caller's job (the stream handler checks `auth.HasScope` before calling List) — by the time List runs the request is authorised; List filters strictly within the supplied identities.

The filter's facets are validated up front: an unknown scope / driver / strategy enum, or a page / page-size out of range, fails loudly (ErrInvalidFilter / ErrPageOutOfRange) — never a silently dropped facet (CLAUDE.md §13).

func Put added in v1.3.0

Put records an operator note and returns its committed, resolvable key.

func StrategyTrace added in v1.3.0

StrategyTrace reports the checkpoint and bounded recent tail used by execution.

Types

type DeleteDeps added in v1.3.0

type DeleteDeps struct {
	// Store is the memory store the turn is evicted from. Mandatory.
	Store memory.MemoryStore
	// Bus is the events bus the audit event publishes on. Optional.
	Bus events.EventBus
}

DeleteDeps carries the Delete dependencies.

type GetDeps

type GetDeps struct {
	// Store supplies the committed execution-memory projection.
	Store memory.MemoryStore
	// DriverName is the configured memory-driver name surfaced on the
	// returned row.
	DriverName string
	// HeavyThreshold is the inline-payload bound in bytes — the runtime
	// supplies the pinned Console inline-payload bound, NOT the
	// operator's LLM-context `artifacts.heavy_output_threshold_bytes`,
	// because the selected arm of this reply is Protocol-visible. A
	// value whose byte length meets or exceeds it routes through the
	// source-bound artifact read. A non-positive threshold fails loud (a zero
	// threshold would route every value).
	HeavyThreshold int
}

GetDeps carries the dependencies Get composes over.

type HealthDeps

type HealthDeps struct {
	// Store supplies the current execution-memory inspection.
	Store memory.MemoryStore
	// Aggregator is the events Aggregator the 24-hour counters derive
	// from. Optional — see ListDeps.Aggregator.
	Aggregator *events.Aggregator
	// DriverByScope is the configured per-scope driver mapping —
	// e.g. {"session":"inmem", "tenant":"postgres"}. The caller
	// supplies it from config; the MemoryStore interface does not
	// expose a per-scope driver split. When unset, Health reports a
	// single-scope mapping for the session scope under DriverName.
	DriverByScope map[string]string
	// DriverName is the configured memory-driver name, used to seed a
	// single-scope DriverByScope mapping when DriverByScope is unset.
	DriverName string
}

HealthDeps carries the dependencies Health composes over.

type ListDeps

type ListDeps struct {
	// Store supplies the committed execution-memory projection.
	Store memory.MemoryStore
	// Aggregator is the events Aggregator the 24-hour counters derive
	// from. Optional — when nil, the IdentityRejected24h /
	// RecoveryDropped24h counters are reported as 0 (the page still
	// renders; the right-rail cards subscribe to the live event stream
	// for the real-time view). The driver-comparison + record counters
	// do not depend on it.
	Aggregator *events.Aggregator
	// DriverName is the configured memory-driver name surfaced on each
	// row (`inmem` / `sqlite` / `postgres`). The MemoryStore interface
	// does not expose it; the caller supplies it from config.
	DriverName string
	// HeavyThreshold is the inline-payload bound in bytes — the runtime
	// supplies the pinned Console inline-payload bound, NOT the
	// operator's LLM-context `artifacts.heavy_output_threshold_bytes`.
	// It is the single classification point for the per-row
	// HeavyContent flag; `memory.list` and `memory.get` MUST agree, so
	// both read the same threshold. A zero / non-positive value disables the flag (no row
	// is reported heavy) — the list still renders.
	HeavyThreshold int
}

ListDeps carries the dependencies List composes over. All are validated at the call site (the stream handler) — a nil Store fails loud rather than nil-panicking mid-projection.

type PutDeps added in v1.3.0

type PutDeps struct {
	// Store is the memory store the turn is appended to. Mandatory.
	Store memory.MemoryStore
	// Bus is the events bus the audit event publishes on. Optional — a
	// nil bus skips the emit (test wiring); production always supplies it.
	Bus events.EventBus
}

PutDeps carries the Put dependencies.

type StrategyTraceDeps added in v1.3.0

type StrategyTraceDeps struct {
	// Store is the memory store the trace projects from. Mandatory.
	Store memory.MemoryStore
}

StrategyTraceDeps carries the StrategyTrace dependencies.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL