errs

Documentation

Overview

Package errs holds every sentinel error of the Scrinium engine. One package, one source of truth — anything matched via errors.Is/errors.As lives here.

Why a flat shared package and not per-layer files (core/errors.go, domain/errors.go, driver/driver.go) — sentinels are part of the public contract, not of the implementation that returns them. `Walk`'s ErrStopWalk is the same idea regardless of whether it surfaces from the storage core or from a driver-level list call; `ErrUnsupportedURIScheme` originates in a driver but is matched by callers two layers up. Splitting the same identity into per-layer duplicates with `var X = otherpkg.X` re-exports has been tried and produced exactly the kind of confusion this package is meant to remove.

Files in this package are organised by domain (manifest, store lifecycle, lease, etc.) so the package stays scannable as it grows. Callers that need only one or two errors are still fine — Go's import system makes the file split transparent.

DAG note: errs is a leaf package, the same as event. It imports only stdlib. driver, domain, core all import errs; nothing imports the other direction.

Index

• Variables

Variables

var ErrAgentAlreadyRunning = errors.New("scrinium: agent already running")

ErrAgentAlreadyRunning — Run was called again on an already running agent.

var ErrAgentNotRunning = errors.New("scrinium: agent not running")

ErrAgentNotRunning — command-style methods (ForceCommit, Eject, Trigger, TakeSnapshot, ...) called on an agent whose Run is not active.

var ErrArchivedArtifact = errors.New("scrinium: archived artifact")

ErrArchivedArtifact — the artifact is reachable only through a Backup with ReadPolicy: Never; AllowColdRead is required.

var ErrArtifactNotFound = newBridgedSentinel(
	"scrinium: artifact not found", fs.ErrNotExist,
)

ErrArtifactNotFound — no manifest with the given ArtifactID exists in the Store, or it is a ManifestTypePack (an internal type that does not exist for the client). Bridges to fs.ErrNotExist for host code that handles missing artifacts the same way as missing files.

var ErrArtifactUnreadable = errors.New("scrinium: projection artifact unreadable")

ErrArtifactUnreadable — the artifact is physically present but cannot be read in the current state (Store Locked, Corrupted, pipeline misconfiguration). Original error via errors.Unwrap.

var ErrConfigMismatch = errors.New("scrinium: config mismatch")

ErrConfigMismatch — an attempt to change an immutable parameter through UpdateConfig, or a conflict between the cfg passed to OpenStore and the configuration loaded from system.config/current, or an attempt to remove NoDelete while DeletionPolicyLock is in effect.

var ErrCorruptedBlob = errors.New("scrinium: corrupted blob")

ErrCorruptedBlob — the hash of the physical blob does not match its BlobRef.

var ErrCorruptedConfigPointer = errors.New("scrinium: corrupted config pointer")

ErrCorruptedConfigPointer — system.config/current exists but is invalid (empty, oversized, malformed ArtifactID).

var ErrCorruptedContent = errors.New("scrinium: corrupted content")

ErrCorruptedContent — after the inverse Pipeline the hash does not match ContentHash.

var ErrCorruptedManifest = errors.New("scrinium: corrupted manifest")

ErrCorruptedManifest — the hash of the manifest file does not match its ArtifactID.

var ErrCuratorClosed = errors.New("scrinium: curator closed")

ErrCuratorClosed — operation issued on a closed Curator.

var ErrDanglingConfigPointer = errors.New("scrinium: dangling config pointer")

ErrDanglingConfigPointer — the pointer is syntactically valid but the artifact it references does not exist.

var ErrDecryptionFailed = errors.New("scrinium: decryption failed")

ErrDecryptionFailed — the key was found but decryption failed (wrong key, corrupted bytes, authentication-tag failure).

var ErrDeletionForbidden = errors.New("scrinium: deletion forbidden")

ErrDeletionForbidden — Delete on a Store with DeletionPolicy: NoDelete.

var ErrDescriptorSplitBrain = errors.New("scrinium: descriptor split-brain (L0 and L1 diverged at the same sequence)")

ErrDescriptorSplitBrain — L0 and L1 are both valid, hold different content, and carry the same Sequence number. The engine cannot pick a winner without external input: a higher Sequence on either side would have made it the canonical version, but identical sequences mean two writers produced divergent descriptors with no causal order.

Recovery is manual: the operator inspects both replicas and either picks one explicitly (overwriting both) or falls back to the Recovery Kit through RebuildIndexAgent.

var ErrDrainNoTarget = errors.New("scrinium: drain has no target")

ErrDrainNoTarget — at Drain time the Router returned an empty target list; follow-up behaviour is determined by OnDrainNoTarget.

var ErrEditingDisabled = newBridgedSentinel(
	"scrinium: projection editing disabled", fs.ErrPermission,
)

