connector

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

type AdmissionOptions struct {
	Ledger   *Ledger
	Queue    *Queue
	Admitter *admission.Admitter
	// Workers is the fetcher pool size; admission's default when zero.
	Workers int
	// Lines is the writer intake's pointer lines go through. Verdict lines
	// share it, so the two never tear each other on one stdout.
	Lines  *ndjson.Writer
	Logger *slog.Logger
}

type AdoptionCandidate struct {
	TaskID           int64
	EventID          int64
	ReplyKind        string
	ReplyRecordingID int64
	// DeliveredAt is the event's ack_dispatch.
	DeliveredAt time.Time
	// NextAckAt is the first acknowledgement of a later instruction on the
	// CONVERSATION, which may be on a task started after this one ended;
	// zero when there is none.
	NextAckAt time.Time
	// AckID is the worker's own acknowledgement, which is never its reply
	// however the clocks compare.
	AckID int64
}

type AgentReply struct {
	ID        int64
	CreatedAt time.Time
}

type AskResult struct {
	RecordingID int64 `json:"recording_id"`
	// Already says the recording was declared an ask before; the first
	// declaration stands.
	Already bool `json:"already"`
	// Edited says the post no longer matches the content it was first
	// declared with: the ask is void, and only a new ask can be a go.
	Edited bool `json:"edited,omitempty"`
	// GoEventID is the event whose boost took the ask's go, zero while none
	// has.
	GoEventID int64 `json:"go_event_id,omitempty"`
}

type AttemptEnd struct {
	AttemptID string
	Stop      StopReason
	// SpawnFailed is the driver's report that no worker process ever existed
	// (driver.ErrNotStarted). Nothing else makes an exposure withdrawable.
	SpawnFailed bool
	// NoAutomaticRetry refuses the withdrawal even then: a task under the
	// sandbox launcher is never retried automatically.
	NoAutomaticRetry bool
	// UnrecordedRefusals are refusals RecordRefusal could not write when they
	// happened, settled here with the attempt. Refusals it did write are
	// already on the attempt.
	UnrecordedRefusals int
}

type AttemptProcess struct {
	PID       int
	PGID      int
	StartedAt time.Time
	// StartedExact says StartedAt is the kernel's own start time for the pid
	// (driver.Process.StartedExact). Only then is it written.
	StartedExact bool
	SessionID    string
}

type AttemptState string

type BlockedRetryScope struct {
	// Buckets is the run's --project scope — the same slice admission's
	// policy gates on, with the same meaning: empty is a run restricted to no
	// project, which is every project the agent can see, NOT no project at
	// all.
	//
	// It is not optional, and it is not a detail. out_of_scope is a terminal
	// discard, and the projects a run leaves out are another run's to
	// dispatch: a sweep that offered a record from outside its scope would
	// cause the permanent loss the retry exists to prevent. Every other
	// terminal verdict a re-offered record can reach — stale, not_addressed,
	// untrusted_performer, agent_authored — is the verdict a fresh event
	// would get, and is correct.
	Buckets []int64
	// Now is the moment the sweep is asking about.
	Now time.Time
	// Limit is the most records one page of the query returns.
	Limit int
	// AfterRetryAt and AfterID are one cursor, in the order the query returns
	// rows: the next page is what sorts after them. The caller pages because
	// only it knows which rows it has already claimed, and a page that came
	// back full of claims would otherwise spend a sweep's whole budget on
	// work nothing can do.
	//
	// The cursor is the due time first and the id second because that is the
	// order events_next_retry holds, and paging in any other order is what
	// makes the query ignore it. Their zero values are before every row.
	AfterRetryAt time.Time
	AfterID      int64
}

type Booster interface {
	Boost(ctx context.Context, recordingID int64, content string) (int64, error)
}

type CommittedVerdict struct {
	EventID     int64
	State       RecordState
	Reason      string
	Trigger     string
	Acknowledge bool
	ReplyKind   string
	// ReplyRecordingID is where a reply to the event goes.
	ReplyRecordingID int64
}

type Completion struct {
	Outcome Outcome
	Links   []string
	ReplyID *int64
}

type ConnectionStatus struct {
	State     string    `json:"state"`
	PID       int       `json:"pid"`
	ChangedAt time.Time `json:"changed_at"`
	Detail    string    `json:"detail,omitempty"`
}

