scriptrun

type Caller interface {
	// CallTool invokes the named tool and returns its structured content. A
	// tool that reports an error returns a non-nil error carrying the tool's
	// message; the script sees it as a Starlark error and the run fails.
	CallTool(ctx context.Context, name string, args map[string]any) (map[string]any, error)
}

type ExportRecord struct {
	Name string `json:"name"`
	// Destination is the name the script wrote, so a run that sends one result
	// to two places reads as two records rather than as a repeat.
	Destination string `json:"destination"`
	Format      string `json:"format"`
	RowCount    int    `json:"row_count"`
	// Document marks an output written verbatim from a string body, whose
	// RowCount is therefore not a fact about it: without the marker a surface
	// rendering "N rows as html" would describe a dashboard as an empty table.
	Document bool `json:"document,omitempty"`
	// Refresh marks a platform.publish_data call: the run replaced the data
	// region of an existing asset rather than writing a whole output, and
	// Bytes is the payload spliced in, not the document around it.
	Refresh bool `json:"refresh,omitempty"`
	// Bytes is the serialized length of the output in its declared format. A
	// preview serializes to measure rather than estimating, so the number is
	// the same one a real run would report for the same rows.
	Bytes int `json:"bytes"`
	// Preview is true when nothing was persisted.
	Preview      bool   `json:"preview"`
	AssetID      string `json:"asset_id,omitempty"`
	AssetVersion int    `json:"asset_version,omitempty"`
	Bucket       string `json:"bucket,omitempty"`
	Key          string `json:"key,omitempty"`
}

type ExportRequest struct {
	// Name identifies the output across runs. It is the stable half of the
	// output's identity: the same name from the same script maps to one asset
	// whose versions are its run history.
	Name string
	// Format is one of the formats exportFormats admits.
	Format string
	// Columns is the column order the script wrote, read from the rows before
	// they became order-free Go maps. A tabular format writes its columns in
	// this order; see columnOrder.
	Columns []string
	// Rows is the list of row dicts to write. Nil when the script passed a
	// string body instead, which Body then carries.
	Rows []any
	// Body is the document arm: a string the script composed, persisted
	// verbatim. Valid for the document formats (markdown, text, html, jsx) and
	// nil for a tabular output — exactly one of Body and Rows is the content.
	Body *string
	// Destination is the destination the output goes to, already resolved from
	// the name the script wrote to the address configuration declares for it.
	Destination script.Destination
	// Key is the object key the script asked for beneath the destination's
	// configured prefix, empty when it named none and never set for the portal.
	Key string
}

type ExportResult struct {
	AssetID      string
	AssetVersion int
	Bucket       string
	Key          string
	// Bytes is the serialized size actually written.
	Bytes int
}

type Exporter interface {
	// Export writes one output and reports where it landed. An error fails the
	// run: a report whose output did not persist did not happen.
	Export(ctx context.Context, req ExportRequest) (*ExportResult, error)

	// PublishData replaces the data region of the named output asset with the
	// request's payload and reports the version that created. An error fails
	// the run: a dashboard that did not refresh did not refresh.
	PublishData(ctx context.Context, req PublishRequest) (*ExportResult, error)
}

type Finding struct {
	Severity string `json:"severity" example:"error"`
	Line     int    `json:"line,omitempty" example:"12"`
	Message  string `json:"message"`
	// Hint is the corrective action. It carries most of the value of this
	// validator: an author who writes Python at a Starlark interpreter needs to
	// be told what to write instead, not merely that the parser disagreed.
	Hint string `json:"hint,omitempty"`
}

