1.0 stability commitment

Sakshi is currently 0.x and the package's own changelog reserves the right to break public API in any minor release. This document declares what changes at 1.0 and which parts of the surface hosts can plan around now.

The commitment

When 1.0.0 ships:

1. SemVer applies. Every name exported in sakshi.__all__ is part of the public API. Breaking changes (rename, removal, signature change, behavior change that an existing caller could observe) are reserved for the next major version.
2. Deprecations before removal. Anything destined for removal in a future major must emit a DeprecationWarning in at least one prior minor release. Removal in the immediate next major is permitted, but the warning must be visible at runtime — not only in release notes.
3. Protocols are contracts. Any symbol classified as a Protocol (in sakshi.protocols and sakshi.meta) keeps its method signatures stable across minors. Hosts that implement these protocols today should keep working unchanged across the entire 1.x series.
4. No silent default changes. Any change to a default value or default policy that would alter agent behavior requires a minor release and a CHANGELOG entry under ### Changed.

This document is the source of truth — the same wording goes into the PyPI long description for 1.0.0 itself.

Surface classification

The categories below are informational. After 1.0, both tiers follow SemVer; the distinction is only how aggressively each is likely to evolve.

STABLE

Battle-tested through real integration paths in the package's own tests. These are the recommended pin points for production hosts.

Category	Symbols
Protocols	BasinHook, Clock, EventBus, GoalStateStore, WriteGuard
Protocol defaults	NoOpBasinHook, NoOpEventBus, AlwaysPermitWriteGuard, DenyByDefaultWriteGuard
Error hierarchy	SakshiError, AnomalyEscalationError, GoalValidationError, PhaseTransitionError, PlanSoundnessError, WorldStateUnavailableError
Cycle primitives	PhaseRegistry, LastNPruner, SinceAnomalyPruner, WhereExpectationFiredPruner, TracePruner
Intervention layer	InterventionExecutor, InterventionPermissionPolicy, AlwaysPermitPolicy, DenyByDefaultPolicy, InterventionRecord, InterventionDecision, InterventionType, InterventionOutcome
Goal lifecycle	GoalEvent, GoalEventType, GoalMode
Defensive guards	RewardIntegrityGuard, EvidenceRequiringRewardIntegrityGuard, ModificationIntegrityGuard, IntegrityCriticalModificationGuard, GuardVerdict, GuardDecision, GuardAuditRecord, make_audit_record
Planning core	Action, GoalConstraint, TaskDecomposer
Meta	__version__

PROVISIONAL

Functional and tested, but newer or more domain-specific. Expected to keep their shapes across 1.x, but if real-world usage surfaces problems these are the symbols most likely to gain a deprecation cycle.

Category	Symbols
Stuck-loop / deliberation	CanalizationMetrics, CanalizationRisk, DeliberationGate, DeliberationDecision, DeliberationPath
Confidence + calibration	CalibrationTracker, CalibrationReport, CalibrationWarning, ConfidenceObservation
Confusion weighting	ConfusionWeighter, ConfusionDecision
Risk	AnticipatoryRiskScorer, PlanRisk, PlanRiskAssessment, RiskBand, RiskModel
Lineage	GoalLineageAuditor, LineageReport, LineageVerdict
Failure-mode classification	TRAPDimension, TRAPRouter, classify_failure_mode
Creativity envelope	CreativityEnvelope, EnvelopeVerdict, evaluate_envelope
Motivation surface	MotivationAuditor, MotivationEvent, MotivationType, ComputationalMotivationMetrics, KnowledgeRewardBalance, biases_toward_exploration, biases_against_exploration
Two-axis trust	TrustReport, TrustBifurcation, TrustRepairAction, TrustRepairRecommendation
Uncertainty typing	UncertaintyBoundary, UncertaintyType
Expectations	ExpectationProfile
Anomaly typing	AnomalySourceType, FailureMode
Discrepancy	DiscrepancyResolution, ResolutionLevel
Transparency	ProjectionTransparency, ReasoningTransparency, StatusTransparency, TransparencyLevel
Goal operations	GoalOperation, GoalOperationEvent, GoalRelevanceFilter
Scheduling	EveryCyclePolicy, OnAnomalyPolicy, ThrottledByLoadPolicy, MetaSchedulingPolicy, SchedulingDecision
Rebel hook	RebelHook, RebelDecision, RebelVerdict, AcceptingRebelHook

What is not public

Anything not in sakshi.__all__ is internal. That includes module paths like sakshi.cycle.blackboard.CognitiveBlackboard — even if it is technically importable, the SemVer commitment does not extend to it. Hosts should import from the package top level.

Reaching 1.0

Two soft prerequisites still in flight:

1. One non-toy reference integration in examples/. The toy_blocks_agent proves the seams; a more realistic example (LLM-driven cognition, multi-goal recovery) validates that the defaults survive contact with real cognition.
2. One quarter of stability on the STABLE tier. No breaking changes to anything in the STABLE table for a full minor-release cycle before 1.0 ships.

When both are true, the next minor cuts as 1.0.0 and this document becomes binding.