type Decision struct {
	// DecidedAt is when the latest verdict was written.
	DecidedAt *time.Time
	// BlockedAt is when the record entered its current run of blocked
	// verdicts; nil unless it is blocked.
	BlockedAt *time.Time
	// RetryAt is a throttled verdict's server deadline; nil otherwise.
	RetryAt *time.Time
	// RetrySince is when the record entered the reason it is blocked on now
	// — not when it entered blocked, which is BlockedAt. The retry window is
	// the reason's, so it counts from here.
	RetrySince *time.Time
	// NextRetryAt is when the schedule next owes this record an attempt, as
	// admission.NextBlockedRetry answered when the verdict was written. Nil
	// when it owes none: an untimed reason, a window that has passed, or any
	// state but blocked.
	NextRetryAt *time.Time

	Trigger          string
	Acknowledge      bool
	ConversationKey  string
	ReplyKind        string
	ReplyRecordingID int64
	// Served is whether connect.json served the record's project when
	// admission decided it.
	Served       bool
	Class        string
	RecordingURL string
	RequesterID  int64
	// Snapshot is the recording's content as admission read it, JSON. An
	// admitted verdict writes it, as admitted or queued; it stays through
	// dispatch and completion until retention drops it, and any move to
	// blocked or discarded clears it.
	Snapshot json.RawMessage
}

type DecisionAction string

type Delivery string

type Destination struct {
	BucketID    int64
	Kind        MessageKind
	RecordingID int64
}

type DiscardResult struct {
	EventID     int64       `json:"event_id"`
	FromState   RecordState `json:"from_state"`
	FromReason  string      `json:"from_reason,omitempty"`
	FromOutcome Outcome     `json:"from_outcome,omitempty"`
	// Already says the record was discarded by a person before; nothing
	// changed.
	Already bool `json:"already_discarded,omitempty"`
	// Canceled counts lifecycle messages still pending for the event that
	// will not be sent.
	Canceled int `json:"canceled_messages"`
}

type DispatchStatus struct {
	TaskID     int64             `json:"task_id"`
	AttemptID  string            `json:"attempt_id"`
	State      string            `json:"state"`
	StopReason string            `json:"stop_reason,omitempty"`
	LaunchedAt time.Time         `json:"launched_at"`
	EndedAt    *time.Time        `json:"ended_at,omitempty"`
	Events     []DispatchedEvent `json:"events"`
}

type DispatchedEvent struct {
	EventID  int64  `json:"event_id"`
	Delivery string `json:"delivery"`
	Outcome  string `json:"outcome,omitempty"`
	ReplyID  *int64 `json:"reply_id,omitempty"`
	// Withdrawn is an exposure taken back after a start that ran nothing.
	Withdrawn bool `json:"withdrawn,omitempty"`
}

type EntryClass string

type Gap struct {
	ID         int64
	DetectedAt time.Time
	Class      GapClass
	// EpochAfterID is set exactly when Class is GapEpoch. It is a pointer
	// because the distinction between "absent" and "zero" is the whole of the
	// difference between the two 410s.
	EpochAfterID *int64
	EntryClass   EntryClass
	Note         string
}

type GapClass string

type GapStatus struct {
	ID           int64     `json:"id"`
	DetectedAt   time.Time `json:"detected_at"`
	Class        string    `json:"class"`
	EpochAfterID *int64    `json:"epoch_after_id,omitempty"`
	EntryClass   string    `json:"entry_class,omitempty"`
}

type HandoffAck struct {
	BoostID int64  `json:"boost_id"`
	Content string `json:"content"`
}

type HandoffAsk struct {
	Title   string `json:"title"`
	Content string `json:"content"`
}

