Documentation
¶
Overview ¶
Package sessionclassification owns the session-classification feature policy.
Index ¶
- Constants
- Variables
- func RoundRemoteDeadlineUpToMicrosecond(deadline time.Time) time.Time
- func ValidateKey(key Key) error
- func ValidatePositiveProposal(proposal session.Classification) error
- func ValidateStoreContext(ctx context.Context) error
- func ValidateStoreTime(now time.Time) error
- type Config
- type HeuristicConfig
- type Key
- type LocalDecision
- type Mode
- type Record
- type RemoteClaim
- type RemoteCompletion
- type RemoteConfig
- type ScopeKind
- type Store
Constants ¶
const ( // MaxIgnoredUserAgentPrefixes bounds the configured literal exclusion list. MaxIgnoredUserAgentPrefixes = 16 // MaxIgnoredUserAgentPrefixBytes caps each normalized exclusion prefix. MaxIgnoredUserAgentPrefixBytes = 128 // MaxWorkspaceMarkers bounds marker inspection for one evaluation. MaxWorkspaceMarkers = 32 // MaxWorkspaceMarkerBytes caps each workspace marker inspected by policy. MaxWorkspaceMarkerBytes = 128 // MaxRemoteAttemptsPerSession bounds configured remote attempts. MaxRemoteAttemptsPerSession = 5 // MinRemoteTimeout is the smallest allowed remote timeout. MinRemoteTimeout = time.Millisecond // MaxRemoteTimeout caps a single remote decision timeout. MaxRemoteTimeout = 30 * time.Second // MaxRemoteLeaseTTL bounds the shared remote decision lease. MaxRemoteLeaseTTL = 2 * time.Minute // MaxRemoteRetryBackoff bounds the delay between remote attempts. MaxRemoteRetryBackoff = 30 * time.Second // RemoteLeaseSafetyMargin ensures lease expiry follows the hard timeout. RemoteLeaseSafetyMargin = 100 * time.Millisecond )
const ( // MaxAuthorityIDBytes bounds proxy-owned identifiers retained by this feature. MaxAuthorityIDBytes = 256 // MaxRemoteLeaseIDBytes bounds the opaque control token for a remote attempt. MaxRemoteLeaseIDBytes = 64 )
const ID = "session-classification"
Variables ¶
var ( // ErrNoAuthority means the session view contains no proxy-owned scope. ErrNoAuthority = errors.New("session classification: no proxy authority") // ErrInvalidKey means an authority key is malformed or outside its fixed bound. ErrInvalidKey = errors.New("session classification: invalid authority key") // ErrInvalidProposal means a promotion is not a valid positive classification. ErrInvalidProposal = errors.New("session classification: invalid positive proposal") // ErrInvalidRemoteOptions means a remote attempt limit or duration is outside its finite bounds. ErrInvalidRemoteOptions = errors.New("session classification: invalid remote claim bounds") // ErrStoreCapacity means a new authoritative record cannot be admitted without evicting retained state. ErrStoreCapacity = errors.New("session classification: store capacity reached") // ErrStaleRemoteClaim means a completion no longer owns the active remote lease. ErrStaleRemoteClaim = errors.New("session classification: stale remote claim") // ErrInvalidRemoteClaim means a remote completion token is malformed. ErrInvalidRemoteClaim = errors.New("session classification: invalid remote claim") // ErrInvalidStoreContext means a store operation received a nil context. ErrInvalidStoreContext = errors.New("session classification: nil store context") // ErrInvalidStoreTime means a store operation received a zero timestamp. ErrInvalidStoreTime = errors.New("session classification: invalid store time") // ErrLeaseNonce means the bounded lease nonce could not be created or validated. ErrLeaseNonce = errors.New("session classification: remote lease nonce unavailable") // ErrLeaseSequenceExhausted means the process-local lease sequence has no remaining values. ErrLeaseSequenceExhausted = errors.New("session classification: remote lease sequence exhausted") // ErrInvalidStoreConfig means the in-memory adapter bounds are invalid. ErrInvalidStoreConfig = errors.New("session classification: invalid memory store bounds") )
Functions ¶
func RoundRemoteDeadlineUpToMicrosecond ¶
RoundRemoteDeadlineUpToMicrosecond rounds a remote lease or retry deadline upward to the shared durable timestamp precision. Keeping expiry deadlines aligned lets SQLite, PostgreSQL, and memory stores enforce identical eligibility boundaries without allowing a deadline to expire early.
func ValidateKey ¶
ValidateKey checks the bounded opaque authority without normalizing it.
func ValidatePositiveProposal ¶
func ValidatePositiveProposal(proposal session.Classification) error
ValidatePositiveProposal checks that a promotion contains a valid positive snapshot.
func ValidateStoreContext ¶
ValidateStoreContext rejects nil contexts and propagates cancellation.
func ValidateStoreTime ¶
ValidateStoreTime rejects an absent timestamp before it enters state.
Types ¶
type Config ¶
type Config struct {
Mode Mode
Heuristic HeuristicConfig
Remote *RemoteConfig
}
type HeuristicConfig ¶
type HeuristicConfig struct {
IgnoredUserAgentPrefixes []string
}
type Key ¶
Key scopes feature state to one proxy-owned secure session or A-leg. ScopeKind is part of the key so equal ID bytes from different authorities do not share state.
func ResolveKey ¶
func ResolveKey(view session.SessionView) (Key, error)
ResolveKey prefers the proxy-owned secure session ID and falls back to the proxy-owned A-leg only when the secure session ID is exactly empty. It never reads ClientSessionHint and never rewrites an authoritative ID.
type LocalDecision ¶
type LocalDecision struct {
Promotes bool
Preserves bool
Source session.ClassificationSource
EvidenceCode session.EvidenceCode
ClientFamily agentfacts.Family
}
LocalDecision contains bounded policy facts without manufacturing persisted classification state or a revision.
func EvaluateLocal ¶
func EvaluateLocal(cfg Config, input sdkclassification.Input) LocalDecision
EvaluateLocal evaluates accepted client identity, canonical tool categories, and the bounded recognized marker snapshot. It never reads transcript, model, route, workspace root, or raw tool-name data.
type Record ¶
type Record struct {
Key Key
Classification session.Classification
RemoteAttempts uint32
RemoteLeaseID string
RemoteLeaseUntil time.Time
RemoteNextEligibleAt time.Time
UpdatedAt time.Time
}
Record is the bounded persisted feature state for one authority key. It contains classification and remote-control metadata only.
type RemoteClaim ¶
RemoteClaim proves ownership of one leased remote attempt. RetryBackoff is captured with the claim so completion can start backoff at completion time; abandoned claims become eligible again as soon as their lease expires.
type RemoteCompletion ¶
type RemoteCompletion struct {
Proposal session.Classification
}
RemoteCompletion carries only a validated positive proposal. The zero value represents a below-threshold, unavailable, or otherwise non-positive result.
type RemoteConfig ¶
type ScopeKind ¶
type ScopeKind string
ScopeKind identifies which proxy-owned authority issued an opaque ID.
type Store ¶
type Store interface {
Load(ctx context.Context, key Key) (Record, bool, error)
Promote(ctx context.Context, key Key, proposal session.Classification, now time.Time) (record Record, promoted bool, err error)
ClaimRemote(ctx context.Context, key Key, now time.Time, maxAttempts uint32, leaseTTL time.Duration, retryBackoff time.Duration) (claim RemoteClaim, record Record, ok bool, err error)
CompleteRemote(ctx context.Context, claim RemoteClaim, result RemoteCompletion, now time.Time) (Record, error)
}
Store is the consumed feature-owned persistence contract. Implementations must preserve first-positive-wins semantics and make remote lease operations atomic for each authority key.
Directories
¶
| Path | Synopsis |
|---|---|
|
Package testfixtures exposes the shared, data-driven evidence matrix used by session-classification acceptance tests.
|
Package testfixtures exposes the shared, data-driven evidence matrix used by session-classification acceptance tests. |