adapter

type Access struct {
	Credential string
}

type ActivationLoader interface {
	LoadActivation(context.Context, Job, Journal) (LoadedActivation, error)
}

type ActivationStore interface {
	Activate(context.Context, Job, Connection, time.Time) error
}

type Change struct {
	Surface       Surface
	EffectiveName string
	Disposition   Disposition
	// ObservedProviderVersion remains internal to plan/adoption custody. The
	// public API still carries only the opaque plan artifact and name selection.
	ObservedProviderVersion *int64
}

type Claim struct {
	Surface       Surface
	EffectiveName string
	KeyID         string
}

type Classification string

type Completion struct {
	Outcome        Outcome
	State          LedgerState
	ReleaseLedger  bool
	Conflict       bool
	Missing        bool
	ProviderStatus int
	Finding        string
}

type Config struct {
	Origin string
	// Provider transport options. Only GitLab accepts them today; every other
	// provider refuses a non-empty value so a pin is never silently ignored.
	// SPKIPin is base64(sha256(SubjectPublicKeyInfo)) and is checked after
	// normal chain verification. CABundlePEM adds trust anchors for a
	// self-hosted instance. AllowPersonalToken is the documented protected
	// opt-in for a broader personal access token.
	SPKIPin            string
	CABundlePEM        string
	AllowPersonalToken bool
}

type Connection struct {
	Version             string
	DestinationID       int64
	RepositoryID        int64
	CredentialExpiresAt time.Time
}

type ConnectionRequest struct {
	Config                  Config
	Destination             Destination
	Access                  Access
	Gate                    func(context.Context) error
	AllowEnvironmentCreate  bool
	BeforeEnvironmentCreate func(context.Context) error
	AfterEnvironmentCreate  func(context.Context, error) error
}

type DesiredRow struct {
	ManifestEntry
	Surface       Surface
	EffectiveName string
}

type Destination struct {
	Kind                  DestinationKind
	Owner                 string
	Name                  string
	Environment           string
	NumericID             int64
	RepositoryID          int64
	Visibility            string
	SelectedRepositoryIDs []int64
	// Scope is the GitLab environment_scope ("*" for every environment).
	// It is empty for every other provider.
	Scope string
}

type DestinationKind string

type Disposition string

type Effect struct {
	Surface       Surface
	EffectiveName string
	Disposition   Disposition
	KeyID         string
	// RequireExplicitRecovery durably marks Vault custody uncertain BEFORE a
	// provider mutation. Process death cannot leave an Owned replay authority.
	RequireExplicitRecovery bool
	// InputRevision is worker-bound provenance for acknowledged progress. The
	// worker overrides module input with the admitted loaded source revision.
	InputRevision int64
}

type ErrorClass string

type Job struct {
	ID                 string
	OrgID              string
	ProjectID          string
	EnvironmentID      string
	TargetID           string
	Kind               JobKind
	RouteMoveID        string
	AuthorityPrincipal string
	Generation         int64
	Attempt            int
	LeaseOwner         string
	CreatedAt          time.Time
}

type JobKind string

type JobStore interface {
	ClaimDue(context.Context, string, time.Time, time.Time) (Job, bool, error)
	Journal(Job) Journal
	Retry(ctx context.Context, job Job, due time.Time, revision int64, failed []Change, warnings []string, cause error) error
	Succeed(context.Context, Job, int64, []string, time.Time) error
	Fail(ctx context.Context, job Job, revision int64, at time.Time, cause error) error
}

type Journal interface {
	Gate(ctx context.Context, effect Effect) error
	Reserve(ctx context.Context, effect Effect) (LedgerState, error)
	Prepare(ctx context.Context, effect Effect, prior LedgerState) error
	// Finish atomically writes the terminal OUTCOME, applies the final ledger
	// state or explicitly releases the ledger row, records any conflict artifact, and releases
	// the provider-write lease held since Prepare.
	Finish(ctx context.Context, effect Effect, completion Completion) error
	// Refuse atomically records a pre-dispatch conflict artifact and releases a
	// bare reservation. It writes no OUTCOME because no provider call began.
	Refuse(ctx context.Context, effect Effect) error
	// ReleaseReservation drops a bare, undispatched reservation that is no
	// longer desired. It records no conflict or OUTCOME and is fenced to the
	// exact current target generation.
	ReleaseReservation(ctx context.Context, effect Effect) error
}