type HandoffLine struct {
	Type      string `json:"type"` // "request"
	EventID   int64  `json:"event_id"`
	EventType string `json:"event_type"`
	Trigger   string `json:"trigger"`

	Recording HandoffRecording `json:"recording"`
	// Ping says the request is a line in a Ping, a private chat with the
	// agent, and in no project: Recording.BucketID is the Ping's id, there is
	// no project to read an AGENTS.md or a repo from, and ReplyTo is the
	// Ping's Campfire. It says where the request was made, not who made it or
	// with what authority: an operator's line reaches the agent there, and so
	// does the mention of a person connect.json lets into that one Ping
	// (--allow-in-ping), who is a participant. Role says which.
	Ping        bool             `json:"ping"`
	ReplyTo     InstructionReply `json:"reply_to"`
	RequesterID int64            `json:"requester_id"`
	// RequesterName is known when the requester wrote the recording.
	RequesterName string `json:"requester_name,omitempty"`
	// Role is "operator" or "participant": whether the request carries an
	// operator's word or only a participant's. The key and its values are
	// the local agent connector's, so one session can read either.
	Role string `json:"role"`
	// Owner says the operator connect.json names — for a personal agent, its
	// owner — asked, and wrote the words when the request is words: not
	// merely someone with an operator's role. Controlling the agent's own
	// connector (start, stop, restart, setup, which build it runs) is the
	// owner's alone, so a reader gates that on this one field rather than
	// comparing ids itself. Admission settles it (Snapshot.Owner); a record
	// admitted before it did says false.
	Owner bool `json:"owner"`
	// Acknowledge says an acknowledgement is still owed: a person asked for
	// something and the connector did not boost it. A comment on a thread the
	// agent follows, or a completion, is context and is not acknowledged.
	Acknowledge bool `json:"acknowledge"`
	// Go says this boosted request is the operator's go: their boost on a
	// post the agent declared an ask (`basecamp connect ask`), and the first
	// boost to take that ask. The ask is Recording. It approves what the ask
	// names and nothing more. False on every other request, a boost on an
	// ask from anyone else and the operator's second boost included.
	Go bool `json:"go"`
	// Ask is the declared ask's own words as admission read them and matched
	// them against the declaration, set only on a go: the text the go
	// approves. The worker acts on these words, never on a fresh read of
	// Recording, which may have been edited since. Empty on every other line.
	Ask HandoffAsk `json:"ask"`
	// Ack is the boost the connector acknowledged the request with, as the
	// agent, before writing this line. Absent when it gave none: the request
	// is not one to acknowledge, the acknowledgement is turned off, or the
	// boost failed, and then the reader acknowledges it as before.
	Ack *HandoffAck `json:"ack,omitempty"`

	Content          string    `json:"content"`
	ContentUpdatedAt time.Time `json:"content_updated_at"`
}

type HandoffOptions struct {
	Ledger *Ledger
	// Served is connect.json's served projects as they are now.
	Served func() (map[int64]admission.Project, error)
	// Buckets narrows the served projects to a run's --project, when given.
	Buckets []int64
	// Pings hands off a Ping's requests: only the connector that hears the
	// agent's Pings does (admission.Policy.HearsPings). A run narrowed by
	// Buckets hands off none, whatever this says, as its feed brings none.
	Pings bool
	// AgentID is the agent's Person id, whose mentions are stripped.
	AgentID int64
	Lines   *ndjson.Writer
	Logger  *slog.Logger
	// Started is when the run started. Zero means now.
	Started time.Time
	// Interval is how often admitted records are looked for. Zero means
	// DefaultHandoffInterval.
	Interval time.Duration
	// AckContent is the boost a request someone made of the agent is
	// acknowledged with, through Booster, before its line is written. Empty
	// turns the acknowledgement off.
	AckContent string
	Booster    Booster
}

type HandoffRecording struct {
	BucketID    int64  `json:"bucket_id"`
	ProjectName string `json:"project_name,omitempty"`
	RecordingID int64  `json:"recording_id"`
	Type        string `json:"type"`
	Title       string `json:"title"`
	URL         string `json:"url"`
}

type HeldStatus struct {
	EventID      int64     `json:"event_id"`
	EventType    string    `json:"event_type"`
	Trigger      string    `json:"trigger,omitempty"`
	BucketID     int64     `json:"bucket_id"`
	RecordingURL string    `json:"recording_url,omitempty"`
	Reason       string    `json:"reason,omitempty"`
	Generation   int64     `json:"generation"`
	UpdatedAt    time.Time `json:"updated_at"`
}

type Hold struct {
	// Generation is the intake generation the latest hold opened. Records of
	// earlier generations were tagged for review.
	Generation int64     `json:"generation"`
	Cause      HoldCause `json:"cause"`
	HeldBy     string    `json:"held_by"`
	HeldAt     time.Time `json:"held_at"`
}

