admission

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

type AssignmentReader interface {
	AddedPersonIDs(ctx context.Context, recordingID, eventID int64) (added []int64, found bool, err error)
}

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

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

type Event struct {
	// ID is the feed-global event id.
	ID int64
	// EventType is the cataloged type, "comment.created" and so on.
	EventType string
	// BucketID is the project the recording lives in.
	BucketID int64
	// RecordingID is the recording the event references.
	RecordingID int64
	// CreatorID is the person the event is attributed to.
	CreatorID int64
	// PerformedByID is the agent that carried out a delegated action on the
	// creator's behalf; nil for a direct action.
	PerformedByID *int64
	// ActorType is "person" or "agent" on the push lane, empty on the poll lane.
	ActorType string
	// Details is the type-specific detail object, verbatim; nil for the v1
	// trigger types, which publish none.
	Details json.RawMessage

	// Revision is the ledger record's revision when it was loaded. It is not
	// part of the feed's pointer: the ledger's Commit compares it, so a
	// decision made on an older load never overwrites a newer one.
	Revision int64
	// SeenAt is when intake wrote the pointer, on this machine's clock — the
	// clock membership listings are stamped with, which is why intake and
	// admission must run on one machine. A backward step of that clock by Δ
	// lets a listing up to Δ older than the event pass as newer. A membership refusal counts as
	// verified only from a project listing asked for after it. The Records
	// adapter must set it; zero falls back to the time admission started
	// deciding, which a busy project can keep from ever verifying a refusal.
	SeenAt time.Time
}

type GateResult struct {
	// Rules are the matrix rules still open after the gate, in matrix order.
	// Empty means the event is discarded for Reason.
	Rules []Rule
	// Reason is why the event was discarded; empty when Rules is not.
	Reason Reason
	// ConfirmMembership says the performer is trusted only if a read confirms
	// they are a non-client member of the project (project trust mode, a
	// performer other than the operator). The gate cannot see membership.
	ConfirmMembership bool
}

type IDSource interface {
	Take(ctx context.Context) (int64, error)
}

type Ledger interface {
	// Commit writes v onto its event's record in one transaction and returns
	// the state it wrote. Within that transaction it must:
	//
	//   - apply only when the record's revision is still v.Revision, the one
	//     the decision was loaded at, and bump it; otherwise return
	//     ErrAlreadyDecided. So an event is admitted at most once however many
	//     fetches, restarts or redispatches decide it, and a decision made on
	//     an older load never overwrites a newer verdict, blocked ones
	//     included;
	//   - for an admitted verdict, read the conversation in the same
	//     transaction and write queued when it is live — a task running, or
	//     an admitted record not yet dispatched, since that record becomes the
	//     task — so an event queued before the task closes joins it and one
	//     after starts a new task;
	//   - write content only for an admitted verdict, which it may write as
	//     queued;
	//   - keep a throttled verdict's RetryAt, which NextBlockedRetry needs.
	Commit(ctx context.Context, v Verdict) (State, error)
}

type Line struct {
	Type         string  `json:"type"`
	EventID      int64   `json:"event_id"`
	EventType    string  `json:"event_type"`
	Trigger      Trigger `json:"trigger,omitempty"`
	Class        string  `json:"class,omitempty"`
	BucketID     int64   `json:"bucket_id"`
	RecordingID  int64   `json:"recording_id"`
	RecordingURL string  `json:"recording_url,omitempty"`
	RequesterID  int64   `json:"requester_id"`
	State        State   `json:"state"`
	Reason       Reason  `json:"reason,omitempty"`
}

type Matrix map[string][]Rule

type MemberReader interface {
	NonClientMember(ctx context.Context, bucketID, personID int64, asOf time.Time) (bool, error)
}

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

type Option func(*Admitter)

type Policy struct {
	// AgentID is the agent's own Person id. Required.
	AgentID int64 `json:"-"`
	// Buckets is the --project scope. Empty means every project the agent can
	// see.
	Buckets []int64 `json:"-"`

	Trust Trust `json:"trust"`
	// Projects maps a bucket id to the entry for the project it serves.
	Projects map[int64]Project `json:"projects,omitempty"`
	// ProjectsUnknown says the served projects could not be read at all —
	// connect.json is unreadable, or now names another agent. It is not the
	// same as serving none, and the difference is what a person is told: a
	// record whose answer turns on the list is held as a configuration
	// error, rather than answered with a claim about the project that is
	// false while the file is broken.
	ProjectsUnknown bool `json:"-"`
}

