conversationview

package
v0.1.0 Latest Latest
Warning

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

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

Documentation

Overview

Package conversationview provides mutable steering CRUD/state, placement and anchor-missing policies, writer/registrar services, persistence and store contracts, and feature diagnostics outside the core conversation projection kernel.

Index

Constants

View Source 
const (
	StageEarly      = conversationprojection.StageEarly
	StageFinal      = conversationprojection.StageFinal
	StageSDKResolve = conversationprojection.StageSDKResolve
)

Stage constants for projection failure/success diagnostics (bounded).

View Source 
const (
	MaxNeverBackendTags   = 4096
	MaxActiveOverlays     = 64
	MaxSteeringTextBytes  = 64 * 1024
	MaxTotalSteeringBytes = 256 * 1024
	MaxReasonCodeBytes    = 64
	MaxOverlayIDBytes     = 128
	MaxALegIDBytes        = 256
)

Bounds from requirements 3.4 and 9.17.

View Source 
const (
	PlacementStablePrefix      = conversationprojection.PlacementStablePrefix
	PlacementAfterMessage      = conversationprojection.PlacementAfterMessage
	AnchorStablePrefixFallback = conversationprojection.AnchorStablePrefixFallback
	AnchorFailClosed           = conversationprojection.AnchorFailClosed
)

Re-exported placement and policy constants.

View Source 
const DefaultMaxLegs = 100000

Variables

View Source 
var (
	// ErrALegNotFound is returned when conversation-view state is requested for an unknown A-leg.
	ErrALegNotFound = conversationprojection.ErrALegNotFound

	// ErrInvalidALegID is returned when an A-leg identifier is missing or malformed.
	ErrInvalidALegID = errors.New("conversationview: invalid a-leg id")

	// ErrInvalidTagRequest is returned when a TagRequest fails validation.
	ErrInvalidTagRequest = errors.New("conversationview: invalid tag request")

	// ErrTagLimitExceeded is returned when a tag mutation would exceed the 4096 unique-identity cap.
	ErrTagLimitExceeded = errors.New("conversationview: never_backend tag limit exceeded")

	// ErrInvalidOverlayID is returned when an overlay identifier is missing or exceeds bounds.
	ErrInvalidOverlayID = conversationprojection.ErrInvalidOverlayID

	// ErrInvalidSteeringRequest is returned when a PutSteeringRequest fails validation.
	ErrInvalidSteeringRequest = errors.New("conversationview: invalid steering request")

	// ErrInvalidSteeringMessage is returned when a StoredMessageV1 fails validation.
	ErrInvalidSteeringMessage = conversationprojection.ErrInvalidSteeringMessage

	// ErrInvalidPlacement is returned when a StoredPlacement fails validation.
	ErrInvalidPlacement = conversationprojection.ErrInvalidPlacement

	// ErrInvalidAnchorMissingPolicy is returned when an AnchorMissingPolicy value is invalid.
	ErrInvalidAnchorMissingPolicy = conversationprojection.ErrInvalidAnchorMissingPolicy

	// ErrInvalidReasonCode is returned when a ReasonCode is missing or exceeds bounds.
	ErrInvalidReasonCode = conversationprojection.ErrInvalidReasonCode

	// ErrSteeringLimitExceeded is returned when a steering mutation would exceed a count or byte cap.
	ErrSteeringLimitExceeded = errors.New("conversationview: steering limit exceeded")

	// ErrOverlayNotFound is returned when an overlay cannot be found for deactivation.
	ErrOverlayNotFound = conversationprojection.ErrOverlayNotFound

	// ErrRevisionExhausted is returned when a revision counter would overflow.
	ErrRevisionExhausted = errors.New("conversationview: revision exhausted")

	// ErrSteeringAnchorExcluded is returned when a steering registration would newly bind an
	// after_message anchor whose identity is already never_backend at the atomic persistence point.
	ErrSteeringAnchorExcluded = errors.New("conversationview: steering anchor identity is never_backend")

	// Re-exported kernel projection and safety errors.
	ErrNonMessageItem             = conversationprojection.ErrNonMessageItem
	ErrEmptyMessage               = conversationprojection.ErrEmptyMessage
	ErrInvalidRole                = conversationprojection.ErrInvalidRole
	ErrInvalidMessageIdentity     = conversationprojection.ErrInvalidMessageIdentity
	ErrInvalidMessageAnchor       = conversationprojection.ErrInvalidMessageAnchor
	ErrAnchorNotFound             = conversationprojection.ErrAnchorNotFound
	ErrPartialContentNotSupported = conversationprojection.ErrPartialContentNotSupported
	ErrAnchorMissing              = conversationprojection.ErrAnchorMissing
	ErrProjectionFailed           = conversationprojection.ErrProjectionFailed
	ErrTerminalUserNotFound       = conversationprojection.ErrTerminalUserNotFound
	ErrTerminalNotUser            = conversationprojection.ErrTerminalNotUser
)
View Source 
var (
	Project                       = conversationprojection.Project
	Reassert                      = conversationprojection.Reassert
	FilterNeverBackend            = conversationprojection.FilterNeverBackend
	MessageIdentityOf             = conversationprojection.MessageIdentityOf
	ItemIdentityOf                = conversationprojection.ItemIdentityOf
	ComputeItemAnchors            = conversationprojection.ComputeItemAnchors
	ComputeCallAnchors            = conversationprojection.ComputeCallAnchors
	ResolveAfterIngressTailAnchor = conversationprojection.ResolveAfterIngressTailAnchor
	NewProjectionSummary          = conversationprojection.NewProjectionSummary
)

