client

type AuthMode int

type AvailableTransitions struct {
	State  string   `json:"state"`
	Inputs []string `json:"inputs"`
}

type CalBooking struct {
	BookingID   string    `json:"booking_id"`
	CalendarID  string    `json:"calendar_id"`
	State       string    `json:"state"`
	Span        CalSpan   `json:"span"`
	Mode        string    `json:"mode"`
	Bearer      uint64    `json:"bearer"`
	BufferAfter time.Time `json:"buffer_after,omitempty"`
	CreatedAt   time.Time `json:"created_at,omitempty"`
	UpdatedAt   time.Time `json:"updated_at,omitempty"`
	DetailRef   string    `json:"detail_ref,omitempty"`
}

type CalCheckResult struct {
	Feasible        bool      `json:"feasible"`
	NearestOpenings []CalSpan `json:"nearest_openings"`
}

type CalOpening struct {
	Start    time.Time `json:"start"`
	End      time.Time `json:"end"`
	MarginMs int64     `json:"margin_ms"`
}

type CalOpeningsResult struct {
	Objective Objective    `json:"objective"`
	Openings  []CalOpening `json:"openings"`
}

type CalProposeRequest struct {
	BookingID   string     `json:"booking_id"`
	CalendarID  string     `json:"calendar_id"`
	Span        CalSpan    `json:"span"`
	Mode        string     `json:"mode,omitempty"`
	Bearer      uint64     `json:"bearer,omitempty"`
	BufferAfter *time.Time `json:"buffer_after,omitempty"`
	DetailRef   string     `json:"detail_ref,omitempty"`
}

type CalSpan struct {
	Start time.Time `json:"start"`
	End   time.Time `json:"end"`
}

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

type ClientOption func(*Client)

type CommitAppend struct {
	Entity string         `json:"entity"`
	ID     *int64         `json:"id,omitempty"` // nil = auto-assign
	Data   map[string]any `json:"data"`
}

type CommitRequest struct {
	Update CommitUpdate   `json:"update"`
	Append []CommitAppend `json:"append"`
}

type CommitResult struct {
	Update struct {
		Entity  string `json:"entity"`
		ID      int64  `json:"id"`
		Created bool   `json:"created"`
		Version int    `json:"version"`
	} `json:"update"`
	Appended []struct {
		Entity string `json:"entity"`
		ID     int64  `json:"id"`
	} `json:"appended"`
}

type CommitUpdate struct {
	Entity  string         `json:"entity"`
	ID      int64          `json:"id"`
	Version *int           `json:"version,omitempty"` // nil = unconditional
	Data    map[string]any `json:"data"`
}

type CreateMachineRequest struct {
	// Definition is the fsm_def_id to instantiate.
	Definition int64 `json:"definition"`
	// Ref is an optional external identifier bound to the machine.
	Ref string `json:"ref,omitempty"`
	// Overrides narrow variable defaults or guard expressions on a
	// per-machine basis. Nil means no overrides.
	Overrides *MachineOverrides `json:"overrides,omitempty"`
}

type Entity struct {
	ID        int64
	Data      map[string]any
	CreatedAt time.Time
	UpdatedAt time.Time
}

type EntitySchema struct {
	// Name is the entity type name (e.g. "users", "orders").
	Name string `json:"name"`
	// Schema is the raw JSON Schema document for the entity, exactly as
	// returned by xolu.
	Schema json.RawMessage `json:"schema"`
	// Fields lists the entity's declared fields with their JSON Schema types.
	Fields []FieldDef `json:"fields,omitempty"`
	// Refs lists the subset of Fields that carry `"format":"ref"` — the
	// reference edges that populate xolu's graph layer.
	Refs []RefFieldDef `json:"refs,omitempty"`
}

type EntityTypeSummary struct {
	Name string `json:"name"`
}

type Error struct {
	// Code is the XOLU-<AREA><NUM> error code (e.g. "XOLU-ST001"). Empty when
	// the server did not return a structured error body.
	Code string
	// HTTPStatus is the HTTP status code (e.g. 400, 404, 500).
	HTTPStatus int
	// Message is the human-readable error message.
	Message string
	// Detail is the raw JSON body of the error response, preserved verbatim
	// so callers can extract server-specific fields the client does not
	// model. Nil when the response body was empty or not valid JSON.
	Detail json.RawMessage

	// StatusCode is preserved as an alias for HTTPStatus for backwards
	// compatibility with earlier client releases. New code should use
	// HTTPStatus.
	//
	// Deprecated: use HTTPStatus.
	StatusCode int
	// Details is preserved as a decoded map for backwards compatibility.
	// New code should use Detail (raw JSON) and decode as needed.
	//
	// Deprecated: use Detail.
	Details map[string]any
}

