admission

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

type AgentRequests interface {
	CountAgentRequests(ctx context.Context, conversationKey string, agents []int64, window time.Duration) (int, error)
}

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

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 BoostReader interface {
	Get(ctx context.Context, boostID int64) (*basecamp.Boost, error)
}

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
	// types that publish none. Of the matrix's types only boost.created
	// publishes one: the boost's id, and the event it landed on when it was
	// not the recording itself.
	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 the policy does not name). The gate cannot see membership.
	ConfirmMembership bool
	// Role is the performer's: operator when the policy names them,
	// participant when only membership can trust them.
	Role Role
	// Agent says the performer is an agent the policy allows to mention this
	// one (Trust.AgentIDs). Only the mentioned rule is open to it, its role
	// is participant, and the committer holds it to the agent caps.
	Agent bool
	// InPing says the performer is trusted only as a participant of the Ping
	// the event's bucket is keyed as (Policy.Pings): only once the Ping read
	// confirms the bucket is a Ping, and only by mention.
	InPing 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 PingReader interface {
	Ping(ctx context.Context, bucketID int64) (*basecamp.Ping, error)
}

type PingTrust struct {
	Participants []int64 `json:"participants,omitempty"`
}

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

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"`
	// Pings maps a Ping's bucket id to who may reach the agent in that Ping
	// alone. Trust, like Trust: read once, never live.
	Pings map[int64]PingTrust `json:"pings,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
	Boosts        BoostReader
	Pings         PingReader
	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 Role string

type Rule struct {
	Trigger Trigger
	// OperatorOnly restricts the rule to events the operator performed,
	// whatever the trust mode, and to the people the allowlist names when
	// Trust.AllowAssignments opts them in. Assignments run the agent against
	// a recording on the assigner's say-so, so no broadened mode extends to
	// them by itself.
	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, a
	// subscription comment or a boost 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"`
	// Role is whose request this is: an operator's or a participant's.
	Role Role `json:"role,omitempty"`
	// Owner says the operator connect.json names asked, in words they wrote:
	// they mentioned the agent, wrote to it in their direct Ping, or assigned
	// it a recording they wrote. A
	// comment on a followed thread, a completion and a boost are never the
	// owner's word; an operator's go on a declared ask is a separate
	// approval (AskRecordingID) and does not make one. Someone named with --allow is an operator but never the
	// owner, and neither is the owner bringing in someone else's words: an
	// allowlisted person's to-do the owner moves in is that person's.
	Owner bool `json:"owner,omitempty"`
	// Ask is the boosted post as this decision read it, on an operator's
	// boost that may be a declared ask's go: the exact words the fingerprint
	// was taken over. A go approves these words, not the post as it is
	// later, so the handoff gives them to the worker to act on.
	Ask *AskCopy `json:"ask,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 as operators besides the
	// operator, in allowlist or project mode.
	AllowlistIDs []int64 `json:"allowlist_ids,omitempty"`
	// AllowAssignments lets the people AllowlistIDs names assign the agent
	// work, as the operator does. Off, assignments are the operator's alone.
	AllowAssignments bool `json:"allow_assignments,omitempty"`

	// AgentIDs are other agents (Agent persons) allowed to wake this one by
	// @mentioning it. Empty, the default, admits no agent at all. An allowed
	// agent reaches the agent by mention only, never by assignment, by a
	// comment on a thread it follows or by a completion, and its request is a
	// participant's, never an operator's. Any trust mode may name them.
	AgentIDs []int64 `json:"agent_ids,omitempty"`
	// AgentThreadCap is how many allowed agents' mentions one conversation
	// (a thread, or a Campfire) admits within AgentCapWindow, across every
	// allowed agent. Zero means DefaultAgentThreadCap.
	AgentThreadCap int `json:"agent_thread_cap,omitempty"`
	// AgentDailyCap is how many of one allowed agent's mentions are admitted
	// within AgentCapWindow across every conversation, so an agent opening a
	// new thread for each reply is bounded too. Zero means
	// DefaultAgentDailyCap.
	AgentDailyCap int `json:"agent_daily_cap,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 who asked: the performer, or, when a participant wrote
	// the words the performer brought in, that participant, the person the
	// role was settled on.
	RequesterID int64
	// Role is whose request an admitted event is, settled on everyone whose
	// trust admitted it: the performer and, for the triggers whose
	// instruction is the recording's content, its author.
	Role Role

	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, subscribed and boosted.
	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

	// AskRecordingID is set on an admitted boost the operator gave, on the
	// agent's own recording: the ask that boost would be the go for, if the
	// agent declared that recording an ask. Admission cannot see asks; the
	// ledger decides in the verdict's own transaction, so one ask gets one go.
	// Only the operator's boost carries it, in every trust mode: as with an
	// assignment, an allowlist or a broader trust mode never extends it.
	AskRecordingID int64
	// AskContentHash is AskFingerprint of the boosted recording's title and
	// content as this decision read it. The ledger gives the go only when it equals the
	// hash the ask was declared with: an ask edited since it was declared is
	// void, and its boost is an ordinary reply.
	AskContentHash string
	// AskBoostID is the boost's own id. Basecamp's boost ids only grow, so the
	// ledger orders it against the boosts already on the ask when it was
	// declared, on Basecamp's clock and no other.
	AskBoostID int64
	// contains filtered or unexported fields
}