type HoldCause string

type HoldResult struct {
	Hold Hold `json:"hold"`
	// Tagged is how many non-terminal records were tagged for review.
	Tagged int `json:"tagged_for_review"`
	// Held is how many of them were waiting for a worker and are now held.
	Held int `json:"held"`
}

type HoldStatus struct {
	Generation int64     `json:"generation"`
	Cause      string    `json:"cause"`
	HeldBy     string    `json:"held_by"`
	HeldAt     time.Time `json:"held_at"`
}

type Hooks struct {
	// VerdictCommitted runs in admission's verdict transaction, after the
	// verdict is written: where the guard acknowledgement and the holding
	// reply are called for.
	VerdictCommitted func(ctx context.Context, tx Tx, v CommittedVerdict) error
	// TaskLaunched runs in LaunchTask's transaction.
	TaskLaunched func(ctx context.Context, tx Tx, launch Launch) error
	// AttemptEnded runs in EndAttempt's transaction, after every event is
	// settled: where the attempt's completion message is called for.
	AttemptEnded func(ctx context.Context, tx Tx, s Settlement) error
	// StillRunning runs in StillRunning's transaction.
	StillRunning func(ctx context.Context, tx Tx, tick StillRunningTick) error
	// RecordDecided runs in the transaction of a person's decision on a
	// record — a redispatch or a discard: where a notice already posted stops
	// asking for anything, and is retracted.
	RecordDecided func(ctx context.Context, tx Tx, d RecordDecision) error
}

type ImportResult struct {
	// Tombstoned counts records closed as discarded(imported_done), Inserted
	// the tombstones written for events the ledger had never seen.
	Tombstoned int `json:"tombstoned"`
	Inserted   int `json:"tombstones_inserted"`
	// AlreadyTerminal counts done entries whose record had already finished.
	AlreadyTerminal int `json:"already_terminal"`
	// Tagged counts non-terminal records tagged for review, and Held those
	// of them that were waiting for a worker and are now held.
	Tagged int `json:"tagged_for_review"`
	Held   int `json:"held"`
}

type InstanceHolderInfo struct {
	PID       int
	StartedAt string
	// Pings is whether it hears the agent's Pings; nil when an older build
	// wrote it, which does not say. PingsBecause is why.
	Pings        *bool
	PingsBecause string
}

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

type Instruction struct {
	EventID   int64  `json:"event_id"`
	EventType string `json:"event_type"`
	Trigger   string `json:"trigger"`
	Class     string `json:"class,omitempty"`

	Recording   InstructionRecording `json:"recording"`
	ReplyTo     InstructionReply     `json:"reply_to"`
	RequesterID int64                `json:"requester_id"`

	// Acknowledge says a person asked for something: the worker acknowledges
	// it and reports the id through ack_dispatch.
	Acknowledge bool `json:"acknowledge"`
	// GuardAcknowledged says the connector's guard already acknowledged the
	// event, so the worker does not acknowledge it again.
	GuardAcknowledged bool     `json:"guard_acknowledged"`
	Delivery          Delivery `json:"delivery"`

	// Content is the instruction as admission read it, with the agent's own
	// mention stripped. The live recording may be newer.
	Content          string    `json:"content"`
	ContentUpdatedAt time.Time `json:"content_updated_at"`
}

type InstructionRecording struct {
	BucketID    int64  `json:"bucket_id"`
	RecordingID int64  `json:"recording_id"`
	Type        string `json:"type"`
	Title       string `json:"title"`
	URL         string `json:"url"`
}

type InstructionReply struct {
	Kind        string `json:"kind"`
	RecordingID int64  `json:"recording_id"`
}

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