ErrEditingDisabled — an editing operation (rename, setattr, truncate, append) was attempted while the corresponding policy bit is off, or any mutation was attempted on a read-only FSOps. Bridges to fs.ErrPermission; surfaces translate to EROFS (FUSE) or 403 (WebDAV).

var ErrEjectorQueueFull = errors.New("scrinium: ejector queue full")

ErrEjectorQueueFull — Ejector.Eject called while the task queue is already full.

var ErrEmptySessionID = errors.New("scrinium: empty session ID")

ErrEmptySessionID — RollbackSession called with an empty string; guards against a mass deletion of sessionless artifacts.

var ErrFUSENotSupported = errors.New("scrinium: FUSE not supported in this build")

ErrFUSENotSupported — MountFUSE called without the `fuse` build tag.

var ErrHostStorageFull = errors.New("scrinium: host storage full")

ErrHostStorageFull — HostStorage hit its hard limit while OnHostStorageFull: Reject was in effect; soft eviction was insufficient.

var ErrHostStorageLocked = errors.New("scrinium: host storage locked by another process")

ErrHostStorageLocked — Curator startup aborted: the WorkspaceDir of the transit buffer is held by another process (OS-level lock).

var ErrHostStorageRequired = errors.New("scrinium: HostStorage required for ManifestStorage=Local")

ErrHostStorageRequired — RebuildIndexAgent.Validate with ManifestStorage: Local without a HostStorage passed in. See docs/2. Internals/10 §10.4.2 step 3.

var ErrIndexCorrupted = errors.New("scrinium: index corrupted")

ErrIndexCorrupted — the StoreIndex is missing or its checksum does not match.

var ErrIndexSchemaMismatch = errors.New("scrinium: index schema mismatch")

ErrIndexSchemaMismatch — the StoreIndex schema version is incompatible with the running binary.

var ErrIngesterNoState = errors.New("scrinium: ingester watch mode requires StateFile")

ErrIngesterNoState — NewIngester invoked with Mode: Watch but no StateFile configured.

var ErrInjected = errors.New("scrinium: injected fault")

ErrInjected is the sentinel returned by the faulty test driver for a deliberately injected fault. Test code asserts errors.Is(err, ErrInjected) to confirm a fault landed.

Lives in errs (rather than driver/faulty) so that a test outside the faulty package can match the sentinel without importing the driver subpackage just for that.

var ErrInvalidConfig = errors.New("scrinium: invalid config")

ErrInvalidConfig — a StoreConfig parameter is out of range or violates the Rules Engine.

var ErrInvalidKDFParams = errors.New("scrinium: invalid KDF params")

ErrInvalidKDFParams — KDFParams fail the minimum-validity check: Time < 1, Memory < 19456 KiB, Threads < 1.

var ErrInvalidKey = errors.New("scrinium: invalid key")

ErrInvalidKey — the KEK does not decrypt the DEK: wrong password or corrupted EncryptedDEK.

var ErrInvalidPath = newBridgedSentinel(
	"scrinium: projection invalid path", fs.ErrInvalid,
)

ErrInvalidPath — the path is malformed (forbidden characters, absolute when relative is required, etc.).

var ErrInvalidRecoveryKey = errors.New("scrinium: invalid recovery key")

ErrInvalidRecoveryKey — failed to decrypt the DEK from the Recovery Kit.

var ErrInvalidTombstoneGracePeriod = errors.New("scrinium: invalid tombstone grace period")

ErrInvalidTombstoneGracePeriod — TombstoneGracePeriod < 1h. A dedicated sentinel because this is the only param with runtime implications for multi-host safety.

var ErrIsADirectory = newBridgedSentinel(
	"scrinium: projection is a directory", fs.ErrInvalid,
)

ErrIsADirectory — Open on a path that points to a directory. Bridges to fs.ErrInvalid for the same reason as ErrNotADirectory.

var ErrKeyNotFound = errors.New("scrinium: key not found")

ErrKeyNotFound — the KeyResolver does not know the key for the requested KeyID.

var ErrLeaseHeld = errors.New("scrinium: lease held")

ErrLeaseHeld — an attempt to acquire a lease held by an active owner.

var ErrLeaseLost = errors.New("scrinium: lease lost")

ErrLeaseLost — the lease was lost in flight or right after a takeover (concurrent steal).

var ErrLocked = errors.New("scrinium: store locked")

ErrLocked — the operation was invoked in StateLocked on an encrypted store. Unlock is required. NOT used for closed stores — those return os.ErrClosed; conflating the two confused Plain-store users into searching for a passphrase.

var ErrMaintenanceInProgress = errors.New("scrinium: maintenance in progress")

ErrMaintenanceInProgress — another Maintenance Agent holds the lease.

var ErrManifestTooLarge = errors.New("scrinium: manifest too large")

ErrManifestTooLarge — serialised Manifest > 1 MB.

