dotc1z

type C1ZFormat int

type C1ZOption func(*c1zOptions)

type DecoderOption func(*decoderOptions) error

type EngineDriver interface {
	Engine() c1zstore.Engine
	Format() C1ZFormat
	OpenStore(ctx context.Context, outputFilePath string, opts StoreOptions) (c1zstore.Store, error)
}

type EnvelopeDecoderPool = formatv3.DecoderPool

type IngestInvariantStore interface {
	// ForEachDistinctGrantEntitlementResource visits each distinct
	// entitlement resource referenced by any grant: one seek per
	// distinct resource, never O(grants).
	ForEachDistinctGrantEntitlementResource(ctx context.Context, visit func(resourceTypeID, resourceID string) error) error

	// GrantsForEntResourceCarryInsertFact reports whether any grant
	// under the entitlement resource carries InsertResourceGrants.
	// Value-reading; reserved for dangling-reference probes.
	GrantsForEntResourceCarryInsertFact(ctx context.Context, resourceTypeID, resourceID string) (bool, error)

	// GrantsForEntitlementAllCarryInsertFact reports whether every grant
	// under the entitlement identity carries InsertResourceGrants — the
	// per-grant side of I8's InsertResourceGrants exemption.
	// Value-reading; reserved for dangling-reference probes.
	GrantsForEntitlementAllCarryInsertFact(ctx context.Context, entitlementID, entResourceTypeID, entResourceID string) (bool, error)

	// HasResourceRecord reports whether a resource row exists.
	HasResourceRecord(ctx context.Context, resourceTypeID, resourceID string) (bool, error)

	// ForEachDistinctEntitlementResource visits each distinct resource
	// referenced by any entitlement row: one seek per distinct
	// resource, never O(entitlements).
	ForEachDistinctEntitlementResource(ctx context.Context, visit func(resourceTypeID, resourceID string) error) error

	// ForEachDanglingGrantEntitlement visits each distinct entitlement
	// referenced by grants that has no entitlement row: one seek plus
	// one point probe per distinct entitlement, never O(grants).
	ForEachDanglingGrantEntitlement(ctx context.Context, visit func(entitlementID, resourceTypeID, resourceID string) error) error

	// EnsureGrantIndexes forces a pending deferred grant-index build to
	// run now, making by_principal complete for the dangling-principal
	// scan. Near-free: the same build would run at EndSync.
	EnsureGrantIndexes(ctx context.Context) error

	// ForEachDanglingGrantPrincipal visits each distinct principal
	// referenced by grants that has no resource row. matchAnnotatedOnly
	// reports that every grant of the principal is an unprocessed
	// ExternalResourceMatch* carrier (exempt shape); carrierGrants is
	// the per-grant count of that population.
	ForEachDanglingGrantPrincipal(ctx context.Context, visit func(principalRT, principalID string, matchAnnotatedOnly bool, carrierGrants int64) error) error
}

type RollbackOption func(*rollbackConfig)

type RollbackResult struct {
	SyncID string
	// GrantsDeleted is the number of purely expander-derived grants
	// removed: their Sources carried only foreign entitlement keys, never
	// a self-source for their own entitlement.
	GrantsDeleted int
	// SourcesCleared is the number of surviving direct grants whose
	// Sources were reset to empty, restoring the pre-expansion shape.
	SourcesCleared int
	// SuspectConnectorSourced counts grants that had Sources but no
	// self-source AND lacked the GrantImmutable annotation that every
	// expander-created grant carries — a shape that looks connector-set
	// rather than expander-set. By default these are deleted (and counted
	// in GrantsDeleted); with WithPreserveSuspectGrants they are kept
	// instead (counted in SuspectPreserved, not GrantsDeleted). Either way
	// the count is surfaced so a real connector-sourced grant is visible.
	// Zero in the common case.
	SuspectConnectorSourced int
	// SuspectPreserved counts suspect grants kept rather than deleted
	// because WithPreserveSuspectGrants was set. Always 0 in the default
	// (delete) mode; a subset of SuspectConnectorSourced when set.
	SuspectPreserved int
	DryRun           bool
}

type SourceCacheReplayResult = pebble.SourceCacheReplayResult