type Intent struct {
	ID    int64
	Key   string
	Kind  IntentKind
	State IntentState
	// EventID is the event a guard or holding reply answers for; zero for a
	// per-attempt intent.
	EventID int64
	// TaskID and AttemptID are set on per-attempt intents.
	TaskID     int64
	AttemptID  string
	Occurrence int
	// Retracts is the intent whose posted message a retraction answers; zero
	// on every other kind.
	Retracts int64

	Destination Destination
	// Body is the message exactly as it is posted, rendered from records when
	// the intent was written.
	Body string

	CreatedAt  time.Time
	NotBefore  time.Time
	SendingAt  *time.Time
	FinishedAt *time.Time
	ReceiptID  *int64
	// Note says why an intent is canceled or indeterminate.
	Note string
	// ResolvedBy names the person who resolved an indeterminate intent.
	ResolvedBy string
	// ReconcileFailures counts listings that failed for a sending intent;
	// ReconcileAt is when the next is due, nil when none failed.
	ReconcileFailures int
	ReconcileAt       *time.Time
}

type IntentFilter struct {
	States  []IntentState
	Kinds   []IntentKind
	EventID int64
	// Limit is the most returned, newest first; zero for all.
	Limit int
}

type IntentKind string

type IntentResolution struct {
	Resolution Resolution
	// ReceiptID is the message a ResolveSent names.
	ReceiptID int64
	// By names who decided, for the record. Required.
	By string
}

type IntentState string

type IntentStatus struct {
	ID          int64      `json:"id"`
	Kind        string     `json:"kind"`
	EventID     int64      `json:"event_id,omitempty"`
	AttemptID   string     `json:"attempt_id,omitempty"`
	BucketID    int64      `json:"bucket_id"`
	MessageKind string     `json:"message_kind"`
	RecordingID int64      `json:"recording_id"`
	SendingAt   *time.Time `json:"sending_at,omitempty"`
	Note        string     `json:"note,omitempty"`
}

type Lane string

type Launch struct {
	TaskID int64
	// Token binds the worker to the task. It is returned once and stored
	// only as a hash.
	Token     string
	AttemptID string
	// EventIDs are the task's events, originating first. Only the originating
	// event is exposed; the rest wait at delivery admitted.
	EventIDs        []int64
	ConversationKey string
	Driver          string
	LaunchedAt      time.Time
	// DeadlineAt is zero when the task has no deadline.
	DeadlineAt time.Time
}

type LaunchSpec struct {
	// EventID is the originating event: an admitted or queued record.
	EventID int64
	// Served is the served projects the caller decided this launch from,
	// already cut to the run's --project scope. For the dispatcher it is the
	// one reading of connect.json that this pass took, handed down — not a
	// fresh read, and not a promise about what the file says at the moment
	// the transaction commits. Records on the originating record's
	// conversation join its task only from its own project, and only while
	// that project is among these.
	Served []int64
	// Driver is the driver's name.
	Driver string
	// Deadline is how long the task may run; zero for none.
	Deadline time.Duration
}

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

type LiveAttempt struct {
	AttemptID       string
	TaskID          int64
	State           AttemptState
	Driver          string
	ConversationKey string
	Process         AttemptProcess
	// Taker is the process the task token went to, where one took it. Its
	// PID is zero when none did.
	Taker AttemptProcess
	// TakerUnaccounted is a token that went out to a process this attempt
	// could not account for. Its PID is zero too, and the difference
	// matters: nothing of such an attempt is released.
	TakerUnaccounted bool
	LaunchedAt       time.Time
	// DeadlineAt is zero when the task has none.
	DeadlineAt time.Time
}

type LiveWorker struct {
	AttemptID string `json:"attempt_id"`
	TaskID    int64  `json:"task_id"`
	// PID, PGID and StartedAt are the recorded process: with the start time,
	// the pid is an identity (driver.OwnsWorker).
	PID       int       `json:"pid"`
	PGID      int       `json:"pgid"`
	StartedAt time.Time `json:"started_at"`
}

type Loss struct {
	ID           int64
	DetectedAt   time.Time
	DroppedCount int
	// RepairSince is the walk's entry: one below the lowest missing id.
	RepairSince int64
	// RepairCursor is the walk's own position, kept here and never written to
	// the feed's checkpoint.
	RepairCursor string
	DeadlineAt   time.Time
	ResolvedAt   *time.Time
	// Filters is the filter set this loss was recorded under. The repair walk
	// uses it, whatever the connector's current filters are: a loss recorded
	// under one set and walked under another is repaired against a lane that
	// never carried its events.
	Filters eventfeed.Filters
	// HasFilters distinguishes a loss recorded with no filters — the
	// whole-account feed, the common case — from one written before losses
	// carried them at all. The first is walked with no filters; the second
	// with the connector's own, which is the best that row can say.
	HasFilters bool
}