var ErrManifestsLost = errors.New("scrinium: manifests lost")

ErrManifestsLost — RebuildIndexAgent did not find any manifests: ManifestStorage: Local with the local disk lost and no HostStorage available.

var ErrMetaKeyNotFound = errors.New("scrinium: meta key not found")

ErrMetaKeyNotFound — the requested key is missing in store_meta.

var ErrMetadataTooLarge = errors.New("scrinium: metadata too large")

ErrMetadataTooLarge — Artifact.Metadata > 64 KB.

var ErrMissingConfigPointer = errors.New("scrinium: missing config pointer")

ErrMissingConfigPointer — system.config/current is absent.

var ErrNamespaceTooLong = errors.New("scrinium: namespace too long")

ErrNamespaceTooLong — namespace > 255 bytes.

var ErrNoSnapshot = errors.New("scrinium: no valid snapshot for Source=Snapshot")

ErrNoSnapshot — RebuildIndexAgent.Validate with Source: Snapshot when no valid snapshots are available.

var ErrNotADirectory = newBridgedSentinel(
	"scrinium: projection not a directory", fs.ErrInvalid,
)

ErrNotADirectory — List on a path that points to a file. Bridges to fs.ErrInvalid (mirrors the historical vfs.WrapErr translation; surfaces map fs.ErrInvalid to ENOTDIR themselves).

var ErrNotEmpty = newBridgedSentinel(
	"scrinium: projection directory not empty", fs.ErrInvalid,
)

ErrNotEmpty — Rmdir on a directory that has children. Bridges to fs.ErrInvalid (mirrors vfs.WrapErr); translates to ENOTEMPTY at the FUSE layer.

var ErrNotImplemented = errors.New("scrinium: not implemented")

ErrNotImplemented signals that a method or branch is part of the declared public surface but its implementation has not landed yet. Distinct from forward-compat sentinels (ErrUnsupportedEncoding, ErrUnsupportedCrypto), which mark "this binary does not support that format" — ErrNotImplemented says "no binary supports this path yet".

Returned (wrapped, with concrete context) by stub bodies of types that exist for compile-time DAG enforcement: agents, the projection layer, chunker / bundler decorators, the curator's constructor — anywhere the M0 contract has a signature but the flesh arrives at M3 or later.

Tests that exercise stubs match against this with errors.Is.

var ErrPassphraseAlreadySet = errors.New("scrinium: passphrase already set (use RotateKEK to change it)")

ErrPassphraseAlreadySet — Store.SetPassphrase was called on a Store whose DEK is already wrapped. The intended path for rotating the passphrase is RotateKEK, which proves possession of the current passphrase before accepting the new one.

Returned only by SetPassphrase; the unwrap-then-wrap flow of RotateKEK does not surface it.

var ErrPassphraseProvider = errors.New("scrinium: passphrase provider error")

ErrPassphraseProvider — the provider returned an error. Wraps the underlying cause (available through errors.Unwrap).

var ErrPassphraseRequired = errors.New("scrinium: passphrase required")

ErrPassphraseRequired — the operation needs a KEK but WithPassphrase was not configured. Also returned by ExportRecoveryKit on a ManifestCrypto: Plain Store.

var ErrPathExists = newBridgedSentinel(
	"scrinium: projection path already exists", fs.ErrExist,
)

ErrPathExists — Create/Mkdir at a path that is already taken (real artifact or pending directory). Bridges to fs.ErrExist; translates to EEXIST at the FUSE layer.

var ErrPathNotFound = newBridgedSentinel(
	"scrinium: projection path not found", fs.ErrNotExist,
)

ErrPathNotFound — Get/Open at a non-existent virtual path. Bridges to fs.ErrNotExist so host code can errors.Is against the standard-library sentinel without knowing scrinium specifics.

var ErrRandomAccessNotSupported = errors.New("scrinium: random access not supported")

ErrRandomAccessNotSupported — ReadAt/ReadAtCtx was called on a stream that does not support random access.

var ErrRecoveryKitCorrupted = errors.New("scrinium: recovery kit corrupted")

ErrRecoveryKitCorrupted — the Recovery Kit is corrupted (the checksum does not match).

var ErrRecoveryKitRequired = errors.New("scrinium: RecoveryKit required (descriptor lost, encrypted store)")

ErrRecoveryKitRequired — RebuildIndexAgent.Validate with the Store in Corrupted after every descriptor replica has been lost and RecoveryKit is nil in the configuration.

var ErrReservedNamespace = errors.New("scrinium: reserved namespace")

ErrReservedNamespace — an attempt to use "*" or the "system." prefix without a CapabilityToken.

var ErrRetentionNotExpired = errors.New("scrinium: retention not expired")

ErrRetentionNotExpired — Delete or RollbackSession on an artifact with an active RetentionUntil.