Re-exported kernel projection functions.

Functions

func EnsureSchema 

func EnsureSchema(ctx context.Context, db *bun.DB) error

EnsureSchema creates the continuity tables and conversation view tables if not present.

func RegistersNewAfterMessageAnchor 

func RegistersNewAfterMessageAnchor(req PutSteeringRequest, exists, placementChanged bool) bool

RegistersNewAfterMessageAnchor reports whether this request would newly bind a fixed after_message anchor at the persistence point.

func ValidateOverlayID 

func ValidateOverlayID(id string) error

func ValidateReasonCode 

func ValidateReasonCode(r ReasonCode) error

ReasonCode validation.

Types

type AnchorMissingPolicy 

type AnchorMissingPolicy = conversationprojection.AnchorMissingPolicy

Re-exported kernel types and DTOs.

type BunStore 

type BunStore struct {
	// contains filtered or unexported fields
}

BunStore is the Bun-backed persistence adapter for conversation view. All operations run under the A-leg row lock so snapshot and mutations are linearizable per A-leg and follow A-leg deletion atomically.

func NewBunStore 

func NewBunStore(db *bun.DB) *BunStore

NewBunStore creates a Bun-backed conversation view store.

func (*BunStore) CreateALeg 

func (m *BunStore) CreateALeg(ctx context.Context, aLegID string) error

CreateALeg creates an A-leg row if not already present (primarily for tests).

func (*BunStore) DB 

func (m *BunStore) DB() *bun.DB

DB returns the underlying Bun DB handle.

func (*BunStore) DeactivateSteering 

func (m *BunStore) DeactivateSteering(ctx context.Context, aLegID string, overlayID string) (SteeringState, error)

DeactivateSteering marks an overlay inactive.

func (*BunStore) DeleteALeg 

func (m *BunStore) DeleteALeg(ctx context.Context, aLegID string) error

DeleteALeg deletes an A-leg row (cascades conversation view data).

func (*BunStore) GetOverlay 

func (m *BunStore) GetOverlay(ctx context.Context, aLegID, overlayID string) (SteeringOverlay, error)

GetOverlay returns a stored overlay (used in tests and inspection).

func (*BunStore) PutSteering 

func (m *BunStore) PutSteering(ctx context.Context, aLegID string, req PutSteeringRequest) (SteeringState, error)