type LossState string

type LossStatus struct {
	ID         int64     `json:"id"`
	DetectedAt time.Time `json:"detected_at"`
	Dropped    int       `json:"dropped"`
	Missing    int       `json:"missing"`
	DeadlineAt time.Time `json:"deadline_at"`
}

type MembershipSource interface {
	Buckets(ctx context.Context) ([]int64, error)
}

type MessageKind string

type Options struct {
	// Origin is the API base URL. It is part of the checkpoint identity and
	// the origin every continuation URL is validated against.
	Origin string
	// AccountID is the Basecamp account.
	AccountID string
	// ConsumerNamespace names this connector's checkpoint lineage. Two
	// connectors in one account must not share one.
	ConsumerNamespace string
	// Filters is the feed's filter set. The checkpoint is keyed by its digest,
	// so changing it re-enters under a new lineage.
	Filters eventfeed.Filters
	// SinceEventID, when positive, enters just after that event id whatever
	// the ledger holds — the `--since` override.
	SinceEventID int64

	Ledger *Ledger
	Queue  *Queue
	Minter eventfeed.TicketMinter
	// PollsFor returns a fresh poll source per walk. The SDK's live source
	// holds walk state (the order a continuation must follow), so the feed's
	// connection and each repair walk get their own. Polls, when set instead,
	// is shared by all of them — for test fakes that hold no walk state.
	PollsFor func() eventfeed.PollSource
	Polls    eventfeed.PollSource

	// Pointers receives one NDJSON line per newly seen event. Writes are
	// serialized: an interleaved write tears a line and breaks the watcher
	// reading it.
	Pointers io.Writer
	// Lines, when set, is the writer the pointer lines go through, and
	// Pointers is ignored. One process stdout has one writer and one lock, so
	// a caller wiring intake and admission onto the same stdout passes the
	// same writer to both rather than relying on them to find each other.
	Lines *ndjson.Writer
	// Logger receives everything else. Pointer lines are the protocol;
	// logging is not.
	Logger *slog.Logger

	// Membership, when set, drives the reconnect that makes a newly granted
	// project visible on the live lane.
	Membership         MembershipSource
	MembershipInterval time.Duration

	RepairInterval time.Duration
	RepairWindow   time.Duration

	Clock     func() time.Time
	Transport eventfeed.CableTransport
}

type Outcome string

type PingsChoice struct {
	Hears bool `json:"hears"`
	// Because is what decided it: --pings or --no-pings, or the default the
	// first start found for the profile's credential. The run names the
	// values; this file only keeps them.
	Because string    `json:"because"`
	At      time.Time `json:"at"`
}

type Pointer struct {
	EventID       int64  `json:"event_id"`
	EventType     string `json:"event_type"`
	Kind          string `json:"kind"`
	Action        string `json:"action"`
	BucketID      int64  `json:"bucket_id"`
	CreatorID     int64  `json:"creator_id"`
	PerformedByID *int64 `json:"performed_by_id"`
	RecordingID   int64  `json:"recording_id"`
	CreatedAt     string `json:"created_at"`
	Lane          Lane   `json:"lane"`
	State         string `json:"state"`
}

type PositionStatus struct {
	Filters          string    `json:"filters"`
	HasPosition      bool      `json:"has_position"`
	LastPollServedID int64     `json:"last_poll_served_id"`
	UpdatedAt        time.Time `json:"updated_at"`
}

type PromoteOptions struct {
	// ShadowDir is the shadow run's state directory, StateDir the normal
	// one. Both must be on one filesystem: the ledger moves by rename.
	ShadowDir string
	StateDir  string
	AccountID string
	AgentID   int64
	// By records who promoted.
	By string
}

type PromoteResult struct {
	// Already says an earlier promote finished: the normal ledger stands
	// under its hold and there was no shadow ledger left to move.
	Already bool `json:"already_promoted,omitempty"`
	Hold    Hold `json:"hold"`
	Tagged  int  `json:"tagged_for_review"`
	Held    int  `json:"held"`
	// Ledger is the promoted ledger's path.
	Ledger string `json:"ledger"`
}