type SourceCacheStore interface {
	// LookupSourceCacheEntry returns this store's manifest entry for
	// (kind, scopeKey). Backs the connector-facing lookup when this
	// store is the previous sync.
	LookupSourceCacheEntry(ctx context.Context, kind sourcecache.RowKind, scopeKey string) (sourcecache.Entry, bool, error)

	// PutSourceCacheEntry writes the current sync's manifest entry for
	// (kind, scopeKey). Zero-row scopes still get entries.
	PutSourceCacheEntry(ctx context.Context, kind sourcecache.RowKind, scopeKey string, cacheValidator string) error

	// ReplaySourceCache copies every row stamped with scopeKey from prev
	// (the previous sync's store, opened read-only) into this store. prev
	// must be a Pebble store. Does NOT write the manifest entry — the
	// caller writes it after the scope's overlay/deletes complete, so a
	// failed replay can't leave a phantom hit for the next sync.
	//
	// On error, the result's Rows reports rows whose bounded intermediate
	// commits landed (retry converges; matching the delete siblings
	// below), and NeedsExpansion may overreport a staged-but-uncommitted
	// row — the safe direction, since arming expansion is idempotent and
	// add-only.
	ReplaySourceCache(ctx context.Context, prev connectorstore.Reader, kind sourcecache.RowKind, scopeKey string) (SourceCacheReplayResult, error)

	// DeleteSourceCacheRows removes rows by public canonical ID from the
	// current sync, after replay + overlay (delta-query tombstones).
	// ID formats per kind: grants and entitlements use their canonical
	// IDs; resources use Baton resource BIDs ("bid:r:...").
	//
	// scopeKey is the scope whose delta reported the tombstones. The
	// deletes act FOR that scope: removing its own rows is the
	// legitimate shrink flow and stages no poison, while removing a row
	// stamped with any OTHER scope is a row-partition violation that
	// durably poisons the stamped scope (CO-015 — it becomes a lookup
	// miss and is refused as a replay source).
	//
	// Grant resolution is BOUNDED: candidate probing only, never the
	// O(all grants) stored-external-id scan. Grants stored under
	// connector-custom ids are unreachable here (delete no-ops); such
	// connectors use DeleteSourceCacheRowsInScope instead. Deletes commit
	// in bounded chunks; deletion is idempotent, so retry converges.
	DeleteSourceCacheRows(ctx context.Context, kind sourcecache.RowKind, scopeKey string, ids []string) error

	// DeleteSourceCacheRowsInScope removes rows stamped with scopeKey by
	// bare object id — grants by principal id (no principal type, no
	// canonical-id reconstruction), resources by resource id (any type).
	// One index scan of the scope per call; a page's tombstones are
	// batched into one call. Deletes commit in bounded chunks; on error,
	// the returned count reports rows already committed and retry converges.
	// Ids with no matching rows are no-ops.
	// Not supported for entitlements.
	DeleteSourceCacheRowsInScope(ctx context.Context, kind sourcecache.RowKind, scopeKey string, ids []string) (int64, error)

	// DeleteSourceCacheGrantsByIDInScope removes grant rows stamped with
	// scopeKey whose STORED grant id is in ids — works for
	// connector-custom grant-id shapes that the global bounded delete
	// cannot resolve, and stays bounded by the scope's row count. Ids with
	// no matching rows are no-ops. Deletes commit in bounded chunks; on
	// error, the returned count reports rows already committed.
	DeleteSourceCacheGrantsByIDInScope(ctx context.Context, scopeKey string, ids []string) (int64, error)
}

type StoreOptions struct {
	TmpDir         string
	DecoderOptions []DecoderOption
	ReadOnly       bool
	SyncLimit      int
	SkipCleanup    bool

	// DisableGrantDigestIndex turns off the Pebble engine's seal-time
	// build of the by_entitlement_principal_hash index + grant digests.
	// Inverted so the zero value keeps the build on (current behavior).
	DisableGrantDigestIndex bool

	Engine c1zstore.Engine

	// PayloadEncoding selects the v3 envelope payload framing for
	// engines that produce a v3 envelope (currently Pebble). Zero
	// value means "engine default" (PayloadEncodingIndexedZstd for
	// Pebble).
	PayloadEncoding c1zstore.PayloadEncoding

	// DecoderPool optionally scopes v3 payload-decoder reuse to the
	// caller's operation (see WithDecoderPool). Nil means a one-shot
	// decoder per open.
	DecoderPool *EnvelopeDecoderPool

	// MaxDecodedPayloadBytes optionally caps v3 envelope payload extraction.
	// Zero means use BATON_DECODER_MAX_DECODED_SIZE_MB or the v3 default.
	MaxDecodedPayloadBytes uint64

	// MaxDecoderMemoryBytes optionally caps zstd decoder memory for v3 envelope
	// payload extraction. Zero means use BATON_DECODER_MAX_MEMORY_MB or the v3
	// default.
	MaxDecoderMemoryBytes uint64
}