PutSteering creates or replaces a steering overlay.

func (*BunStore) Snapshot 

func (m *BunStore) Snapshot(ctx context.Context, aLegID string) (conversationprojection.Snapshot, error)

Snapshot returns a deep-owned coherent snapshot for the A-leg. Legacy legs with no state row read as empty revision 0.

func (*BunStore) TagNeverBackend 

func (m *BunStore) TagNeverBackend(ctx context.Context, aLegID string, tags []TagRequest) (TagResult, error)

TagNeverBackend atomically tags a batch of identities.

type CacheDiscontinuityKind 

type CacheDiscontinuityKind string

CacheDiscontinuityKind is the bounded cache-discontinuity operation recorded for steering mutations. 

const (
	CacheDiscontinuityNone       CacheDiscontinuityKind = "none"
	CacheDiscontinuityCreate     CacheDiscontinuityKind = "create"
	CacheDiscontinuityReplace    CacheDiscontinuityKind = "replace"
	CacheDiscontinuityMove       CacheDiscontinuityKind = "move"
	CacheDiscontinuityDeactivate CacheDiscontinuityKind = "deactivate"
)

func (CacheDiscontinuityKind) Validate 

func (k CacheDiscontinuityKind) Validate() error

type FallbackEvidence 

type FallbackEvidence = conversationprojection.FallbackEvidence

Re-exported kernel types and DTOs.

type MessageAnchor 

type MessageAnchor = conversationprojection.MessageAnchor

Re-exported kernel types and DTOs.

type MessageIdentity 

type MessageIdentity = conversationprojection.MessageIdentity

Re-exported kernel types and DTOs.

type NopObserver 

type NopObserver struct{}

NopObserver is a no-op Observer.

func (NopObserver) OnAnchorFailure 

func (NopObserver) OnAnchorFailure(AnchorMissingPolicy)

func (NopObserver) OnAnchorFallback 

func (NopObserver) OnAnchorFallback(string, AnchorMissingPolicy)

func (NopObserver) OnProjection 

func (NopObserver) OnProjection(string, ProjectionSummary)

func (NopObserver) OnProjectionFailure 

func (NopObserver) OnProjectionFailure(string)

func (NopObserver) OnSteeringMutation 

func (NopObserver) OnSteeringMutation(CacheDiscontinuityKind, PlacementKind)

type Observer 

type Observer interface {
	conversationprojection.Observer
	OnSteeringMutation(kind CacheDiscontinuityKind, placement PlacementKind)
}

Observer is an optional narrow callback for bounded, content-free diagnostics. Implementations must not log or label by OverlayID, ALegID, digest, or plaintext. All label values are bounded enums only: reason_class, placement, operation, policy, stage. Stage values are bounded: "early", "final", "sdk_resolve". Operation values are CacheDiscontinuityKind (create, replace, move, deactivate). Placement values are PlacementKind (stable_prefix, after_message). Policy values are AnchorMissingPolicy (stable_prefix_fallback, fail_closed). Nil observer is a no-op. All callbacks must be panic-isolated by callers via SafeObserver.

func SafeObserver 

func SafeObserver(o Observer) Observer

SafeObserver returns a panic-isolated wrapper. Nil returns NopObserver. All Observer callbacks are recovered so no observer panic can affect request or mutation.

type Overlay 

type Overlay = conversationprojection.Overlay

Re-exported kernel types and DTOs.

type OverlayID 

type OverlayID = string

OverlayID alias for documentation; validated as bounded identifier.

type OverlayMessage 

type OverlayMessage = conversationprojection.OverlayMessage

Re-exported kernel types and DTOs.

type OverlayProvenance 

type OverlayProvenance = conversationprojection.OverlayProvenance

Re-exported kernel types and DTOs.

type Placement 

type Placement = conversationprojection.Placement

Re-exported kernel types and DTOs.

type PlacementKind 

type PlacementKind = conversationprojection.PlacementKind

Re-exported kernel types and DTOs.

type ProjectionEvidence 

