client

func (*Client) BalAsOf ¶ added in v0.26.0

func (c *Client) BalAsOf(ctx context.Context, accountID string, at time.Time) (*BalAsOfResult, error)

BalAsOf returns accountID's balance as of instant at, read from the derived rollup plane (the fast path — nearest sealed checkpoint plus intervening buckets). Always agrees with the authoritative journal; the rollup rebuild oracle proves it server-side, not something a caller re-verifies per request.

Hits GET /api/v2/.../bal/asof?account={accountID}&at={RFC3339}. Returns *client.Error on non-2xx — notably XOLU-BAL002 for an unknown account.

func (*Client) BalBalance ¶ added in v0.26.0

func (c *Client) BalBalance(ctx context.Context, accountID string) (*BalBalanceResult, error)

BalBalance returns accountID's current authoritative balance — the guard-plane value, always exact and always current, unlike BalAsOf's derived-plane fast path.

Hits GET /api/v2/.../bal/balance?account={accountID}. Returns *client.Error on non-2xx — notably XOLU-BAL002 for an unknown account.

func (*Client) BalClose ¶ added in v0.26.0

func (c *Client) BalClose(ctx context.Context, at time.Time) (*BalCloseResult, error)

BalClose seals the tenant's whole account-set as of instant at (item 16 §7): advances the seal frontier and writes a closing checkpoint for every postable account together. Sealing is tenant-wide, not per-account — there is no way to close only one account's period over this API, by design (bal-conservation- primitive.md §7's "account-set" is the whole tenant here).

A closed period permanently refuses any future entry dated within it (XOLU-BAL003), regardless of an account's own backdated policy. This cannot be undone over the API or otherwise.

Hits POST /api/v2/.../bal/close. Returns *client.Error on non-2xx.

func (*Client) BalDefine ¶ added in v0.26.0

func (c *Client) BalDefine(ctx context.Context, req BalDefineRequest) (*BalAccount, error)

BalDefine creates or configures an account. Postable summary accounts (Postable: false) may parent postable leaves for hierarchical reporting but never receive a direct transfer.

Hits POST /api/v2/.../bal/def. Returns *client.Error on non-2xx.

func (*Client) BalEntries ¶ added in v0.26.0

func (c *Client) BalEntries(ctx context.Context, accountID string) (*BalEntriesResult, error)

BalEntries returns accountID's most recent journal entries (the server currently caps this at 100; see BalEntriesResult's doc).

Hits GET /api/v2/.../bal/entries?account={accountID}. Returns *client.Error on non-2xx — notably XOLU-BAL002 for an unknown account.

func (*Client) BalListAccounts ¶ added in v0.30.23

func (c *Client) BalListAccounts(ctx context.Context) (*BalListAccountsResult, error)

BalListAccounts returns every account defined on the tenant, each with its own definition and current balance -- no way existed to enumerate a tenant's own accounts at all before this (XM-2, XOT172); every other bal method requires already knowing an account's own id.

Hits GET /api/v2/.../bal/accounts. Returns *client.Error on non-2xx.

func (*Client) BalTransfer ¶ added in v0.26.0

func (c *Client) BalTransfer(ctx context.Context, req BalTransferRequest) (*BalTransferResult, error)

BalTransfer moves req.Amount (a decimal string at req.Scale) from req.From to req.To, both existing postable account ids. Supply req.TransferID for a caller-controlled idempotency key; a UUID is generated server-side when omitted.

Hits POST /api/v2/.../bal/transfer. Returns *client.Error on non-2xx — notably XOLU-BAL001 when the transfer would breach a floor or ceiling, and XOLU-BAL006 for a backdated entry.

func (*Client) BlobDelete ¶ added in v0.26.0

func (c *Client) BlobDelete(ctx context.Context, key string) (*BlobDeleteResult, error)

BlobDelete removes a key alias. The underlying content-addressed blob is not immediately removed -- xolu's own GC handles unreferenced blobs separately.

Hits DELETE /api/v1/blob/{key}. Returns *client.Error on non-2xx (XOLU-BLOB-not-found family maps to 404).

func (*Client) BlobExportStart ¶ added in v0.26.0

func (c *Client) BlobExportStart(ctx context.Context) (*BlobExportJob, error)

BlobExportStart starts an async export job for this client's own tenant. Returns immediately with a ticket; the export itself runs in the background server-side (deliberately low-priority and throttled to one job in flight per tenant -- a second call while one is already running returns *client.Error with HTTPStatus 409, carrying the existing ticket in its message).

Hits POST /api/v1/tenant/{tenant}/blob/export. Returns *client.Error on non-2xx.

func (*Client) BlobExportStatus ¶ added in v0.26.0

func (c *Client) BlobExportStatus(ctx context.Context, ticket string) (*BlobExportJob, error)

BlobExportStatus polls one export job's status by ticket.

Hits GET /api/v1/tenant/{tenant}/blob/export/{ticket}. Returns *client.Error (HTTPStatus 404) if the ticket is unknown to this tenant -- including a ticket that belongs to a different tenant, which is treated identically to "not found" rather than confirming it exists elsewhere.

func (*Client) BlobGet ¶ added in v0.26.0

func (c *Client) BlobGet(ctx context.Context, key string) (*BlobGetResult, error)

BlobGet retrieves a blob's content as a stream -- the response body is never buffered into memory, so this is safe to use for blobs of any size. The caller is responsible for reading and closing result.Body.

Hits GET /api/v1/blob/{key}. Single attempt, not retried -- see this file's own header comment. Returns *client.Error on non-2xx (Body is nil in that case; the error response itself is small and safely buffered internally before being decoded).

func (*Client) BlobHead ¶ added in v0.26.0

func (c *Client) BlobHead(ctx context.Context, key string) (*BlobHeadResult, error)

BlobHead retrieves a blob's metadata without its content -- cheaper than BlobGet when only size/hash/existence is needed.

Hits HEAD /api/v1/blob/{key}. Single attempt, not retried -- see this file's own header comment. Returns *client.Error on non-2xx; the server's own HEAD handler returns bare status codes with no JSON body on error, so the resulting *client.Error carries an HTTP status but no Code/Message.

func (*Client) BlobList ¶ added in v0.26.0

func (c *Client) BlobList(ctx context.Context, prefix string) (*BlobListResult, error)

