notebook

type Action string

type BackoffWaiter interface {
	Wait(ctx context.Context, attempt int) error
}

type Change struct {
	Path       string
	Kind       ChangeKind
	Insertions int
	Deletions  int
}

type ChangeKind string

type Code string

type Config struct {
	// Workspace is the managed visible path.
	Workspace Workspace
	// Store is the semantic object-store boundary.
	Store storage.ObjectStore
	// ReadOnlyPaths are the notebook-relative read-only entries
	// (architecture/product-contract.md, Read-only and writable paths); New
	// rejects an invalid one.
	ReadOnlyPaths []string
	// WritablePaths are the notebook-relative writable entries. A non-empty
	// set protects every unmatched path (architecture/product-contract.md,
	// Read-only and writable paths); New rejects an invalid entry and a
	// path named by both sets.
	WritablePaths []string
	// RetryLimit bounds CAS retries after the first attempt.
	RetryLimit int
	// CheckpointPacks triggers one checkpoint effort when the active tail
	// length reaches this count.
	CheckpointPacks int
	// RetainedCheckpoints keeps this many previous checkpoint generations
	// as cleanup roots in addition to the active generation.
	RetainedCheckpoints int
	// NewID produces protocol publication and checkpoint IDs.
	NewID func() (storage.UUID, error)
	// Now is the operation-attempt clock for commit timestamps.
	Now func() time.Time
	// Waiter sleeps between CAS retries; nil uses bounded full-jitter
	// exponential backoff. Tests inject a deterministic waiter.
	Waiter BackoffWaiter
	// Failpoints injects deterministic failures; nil disables injection.
	Failpoints *Failpoints
}

type Error struct {
	Code     Code
	Reason   Reason
	Action   Action
	Message  string
	Files    []ErrorFile
	Recovery *RecoveryReport
	Cause    error
}

type ErrorFile struct {
	Path   string
	Reason FileReason
	Ranges []git.MarkerRange
}

type Failpoints struct {
	// CAS fires after the manifest CAS accepted the proposal and before
	// the local acceptance begins. A failure leaves the remote accepted
	// and P/L unadvanced: the exact window the generic recovery path
	// repairs, with remote acceptance known to be yes.
	CAS func() error
}

type FileReason string

type History struct {
	Entries []LogEntry
	// More reports that older publications exist beyond Entries, or were
	// dropped by a checkpoint.
	More bool
}

type LogEntry struct {
	Message string
}

type Metrics struct {
	// TailCount is the active increment count of the last observed
	// authoritative manifest. Retained tails do not count.
	TailCount atomic.Uint64
	// TailBytes is the sum of the active increment pack sizes of the last
	// observed authoritative manifest.
	TailBytes atomic.Uint64

	// CheckpointRuns counts scheduled checkpoint efforts.
	CheckpointRuns atomic.Uint64
	// CheckpointFailures counts checkpoint efforts that ended without a
	// successful manifest replacement. The failure never changes an
	// already accepted commit result.
	CheckpointFailures atomic.Uint64
	// CheckpointCASAttempts counts manifest CAS attempts by checkpoint
	// workers.
	CheckpointCASAttempts atomic.Uint64
	// CheckpointSize is the byte size of the last successfully indexed
	// checkpoint pack.
	CheckpointSize atomic.Uint64
	// CheckpointDurationNanos is the wall duration of the last successful
	// checkpoint effort, from selection to manifest acceptance.
	CheckpointDurationNanos atomic.Int64

	// CleanupRuns counts cleanup runs after a successful checkpoint CAS.
	CleanupRuns atomic.Uint64
	// CleanupCandidates counts listed pack keys at or before the cleanup
	// cutoff.
	CleanupCandidates atomic.Uint64
	// CleanupDeleted counts pack keys deleted by cleanup.
	CleanupDeleted atomic.Uint64
	// CleanupErrors counts failed delete batches and aborted cleanup
	// runs. A failed batch may have deleted part of its keys; the
	// semantic boundary cannot name them, so the error is recorded at
	// batch granularity and retried on a later checkpoint cleanup.
	CleanupErrors atomic.Uint64
}

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

type Reason string

type RecoveryReport struct {
	Stage          string
	RemoteAccepted RemoteAccepted
	Resynchronized bool
}

type RemoteAccepted string

type Result struct {
	Generation uint64
	Stat       git.DiffStat
}

type Status struct {
	// Generation is the accepted remote generation; zero before the first pull.
	Generation uint64
	// Pulled reports whether the directory has been pulled, which a commit requires.
	Pulled bool
	// RecoveryRequired reports that the next pull or commit resynchronizes
	// the directory first. Changes is empty then: the directory is not compared.
	RecoveryRequired bool
	// Changes lists the local changes sorted by path.
	Changes []Change
}

type Workspace interface {
	Hold(ctx context.Context) (context.Context, func(), error)
	Snapshot(ctx context.Context) (git.Snapshot, error)
	Baseline() workspace.Baseline
	Repo() git.Repository
	Accept(ctx context.Context, baseline workspace.Baseline) error
	Materialize(ctx context.Context, baseline workspace.Baseline, tree git.OID) error
	Recover(ctx context.Context, baseline workspace.Baseline) error
	RecoveryRequired() bool
	CacheDir() string
	Pulled() bool
	MarkPulled(ctx context.Context) error
}