type EventDef struct {
	// ID is the subscription's numeric identifier, tenant-scoped.
	ID int64 `json:"id"`
	// EventType is the event type this subscription reacts to
	// (e.g. "entity.updated", "fsm.step", "commit.applied").
	EventType string `json:"event_type"`
	// ActionType names the delivery mechanism ("webhook", "oql").
	ActionType string `json:"action_type"`
	// Config is the raw action configuration.
	Config json.RawMessage `json:"config,omitempty"`
	// Execution declares the delivery mode ("async" today; "sync" is
	// accepted but silently downgraded — see the xolu changelog).
	Execution string `json:"execution"`
	// CreatedAt is the timestamp of subscription creation.
	CreatedAt string `json:"created_at,omitempty"`
}

type FieldDef struct {
	// Name is the field name as it appears in JSON documents.
	Name string `json:"name"`
	// Type is the JSON Schema type ("string", "integer", "number",
	// "boolean", "object", "array") or a xolu-specific format tag
	// ("decimal", "timestamp", "ref").
	Type string `json:"type"`
	// Required is true when the field is listed under the schema's
	// "required" array.
	Required bool `json:"required,omitempty"`
	// Format is the JSON Schema "format" declaration when present
	// (e.g. "email", "uuid", "date-time"). Empty when absent.
	Format string `json:"format,omitempty"`
}

type GCPolicy struct {
	StalledAfter string `json:"stalled_after,omitempty"`
	DeadAfter    string `json:"dead_after,omitempty"`
	OnGCCollect  string `json:"on_gc_collect,omitempty"`
}

type GeneratorDef struct {
	Name   string          `json:"name"`
	Config json.RawMessage `json:"config,omitempty"`
}

type GeneratorKind string

type GraphQueryResult struct {
	Status string           `json:"status"`
	Result []map[string]any `json:"result"` // xolu uses "result", not "data"
	Stats  GraphQueryStats  `json:"stats"`
}

type GraphQueryStats struct {
	NodesTraversed int   `json:"nodes_traversed"`
	PathsFound     int   `json:"paths_found"`
	ExecutionTime  int64 `json:"execution_time_ms"`
}

type HistoryEntry struct {
	// ID is the numeric identifier of this history row.
	ID int64 `json:"id"`
	// From is the state the machine was in before this step. Nil for the
	// initial "machine created" entry.
	From *string `json:"from"`
	// To is the state the machine was in after this step. Always set,
	// including on the initial entry (equal to the initial state).
	To string `json:"to"`
	// Input is the input symbol that drove the transition. Nil for the
	// initial entry.
	Input *string `json:"input"`
	// Payload is the raw payload supplied by the walk caller. Preserved
	// as raw JSON because xolu emits arbitrary caller-supplied shapes.
	Payload json.RawMessage `json:"payload,omitempty"`
	// Vars is the live variable map after this step, preserved as raw
	// JSON for the same reason.
	Vars json.RawMessage `json:"vars"`
	// Outputs is the transition's Mealy output, preserved as raw JSON.
	// Omitted when the transition emitted nothing.
	Outputs json.RawMessage `json:"outputs,omitempty"`
	// Note is a human-readable annotation. Present on the initial
	// "machine created" entry; typically nil on walk entries.
	Note string `json:"note,omitempty"`
	// At is the timestamp of this step.
	At string `json:"at"`
}

type ListParams struct {
	Limit  int
	Offset int
	Sort   string // field name, prefix with - for descending
}

type ListResult struct {
	Entities   []Entity
	Page       int
	PerPage    int
	TotalItems int
	TotalPages int
}

type Machine struct {
	// ID is the machine's numeric identifier, tenant-scoped.
	ID int64 `json:"id"`
	// Definition is the fsm_def_id the machine was instantiated from.
	Definition int64 `json:"definition"`
	// DefinitionName is the cached copy of the definition's name.
	DefinitionName string `json:"definition_name"`
	// DefinitionDeleted is true when the source definition has been
	// deleted since machine creation. The machine continues to operate
	// on its self-contained snapshot; this flag is informational.
	DefinitionDeleted bool `json:"definition_deleted"`
	// State is the machine's current state name.
	State string `json:"state"`
	// Vars is the current live variable map. Keys are variable names,
	// values are the raw JSON values as the FSM evaluator stores them.
	Vars map[string]interface{} `json:"vars"`
	// Ref is the optional external identifier bound at creation time,
	// echoed only when present.
	Ref string `json:"ref,omitempty"`
	// CreatedAt is the timestamp of machine creation.
	CreatedAt string `json:"created_at"`
}