BlobList lists stored blobs, optionally filtered by key prefix, sorted by key ascending (the server's own sort order).

Hits GET /api/v1/blob. Returns *client.Error on non-2xx.

func (*Client) BlobPut ¶ added in v0.26.0

func (c *Client) BlobPut(ctx context.Context, key, contentType string, body io.Reader) (*BlobPutResult, error)

BlobPut uploads content under key. If key is empty, the server stores the content addressed by its own SHA256 and returns that hash as the effective key (BlobPutResult.Key) -- no separate alias is written. contentType is sent as-is; pass "" to let the server default to application/octet-stream.

Keys are FLAT, not hierarchical -- there is no folder/prefix structure at the storage layer. A non-empty key must not contain '/' or '\', must not be "." or "..", and must not start with "." (reserved for internal use) -- validated client-side against xolu's own rules (pkg/blob/store.go's validateKey) before any request is sent, matching this client's established convention (see bal.go) of catching an obviously-invalid call before spending a round trip on it. BlobList's prefix filter still works normally on flat keys (a plain string prefix match, e.g. prefix "log-" matches "log-2026-01" and "log-2026-02") -- "flat" means no '/' delimiter is meaningful, not that prefix filtering is unavailable.

Hits POST /api/v1/blob with X-Blob-Key set when key is non-empty. Single attempt, not retried -- see this file's own header comment. Returns *client.Error on non-2xx.

func (*Client) BlobUsage ¶ added in v0.26.0

func (c *Client) BlobUsage(ctx context.Context) (*BlobUsageResult, error)

BlobUsage returns the most recently sampled disk usage for the tenant's blob namespace. Served from an in-memory cache the server's own background sampler maintains -- cheap, but SampledAt may be nil (and all counts zero) if the sampler has not yet completed its first walk. That is a valid response, not an error.

Hits GET /api/v1/blob/usage. Returns *client.Error on non-2xx (503 if the blob subsystem is not enabled server-side at all).

func (*Client) CalCheck ¶

func (c *Client) CalCheck(ctx context.Context, calendarID string, span CalSpan) (*CalCheckResult, error)

CalCheck asks whether span is bookable on the calendar right now, without creating anything. On infeasibility the result carries the nearest alternative openings.

Hits POST /api/v2/.../cal/check. Returns *client.Error on non-2xx.

func (*Client) CalConfirm ¶

func (c *Client) CalConfirm(ctx context.Context, calendarID, bookingID string) (*CalBooking, error)

CalConfirm transitions a proposed booking to binding and returns the updated record.

Hits POST /api/v2/.../cal/confirm. Returns *client.Error on non-2xx — notably XOLU-CAL003 for an illegal state transition and XOLU-CAL005 for an unknown booking.

func (*Client) CalCreateCalendar ¶ added in v0.30.23

func (c *Client) CalCreateCalendar(ctx context.Context, req CalCreateCalendarRequest) (*CalendarSummary, error)

CalCreateCalendar creates a new calendar on the tenant -- XM-8, xoluman's own report: no route anywhere created a calendar at all before this, despite the underlying capability (Manager.CreateCalendar) already existing and working correctly. The actual root blocker behind their own XM-2 report: CalListCalendars/CalListBookings both worked correctly, but had nothing to list, since nothing could be created through the public API to list in the first place.

Hits POST /api/v2/.../cal/calendars. Returns *client.Error on non-2xx — notably XOLU-CAL008 (ErrCalCalendarExists) if req.CalendarID is already taken.

func (*Client) CalListBookings ¶ added in v0.30.23

func (c *Client) CalListBookings(ctx context.Context, calendarID string, from, to time.Time) (*CalListBookingsResult, error)

CalListBookings returns every live (proposed, binding, or honoured) booking on calendarID whose own span overlaps [from, to) -- the inverse of CalOpenings: what's already booked, not what's free. Requested by xoluman (XM-2) for an occupancy grid, where CalOpenings alone can't show what's actually on the calendar.

Hits GET /api/v2/.../cal/bookings. Returns *client.Error on non-2xx — notably XOLU-CAL002 (ErrCalCalendarNotFound) for an unknown calendar.

func (*Client) CalListBookingsForBearer ¶ added in v0.30.23

func (c *Client) CalListBookingsForBearer(ctx context.Context, bearer uint64) (*CalListBookingsResult, error)

CalListBookingsForBearer returns every live (proposed, binding, or honoured) booking held by bearer across every calendar on the tenant -- the cross-calendar complement to CalListBookings, which is scoped to one calendar at a time. Requested by xoluman (XM-2) as an example of a gap the per-calendar shape leaves open: "what bookings does bearer X hold across every calendar."

Hits GET /api/v2/.../cal/bookings/by-bearer. Returns *client.Error on non-2xx.

func (*Client) CalListCalendars ¶ added in v0.30.23

func (c *Client) CalListCalendars(ctx context.Context) (*CalListCalendarsResult, error)

CalListCalendars returns every calendar defined on the tenant. Confirmed missing during the XOT180 audit (2026-08-11) -- the underlying storage capability already existed but was never reachable via HTTP; any UI building an occupancy grid needs to know which calendars exist before it can ask what's booked on any one.

Hits GET /api/v2/.../cal/calendars. Returns *client.Error on non-2xx.

func (*Client) CalOpenings ¶

func (c *Client) CalOpenings(ctx context.Context, calendarID string, from, to time.Time, duration time.Duration, objective Objective) (*CalOpeningsResult, error)

CalOpenings searches [from, to) for windows admitting duration, ranked by objective. The zero Objective lets the server default to ObjectiveEarliest; any other value is validated client-side against the four implemented objectives before the request is sent.

Hits POST /api/v2/.../cal/openings. Returns *client.Error on non-2xx.

func (*Client) CalPropose ¶

func (c *Client) CalPropose(ctx context.Context, req CalProposeRequest) (*CalBooking, error)

CalPropose creates a booking in the proposed state. req.BookingID is client-generated identity (e.g. a ULID) and required; the returned booking carries the server-assigned fields (state, timestamps).

Hits POST /api/v2/.../cal/propose. Returns *client.Error on non-2xx — notably XOLU-CAL004 when the span conflicts with existing occupancy.

func (*Client) Commit ¶

func (c *Client) Commit(ctx context.Context, req CommitRequest) (*CommitResult, error)

Commit performs an atomic upsert + one or more inserts in a single storage transaction. Use this when state-transition and audit-trail writes must land together or not at all. xolu endpoint: POST /commit (tenant-scoped: /api/v1/tenant/{t}/commit) Returns ErrConflict (wrapped) when the optimistic version check fails. Returns an error wrapping the xolu error message when an append entry uses an explicit ID that already exists. Maximum 25 entries in req.Append — enforced server-side (400 if exceeded).

func (*Client) Create ¶

func (c *Client) Create(ctx context.Context, entity string, data map[string]any) (*Entity, error)

Create creates a new entity in the specified collection. xolu returns {"message":"…","id":N} on creation — the document is not echoed back. Data on the returned Entity is nil; call Get if the full document is needed.

func (*Client) CreateMachine ¶

func (c *Client) CreateMachine(ctx context.Context, req CreateMachineRequest) (*Machine, error)

CreateMachine instantiates a new FSM machine from a definition. The definition must exist in the current tenant scope.

Hits POST /api/v2/fsm/machine. Returns *Machine on 201, *client.Error on non-2xx.

The response carries the machine's identity, initial state, and initial variable values (from the definition's declared defaults, further modified by any overrides supplied in the request).

func (*Client) CreateMachineDef ¶ added in v0.26.0

func (c *Client) CreateMachineDef(ctx context.Context, spec MachineSpec) (*MachineDefCreateResult, error)

CreateMachineDef registers a new FSM definition in the current tenant scope. spec is sent exactly as given -- server-side validation (determinism declared, states/transitions well-formed, exclusivity provable for a non-firstmatch machine) happens before anything is persisted; a spec that fails validation comes back as *client.Error, not a partially-created definition.

Hits POST /api/v2/fsm/def. Returns *client.Error on non-2xx (422 with an XOLU-FSM* code for a spec that fails validation, per the same rules ValidateMachineDef checks without storing).

func (*Client) DefineEntitySchema ¶ added in v0.26.0

func (c *Client) DefineEntitySchema(ctx context.Context, entityType string, schema map[string]interface{}) error

DefineEntitySchema registers or updates the schema for an entity type -- the write counterpart to GetEntitySchema. schema is the raw JSON Schema document (draft-07 shape: {"type":"object", "properties":{...},"required":[...]}), sent exactly as given; this client does not validate its contents beyond the entity type name itself, matching the server's own posture (schema shape validation happens server-side, at pkg/server/handlers.go's own validateSchemaFieldNames and the JSON Schema loader).

Calling this for an entity type that already has a schema updates it -- the server's own response message says "created/updated" regardless, and this client makes no distinction between the two cases in its own return value either.

Side effects, all server-side and outside this client's control: registering a schema creates or updates that entity type's adapted table (a column-per-field table optimised for direct SQL querying, replacing pure JSON-blob storage) and takes effect for validation immediately -- an existing entity of this type that doesn't conform to the new schema is not retroactively checked, but any subsequent write to it will be.