type Options struct {
	// Source is the Starlark source to execute, and Name labels it in tracebacks.
	Source string
	Name   string

	// RunID, FireTime and Params populate the frozen run dict — the script's
	// only source of time and of caller input.
	RunID    string
	FireTime time.Time
	Params   map[string]any

	// Caller issues the script's platform tool calls. A nil Caller leaves the
	// platform module predeclared but every call on it fails, which is what a
	// syntax-only execution wants.
	Caller Caller

	// Destinations is the deployment's configured bucket destinations, the set
	// a platform.export destination name resolves against at run time. The
	// portal is built in and never listed here. A draft run and a platform run
	// carry the same set, so the script an author finishes is the script that
	// runs.
	Destinations []script.Destination

	// Exporter persists what platform.export produces. nil previews instead,
	// which is what a draft run does.
	Exporter Exporter

	// Limits. Zero means the draft default.
	MaxSteps       uint64
	Timeout        time.Duration
	MaxRows        int
	MaxResultBytes int
	MaxLogBytes    int
}

type OutputIdentity struct {
	ContentType string
	Extension   string
}

type PublishRequest struct {
	// Name identifies the target asset through the same identity rule an
	// export's name resolves by: one (script, name) pair is one asset. The
	// asset must already exist — this call refreshes a region of it and can
	// create nothing.
	Name string
	// Data is the payload the asset's data region will hold, already converted
	// to plain Go values. FormatDataPayload is its one serializer, shared by
	// the draft preview and the platform run's write.
	Data any
}

type Report struct {
	OK       bool      `json:"ok"`
	Findings []Finding `json:"findings"`
	// Capabilities is the set of host bindings the source references, and
	// Connections the connection names it names literally, across every call.
	Capabilities []string `json:"capabilities"`
	Connections  []string `json:"connections"`
	// Destinations is where this script's OUTPUTS go: the destination names
	// platform.export writes to, plus the portal for an export that names none
	// and for every platform.publish_data. It is a statement about the output
	// surface, not about every byte the script can move — a script that writes
	// through a tool, say platform.call("s3_put_object", ...), produces no
	// output in this sense and is read in Tools instead.
	Destinations []string `json:"destinations"`
	// Tools is the tool names the source passes to platform.call literally,
	// sorted. It is where a reader learns the reach of the open half of the
	// surface: the persona filter decides what a run MAY call, and this says
	// what this source DOES call (#1419).
	Tools []string `json:"tools"`
	// RefreshTargets is the output names platform.publish_data refreshes, read
	// literally from the calls, so a reader sees WHICH asset's data region a
	// script rewrites.
	RefreshTargets []string `json:"refresh_targets"`
	// DynamicConnections is true when a platform.query call computes its
	// connection instead of naming one literally, DynamicDestinations when
	// a platform.export call computes its destination, and DynamicRefreshTargets
	// when a platform.publish_data call computes the name it refreshes, so the
	// list in question is known to be incomplete. Reporting the gap is the
	// point: a reader shown a list that silently omitted a computed name would
	// be reading a false statement.
	DynamicConnections    bool `json:"dynamic_connections"`
	DynamicDestinations   bool `json:"dynamic_destinations"`
	DynamicRefreshTargets bool `json:"dynamic_refresh_targets"`
	// DynamicTools is true when a platform.call computes the tool it invokes,
	// so the tool list is known to be incomplete. A call that computes its
	// ARGUMENT SET leaves the tool list intact and sets DynamicConnections
	// instead, because the connection is the only claim this report makes
	// about what is inside those arguments.
	DynamicTools bool `json:"dynamic_tools"`
}

type Result struct {
	// Log is the captured print output, truncated at the log cap.
	Log string `json:"log"`
	// LogTruncated is true when output was dropped at the cap.
	LogTruncated bool `json:"log_truncated"`
	// Steps is the interpreter step count the run consumed, and Duration its
	// wall-clock time. Both are the raw material for sizing a platform run's
	// limits against a draft that already works.
	Steps    uint64        `json:"steps"`
	Duration time.Duration `json:"-"`
	// Queries counts the platform.query calls the run issued.
	Queries int `json:"queries"`
	// Exports lists what every platform.export call did, in call order.
	Exports []ExportRecord `json:"exports"`
}

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