type ProjectionEvidence = conversationprojection.ProjectionEvidence

Re-exported kernel types and DTOs.

type ProjectionSummary 

type ProjectionSummary = conversationprojection.ProjectionSummary

Re-exported kernel types and DTOs.

type PutSteeringRequest 

type PutSteeringRequest struct {
	OverlayID           string              `json:"overlay_id"`
	Message             StoredMessageV1     `json:"message"`
	Placement           StoredPlacement     `json:"placement"`
	AnchorMissingPolicy AnchorMissingPolicy `json:"anchor_missing_policy"`
	Reason              ReasonCode          `json:"reason"`
}

PutSteeringRequest is the writer-facing steering mutation.

func (PutSteeringRequest) Validate 

func (r PutSteeringRequest) Validate() error

type Reader 

type Reader = conversationprojection.Reader

Re-exported kernel types and DTOs.

func AsReader 

func AsReader(v any) (Reader, bool)

AsReader reports whether v implements the optional conversation-view reader capability.

type ReasonCode 

type ReasonCode = conversationprojection.ReasonCode

Re-exported kernel types and DTOs.

type ReferenceStore 

type ReferenceStore struct {
	// contains filtered or unexported fields
}

ReferenceStore is an in-memory Store used to pin contract semantics.

func NewReferenceStore 

func NewReferenceStore() *ReferenceStore

NewReferenceStore creates an empty store.

func NewReferenceStoreWithClock 

func NewReferenceStoreWithClock(now func() time.Time) *ReferenceStore

NewReferenceStoreWithClock creates a store with a deterministic clock (test use).

func (*ReferenceStore) CreateALeg 

func (s *ReferenceStore) CreateALeg(ctx context.Context, aLegID string) error

CreateALeg registers an A-leg for conversation-view state.

func (*ReferenceStore) DeactivateSteering 

func (s *ReferenceStore) DeactivateSteering(ctx context.Context, aLegID string, overlayID string) (SteeringState, error)

DeactivateSteering marks an overlay inactive.

func (*ReferenceStore) DeleteALeg 

func (s *ReferenceStore) DeleteALeg(ctx context.Context, aLegID string) error

DeleteALeg removes all conversation-view state for an A-leg.

func (*ReferenceStore) GetOverlay 

func (s *ReferenceStore) GetOverlay(ctx context.Context, aLegID string, overlayID string) (SteeringOverlay, error)

GetOverlay is a test/debugging helper to inspect an overlay regardless of active state.

func (*ReferenceStore) PutSteering 

func (s *ReferenceStore) PutSteering(ctx context.Context, aLegID string, req PutSteeringRequest) (SteeringState, error)

PutSteering creates or replaces a steering overlay.

func (*ReferenceStore) SetMaxLegs 

func (s *ReferenceStore) SetMaxLegs(maxLegs int)

SetMaxLegs configures the maximum concurrent A-legs retained in memory.

func (*ReferenceStore) Snapshot 

func (s *ReferenceStore) Snapshot(ctx context.Context, aLegID string) (Snapshot, error)

Snapshot returns a deep-owned coherent snapshot.

func (*ReferenceStore) TagNeverBackend 

func (s *ReferenceStore) TagNeverBackend(ctx context.Context, aLegID string, tags []TagRequest) (TagResult, error)

TagNeverBackend atomically tags a batch of identities.

type Snapshot 

type Snapshot = conversationprojection.Snapshot

Re-exported kernel types and DTOs.

type Stage 

type Stage = conversationprojection.Stage

Re-exported kernel types and DTOs.

type SteeringOverlay 

type SteeringOverlay struct {
	OverlayID           string              `json:"overlay_id"`
	Revision            uint64              `json:"revision"`
	SlotOrdinal         uint64              `json:"slot_ordinal"`
	Active              bool                `json:"active"`
	Message             StoredMessageV1     `json:"message"`
	Placement           StoredPlacement     `json:"placement"`
	AnchorMissingPolicy AnchorMissingPolicy `json:"anchor_missing_policy"`
	Reason              ReasonCode          `json:"reason"`
	CreatedAt           time.Time           `json:"created_at"`
	UpdatedAt           time.Time           `json:"updated_at"`
}