Hits POST /api/v1/schema/{entity}. Returns *client.Error on non-2xx (400 for an invalid entity name or non-identifier field names in the schema itself -- D-009's own DDL-injection guard -- 500 if schema loading or adapted-table registration fails server-side).

func (*Client) Delete ¶

func (c *Client) Delete(ctx context.Context, entity string, id int64) error

Delete removes an entity by ID.

func (*Client) DeleteMachine ¶

func (c *Client) DeleteMachine(ctx context.Context, id int64) error

DeleteMachine removes a machine and all its history from the current tenant scope.

Hits DELETE /api/v2/fsm/machine/{id}. Returns nil on 204, *client.Error on non-2xx (404 with XOLU-FSM003 when the machine does not exist).

func (*Client) DeleteMachineDef ¶ added in v0.26.0

func (c *Client) DeleteMachineDef(ctx context.Context, id int64) error

DeleteMachineDef removes an FSM definition.

Always permitted: confirmed directly against the server's own route comment ("delete a definition (always permitted)") and its handler (a plain DELETE with no check against existing machines) -- unlike ReplaceMachineDef's own future-machines-only framing might suggest by contrast, deleting a definition does NOT check whether any machine still references it. This client does not add a safety check of its own: no server-side query exists to count machines by definition ID to build one against, and adding that is a server-side feature request, not something to fake client-side.

Hits DELETE /api/v2/fsm/def/{id}. Returns nil on 204, *client.Error on non-2xx (404 with XOLU-FSM001/002/012 if id doesn't exist).

func (*Client) DxpDefCreate ¶ added in v0.26.0

func (c *Client) DxpDefCreate(ctx context.Context, req DxpDefCreateRequest) (*DxpDef, error)

DxpDefCreate registers a new dxp definition. The server computes and returns DxpAnalysis (CollapseEligible, EngineHomogeneous) at registration time; a caller does not supply it.

Hits POST /api/v2/.../dxp/def. Returns *client.Error on non-2xx -- notably XOLU-DXP006 when static analysis refuses the definition (unknown primitive, invalid pattern, malformed participant params).

func (*Client) DxpDefGet ¶ added in v0.26.0

func (c *Client) DxpDefGet(ctx context.Context, id int64) (*DxpDef, error)

DxpDefGet retrieves one definition by id, including its full spec, analysis, and bindings_schema -- everything a caller (or a molu-side tool adapter) needs to construct a valid DxpTxnCreateRequest against it without having to remember what was originally registered.

Hits GET /api/v2/.../dxp/def/{id}. Returns *client.Error on non-2xx -- notably XOLU-DXP006 (this def's own reserved code family) with HTTP 404 when id does not exist.

func (*Client) DxpDefList ¶ added in v0.26.0

func (c *Client) DxpDefList(ctx context.Context) (*DxpDefListResult, error)

DxpDefList returns every definition registered for the tenant, oldest first. Each entry is a DxpDefSummary, not a full DxpDef -- use DxpDefGet for one definition's spec and analysis.

Hits GET /api/v2/.../dxp/def. Returns *client.Error on non-2xx.

func (*Client) DxpTxnCreate ¶ added in v0.26.0

func (c *Client) DxpTxnCreate(ctx context.Context, req DxpTxnCreateRequest) (*DxpTxn, error)

DxpTxnCreate instantiates req.DefID and dispatches it -- one complete, synchronous call: by the time this returns, the instance has already reached a terminal status (committed, released, or expired). There is no separate "start" step and nothing left in-flight to poll for on a normal path; DxpTxnGet exists for after-the-fact observability (the sweep worker's own terminal states, or re-reading an instance created by another caller), not for waiting on this one to finish.

Hits POST /api/v2/.../dxp/txn. Returns *client.Error on non-2xx -- notably XOLU-DXP001 when Bindings fails DefID's own bindings_schema, and HTTP 404 when DefID does not exist. A non-committed outcome (released or expired) is NOT an error -- it is a normal response with Status set accordingly and Reason naming why; check resp.Status, do not assume a nil error means committed.

func (*Client) DxpTxnGet ¶ added in v0.26.0

func (c *Client) DxpTxnGet(ctx context.Context, id int64) (*DxpTxn, error)

DxpTxnGet retrieves one transaction instance by id, including its full resolved snapshot -- the after-the-fact observability surface item 20's own remaining scope named explicitly as missing until it was built: a caller (or the sweep worker's own operator-facing tooling) can now see a swept, expired, or torn instance's full participant list and outcome, not just that something happened.

Hits GET /api/v2/.../dxp/txn/{id}. Returns *client.Error on non-2xx -- HTTP 404 when id does not exist.

func (*Client) DxpTxnList ¶ added in v0.26.0

func (c *Client) DxpTxnList(ctx context.Context, status string) (*DxpTxnListResult, error)

DxpTxnList returns every transaction instance for the tenant, oldest first. status, if non-empty, filters to exactly one of "active", "committed", "released", or "expired" -- server-validated, not client-validated, since the set is small and stable enough that duplicating it here would only be one more place for it to drift. An empty status returns every instance regardless of outcome.

Hits GET /api/v2/.../dxp/txn[?status=]. Returns *client.Error on non-2xx.

func (*Client) Export ¶ added in v0.26.0

func (c *Client) Export(ctx context.Context, w io.Writer) (*ExportResult, error)

Export runs a complete tenant export and streams the result to w: starts the job, polls until it completes or fails, then downloads the resulting blob (via BlobGet, which streams rather than buffers) directly into w. This is the one-call convenience form; a caller wanting to observe progress, poll on its own schedule, or start an export without immediately waiting on it should use BlobExportStart/BlobExportStatus directly instead.

Polls every 2 seconds -- fixed, not configurable here; a caller needing a different cadence is exactly the caller who should be using the two primitives directly rather than this convenience wrapper. Respects ctx: cancelling or setting a deadline on ctx stops the poll loop and returns ctx.Err(), same as any other call on this client -- there is no separate timeout parameter, by design (Go's own idiom: the caller controls how long they're willing to wait via the context they pass in, e.g. context.WithTimeout(ctx, 10*time.Minute) for a large tenant).

Returns a plain Go error (not *client.Error) if the job itself fails server-side -- there's no HTTP status to carry for that case, just the job's own recorded failure reason.

func (*Client) Get ¶

func (c *Client) Get(ctx context.Context, entity string, id int64) (*Entity, error)

Get retrieves a single entity by ID. xolu returns the flat document directly: {"id":1,"name":"Alice",…} The full document is stored in Entity.Data; ID is also extracted for convenience.

func (*Client) GetEntitySchema ¶

func (c *Client) GetEntitySchema(ctx context.Context, entityType string) (*EntitySchema, error)

GetEntitySchema fetches the schema declaration for a single entity type.

Hits GET /api/v1/schema/{entity}. Returns *client.Error on non-2xx.

The returned EntitySchema carries the raw JSON Schema in `Schema` plus a field breakdown (`Fields`, `Refs`) extracted client-side by walking the schema. Consumers that need finer control over field extraction can decode `Schema` themselves — it is preserved verbatim.

func (*Client) GetEventDef ¶

func (c *Client) GetEventDef(ctx context.Context, id int64) (*EventDef, error)

GetEventDef fetches a single event subscription by ID.

Hits GET /api/v2/event/def/{id}. Returns *client.Error on non-2xx.

func (*Client) GetMachine ¶

func (c *Client) GetMachine(ctx context.Context, id int64) (*Machine, error)

GetMachine fetches a machine's full record — identity, current state, live variables.

Hits GET /api/v2/fsm/machine/{id}. Returns *client.Error with code XOLU-FSM* on non-2xx (including 404 when the machine does not exist).

func (*Client) GetMachineDef ¶

func (c *Client) GetMachineDef(ctx context.Context, id int64) (*MachineDef, error)

GetMachineDef fetches the full definition body for a single FSM definition by ID.

Hits GET /api/v2/fsm/def/{id}. Returns *client.Error on non-2xx (including XOLU-FSM* codes when the definition is not found or is malformed).

func (*Client) GetMachineHistory ¶

func (c *Client) GetMachineHistory(ctx context.Context, id int64) ([]HistoryEntry, error)

GetMachineHistory returns the ordered walk history for a machine, oldest first. The first entry records the machine's creation; each subsequent entry records one walk.

Hits GET /api/v2/fsm/machine/{id}/history. The wire envelope is {"machine": id, "entries": [...]} — this method returns the inner slice.

xolu v0.14.4 does not support pagination on this endpoint; the full history is returned in one response. Consumers of large history sets should design their access patterns around this.

func (*Client) GetMachineResult ¶

func (c *Client) GetMachineResult(ctx context.Context, id int64) (*MachineResult, error)

GetMachineResult returns a convenience summary: current state, terminal flag, live vars, and (when terminal) the final transition's output.

Hits GET /api/v2/fsm/machine/{id}/result.

The FinalOutput field is nil until Terminal becomes true. A caller can poll this endpoint and act once Terminal flips.

func (*Client) GetMachineState ¶

func (c *Client) GetMachineState(ctx context.Context, id int64) (*MachineState, error)

GetMachineState returns just the current state and terminal flag for a machine — a lightweight probe compared to GetMachine.

Hits GET /api/v2/fsm/machine/{id}/state.

func (*Client) GetMachineTransitions ¶

func (c *Client) GetMachineTransitions(ctx context.Context, id int64) (*AvailableTransitions, error)

GetMachineTransitions returns the input symbols for which a transition from the machine's current state exists.

Hits GET /api/v2/fsm/machine/{id}/transitions.

Guards are not pre-evaluated: an input appears here if any transition names it from the current state, whether or not that transition's guard would currently permit the walk. Callers wanting a proven-permissible input must attempt the walk and handle the XOLU-FSM005 rejection.

func (*Client) GetMachineVars ¶

func (c *Client) GetMachineVars(ctx context.Context, id int64) (map[string]VariableSnapshot, error)

GetMachineVars returns the machine's live variable snapshot: each variable's current value alongside its declared type and default.

Hits GET /api/v2/fsm/machine/{id}/vars. The response is a flat map (no envelope key) — the returned map is keyed by variable name.

func (*Client) GetSchemaSuggestion ¶ added in v0.26.0

func (c *Client) GetSchemaSuggestion(ctx context.Context, entityType string) (*SchemaSuggestion, error)

GetSchemaSuggestion previews what schema-promotion's heuristic engine would infer for entityType, without applying anything -- safe to call at any time, purely read-only.

Hits GET /api/v1/entity/{type}/schema-suggestion. Returns *client.Error on non-2xx (404 if the entity type has no data to infer from).

func (*Client) GetSequence ¶

func (c *Client) GetSequence(ctx context.Context, name string) (*Sequence, error)

GetSequence fetches a single named sequence's current metadata (start, step, current value, creation timestamp).

Hits GET /api/v2/gen/seq/{name} (equivalent to /api/v2/seq/{name}, xolu's permanent alias). Returns *client.Error on non-2xx.

Use ListSequences to enumerate all sequences; this method retrieves a specific sequence when the name is known out of band.

func (*Client) GraphNeighbors ¶

func (c *Client) GraphNeighbors(ctx context.Context, nodeID string, direction string) (*NeighborResult, error)

GraphNeighbors retrieves neighbors of a node in the graph. direction must be "out", "in", or "both" (default: "out"). xolu endpoint: POST /graph/neighbors with JSON body. Response: {"neighbors":{"outgoing":{node:label},"incoming":{node:label}}}

func (*Client) GraphQuery ¶

func (c *Client) GraphQuery(ctx context.Context, query string, maxDepth int) (*GraphQueryResult, error)

GraphQuery executes a Sulpher graph path query. Previously named Sulpher; renamed to match the xolu endpoint. xolu endpoint: POST /graph/query maxDepth of 0 uses xolu's server default.

func (*Client) GraphShortestPath ¶

func (c *Client) GraphShortestPath(ctx context.Context, from, to string, maxDepth int) (*PathResult, error)

GraphShortestPath finds the shortest path between two nodes. maxDepth of 0 uses xolu's server default. xolu endpoint: POST /graph/shortestPath with JSON body. Returns PathResult with Exists=false and empty Path when no path exists.

func (*Client) Health ¶

func (c *Client) Health(ctx context.Context) error

Health checks if the xolu server is healthy.

Hits GET /health. Returns nil on 200 (server process is alive; storage layer's Ping succeeded within the server's 2-second timeout). Returns a non-nil error on any non-2xx response, transport failure, or timeout.

Health is appropriate for liveness probes (is the process alive?). For readiness probes (is the process ready to serve traffic?) use Ready instead.

Health does NOT apply the client's configured auth header, and never will: confirmed directly against the server's own auth middleware (2026-08-04, T-161, reported by the xoluman team) -- /health is deliberately exempt from auth server-side, alongside /ready, /version, and /metrics, the standard convention for liveness/ readiness probes (an orchestrator checking whether to restart a process shouldn't need a credential to ask). Sending an auth header here would be a pure no-op: the server ignores it for this route regardless of what the client sends, valid or not. A connection with a wrong or expired credential looks identical to a correctly configured one through Health alone -- that is inherent to what /health checks, not a client-side gap. Use TestConnection instead to verify a credential is actually accepted.

func (*Client) List ¶

func (c *Client) List(ctx context.Context, entity string, params *ListParams) (*ListResult, error)

List retrieves entities from a collection with optional pagination. xolu returns a PagedResponse envelope:

{"data":[…],"pagination":{"page":N,"per_page":N,"total_items":N,"total_pages":N}}

Pagination parameters: xolu uses page/per_page; Limit maps to per_page, Offset is converted to a page number (Offset/Limit + 1, floored at 1).

func (*Client) ListEntities ¶ added in v0.26.0

func (c *Client) ListEntities(ctx context.Context, includeGraph bool) ([]EntityListEntry, error)

ListEntities enumerates every entity type that currently has data for this tenant, schemaless or not -- the fuller counterpart to ListEntityTypes, which only sees entity types with a registered schema. Pass includeGraph=true to also compute each entity type's graph edge counts and the relationship names touching it; leave it false for the common case, since that computation costs one indexed pass over the tenant's graph table per entity type and most callers don't need it.

Hits GET /api/v1/entities (?include_graph=true when requested). Returns *client.Error on non-2xx (501 if the store isn't SQLite- backed).

func (*Client) ListEntityTypes ¶

func (c *Client) ListEntityTypes(ctx context.Context) ([]EntityTypeSummary, error)

ListMachineDefs returns summaries of every FSM definition registered in the current tenant scope. Each summary carries id, name, and creation timestamp only; use GetMachineDef to fetch the full spec.

Hits GET /api/v2/fsm/def. Requires xolu's v2 API to be enabled (XOLU_API_V2_ENABLED=true). Returns *client.Error on non-2xx. ListEntityTypes enumerates the entity types that currently have a registered schema, sorted by name.

Hits GET /api/v1/schemas (T-24). Returns *client.Error on non-2xx.

func (*Client) ListEventDefs ¶

func (c *Client) ListEventDefs(ctx context.Context) ([]EventDef, error)

ListEventDefs returns every registered event subscription in the current tenant scope.

Hits GET /api/v2/event/def. Returns *client.Error on non-2xx.

The wire envelope key is "subscriptions" (not "events" or "definitions"); see xolu's pkg/server/v2_event_handlers.go handleEventList.

func (*Client) ListGenerators ¶

func (c *Client) ListGenerators(ctx context.Context, kind GeneratorKind) ([]GeneratorDef, error)

ListGenerators returns the named generators registered under a single generator kind in the current tenant scope. Since xolu keeps a separate list per kind, a consumer building a full generator inventory must call this method for each of AllGeneratorKinds.

Hits GET /api/v2/gen/{kind}. Returns *client.Error on non-2xx.

Note: named sequences do NOT appear in this listing. Sequences live at a separate route (/api/v2/gen/seq) which xolu v0.14.3 exposes only per-name, not as a list. See the xolu technical-debt tracker.

func (*Client) ListMachineDefs ¶

func (c *Client) ListMachineDefs(ctx context.Context) ([]MachineDefSummary, error)

ListMachineDefs enumerates every registered FSM definition in the current tenant scope.

Hits GET /api/v2/.../fsm/def. Returns *client.Error on non-2xx.

func (*Client) ListMachines ¶

func (c *Client) ListMachines(ctx context.Context, filter *MachineFilter) ([]MachineSummary, error)

ListMachines returns every machine matching an optional filter. A nil filter (or a filter with all fields zero) returns every machine in the current tenant scope.

Hits GET /api/v2/fsm/machine?[filter query params].

The wire envelope key is "machines" per xolu's handleFSMMachineList.

func (*Client) ListSequences ¶

func (c *Client) ListSequences(ctx context.Context) ([]SequenceSummary, error)

ListSequences enumerates the tenant's named sequences, sorted by name.

Hits GET /api/v2/.../gen/seq (T-25). Returns *client.Error on non-2xx. Returns SequenceSummary values (which match the list wire format), not the Sequence type used by GetSequence — see T-32 for the divergence.

func (*Client) LocContains ¶ added in v0.30.38

func (c *Client) LocContains(ctx context.Context, lat, lon float64) (*LocContainsResult, error)

LocContains returns every fence the given point currently falls inside.

Hits GET /api/v2/.../loc/contains?lat=...&lon=.... Returns *client.Error on non-2xx.

func (*Client) LocDefine ¶ added in v0.30.38

func (c *Client) LocDefine(ctx context.Context, req LocDefineRequest) (*LocLocation, error)

LocDefine creates or reconfigures a location. Set req.ParentID to nil for a root location, or to an existing location's own id to place this one under it.

Hits POST /api/v2/.../loc/def. Returns *client.Error on non-2xx.

func (*Client) LocDelete ¶ added in v0.30.38

func (c *Client) LocDelete(ctx context.Context, locationID string, force bool) error

LocDelete removes locationID. force, when true, matches the server's own ?force=true query flag (behaviour for a non-empty location is a server-side policy this client does not second-guess or duplicate -- whatever LocDelete without force refuses, force is the caller's own explicit override).

Hits DELETE /api/v2/.../loc/{location_id}[?force=true]. Returns *client.Error on non-2xx.

func (*Client) LocFenceAttach ¶ added in v0.30.38

func (c *Client) LocFenceAttach(ctx context.Context, req LocFenceAttachRequest) (*LocFence, error)

LocFenceAttach defines a fence -- either obj-anchored (req.Subject, "kind:key" shorthand) or tree-aligned (req.AlignedTo, a plain location id) -- exactly one of the two set.

Hits POST /api/v2/.../loc/fences/attach. Returns *client.Error on non-2xx -- notably XOLU-LOC022 if both Capacity and Pattern are set.

func (*Client) LocFenceDelete ¶ added in v0.30.38

func (c *Client) LocFenceDelete(ctx context.Context, ref LocFenceRef) error

LocFenceDelete removes ref.

Hits DELETE /api/v2/.../loc/fences/{kind}/{key}. Returns *client.Error on non-2xx.

func (*Client) LocFenceGet ¶ added in v0.30.38

func (c *Client) LocFenceGet(ctx context.Context, ref LocFenceRef) (*LocFence, error)

LocFenceGet returns ref's own current record. Construct ref via LocFenceRefByLocation or LocFenceRefBySubject.

Hits GET /api/v2/.../loc/fences/{kind}/{key}. Returns *client.Error on non-2xx -- notably 404 if ref was never defined.

func (*Client) LocFenceList ¶ added in v0.30.38

func (c *Client) LocFenceList(ctx context.Context) (*LocFenceListResult, error)

LocFenceList returns every fence defined on the tenant.

Hits GET /api/v2/.../loc/fences/list. Returns *client.Error on non-2xx.

func (*Client) LocFencePatch ¶ added in v0.30.38

func (c *Client) LocFencePatch(ctx context.Context, ref LocFenceRef, geometry LocFenceGeometry) (*LocFence, error)

LocFencePatch replaces ref's own geometry. Never touches capacity, pattern, or current membership -- only the stored shape changes; membership stays correct until the next report/move naturally revisits it, or until LocFenceReconcile is asked to look.

Hits PATCH /api/v2/.../loc/fences/{kind}/{key}. Returns *client.Error on non-2xx.

func (*Client) LocFenceReconcile ¶ added in v0.30.38

func (c *Client) LocFenceReconcile(ctx context.Context, ref LocFenceRef) (*LocFenceReconcileResult, error)

LocFenceReconcile reports ref's own recorded-vs-observed membership drift -- advisory only, never writes anything.

Hits GET /api/v2/.../loc/fences/{kind}/{key}/reconcile. Returns *client.Error on non-2xx.

func (*Client) LocGet ¶ added in v0.30.38

func (c *Client) LocGet(ctx context.Context, locationID string) (*LocLocation, error)

LocGet returns locationID's own current record.

Hits GET /api/v2/.../loc/{location_id}. Returns *client.Error on non-2xx -- notably 404 if locationID was never defined.

func (*Client) LocList ¶ added in v0.30.38

func (c *Client) LocList(ctx context.Context, optParentID string) (*LocListResult, error)

LocList returns every location defined on the tenant. optParentID, when non-empty, filters to direct children of that location only (matching the server's own ?parent_id= query filter); pass "" for every location regardless of parent.

Hits GET /api/v2/.../loc/list[?parent_id=...]. Returns *client.Error on non-2xx.

func (*Client) LocMove ¶ added in v0.30.38

func (c *Client) LocMove(ctx context.Context, entityType string, entityID int64, toLocationID string) (*LocMoveResult, error)

LocMove moves the entity identified by entityType/entityID to toLocationID, computing and reporting any fence boundaries crossed by the move.

Hits POST /api/v2/.../loc/move. Returns *client.Error on non-2xx.

func (*Client) LocNearby ¶ added in v0.30.38

func (c *Client) LocNearby(ctx context.Context, lat, lon, radiusM float64) (*LocNearbyResult, error)

LocNearby returns locations and fences near the given point, within radiusM meters.

Hits GET /api/v2/.../loc/nearby?lat=...&lon=...&radius_m=.... Returns *client.Error on non-2xx.

func (*Client) LocPatch ¶ added in v0.30.38

func (c *Client) LocPatch(ctx context.Context, locationID string, req LocPatchRequest) (*LocLocation, error)

LocPatch partially updates locationID. See LocPatchRequest's own doc comment for the tri-state Capacity semantics (nil outer pointer = leave unchanged; non-nil outer pointing at nil inner = clear to unlimited; non-nil outer pointing at a value = set that ceiling). Capacity is excluded from this struct's own JSON tags precisely because standard marshaling cannot distinguish those three states through one field the way a hand-built body can -- built manually here rather than relying on encoding/json for exactly that field.

Hits PATCH /api/v2/.../loc/{location_id}. Returns *client.Error on non-2xx.

func (*Client) LocPatternDefine ¶ added in v0.30.38

func (c *Client) LocPatternDefine(ctx context.Context, name string, capacity int64) (*LocPattern, error)

LocPatternDefine defines a fence-type pattern -- not a fence or a location itself, addressed by a plain (tenant, name).

Hits POST /api/v2/.../loc/patterns/def. Returns *client.Error on non-2xx.

func (*Client) LocPatternDelete ¶ added in v0.30.38

func (c *Client) LocPatternDelete(ctx context.Context, id string) error

LocPatternDelete removes id.

Hits DELETE /api/v2/.../loc/patterns/{id}. Returns *client.Error on non-2xx.

func (*Client) LocPatternGet ¶ added in v0.30.38

func (c *Client) LocPatternGet(ctx context.Context, id string) (*LocPattern, error)

LocPatternGet returns id's own current record.

Hits GET /api/v2/.../loc/patterns/{id}. Returns *client.Error on non-2xx -- notably 404 if id was never defined.

func (*Client) LocPatternList ¶ added in v0.30.38

func (c *Client) LocPatternList(ctx context.Context) (*LocPatternListResult, error)

LocPatternList returns every pattern defined on the tenant.

Hits GET /api/v2/.../loc/patterns/list. Returns *client.Error on non-2xx.

func (*Client) LocReport ¶ added in v0.30.38

func (c *Client) LocReport(ctx context.Context, entityType string, entityID int64, point LocPoint) (*LocReportResult, error)

LocReport records a raw lat/lon/alt point for the entity identified by entityType/entityID, independent of any /loc leaf placement, and reports whether the report itself crossed a fence boundary.

Hits POST /api/v2/.../loc/report. Returns *client.Error on non-2xx.

func (*Client) LocSubjectHistory ¶ added in v0.30.38

func (c *Client) LocSubjectHistory(ctx context.Context, entityType string, entityID int64) (*LocSubjectHistoryResult, error)

LocSubjectHistory returns the entity/id subject's own movement journal, newest first.

Hits GET /api/v2/.../loc/subjects/{entity}/{id}/history. Returns *client.Error on non-2xx.

func (*Client) LocSubjectPosition ¶ added in v0.30.38

func (c *Client) LocSubjectPosition(ctx context.Context, entityType string, entityID int64) (*LocSubjectPosition, error)

LocSubjectPosition resolves the entity/id subject's own current canonical state -- leaf placement, fence membership, and last raw report, whichever of those this subject has actually been tracked by.

Hits GET /api/v2/.../loc/subjects/{entity}/{id}/position. Returns *client.Error on non-2xx.

func (*Client) OQL ¶

func (c *Client) OQL(ctx context.Context, query string) (*OQLResult, error)

OQL executes an OQL (SQL-like) query.

func (*Client) ObjAttach ¶ added in v0.30.38

func (c *Client) ObjAttach(ctx context.Context, req ObjAttachRequest) (*ObjSubject, error)

ObjAttach attaches obj capability to req.Subject ("kind:key" shorthand). A freshly-attached subject always starts unassigned (PositionKind == "").

Hits POST /api/v2/.../obj/attach. Returns *client.Error on non-2xx -- notably XOLU-OBJ006 if the subject is already attached.

func (*Client) ObjCapacityPatch ¶ added in v0.30.38

func (c *Client) ObjCapacityPatch(ctx context.Context, subject string, capacity ObjCapacity) (*ObjSubject, error)

ObjCapacityPatch updates subject's own capacity ceilings (any of the three dimensions may be omitted to leave it unchanged; the server's own current-usage totals are read-only and never set from here). Returns subject's own updated record.

Hits PATCH /api/v2/.../obj/{kind}/{key}/capacity. Returns *client.Error on non-2xx.

func (*Client) ObjContents ¶ added in v0.30.38

func (c *Client) ObjContents(ctx context.Context, subject string, transitive bool) (*ObjContentsResult, error)

ObjContents returns subject's own directly-contained subjects, or every subject in its transitive containment tree when transitive is true.

Hits GET /api/v2/.../obj/{kind}/{key}/contents[?depth=all]. Returns *client.Error on non-2xx.

func (*Client) ObjDemote ¶ added in v0.30.38

func (c *Client) ObjDemote(ctx context.Context, req ObjDemoteRequest) (*ObjPromoteResult, error)

ObjDemote reverses a promotion -- removes obj capability from req.Subject together with a bal transfer back out, the same atomic pairing ObjPromote makes going in.

Hits POST /api/v2/.../obj/demote. Returns *client.Error on non-2xx.

func (*Client) ObjDetach ¶ added in v0.30.38

func (c *Client) ObjDetach(ctx context.Context, subject string) error

ObjDetach removes obj capability from subject entirely -- distinct from Retire (the lifecycle terminal state, §6); this is plain bookkeeping cleanup. Refused (409) if subject is currently positioned anywhere other than unassigned.

Hits DELETE /api/v2/.../obj/{kind}/{key}. Returns *client.Error on non-2xx.

func (*Client) ObjGet ¶ added in v0.30.38

func (c *Client) ObjGet(ctx context.Context, subject string) (*ObjSubject, error)

ObjGet returns subject's own current record.

Hits GET /api/v2/.../obj/{kind}/{key}. Returns *client.Error on non-2xx -- notably 404 if subject was never attached.

func (*Client) ObjList ¶ added in v0.30.38

func (c *Client) ObjList(ctx context.Context) (*ObjListResult, error)

ObjList returns every subject currently attached in the tenant -- no way existed to enumerate obj data at all before this (XOT209, found by reading the full obj route table directly: every other route requires an already-known subject). An empty tenant returns an empty slice, not an error -- exactly the shape a caller doing a tenant-emptiness check needs.

Hits GET /api/v2/.../obj/list. Returns *client.Error on non-2xx.

func (*Client) ObjMove ¶ added in v0.30.38

func (c *Client) ObjMove(ctx context.Context, subject string, target ObjMoveTarget) (*ObjSubject, error)

ObjMove moves subject to target -- either a real /loc leaf (Kind: "loc_leaf", LocationID set) or containment inside another already-attached subject (Kind: "obj", Subject set to the container's own "kind:key"). Returns subject's own updated record.

Hits PUT /api/v2/.../obj/{kind}/{key}/move. Returns *client.Error on non-2xx -- a move to a loc_leaf can surface /loc's own errors unwrapped (e.g. XOLU-LOC002 for a capacity refusal).

func (*Client) ObjPosition ¶ added in v0.30.38

func (c *Client) ObjPosition(ctx context.Context, subject string) (*ObjPositionResult, error)

ObjPosition resolves subject's own current position, following a containment chain to its own root if subject is contained by another subject rather than placed directly on a /loc leaf. AsOf is always "live" today -- there is no historical-position query yet.

Hits GET /api/v2/.../obj/{kind}/{key}/position. Returns *client.Error on non-2xx.

func (*Client) ObjPromote ¶ added in v0.30.38

func (c *Client) ObjPromote(ctx context.Context, req ObjPromoteRequest) (*ObjPromoteResult, error)

ObjPromote promotes an entity (either an existing one, by key, or a new one created inline) to obj capability together with a bal transfer, as one atomic dxp-orchestrated operation -- not two separate calls a caller sequences and hopes stay consistent. req.Position.Kind must be "obj" in this server release (containment into an already-attached subject); req.Entity must set exactly one of ExistingKey or Create.

Hits POST /api/v2/.../obj/promote. Returns *client.Error on non-2xx -- notably XOLU-OBJ (entity-selection) errors when Entity sets both or neither of its own two fields.

func (*Client) ObjReport ¶ added in v0.30.38

func (c *Client) ObjReport(ctx context.Context, subject string, lat, lon, alt float64) error

ObjReport records subject's own current point (lat/lon, alt optional) -- a raw position report, independent of /loc containment.

Hits POST /api/v2/.../obj/{kind}/{key}/report. Returns *client.Error on non-2xx.

func (*Client) ObjRetire ¶ added in v0.30.38

func (c *Client) ObjRetire(ctx context.Context, subject string) error

ObjRetire moves subject to its own terminal lifecycle state (obj-00-design.md §12) -- once set, never cleared. Distinct from Detach (bookkeeping removal); this is a permanent record.

Hits POST /api/v2/.../obj/{kind}/{key}/retire. Returns *client.Error on non-2xx.

func (*Client) Patch ¶

func (c *Client) Patch(ctx context.Context, entity string, id int64, data map[string]any) (*Entity, error)

Patch partially updates an existing entity. xolu returns {"message":"…"} on success — no document echo. Data on the returned Entity is nil; call Get if the updated document is needed.

func (*Client) PatchMachine ¶

func (c *Client) PatchMachine(ctx context.Context, id int64, req PatchMachineRequest) (*Machine, error)

PatchMachine applies overrides to a machine's spec snapshot. Live state, live variable values, and history are preserved unchanged.

Hits PATCH /api/v2/fsm/machine/{id}. Returns *client.Error carrying an XOLU-FSM* validation code on non-2xx.

The returned *Machine reflects the patched machine (identity, current state, live vars) — the underlying snapshot spec is not echoed back; callers who need the post-patch spec should re-fetch the machine's definition or read the snapshot from xolu's storage tier directly.

func (*Client) PromoteFlex ¶ added in v0.26.0

func (c *Client) PromoteFlex(ctx context.Context, entityType string, schema map[string]interface{}) (*PromoteFlexResult, error)

PromoteFlex promotes entityType to schemaful immediately: registers schema (or, if schema is nil, an auto-inferred one) and creates the adapted table. Does not migrate pre-existing rows -- check result.Warning; a non-empty value means some exist and are now split across storage (reachable by ID, invisible to LIST/count). Use PromoteStrict instead if that split is not acceptable for this entity type.

Hits POST /api/v1/entities/promote/flex/{type}. Returns *client.Error on non-2xx (404 if schema is nil and the entity type has no data to infer from).

func (*Client) PromoteStrict ¶ added in v0.26.0

func (c *Client) PromoteStrict(ctx context.Context, entityType string, schema map[string]interface{}) (*PromoteJob, error)

PromoteStrict runs a complete strict promotion and waits for the result: starts the job, polls until it completes, is rejected, or fails, and returns the final PromoteJob. This is the one-call convenience form; a caller wanting to observe progress or start a promotion without immediately waiting on it should use PromoteStrictStart/PromoteStrictStatus directly instead.

Respects ctx: cancelling or setting a deadline on ctx stops the poll loop and returns ctx.Err(). Does NOT return an error for a rejected promotion -- rejection is a normal, successful outcome of strict promotion's own design (it means the check worked); inspect job.Status and job.Failures rather than relying on the error return to distinguish rejection from success.

func (*Client) PromoteStrictStart ¶ added in v0.26.0

func (c *Client) PromoteStrictStart(ctx context.Context, entityType string, schema map[string]interface{}) (*PromoteJob, error)

PromoteStrictStart starts an async strict promotion for entityType: validates every existing row against schema (or, if schema is nil, an auto-inferred one) and, only if every row passes, migrates all of them into a newly-registered adapted table as one atomic operation. Returns immediately with a ticket to poll via PromoteStrictStatus.

Throttled per (tenant, entity type), not per tenant -- promoting two different entity types for the same tenant concurrently is fine. A second call for an entity type already being promoted returns *client.Error with HTTPStatus 409, carrying the existing ticket in its message.

Hits POST /api/v1/entities/promote/strict/{type}. Returns *client.Error on non-2xx.

func (*Client) PromoteStrictStatus ¶ added in v0.26.0

func (c *Client) PromoteStrictStatus(ctx context.Context, ticket string) (*PromoteJob, error)

PromoteStrictStatus polls one strict-promotion job's status by ticket.

Hits GET /api/v1/entities/promote/status/{ticket}. Returns *client.Error (HTTPStatus 404) if the ticket is unknown.

func (*Client) Raw ¶ added in v0.26.0

func (c *Client) Raw(ctx context.Context, method, path string, contentType string, body io.Reader) (*RawResult, error)

Raw issues an arbitrary HTTP request against this client's connected instance, applying the client's configured auth and nothing else -- no tenant-path rewriting, no error-shape decoding, no retry.

path is appended directly to the client's base URL and must start with "/" (e.g. "/api/v1/bal/def", "/api/v1/tenant/t0000/bal/def", "/health"); it is not rewritten or tenant-prefixed. body may be nil for methods that don't send one. contentType is sent as the Content-Type header when body is non-nil; pass "" to default to "application/json", matching every other method in this package (Raw is most often used for the same JSON API surface, just for a path this client has no typed wrapper for).

A non-nil error means the request never completed -- a transport failure, not an HTTP error status. Any response the server actually sent, including 4xx/5xx, comes back as a non-nil *RawResult with a nil error; check result.StatusCode.

func (*Client) Ready ¶

func (c *Client) Ready(ctx context.Context) error

Ready checks if the xolu server is ready to serve traffic.

Hits GET /ready. Returns nil on 200 (server is fully initialised and the storage layer's Ping succeeded). Returns a non-nil error on 503 (server is still initialising or storage is unreachable), any other non-2xx response, transport failure, or timeout.

Ready is the correct endpoint for readiness probes and for consumers that want to gate their own traffic on xolu's ability to serve — for example, molu's health probe in its gated-dispatch design.

Auth is not required to reach /ready; the endpoint is deliberately unauthenticated so probes work without credentials.

func (*Client) ReplaceMachineDef ¶ added in v0.26.0

func (c *Client) ReplaceMachineDef(ctx context.Context, id int64, spec MachineSpec) (*MachineDefReplaceResult, error)

ReplaceMachineDef overwrites an existing FSM definition's spec in place, re-validating it the same way CreateMachineDef does.

Affects future machines only: a machine already created against the old spec keeps running against the version it was created with. This is not retroactive, and there is no way to migrate an in-flight machine to a replaced definition -- confirmed directly against the server's own route comment ("replace a definition (future machines only)"), not assumed.

Hits PUT /api/v2/fsm/def/{id}. Returns *client.Error on non-2xx (404 with XOLU-FSM001/002/012 if id doesn't exist, 422 for a spec that fails validation).

func (*Client) Save ¶

func (c *Client) Save(ctx context.Context, entity string, id int64, data map[string]any) (created bool, err error)

Save upserts an entity with a caller-specified ID. xolu endpoint: POST /{entity}/save/{id} Returns created=true when a new record was inserted, false when an existing record was replaced. Use this for idempotent writes where the caller owns the ID (e.g. device registration keyed on hardware ID).

func (*Client) Search ¶

func (c *Client) Search(ctx context.Context, entity string, params SearchParams) ([]Entity, error)

Search performs a full-text search on an entity collection. Search performs a full-text search across entities. xolu endpoint: GET /api/v1/search?q=…&entity={optional} Response: {"query":"…","entity":"…","count":N,"results":[flat docs…]} The entity argument is deprecated — populate SearchParams.Entity instead. If both are non-empty, SearchParams.Entity takes precedence.

func (*Client) Sulpher ¶

func (c *Client) Sulpher(ctx context.Context, query string) (*GraphQueryResult, error)

Sulpher is a backward-compatible alias for GraphQuery with maxDepth=0. Deprecated: use GraphQuery.

func (*Client) TSAggregate ¶ added in v0.30.38

func (c *Client) TSAggregate(ctx context.Context, req TSAggregateRequest) (*TSAggregateResult, error)

TSAggregate computes req.Function over req.NumField, optionally bucketed by req.Interval. See TSAggregateRequest's own doc comment for the exact 9-value Interval enum, and TSAggregateResult's own doc comment for the bucketed-vs-scalar union shape the response takes.

Hits POST /api/v1/.../ts/aggregate. Returns *client.Error on non-2xx -- notably XOLU-TS (invalid-agg-field) if NumField is out of the 0-6 range.

func (*Client) TSAppend ¶ added in v0.30.38

func (c *Client) TSAppend(ctx context.Context, e TSEvent) error

TSAppend appends a single event to a timeline. e.Time is marshaled as RFC3339Nano (Go's own time.Time JSON encoding), matching what the server's own parseTSTime accepts.

Hits POST /api/v1/.../ts/events. Returns *client.Error on non-2xx -- notably XOLU-TS004 for an undefined timeline, XOLU-TS007 for a dims-count mismatch against the timeline's own definition.

func (*Client) TSBatchAppend ¶ added in v0.30.38

func (c *Client) TSBatchAppend(ctx context.Context, events []TSEvent) (*TSBatchAppendResult, error)

TSBatchAppend appends events atomically -- checked directly against pkg/timeseries's own AppendBatch before writing this: the current implementation validates every event first and returns an outright error if any one is invalid, before any event is written, so a response is only ever returned when every event in this call succeeded together. See TSBatchAppendResult's own doc comment for why Accepted/Failed are still surfaced as returned rather than this client asserting Accepted == Total itself.

Hits POST /api/v1/.../ts/events/batch. Returns *client.Error on non-2xx -- notably XOLU-TS006 if len(events) exceeds the server's own configured maximum batch size.

func (*Client) TSDefineTimeline ¶ added in v0.30.38

func (c *Client) TSDefineTimeline(ctx context.Context, req TSDefineTimelineRequest) (*TSTimeline, error)

TSDefineTimeline defines a new timeline. req.Dims is fixed for the timeline's own lifetime once set here.

Hits POST /api/v1/.../ts/tl/def. Returns *client.Error on non-2xx.

func (*Client) TSDeleteTimeline ¶ added in v0.30.38

func (c *Client) TSDeleteTimeline(ctx context.Context, timelineID int64) error

TSDeleteTimeline removes timelineID's own definition together with its event data and rollups -- the inverse of TSDefineTimeline. Distinct from a future data-only purge (Wave 16 Stage 7), which keeps the definition.

Hits DELETE /api/v1/.../ts/tl/{timeline_id}. Returns *client.Error on non-2xx -- notably 409 if the timeline still has rollups and cascade deletion is disabled server-side (remove the rollups first), 404 for an undefined timeline.

func (*Client) TSDeleteTimelineData ¶ added in v0.30.38

func (c *Client) TSDeleteTimelineData(ctx context.Context, timelineID int64) error

TSDeleteTimelineData removes every event from timelineID, keeping the timeline's own definition -- distinct from TSDeleteTimeline (Wave 16 Stage 3), which removes both together.

Hits DELETE /api/v1/.../ts/tl/{timeline_id}/data. Returns *client.Error on non-2xx.

func (*Client) TSFullAggregate ¶ added in v0.30.38

func (c *Client) TSFullAggregate(ctx context.Context, req TSFullAggregateRequest) (*TSFullAggregateResult, error)

TSFullAggregate combines TSRangeAggregate's own exact statistics with approximate quantile estimates in one pass. An empty/nil req.Quantiles is equivalent to plain TSRangeAggregate at no extra cost server-side (no quantile sketch allocated).

Hits POST /api/v1/.../ts/full_aggregate. Returns *client.Error on non-2xx.

func (*Client) TSGetRetention ¶ added in v0.30.38

func (c *Client) TSGetRetention(ctx context.Context) (*TSRetentionResult, error)

TSGetRetention returns the tenant's own store-level default retention plus every timeline's own current setting.

Hits GET /api/v1/.../ts/retention. Returns *client.Error on non-2xx.

func (*Client) TSGetTimeline ¶ added in v0.30.23

func (c *Client) TSGetTimeline(ctx context.Context, timelineID int64) (*TSTimeline, error)

TSGetTimeline returns a single timeline's own definition.

Hits GET /api/v1/.../ts/tl/{timelineID}. Returns *client.Error on non-2xx — notably XOLU-TS004 for an undefined timeline.

func (*Client) TSLatest ¶ added in v0.30.38

func (c *Client) TSLatest(ctx context.Context, req TSLatestRequest) (*TSQueryRangeResult, error)

TSLatest returns the req.N most recent events for a timeline (defaulting to 10 if req.N is 0), optionally bounded by From/To.

Hits GET /api/v1/.../ts/events/latest?timeline=...&dims=...&n=.... Returns *client.Error on non-2xx.

func (*Client) TSListTimelines ¶ added in v0.30.23

func (c *Client) TSListTimelines(ctx context.Context) ([]TSTimeline, error)

TSListTimelines returns every timeline defined on the tenant.

Hits GET /api/v1/.../ts/tl/list. Returns *client.Error on non-2xx.

func (*Client) TSPatchRetention ¶ added in v0.30.38

func (c *Client) TSPatchRetention(ctx context.Context, defaultRetentionDays int) (*TSPatchRetentionResult, error)

TSPatchRetention updates the tenant's own store-level default retention. Per-timeline retention is set via TSUpdateTimeline, not here.

Hits PATCH /api/v1/.../ts/retention. Returns *client.Error on non-2xx.

func (*Client) TSProvision ¶ added in v0.30.38

func (c *Client) TSProvision(ctx context.Context) (*TSProvisionResult, error)

TSProvision is a one-time per-tenant setup call, required before any other ts operation succeeds against a fresh tenant.

Hits POST /api/v1/.../ts/provision. Returns *client.Error on non-2xx.

func (*Client) TSPurgeTimelineRange ¶ added in v0.30.38

func (c *Client) TSPurgeTimelineRange(ctx context.Context, timelineID int64, from, to time.Time) error

TSPurgeTimelineRange removes events in [from, to) from timelineID, keeping everything outside that range. from/to are formatted explicitly as time.RFC3339 (not relying on time.Time's default JSON marshaling, which produces RFC3339Nano) -- confirmed directly against the server's own strict time.Parse(time.RFC3339, ...) call before choosing this, the same discipline TSRollupRun already follows for the identical reason.

Hits POST /api/v1/.../ts/tl/{timeline_id}/data/purge. Returns *client.Error on non-2xx -- notably a refusal if to is not after from.

func (*Client) TSQueryRange ¶ added in v0.30.23

func (c *Client) TSQueryRange(ctx context.Context, req TSQueryRangeRequest) (*TSQueryRangeResult, error)

TSQueryRange returns every event on req.Timeline within [req.From, req.To) across req.Dims. req.Dims is required and must be non-empty — the server rejects an empty Dims with XOLU-TS007 before ever querying the store. req.Limit defaults server-side to 1000 (capped at the server's own configured maximum) when left zero; req.Order defaults to "asc".

Hits POST /api/v1/.../ts/query/range (the POST form of range query — a structured JSON body rather than a query string, avoiding URL-length limits for wide Dims sets). Returns *client.Error on non-2xx — notably XOLU-TS011 if [From, To) exceeds the server's own configured maximum range.

func (*Client) TSQueryRangeGet ¶ added in v0.30.38

func (c *Client) TSQueryRangeGet(ctx context.Context, req TSQueryRangeRequest) (*TSQueryRangeResult, error)

TSQueryRangeGet is the query-string-based alternative to TSQueryRange -- same semantics, same result shape (reused directly, no separate type), different transport: query parameters instead of a JSON body. The server's own doc comment on the POST variant notes it exists specifically to avoid URL-length limits for complex queries -- this GET form is the simpler, curl-friendly counterpart for everything else.

Hits GET /api/v1/.../ts/events?timeline=...&dims=...&from=...&to=.... Returns *client.Error on non-2xx.

func (*Client) TSRangeAggregate ¶ added in v0.30.38

func (c *Client) TSRangeAggregate(ctx context.Context, req TSRangeAggregateRequest) (*TSRangeAggregateResult, error)

TSRangeAggregate computes count/sum/avg/min/max for all seven numeric fields in one pass -- more efficient than several TSAggregate calls when multiple fields are needed. Does not support time bucketing; use TSAggregate for that.

Hits POST /api/v1/.../ts/range_aggregate. Returns *client.Error on non-2xx.

func (*Client) TSRollupDefine ¶ added in v0.30.38

func (c *Client) TSRollupDefine(ctx context.Context, timelineID int64, req TSRollupDefineRequest) (*TSRollup, error)

TSRollupDefine defines a rollup on timelineID, aggregating into req.DestTID at req.BucketDuration intervals.

Hits POST /api/v1/.../ts/tl/{timeline_id}/rollup/def. Returns *client.Error on non-2xx -- notably XOLU-TS (rollup-cycle or rollup-depth) errors if this definition would create a cycle or exceed the server's own max rollup chain depth.

func (*Client) TSRollupDelete ¶ added in v0.30.38

func (c *Client) TSRollupDelete(ctx context.Context, timelineID int64, rollupID string) error

TSRollupDelete removes rollupID and stops its worker.

Hits DELETE /api/v1/.../ts/tl/{timeline_id}/rollup/{rollup_id}. Returns *client.Error on non-2xx.

func (*Client) TSRollupGet ¶ added in v0.30.23

func (c *Client) TSRollupGet(ctx context.Context, timelineID int64, rollupID string) (*TSRollup, error)

TSRollupGet returns a single rollup's own definition.

Hits GET /api/v1/.../ts/tl/{timelineID}/rollup/{rollupID}. Returns *client.Error on non-2xx — notably XOLU-TS025 (ErrTSRollupNotFound) for an unknown rollup id.

func (*Client) TSRollupList ¶ added in v0.30.23

func (c *Client) TSRollupList(ctx context.Context, timelineID int64) ([]TSRollup, error)

TSRollupList returns every rollup defined with timelineID as its own source.

Hits GET /api/v1/.../ts/tl/{timelineID}/rollup/list. Returns *client.Error on non-2xx — notably XOLU-TS004 for an undefined timeline.

func (*Client) TSRollupParent ¶ added in v0.30.38

func (c *Client) TSRollupParent(ctx context.Context, timelineID int64) (*TSRollup, error)

TSRollupParent returns the rollup definition for which timelineID is the destination -- its own parent in the rollup tree.

Hits GET /api/v1/.../ts/tl/{timeline_id}/rollup/parent. Returns *client.Error on non-2xx -- notably 404 if timelineID has no rollup parent.

func (*Client) TSRollupRun ¶ added in v0.30.38

func (c *Client) TSRollupRun(ctx context.Context, timelineID int64, rollupID string, req TSRollupRunRequest) error

TSRollupRun manually triggers rollupID for req's own bounded range. The request body's own From/To are formatted explicitly as time.RFC3339 (not relying on time.Time's default JSON marshaling, which produces RFC3339Nano) -- confirmed directly against the server's own strict time.Parse(time.RFC3339, ...) call before choosing this, not assumed lenient.

Hits POST /api/v1/.../ts/tl/{timeline_id}/rollup/{rollup_id}/run. Returns *client.Error on non-2xx -- notably 404 for an unknown rollup.

func (*Client) TSRollupStatus ¶ added in v0.30.38

func (c *Client) TSRollupStatus(ctx context.Context, timelineID int64, rollupID string) (*TSRollupStatusReport, error)

TSRollupStatus returns rollupID's own operational status.

Hits GET /api/v1/.../ts/tl/{timeline_id}/rollup/{rollup_id}/status. Returns *client.Error on non-2xx -- notably 404 for an unknown rollup.

func (*Client) TSRollupTree ¶ added in v0.30.38

func (c *Client) TSRollupTree(ctx context.Context) (*TSRollupTreeNode, error)

TSRollupTree returns the full rollup tree for the tenant. Returns nil (not an error) for a tenant with no timelines at all -- the server's own response body is a bare JSON null in that case, confirmed directly against treeNodeToResponse's own nil handling.

Hits GET /api/v1/.../ts/rollup/tree. Returns *client.Error on non-2xx.

func (*Client) TSStats ¶ added in v0.30.38

func (c *Client) TSStats(ctx context.Context) (*TSStatsResult, error)

TSStats returns store-level diagnostics for the whole tenant.

Hits GET /api/v1/.../ts/stats. Returns *client.Error on non-2xx.

func (*Client) TSSyncGet ¶ added in v0.30.38

func (c *Client) TSSyncGet(ctx context.Context, timelineID int64) (*TSSyncStatus, error)

TSSyncGet returns timelineID's own current WAL-fsync durability mode. See TSSyncStatus's own doc comment for what NoSync actually governs.

Hits GET /api/v1/.../ts/tl/{timeline_id}/sync. Returns *client.Error on non-2xx.

func (*Client) TSSyncOff ¶ added in v0.30.38

func (c *Client) TSSyncOff(ctx context.Context, timelineID int64) (*TSSyncStatus, error)

TSSyncOff enables nosync mode for timelineID -- an append returns immediately without waiting for WAL fsync. Faster, but a crash before the kernel's own dirty-page writeback (typically under a second) can lose the most recent writes to this timeline.

Hits POST /api/v1/.../ts/tl/{timeline_id}/sync/off. Returns *client.Error on non-2xx.

func (*Client) TSSyncOn ¶ added in v0.30.38

func (c *Client) TSSyncOn(ctx context.Context, timelineID int64) (*TSSyncStatus, error)

TSSyncOn restores synchronous (crash-durable) write mode for timelineID -- the default mode; an append waits for WAL fsync before returning.

Hits POST /api/v1/.../ts/tl/{timeline_id}/sync/on. Returns *client.Error on non-2xx.

func (*Client) TSTimelineStats ¶ added in v0.30.38

func (c *Client) TSTimelineStats(ctx context.Context, timelineID int64) (*TSTimelineStatsResult, error)

TSTimelineStats returns per-timeline diagnostics for timelineID.

Hits GET /api/v1/.../ts/stats/{timeline_id}. Returns *client.Error on non-2xx -- notably 404 for an undefined timeline.

func (*Client) TSUpdateTimeline ¶ added in v0.30.38

func (c *Client) TSUpdateTimeline(ctx context.Context, timelineID int64, req TSUpdateTimelineRequest) (*TSTimeline, error)

TSUpdateTimeline updates timelineID's own mutable fields (name, retention). See TSUpdateTimelineRequest's own doc comment for why dims cannot be changed here.

Hits PATCH /api/v1/.../ts/tl/{timeline_id}. Returns *client.Error on non-2xx -- notably 404 for an undefined timeline.

func (*Client) TenantSummary ¶ added in v0.30.38

func (c *Client) TenantSummary(ctx context.Context) (*TenantSummary, error)

TenantSummary returns a single-round-trip data-presence summary for the connected tenant -- every store a tenant's own data can live in, derived server-side from the same table inventory pkg/tenantexport's own backup path uses. res.Empty is the boolean answer; the full per-store breakdown is included in the same response for a caller that wants more than yes/no.

Hits GET /api/v1/.../tenant-summary. Returns *client.Error on non-2xx.

func (*Client) TestConnection ¶ added in v0.27.2

func (c *Client) TestConnection(ctx context.Context) error

TestConnection verifies both that the server is reachable and that the client's configured credential is actually accepted -- the check Health cannot do (see Health's own doc comment for why).

Hits GET /api/v1/schemas: authenticated like any other v1 request (goes through the normal request pipeline, unlike /health), cheap (a schema listing, no heavy work), and tenant-independent (works regardless of whether a tenant is configured on the client, so a connection can be tested before a tenant is even chosen).

Returns nil only on a genuine 200. Returns *client.Error on non-2xx -- in particular HTTPStatus 401/403 for a rejected or missing credential, the exact distinction Health cannot make. Suited to a "Test connection" UI action: unlike Health, a wrong or expired credential here is reported, not silently accepted.

func (*Client) Update ¶

func (c *Client) Update(ctx context.Context, entity string, id int64, data map[string]any) (*Entity, error)

Update replaces an existing entity. xolu returns {"message":"…"} on success — no document echo. Data on the returned Entity is nil; call Get if the updated document is needed.

func (*Client) V2Availability ¶

func (c *Client) V2Availability(ctx context.Context) (*V2Availability, error)

V2Availability fetches the v2 subsystem availability map — a consumer can use this to check whether xolu's v2 API is enabled on the target server and which subsystems are currently live.

Hits GET /api/v2/. This endpoint always exists when v2 is enabled and returns 404 when v2 is disabled. Does not require auth.

func (*Client) ValidateMachineDef ¶ added in v0.26.0

func (c *Client) ValidateMachineDef(ctx context.Context, spec MachineSpec) (*MachineDefValidation, error)

ValidateMachineDef checks spec the same way CreateMachineDef would, without storing anything.

Always responds 200, valid or not -- validity is data in the response body (result.Valid), never encoded as an HTTP status. A non-nil error from this method means the request itself failed (transport, decode) — it is NOT how an invalid spec is reported. Check result.Valid and result.Errors for that; do not use errors.As/*client.Error to detect an invalid spec, since a correctly-rejected spec never produces one.

Hits POST /api/v2/fsm/def/validate. Returns *client.Error only for a genuine transport-level non-2xx, which this endpoint is not expected to produce under normal use.

func (*Client) WalkMachine ¶

func (c *Client) WalkMachine(ctx context.Context, id int64, req WalkRequest) (*WalkResult, error)

WalkMachine drives a machine through one transition. The input symbol is required; the payload is available to guards and set-clauses under the "payload." prefix during evaluation.

Hits POST /api/v2/fsm/machine/{id}/walk.

On success returns *WalkResult with the previous and current states, the terminal flag, any Mealy outputs emitted, the post-walk variable map, and the history row id.

On rejection returns *client.Error with an XOLU-FSM* code. Common rejection codes:

XOLU-FSM003  machine not found
XOLU-FSM004  no transition for (state, input)
XOLU-FSM005  guard rejected the transition
XOLU-FSM006  machine is in a terminal state (no further walks)
XOLU-FSM007  input query failed
XOLU-FSM008  storage error inside the walk transaction

Callers can dispatch on Error.Code to distinguish these.

func (*Client) WithTenantContext ¶

func (c *Client) WithTenantContext(tenantID string) *Client

WithTenantContext returns a new client with the specified tenant ID. This is useful for per-request tenant context.

func (*Client) WithTimeout ¶

func (c *Client) WithTimeout(timeout time.Duration) *Client

WithTimeout returns a shallow-copied client whose per-call timeout is set to the given value. Useful for one-off overrides:

err := client.WithTimeout(2*time.Second).Ready(ctx)

The parent client is not modified.

func (*Error) Error ¶

func (e *Error) Error() string

func (*MachineDef) ParsedAnalysis ¶ added in v0.26.0

func (m *MachineDef) ParsedAnalysis() (*MachineDefAnalysis, error)

ParsedAnalysis decodes Analysis into its structured form.

Analysis itself stayed json.RawMessage rather than becoming *MachineDefAnalysis directly to avoid a breaking change to an already-shipped field for any existing caller relying on the raw bytes; this method is the additive, opt-in path to the same structured data CreateMachineDef/ReplaceMachineDef/ValidateMachineDef return directly. The original doc comment on Analysis claimed the shape "is xolu-server-internal and may evolve" -- checked directly against pkg/server/v2_fsm_common.go's own fsmAnalysis struct before writing this: it's a stable, well-defined set of fields (reachability, determinism, cycles, warnings), not internal debug scratch data, and carries no instability markers anywhere in the server code. Worth exposing structured, not worth forcing every caller to re-parse raw JSON for.

Returns nil, nil if Analysis is empty (e.g. a MachineDef fetched before analysis was populated, or a definition predating this field).

func (*TransitionDef) FromStates ¶

func (t *TransitionDef) FromStates() ([]string, error)

FromStates normalises the From field into a slice of state names, accepting either a JSON string or a JSON array of strings.