tableregister

type AuditLogger interface {
	Log(ctx context.Context, event audit.Event) error
}

type Caller struct {
	UserID  string
	Email   string
	Persona string
	Roles   []string
	IsAdmin bool
	// OnBehalfOf is the address of the person an unattended caller acts for,
	// empty for a person acting as themselves. A managed-script run
	// authenticates as a principal that owns no stored file, so the authority
	// checks over the file being registered read this to reach what the run's
	// author reaches (#1419, #1487). The portal path never sets it: a browser
	// request is always somebody acting as themselves.
	OnBehalfOf string
}

type Column = tablecsv.Column

type ConnectionScope interface {
	AllowConnection(persona, connection string) bool
}

type Deps struct {
	Store Store
	Trino Executor
	// Objects reads a source's bytes, keyed by source kind. It is per kind
	// because the two kinds do not have to share an object store: a
	// deployment names the portal's S3 connection and the managed-resources
	// one separately, and reading a resource through the portal's client
	// would look in the wrong bucket on any deployment that split them.
	Objects map[string]ObjectReader
	// Revisers save a corrected copy of a source as a new version of itself,
	// keyed by source kind the way Objects is and for the same reason: the two
	// kinds keep their version trails in different places. A kind with no
	// entry can be registered and refused, but not corrected.
	Revisers map[string]Reviser
	Scope    ConnectionScope
	Audit    AuditLogger
	NewID    func() (string, error)
	MaxBytes int64
}

type Executor interface {
	Exec(ctx context.Context, connection, sql string) error
	ScratchTarget(connection string) (trino.ScratchConfig, bool)
	// AcceptsWrites reports whether Exec would be allowed to run write SQL on
	// this connection. It is on the port rather than discovered by assertion
	// because the picker MUST ask it: a connection that carries a scratch
	// target but refuses writes was offered and then refused its DDL.
	AcceptsWrites(connection string) bool
	// TableExists reports whether the catalog on a connection still holds a
	// table. It is what a write that ran DROP TABLE asks about every OTHER
	// registration on the connection afterwards (#1546): an object store
	// whose prefix listing does not stop at a directory boundary lets one
	// table's drop take a name-prefix sibling's metadata with it, and the
	// registration row would otherwise go on describing a table that is
	// not there.
	TableExists(ctx context.Context, connection, catalog, schema, table string) (bool, error)
}

type Filter struct {
	// AllConnections lifts the connection boundary, which is what an
	// administrator gets.
	//
	// It is a flag rather than a nil Connections slice because the two states
	// it separates are opposites and both are reachable: a persona granted no
	// connection reaches nothing, and an administrator reaches everything.
	// Reading one as the other would either hide every table from an operator
	// or show every table to a persona that may query none of them.
	AllConnections bool
	// Connections is what the caller may see when AllConnections is not set.
	Connections []string
	// SourceKind limits the listing to KindResource or KindAsset. Empty spans
	// both, which is the point of the listing.
	SourceKind string
	// Query matches the qualified name -- catalog, schema and table -- without
	// regard to case.
	Query string
	// Limit and Offset page the result. A Limit at or below zero takes
	// DefaultListLimit, and one above MaxListLimit takes that: the caller of a
	// listing does not get to ask for the whole table.
	Limit  int
	Offset int
}