type MachineDef struct {
	// ID is the definition's numeric identifier, tenant-scoped.
	ID int64 `json:"id"`
	// CreatedAt is the timestamp of definition creation.
	CreatedAt string `json:"created_at"`
	// Spec is the definition body — states, transitions, variables.
	Spec MachineSpec `json:"spec"`
	// Analysis is xolu's structural-analysis output for the definition.
	// Kept opaque as json.RawMessage because the shape is server-internal.
	Analysis json.RawMessage `json:"analysis,omitempty"`
}

type MachineDefSummary struct {
	ID        int64  `json:"id"`
	Name      string `json:"name"`
	CreatedAt string `json:"created_at"`
}

type MachineFilter struct {
	// Definition filters by fsm_def_id. Zero means no filter.
	Definition int64
	// State filters by current state name. Empty string means no filter.
	State string
	// Ref filters by the external identifier bound at creation. Empty
	// string means no filter.
	Ref string
}

type MachineOverrides struct {
	// Variables overrides variable declarations. Keyed by variable name.
	Variables map[string]VariableDef `json:"variables,omitempty"`
	// Transitions overrides transition guards. Keyed by transition input.
	Transitions map[string]TransitionOverride `json:"transitions,omitempty"`
}

type MachineResult struct {
	// Machine is the machine's numeric identifier.
	Machine int64 `json:"machine"`
	// State is the current state name.
	State string `json:"state"`
	// Terminal is true when State is a terminal state.
	Terminal bool `json:"terminal"`
	// Vars is the live variable map.
	Vars map[string]interface{} `json:"vars"`
	// FinalOutput is the output emitted by the transition that reached
	// the current state, but only meaningful once Terminal is true.
	// Preserved as raw JSON because xolu emits either a JSON array of
	// output names or an empty array; consumers can decode as needed.
	FinalOutput json.RawMessage `json:"final_output,omitempty"`
}

type MachineSpec struct {
	Name           string                 `json:"name"`
	Description    string                 `json:"description,omitempty"`
	Initial        string                 `json:"initial"`
	Determinism    string                 `json:"determinism"`
	States         map[string]StateDef    `json:"states"`
	Variables      map[string]VariableDef `json:"variables,omitempty"`
	Transitions    []TransitionDef        `json:"transitions"`
	OutputAlphabet []string               `json:"output_alphabet,omitempty"`
	LinkedStates   map[string]int64       `json:"linked_states,omitempty"`
	GC             *GCPolicy              `json:"gc,omitempty"`
	// InputQueries associates an OQL SELECT with an input symbol. See the
	// xolu documentation for the exact semantics of the query-before-walk
	// evaluation pattern.
	InputQueries map[string]string `json:"input_queries,omitempty"`
}

type MachineState struct {
	State    string `json:"state"`
	Terminal bool   `json:"terminal"`
}

type MachineSummary struct {
	// ID is the machine's numeric identifier, tenant-scoped.
	ID int64 `json:"id"`
	// Definition is the fsm_def_id the machine was instantiated from.
	Definition int64 `json:"definition"`
	// DefinitionName is a cached copy of the definition's name at
	// creation time. Persists even if the definition is later renamed or
	// deleted.
	DefinitionName string `json:"definition_name"`
	// State is the machine's current state name.
	State string `json:"state"`
	// Ref is the optional external identifier bound at creation time,
	// e.g. an entity URI. Nil when the machine was created without a ref.
	Ref *string `json:"ref"`
	// CreatedAt is the timestamp of machine creation.
	CreatedAt string `json:"created_at"`
}

type NeighborResult struct {
	Outgoing map[string]string `json:"outgoing,omitempty"`
	Incoming map[string]string `json:"incoming,omitempty"`
}

type OQLResult struct {
	Status string           `json:"status"`
	Data   []map[string]any `json:"data"`
	Stats  OQLStats         `json:"stats"`
}

type OQLStats struct {
	RowsScanned   int   `json:"rows_scanned"`
	RowsReturned  int   `json:"rows_returned"`
	RowsAffected  int   `json:"rows_affected,omitempty"`
	ExecutionTime int64 `json:"execution_time_ms"`
}

type Objective string

type PatchMachineRequest struct {
	Overrides *MachineOverrides `json:"overrides,omitempty"`
}

type PathResult struct {
	From   string   `json:"from"`
	To     string   `json:"to"`
	Exists bool     `json:"exists"`
	Path   []string `json:"path"`
	Length int      `json:"length"`
}