type Queue struct {

	// OnWarn fires when the depth first crosses the warning threshold, and
	// OnRecover when it falls back below. Both are optional.
	OnWarn    func(depth int)
	OnRecover func(depth int)
	// OnPause fires when an offer begins waiting for room, and OnResume when
	// it stops. The feed is not being consumed in between.
	OnPause  func(depth int)
	OnResume func(depth int)
	// contains filtered or unexported fields
}

type Receipt struct {
	EventID  int64    `json:"event_id"`
	Delivery Delivery `json:"delivery"`
	AckID    *int64   `json:"ack_id,omitempty"`
	Outcome  Outcome  `json:"outcome,omitempty"`
	ReplyID  *int64   `json:"reply_id,omitempty"`
	Links    []string `json:"links,omitempty"`
}

type Reconciliation struct {
	Version int                   `json:"version"`
	Entries []ReconciliationEntry `json:"entries"`
}

type ReconciliationEntry struct {
	EventID  int64  `json:"event_id"`
	Decision string `json:"decision"`
}

type Record struct {
	ID               int64
	State            RecordState
	Reason           string
	Lane             Lane
	EventType        string
	Kind             string
	Action           string
	BucketID         int64
	CreatorID        int64
	PerformedByID    *int64
	RecordingID      int64
	Details          json.RawMessage
	ActorType        string
	VisibleToClients *bool
	CreatedAt        time.Time
	SeenAt           time.Time
	UpdatedAt        time.Time
	ContentDropped   bool

	// Revision counts every state write applied to the record since intake
	// recorded it, a repeat of the state it already has included. A decision
	// applies only at the revision it loaded.
	Revision int64
	// Decision is admission's latest verdict on the record; its zero value
	// until one is written.
	Decision Decision
}

type RecordDecision struct {
	EventID int64
	Action  DecisionAction
	At      time.Time
}

type RecordState string

type RedispatchResult struct {
	EventID     int64       `json:"event_id"`
	FromState   RecordState `json:"from_state"`
	FromReason  string      `json:"from_reason,omitempty"`
	FromOutcome Outcome     `json:"from_outcome,omitempty"`
	// State is the record's state after the authorization.
	State RecordState `json:"state"`
	// Admitted says the record waits for a worker now.
	Admitted bool `json:"admitted"`
	// Pending says the record's task is still live: it is admitted in the
	// transaction that ends that task.
	Pending bool `json:"pending,omitempty"`
	// Rerun says the record was authorized as blocked: the caller runs its
	// prerequisite again (admission), which admits it when it succeeds.
	Rerun bool `json:"rerun,omitempty"`
	// SupersededTaskID is the task whose token this redispatch retired; zero
	// when it was already retired.
	SupersededTaskID int64 `json:"superseded_task_id,omitempty"`
	// Worker is the replaced attempt's recorded process, still live in the
	// ledger: the caller terminates it (driver.TerminateRecorded).
	Worker *LiveWorker `json:"worker,omitempty"`
	// Held says the hold marker stands: authorized, and nothing launches
	// until release.
	Held bool `json:"held,omitempty"`
}

type ReleaseResult struct {
	// Released is false when no hold stood.
	Released bool `json:"released"`
	Hold     Hold `json:"hold,omitzero"`
	// StillHeld counts held records, which stay held.
	StillHeld int `json:"still_held"`
}

type Resolution string

type SDKBooster struct {
	Client *basecamp.AccountClient
}

type SDKMembership struct {
	Client *basecamp.AccountClient
}

type SettledEvent struct {
	EventID int64
	// Outcome is the reported outcome, or unknown for an event exposed and
	// never reported. Empty for an event never exposed, or withdrawn.
	Outcome Outcome
	// Reported is whether the outcome is the worker's own report.
	Reported bool
	ReplyID  *int64
	// Returned is an event never exposed: it waits for a task of its own.
	Returned bool
	// Withdrawn is an exposure withdrawn after a start that ran nothing; the
	// record is admitted again, or blocked(spawn_failed) when it already was
	// once.
	Withdrawn bool
	// Blocked is a withdrawal refused a second automatic retry.
	Blocked bool
	// Decided is a record a person has already redispatched or discarded, so
	// the completion notice asks nothing of them.
	Decided bool
	// Pulled is whether a worker asked for the event's instruction. An event
	// the launch exposed and no worker pulled is one the worker never picked
	// up: it stopped before it began.
	Pulled bool
}