SteeringOverlay is a persisted steering record.

func (SteeringOverlay) Clone 

func (o SteeringOverlay) Clone() SteeringOverlay

func (SteeringOverlay) ToProjectionOverlay 

func (o SteeringOverlay) ToProjectionOverlay() conversationprojection.Overlay

func (SteeringOverlay) Validate 

func (o SteeringOverlay) Validate() error

type SteeringState 

type SteeringState struct {
	OverlayID                   string                 `json:"overlay_id"`
	Revision                    uint64                 `json:"revision"`
	SlotOrdinal                 uint64                 `json:"slot_ordinal"`
	Active                      bool                   `json:"active"`
	StateRevision               uint64                 `json:"state_revision"`
	CacheDiscontinuityKind      CacheDiscontinuityKind `json:"cache_discontinuity_kind,omitempty"`
	CacheDiscontinuityPlacement PlacementKind          `json:"cache_discontinuity_placement,omitempty"`
}

SteeringState is the post-mutation steering summary.

type SteeringStore 

type SteeringStore interface {
	PutSteering(ctx context.Context, aLegID string, req PutSteeringRequest) (SteeringState, error)
	DeactivateSteering(ctx context.Context, aLegID string, overlayID string) (SteeringState, error)
}

func AsSteeringStore 

func AsSteeringStore(v any) (SteeringStore, bool)

AsSteeringStore reports whether v implements the optional steering store capability.

type Store 

type Store interface {
	Reader
	Tagger
	SteeringStore
}

Store is the combined port for implementations.

func AsStore 

func AsStore(v any) (Store, bool)

AsStore reports whether v implements the optional conversation-view store capability.

type StoredMessageV1 

type StoredMessageV1 struct {
	Role lipapi.Role `json:"role"`
	Text string      `json:"text"`
}

StoredMessageV1 is the persisted model-visible steering payload.

func (StoredMessageV1) Equal 

func (m StoredMessageV1) Equal(other StoredMessageV1) bool

func (StoredMessageV1) Validate 

func (m StoredMessageV1) Validate() error

type StoredPlacement 

type StoredPlacement struct {
	Kind   PlacementKind  `json:"kind"`
	Anchor *MessageAnchor `json:"anchor,omitempty"`
}

StoredPlacement is the persisted placement for a steering overlay.

func (StoredPlacement) Validate 

func (sp StoredPlacement) Validate() error

type Tag 

type Tag = conversationprojection.Tag

Re-exported kernel types and DTOs.

type TagRequest 

type TagRequest struct {
	Identity MessageIdentity `json:"identity"`
	Reason   ReasonCode      `json:"reason"`
}

TagRequest is one element of a TagNeverBackend batch.

func (TagRequest) Validate 

func (r TagRequest) Validate() error

type TagResult 

type TagResult struct {
	StateRevision uint64 `json:"state_revision"`
	Tags          []Tag  `json:"tags"`
}

TagResult is returned from a successful TagNeverBackend call.

type Tagger 

type Tagger interface {
	TagNeverBackend(ctx context.Context, aLegID string, tags []TagRequest) (TagResult, error)
}

func AsTagger 

func AsTagger(v any) (Tagger, bool)

AsTagger reports whether v implements the optional conversation-view tagger capability.

Source Files

View all Source files

Directories

Path Synopsis
Package sdkadapter bridges trusted SDK contracts to the authoritative conversation-view domain ports.
 Package sdkadapter bridges trusted SDK contracts to the authoritative conversation-view domain ports.
Package storecontract holds reusable contract tests for conversationview.Store implementations (ReferenceStore, MemoryStore, Bun).
 Package storecontract holds reusable contract tests for conversationview.Store implementations (ReferenceStore, MemoryStore, Bun).

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.