type FollowOutcome struct {
	RegistrationID string `json:"registration_id"`
	// Table is the qualified name a query writes, and Connection where it
	// lives; together they name the table the way every surface does.
	Table      string `json:"table"`
	Connection string `json:"connection"`
	// Followed means the table now reads the version the write produced.
	Followed bool `json:"followed"`
	// Version is the version the write produced, which a followed table now
	// reads and a table that did not follow is behind.
	Version int `json:"version"`
	// Pinned means the registration was made without follow, so it stays on
	// the version it was registered over by design.
	Pinned bool `json:"pinned,omitempty"`
	// Reason is why a following registration was not moved. Empty when it
	// followed or is pinned.
	Reason string `json:"reason,omitempty"`
	// ColumnsChanged means the new version's header differs from the one the
	// table declared, so the table was rebuilt with the new columns.
	ColumnsChanged bool `json:"columns_changed,omitempty"`
	// Missing means the table this registration names no longer exists on
	// its connection: a write that ran DROP TABLE on the connection found it
	// gone afterwards (#1546). Reason says which write. The registration is
	// kept, with the reason recorded on it, so the listing says so too.
	Missing bool `json:"missing,omitempty"`
	// Repaired is what a correction of the new version changed, when the
	// version arrived with a defect a reader cannot see past and a
	// registration carrying the repair choice had it corrected (#1577).
	//
	// It is carried by one outcome, not by every table over the file: the
	// corrected version is a fact about the file, and the follow that read
	// the new head is the one that saved it.
	Repaired string `json:"repaired,omitempty"`
}

type Locator func(ctx context.Context, kind, id string) (Source, bool)

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

type ObjectEntry struct {
	Key  string
	Size int64
}

type ObjectReader interface {
	GetObject(ctx context.Context, bucket, key string) (body []byte, contentType string, err error)
	ListDirectory(ctx context.Context, bucket, prefix string) (entries []ObjectEntry, truncated bool, err error)
}

type Record struct {
	ID          string
	Name        string
	Bucket      string
	Key         string
	ContentType string
}

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

type Registration struct {
	ID           string    `json:"id"`
	SourceKind   string    `json:"source_kind"`
	SourceID     string    `json:"source_id"`
	Connection   string    `json:"connection"`
	Catalog      string    `json:"catalog"`
	Schema       string    `json:"schema"`
	Table        string    `json:"table"`
	Location     string    `json:"location"`
	Columns      []Column  `json:"columns"`
	RegisteredBy string    `json:"registered_by"`
	RegisteredAt time.Time `json:"registered_at"`
	// Follow means the registration is moved to the source's new head
	// directory when a revision or version is written (#1536). It is what a
	// registration gets unless the caller pins it: a person or an agent that
	// replaces a file expects the table over it to read the new contents.
	// Pinned -- follow off -- is the choice for a report that must keep
	// returning the rows it was registered over until somebody decides
	// otherwise.
	Follow bool `json:"follow"`
	// Repair means the registration corrects its file: a version of the source
	// carrying a defect a reader cannot see past, of a kind the platform can
	// correct, is saved corrected as the file's next version and the table is
	// moved onto that version (#1577). Off -- the default, and what a
	// registration made without asking gets -- such a version leaves the
	// registration where it was with the reason recorded on it, because nobody
	// asked for the file to be rewritten.
	//
	// It is on the record because the follow has nothing else to act on: the
	// choice was made once, at a registration, and the versions it applies to
	// arrive afterwards. It does nothing for a registration that is not
	// following, which never meets a new version at all.
	Repair bool `json:"repair"`
	// FollowError is why the last follow did not move the registration, and is
	// empty while it is where the file is. It is kept on the record because a
	// follow never fails the write that triggered it, so the listing has to be
	// able to say what is behind and why without the log of that write.
	FollowError string `json:"follow_error,omitempty"`
}

type RepairReport struct {
	tablecsv.NormalizeReport
	Version int `json:"version"`
	// Followed is what writing the corrected version did to every OTHER
	// registration over the file (#1536): a following one was moved onto it,
	// a pinned one is now behind it. The registration the correction was made
	// for is not among them, being current by construction.
	Followed []FollowOutcome `json:"followed,omitempty"`
}