type Project struct {
	// Class is the project's classification, carried on the record.
	Class string `json:"class,omitempty"`
	// WatchCompletions makes the agent a driver of the project: every trusted
	// completion in it is admitted as trigger completed, without the agent
	// being assigned or subscribed.
	WatchCompletions bool `json:"watch_completions,omitempty"`

	// LegacyPath is the directory a connector that routed projects to
	// directories ran this project's work in. Nothing reads it: a task runs
	// where the connector was started. It is still a field because
	// setup.Parse refuses an unknown key, and every connect.json written
	// before the paths went has "path" on every project — deleting the field
	// outright would stop every connector already set up. setup.Parse zeroes
	// it, and omitempty keeps it out of everything written from here, so the
	// next `connect setup` writes the key away for good.
	LegacyPath string `json:"path,omitempty"`
}

type Reads struct {
	Summaries     SummaryReader
	Subscriptions SubscriptionReader
	Assignments   AssignmentReader
	Members       MemberReader
}

type Reason string

type Records interface {
	LoadUndecided(ctx context.Context, id int64) (ev Event, ok bool, err error)
}

type ReplyDestination struct {
	Kind        ReplyKind `json:"kind"`
	RecordingID int64     `json:"recording_id"`
}

type ReplyKind string

type Rule struct {
	Trigger Trigger
	// OperatorOnly restricts the rule to events the operator performed,
	// whatever the trust mode. Assignments run the agent against a recording
	// on the assigner's say-so, so no broadened mode extends to them.
	OperatorOnly bool
	// RequiresServed discards the rule at the gate when connect.json does not
	// serve the project. Only mentioned and assigned are answered in an
	// unserved project (blocked(no_route) and a holding reply); every other
	// trigger is discarded there, so it is cheaper to discard it before any
	// read.
	RequiresServed bool
	// Acknowledge says a person asked for something, so the worker's
	// acknowledgement and the thirty-second guard apply. A completion or a
	// subscription comment is not a request.
	Acknowledge bool
}

type RunOptions struct {
	Source    IDSource
	Records   Records
	Admitter  *Admitter
	Committer *Committer
	// Workers is the fetcher pool size; DefaultWorkers when zero.
	Workers int
	// Lines receives one NDJSON line per committed verdict.
	Lines io.Writer
	// LineWriter, when set, is the writer the lines go through, and Lines is
	// ignored: one sink has one writer and one lock, and a caller wiring
	// admission beside intake passes the same writer to both.
	LineWriter *ndjson.Writer
	Logger     *slog.Logger
}

type Snapshot struct {
	Type      string    `json:"type"`
	Title     string    `json:"title"`
	AppURL    string    `json:"app_url"`
	Content   string    `json:"content"`
	UpdatedAt time.Time `json:"updated_at"`
	// ProjectName and RequesterName are what the session reading the
	// handoff calls them, so it need not ask Basecamp as the agent.
	// RequesterName is known only when the requester wrote the recording.
	ProjectName   string `json:"project_name,omitempty"`
	RequesterName string `json:"requester_name,omitempty"`
}

type State string

type SubscriptionReader interface {
	Subscribed(ctx context.Context, recordingID int64) (bool, error)
}

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

type SummaryReader interface {
	Summarize(ctx context.Context, ref basecamp.RecordingRef) (*basecamp.RecordingSummary, error)
}

type ThrottledError struct {
	RetryAt time.Time
	Err     error
}

type Trigger string

type Trust struct {
	Mode TrustMode `json:"mode"`
	// OperatorID is the Person id of the person who approved the connection.
	OperatorID int64 `json:"operator_id"`
	// AllowlistIDs are the Person ids trusted in allowlist mode.
	AllowlistIDs []int64 `json:"allowlist_ids,omitempty"`
}

type TrustMode string

type Verdict struct {
	EventID     int64
	EventType   string
	BucketID    int64
	RecordingID int64
	// Revision is the record revision the decision started from.
	Revision int64
	// RetryAt is set on a blocked(throttled) verdict: the server's deadline,
	// before which the record is not decided again.
	RetryAt time.Time
	// RequesterID is the performer whose trust admitted the event.
	RequesterID int64

	State  State
	Reason Reason

	// The rest is set once the recording was read; a gate discard carries
	// none of it.
	Trigger Trigger
	// Acknowledge says the worker acknowledges and the guard arms. False for
	// completed and subscribed.
	Acknowledge bool
	// ConversationKey groups events into one task: the commented recording
	// for a comment, the Campfire for a chat line, the recording otherwise.
	ConversationKey string
	Reply           *ReplyDestination
	// Served is whether connect.json serves the record's project, and Class
	// is that entry's classification. No directory comes from connect.json:
	// the connector runs where it was started.
	Served bool
	Class  string
	// RecordingURL is the recording's app URL, once read. A URL, not content.
	RecordingURL string
	// Snapshot is set on an admitted verdict only.
	Snapshot *Snapshot
}