type Settlement struct {
	TaskID    int64
	AttemptID string
	Stop      StopReason
	// SpawnFailed repeats AttemptEnd.SpawnFailed.
	SpawnFailed bool
	// OriginatingEventID is the task's originating event.
	OriginatingEventID int64
	Events             []SettledEvent
}

type StartableFilter struct {
	// Served are the served project ids the caller decided this query from,
	// already narrowed to --project — one reading, not a promise about the
	// file at any later moment. A record in any other project is not
	// startable. Empty means nothing is.
	Served []int64
	Limit  int
}

type Status struct {
	SchemaVersion int `json:"schema_version"`
	// Connection is the last run's own record, if one ran on this build.
	Connection *ConnectionStatus `json:"connection,omitempty"`
	// Hold is the standing hold marker.
	Hold       *HoldStatus `json:"hold,omitempty"`
	Generation int64       `json:"generation"`

	Positions   []PositionStatus `json:"positions"`
	Gaps        []GapStatus      `json:"gaps"`
	Losses      []LossStatus     `json:"open_losses"`
	Unrecovered int              `json:"unrecovered_ids"`

	// Queues counts records by state; Blocked counts blocked records by reason.
	Queues  map[string]int `json:"queues"`
	Blocked map[string]int `json:"blocked"`
	// Review counts records tagged for review that have not reached a
	// person yet, and Authorized those a person authorized that have not run.
	Review            int `json:"review_tagged"`
	AuthorizedBlocked int `json:"authorized_blocked"`
	RedispatchPending int `json:"redispatch_pending"`

	Tasks         []TaskStatus     `json:"live_tasks"`
	Indeterminate []IntentStatus   `json:"indeterminate_intents"`
	Held          []HeldStatus     `json:"held_records"`
	Dispatches    []DispatchStatus `json:"dispatches"`
}

type StillRunningTick struct {
	AttemptID string
	TaskID    int64
	// Occurrence counts from 1 per attempt.
	Occurrence int
	// ProgressAt is the attempt's last progress; zero when none was seen.
	ProgressAt time.Time
}

type StopReason string

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

type TaskGrant struct {
	ID    int64
	Token string
}

type TaskStatus struct {
	TaskID    int64  `json:"task_id"`
	AttemptID string `json:"attempt_id"`
	State     string `json:"state"`
	Driver    string `json:"driver"`
	PID       int    `json:"pid,omitempty"`
	PGID      int    `json:"pgid,omitempty"`
	// ProcessStartedAt is the start time recorded with the pid: with it, the
	// pid is an identity (driver.OwnsWorker).
	ProcessStartedAt *time.Time `json:"process_started_at,omitempty"`
	// TakerPID, TakerPGID and TakerStartedAt are the process the task token
	// went to, where one took it: a worker's MCP server, which lives in a
	// process group of its own.
	TakerPID       int        `json:"taker_pid,omitempty"`
	TakerPGID      int        `json:"taker_pgid,omitempty"`
	TakerStartedAt *time.Time `json:"taker_started_at,omitempty"`
	// TakerUnaccounted is the case the zero taker cannot express: the token
	// was delivered and the connector could not name the process that took
	// it, or the kernel stopped answering whether it is gone. The attempt is
	// held for it, and a person reading this status is the one who settles
	// it, so it is never shown as nothing having taken the token.
	TakerUnaccounted bool `json:"taker_unaccounted,omitempty"`
	// Worker and Taker are whether each recorded process is still this task's,
	// as the caller established it; the ledger read leaves them empty.
	Worker     string     `json:"worker,omitempty"`
	Taker      string     `json:"taker,omitempty"`
	LaunchedAt time.Time  `json:"launched_at"`
	DeadlineAt *time.Time `json:"deadline_at,omitempty"`
	EventIDs   []int64    `json:"event_ids"`
}

type Tx interface {
	ExecContext(ctx context.Context, query string, args ...any) (sql.Result, error)
	QueryRowContext(ctx context.Context, query string, args ...any) *sql.Row
	QueryContext(ctx context.Context, query string, args ...any) (*sql.Rows, error)
}