var ErrScratchQuota = newBridgedSentinel(
	"scrinium: projection scratch quota exceeded", fs.ErrPermission,
)

ErrScratchQuota — FSOps.Create/Write would exceed the configured scratch quota. Bridges to fs.ErrPermission (host surfaces map it to ENOSPC); the bridge keeps "is it permission-class?" answers uniform across editing-policy and quota refusals.

var ErrSessionIDTooLong = errors.New("scrinium: session ID too long")

ErrSessionIDTooLong — SessionID > 255 bytes.

var ErrSharedIndexRequired = errors.New("scrinium: shared index required")

ErrSharedIndexRequired — OpenStore on the SQLite backend has found a live foreign location.lock; a shared backend (Postgres) or a clean shutdown of the other process is required.

var ErrSourceUnavailable = errors.New("scrinium: projection source unavailable")

ErrSourceUnavailable — the projection source returned a transient error during backfill or a runtime call. The original error is available via errors.Unwrap.

var ErrStopWalk = errors.New("scrinium: stop walk")

ErrStopWalk is the early-exit sentinel for any iteration callback in the engine: Store.Walk, Store.WalkSystem, StoreIndex.List*, Driver.ListObjectsWithModTime. Returning this from the callback stops the walk without an error — the function returns nil to its caller.

One sentinel covers every walk because the meaning is identical across layers. Splitting it ("driver-level walk" vs "store-level walk") was tried and only forced callers to choose between two values that mean the same thing.

var ErrStoreAlreadyExists = newBridgedSentinel(
	"scrinium: store already exists", fs.ErrExist,
)

ErrStoreAlreadyExists — InitStore without WithForceReinit on top of an existing Store. Bridges to fs.ErrExist.

var ErrStoreCorrupted = errors.New("scrinium: store corrupted")

ErrStoreCorrupted — every descriptor replica is corrupted, or the StoreIndex is corrupted. The Store is in StateCorrupted.

var ErrStoreNotFound = newBridgedSentinel(
	"scrinium: store not found", fs.ErrNotExist,
)

ErrStoreNotFound — OpenStore: no store.json in the Location. Bridges to fs.ErrNotExist so a host can errors.Is(err, fs.ErrNotExist) when probing for an existing store. Distinct from ErrArtifactNotFound (an artifact inside an open Store).

var ErrStoreNotReady = errors.New("scrinium: store not ready")

ErrStoreNotReady — the Store is in StateBootstrapping. The API is blocked until initialisation completes.

var ErrStoreNotRegistered = errors.New("scrinium: store not registered with curator")

ErrStoreNotRegistered — Curator.Store(id) with an unknown id.

var ErrStoreOffline = errors.New("scrinium: store offline")

ErrStoreOffline — MaintenanceModeOffline.

var ErrStoreReadOnly = newBridgedSentinel(
	"scrinium: store read-only", fs.ErrPermission,
)

ErrStoreReadOnly — MaintenanceModeReadOnly + a mutating operation. Bridges to fs.ErrPermission so generic "is this a permission problem?" checks at host layer return true.

var ErrUnknownPackFormat = errors.New("scrinium: unknown pack format")

ErrUnknownPackFormat — the magic bytes of a .pack volume are unrecognised.

var ErrUnsupportedAlgorithm = errors.New("scrinium: unsupported algorithm")

ErrUnsupportedAlgorithm — the algorithm has not been registered in the corresponding registry.

var ErrUnsupportedCrypto = errors.New("scrinium: unsupported manifest crypto")

ErrUnsupportedCrypto — the manifest header carries a ManifestCrypto value (Plain, MetadataOnly, Envelope, or a future addition) that this binary does not implement, or StoreConfig.ManifestCrypto names such a value.

var ErrUnsupportedEncoding = errors.New("scrinium: unsupported manifest encoding")

ErrUnsupportedEncoding — the manifest header carries an encoding magic (\x00SC1\x00 for JSON, \x00SC2\x00 for the binary codec, etc.) that this binary was not built to decode, or StoreConfig.ManifestEncoding names a value not registered in the current build.

var ErrUnsupportedSchemaVersion = errors.New("scrinium: unsupported schema version")

ErrUnsupportedSchemaVersion — the manifest's schema_version is not supported by the running binary.

var ErrUnsupportedURIScheme = errors.New("scrinium: unsupported URI scheme")

ErrUnsupportedURIScheme — the driver does not support the URI scheme passed to Open. Used with BlobStorage: ExternalRef for schemes unknown to the driver.

var ErrViewClosed = errors.New("scrinium: projection view closed")

ErrViewClosed — operation on a closed projection View.

var ErrWebDAVNotSupported = errors.New("scrinium: WebDAV not supported in this build")

ErrWebDAVNotSupported — MountWebDAV called without the `webdav` build tag.