type LedgerEntry struct {
	Surface       Surface
	EffectiveName string
	State         LedgerState
	// Missing records that Hikyo owns this name but the provider no longer has
	// it. This makes PATCH-404 -> POST crash safe without treating the retry as
	// an unowned capture attempt.
	Missing bool
	// AdoptionPending is durable explicit adoption evidence newer than every
	// successful provider write for this scoped name. Owned alone is not consent
	// to take over a path whose provider ownership markers disappeared.
	AdoptionPending bool
	// AdoptionVersion is the non-secret provider version observed by the fresh
	// plan artifact, never a value hash or a guessed write outcome.
	AdoptionVersion *int64
}

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

type LedgerState string

type LoadedActivation struct {
	Module  Module
	Request ConnectionRequest
	Release func()
}

type LoadedSync struct {
	Module   Module
	Request  SyncRequest
	Revision int64
	Release  func()
}

type Loader interface {
	Load(context.Context, Job, Journal) (LoadedSync, error)
}

type ManifestEntry struct {
	KeyID          string
	CanonicalName  string
	Classification Classification
	Value          string
}

type Module interface {
	ValidateConfig(Config) error
	TestConnection(context.Context, ConnectionRequest) (Connection, error)
	Plan(context.Context, PlanRequest) (Plan, error)
	Sync(context.Context, SyncRequest, Journal) (SyncResult, error)
}

type ModuleFactory func(Provider, Config, string) (*ModuleLease, error)

type ModuleLease struct {
	Module Module
	// contains filtered or unexported fields
}

type Outcome string

type Plan struct {
	Changes  []Change
	Warnings []string
}

type PlanRequest struct {
	Config   Config
	Target   Target
	Access   Access
	Manifest []ManifestEntry
	Ledger   []LedgerEntry
	Gate     func(context.Context) error
}

type Provider string

type RetryAtError interface {
	error
	RetryAt() time.Time
}

type Source struct {
	OrgID         string
	ProjectID     string
	EnvironmentID string
	Revision      int64
}

type Surface string

type SyncRequest struct {
	Config   Config
	Target   Target
	Access   Access
	Manifest []ManifestEntry
	Ledger   []LedgerEntry
	// Teardown is explicit and fail-closed. Every ordinary sync desires both
	// sentinels; only a tombstoned target's scrub sets this true.
	Teardown bool
	// Completed names were durably finished earlier in this leased job before
	// an in-job provider-rate wait. Modules skip them when plaintext is reloaded.
	Completed []Change
	// JobID is the outbox job this attempt belongs to. It is identical across
	// every retry of one job, so a provider that supports request idempotency
	// tokens can replay an unknown outcome without writing twice.
	JobID string
	// Source pins the exact source scope and revision this job converges.
	// Providers that carry provenance on the wire (sealed-webhook) require it.
	Source Source
}

type SyncResult struct {
	Changes   []Change
	Conflicts []Change
	Failed    []Change
	Warnings  []string
}

type Target struct {
	ID          string
	Environment string
	Destination Destination
	NamePrefix  string
	Generation  int64
	Options     VariableOptions
}

type TargetHealth string

type VariableOptions struct {
	// Protected exposes managed variables only to protected branches and tags.
	Protected bool
	// Hidden creates secret-classified variables as masked and hidden.
	Hidden bool
	// Expand lets the provider expand $VARIABLE references inside values.
	// The default (false) delivers values byte-exactly as raw variables.
	Expand bool
}

type Worker struct {
	Store  JobStore
	Loader Loader
	ID     string
	Poll   time.Duration
	Now    func() time.Time
	Log    *slog.Logger
	Jitter func(time.Duration) time.Duration
	Wait   func(context.Context, time.Duration) error
}