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"`
	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.
	Rows []any
	// Destination is the granted destination the output goes to, already
	// resolved from the name the script wrote to the address its approval
	// pinned. A draft carries only the name, because a draft writes nothing and
	// there is no approval yet to resolve against.
	Destination script.Destination
	// Key is the object key the script asked for beneath the destination's
	// granted 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, which the writer knows
	// exactly and the engine can only estimate.
	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)
}

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

	// Grants, when non-nil, is the approved capability set this run is confined
	// to: the host bindings it may call, the connections it may query, and the
	// destinations it may write. nil means no grant layer applies, which is the
	// draft case — a draft executes as its own author, with that author's
	// authority, so there is nothing to narrow.
	//
	// A non-nil grant with empty lists denies everything, which is the correct
	// reading of "approved with nothing granted" and the reason this is a
	// pointer rather than a value.
	Grants *script.Grants

	// 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 Report struct {
	OK       bool      `json:"ok"`
	Findings []Finding `json:"findings"`
	// Capabilities is the set of host bindings the source references,
	// Connections the connection names it names literally, and Destinations
	// the output destinations it names literally. Together they are the raw
	// material for the grants diff a reviewer will be shown: what the code
	// reaches, next to what it was granted.
	Capabilities []string `json:"capabilities"`
	Connections  []string `json:"connections"`
	Destinations []string `json:"destinations"`
	// DynamicConnections is true when a platform.query call computes its
	// connection instead of naming one literally, and DynamicDestinations when
	// a platform.export call computes its destination, so the list in question
	// is known to be incomplete. Reporting the gap is the point: a reviewer
	// reading a list that silently omitted a computed name would be reading a
	// false statement.
	DynamicConnections  bool `json:"dynamic_connections"`
	DynamicDestinations bool `json:"dynamic_destinations"`
}

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 an approved 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
}