type RefFieldDef struct {
	// Name is the field name (e.g. "author_id").
	Name string `json:"name"`
	// Target is the entity type the reference points to
	// (e.g. "users"). Extracted from the schema's `"target"` extension
	// when present; empty when the target is polymorphic.
	Target string `json:"target,omitempty"`
}

type RetryPolicy struct {
	// MaxAttempts is the total number of attempts including the first.
	// MaxAttempts=1 means "no retry", MaxAttempts=3 means "up to two
	// retries after the first attempt". Values less than 1 are treated
	// as 1.
	MaxAttempts int

	// InitialBackoff is the wait before the second attempt. Subsequent
	// attempts wait InitialBackoff * BackoffMultiplier^(attempt-1),
	// capped at MaxBackoff.
	InitialBackoff time.Duration

	// MaxBackoff is the ceiling on backoff between attempts. Zero means
	// "no ceiling", which is rarely what a caller wants; the default
	// policy from DefaultRetryPolicy sets a sensible ceiling.
	MaxBackoff time.Duration

	// BackoffMultiplier is the factor by which backoff grows between
	// attempts. Values less than 1 (including zero) are treated as 1,
	// producing constant backoff.
	BackoffMultiplier float64

	// RetryOn decides whether a given attempt outcome is retryable.
	// If nil, DefaultRetryOn is used, which retries transport errors
	// and 5xx responses.
	//
	// The predicate MUST NOT return true for context cancellation or
	// deadline exceeded — the retry loop honours those errors as final
	// regardless of RetryOn's answer, but the predicate is called first
	// and should return false on them for clarity.
	RetryOn func(resp *http.Response, err error) bool
	// contains filtered or unexported fields
}

type SearchParams struct {
	Query  string
	Entity string // optional entity type filter
	Limit  int
	Offset int
}

type Sequence struct {
	Name        string `json:"name"`
	Start       int64  `json:"start"`
	Current     int64  `json:"current"`
	IncrementBy int64  `json:"increment_by"`
	Cycle       bool   `json:"cycle"`
	MinVal      *int64 `json:"min_val,omitempty"`
	MaxVal      *int64 `json:"max_val,omitempty"`
}

type SequenceSummary struct {
	Name        string `json:"name"`
	Current     int64  `json:"current"`
	IncrementBy int64  `json:"increment_by"`
	Cycle       bool   `json:"cycle"`
}

type StateDef struct {
	Terminal bool `json:"terminal"`
}

type SulpherResult = GraphQueryResult

type TransitionDef struct {
	From   json.RawMessage   `json:"from"`
	Input  string            `json:"input"`
	To     string            `json:"to"`
	Guard  string            `json:"guard,omitempty"`
	Output string            `json:"output,omitempty"`
	Set    map[string]string `json:"set,omitempty"`
}

type TransitionOverride struct {
	// Guard is the new T-SQL guard expression. Nil means "leave the
	// existing guard in place"; the empty string means "clear the guard".
	Guard *string `json:"guard,omitempty"`
}

type V2Availability struct {
	Version    string          `json:"version"`
	Enabled    bool            `json:"enabled"`
	AsOf       time.Time       `json:"as_of"`
	Warning    string          `json:"warning,omitempty"`
	Subsystems json.RawMessage `json:"subsystems,omitempty"`
}

type VariableDef struct {
	Type    string      `json:"type"`
	Default interface{} `json:"default"`
}

type VariableSnapshot struct {
	Value   interface{} `json:"value"`
	Type    string      `json:"type,omitempty"`
	Default interface{} `json:"default,omitempty"`
}

type WalkRequest struct {
	// Input is the input symbol driving the transition. Required.
	Input string `json:"input"`
	// Payload provides arbitrary key/value data available to guards and
	// set-clauses under the "payload." prefix during evaluation. Nil is
	// permitted; the FSM will use only variables and (optionally) the
	// pre-walk query result.
	Payload map[string]interface{} `json:"payload,omitempty"`
}

type WalkResult struct {
	// Previous is the state the machine was in before the walk.
	Previous string `json:"previous"`
	// Current is the state the machine is in after the walk.
	Current string `json:"current"`
	// Terminal is true when Current is a terminal state.
	Terminal bool `json:"terminal"`
	// Outputs is the Mealy output emitted by the transition. Multi-valued
	// because a machine's output alphabet may name several outputs;
	// individual transitions typically emit at most one.
	Outputs []string `json:"outputs"`
	// Vars is the live variable map after set-clauses have applied.
	Vars map[string]interface{} `json:"vars"`
	// HistoryID is the id of the history row recording this walk.
	HistoryID int64 `json:"history_id"`
}