type Request struct {
	Connection string
	// TableName is the caller's choice. Empty takes a slug of the source's
	// filename. Either way it is slugified and persona-prefixed.
	TableName string
	// Source names where the registration comes from: "portal" for a REST or
	// UI action, "mcp" for a tool call. It is recorded on the audit event.
	Source string
	// Repair asks the platform to save a corrected version of the file when it
	// cannot be read as a table the way it is stored, and to register that
	// version. Without it such a file is refused and the refusal says what is
	// wrong with it, because correcting somebody's file is not something to do
	// on the way to something they asked for.
	Repair bool
	// Follow moves the registration to the file's new head whenever a
	// revision or version of it is written (#1536). Off, the registration is
	// pinned to the directory it was registered over, and a later write
	// leaves it behind the file and says so. The surfaces default it to on;
	// the registrar takes the resolved choice.
	Follow bool
}

type Result struct {
	Registration
	Source Source `json:"-"`
	// Correction is what saving a corrected version changed, or nil when the
	// file was registered exactly as it was stored.
	//
	// It is not called Repair. The embedded Registration carries a Repair of
	// its own -- the standing choice this registration was made with (#1577) --
	// and two fields under one name at two depths is a shadow in Go and a
	// dropped field in JSON: encoding/json keeps the shallower tag and emits
	// neither the report nor the choice.
	Correction *RepairReport `json:"correction,omitempty"`
	// Siblings is what a replacing registration found about the OTHER
	// registrations on the connection after its DROP ran (#1546): one outcome
	// per table that no longer exists. Empty when every other table is still
	// there, and always empty for a registration that replaced nothing.
	Siblings []FollowOutcome `json:"siblings,omitempty"`
}

type Revised struct {
	Bucket  string
	Key     string
	Version int
}

type Reviser interface {
	Revise(ctx context.Context, src Source, caller Caller, content []byte, summary string) (Revised, error)
}

type Source struct {
	Kind        string
	ID          string
	Name        string
	Bucket      string
	HeadKey     string
	ContentType string
}

type SourceRef struct {
	// Name is what the source is called, for a reader who is looking at a
	// table name and does not recognize it.
	Name string
	// Bucket and HeadKey are where the source's content sits NOW, which is the
	// half IsStale needs and the registration does not carry.
	Bucket  string
	HeadKey string
	// CanModify is authority over the source, the half of the unregister rule
	// the registration cannot answer. It is resolved here rather than at the
	// point of the action because a listing has to decide whether to offer the
	// action at all, and offering one that is then refused is the same defect
	// as refusing one that was never offered.
	CanModify bool
}

type Sources func(ctx context.Context, kind string, ids []string, caller Caller) map[string]SourceRef

type Store interface {
	Insert(ctx context.Context, r Registration) error
	Get(ctx context.Context, id string) (*Registration, error)
	// ByName returns the registration holding a name on a connection, or nil
	// when the name is free.
	ByName(ctx context.Context, connection, catalog, schema, table string) (*Registration, error)
	// BySource returns every registration of one resource or asset.
	BySource(ctx context.Context, kind, sourceID string) ([]Registration, error)
	// ForSources returns the registrations of many sources of one kind, keyed
	// by source id. It is the read a list view and a search result set use, so
	// a page of hits costs one query rather than one per hit.
	ForSources(ctx context.Context, kind string, sourceIDs []string) (map[string][]Registration, error)
	// List returns a page of registrations across every source, newest first,
	// with the total the filter matched.
	//
	// It is the only read here that is not keyed by one source or one name,
	// which is why nothing could answer "what is registered on this platform"
	// before it: the scratch schema is shared, so a reader could query a table
	// through Trino that no surface would list (#1472).
	List(ctx context.Context, f Filter) ([]Registration, int, error)
	// Relocate moves a registration onto a new directory with the columns the
	// file there declares, and clears the failure of any earlier follow. It
	// is the store half of a follow (#1536): the table was already moved by
	// the DDL, and the row has to say what the table now reads.
	Relocate(ctx context.Context, id, location string, columns []Column) error
	// RecordFollowFailure keeps why a follow did not move a registration, so
	// a listing reports it behind the file with the reason.
	RecordFollowFailure(ctx context.Context, id, reason string) error
	Delete(ctx context.Context, id string) error
}

type Subject func(ctx context.Context, id string, caller Caller) (Source, bool)

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