client

type APIError struct {
	Status  int
	Code    string
	Message string
	Body    string
}

type AddEntityFieldsInput struct {
	Columns []SchemaColumnInput `json:"columns"`
	Indexes []SchemaIndexInput  `json:"indexes,omitempty"`
}

type CacheInfo struct {
	// Configured reports whether an engine cache is wired (Redis present).
	Configured bool            `json:"configured"`
	Keyspaces  []CacheKeyspace `json:"keyspaces"`
}

type CacheInvalidateResult struct {
	Invalidated bool `json:"invalidated"`
}

type CacheKeyspace struct {
	Entity string `json:"entity"`
	Name   string `json:"name"`
	// Partition is "tenant" or "tenant+scope".
	Partition string `json:"partition"`
	// Mode is the invalidation mode, e.g. "versioned".
	Mode       string `json:"mode"`
	TTLSeconds int64  `json:"ttlSeconds"`
	Scoped     bool   `json:"scoped"`
}

type CacheStats struct {
	// Available is false when a cache is configured but exposes no counters.
	Available     bool  `json:"available"`
	Hits          int64 `json:"hits"`
	Misses        int64 `json:"misses"`
	Sets          int64 `json:"sets"`
	Invalidations int64 `json:"invalidations"`
	// HitRate is Hits/(Hits+Misses), 0 when there have been no lookups.
	HitRate float64 `json:"hitRate"`
}

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

type CommandInput struct {
	// Entity is the registered entity name (e.g. "product").
	Entity string `json:"entity"`
	// Op is the command verb: create | update | delete | upsert.
	Op CommandOp `json:"op"`
	// AggID identifies the aggregate. Required for update/delete/upsert; a
	// ULID is minted server-side for create when omitted.
	AggID string `json:"aggId,omitempty"`
	// Payload is the column-keyed body (create/update/upsert). Ignored for delete.
	Payload map[string]any `json:"payload,omitempty"`
	// ExpectedVersion enables optimistic concurrency — a mismatch is a 409.
	ExpectedVersion *int64 `json:"expectedVersion,omitempty"`
}

type CommandOp string

type CommandResult struct {
	AggID   string `json:"aggId"`
	Version int64  `json:"version"`
	EventID string `json:"eventId"`
}

type CrdtDocument struct {
	// DocID is the document id ("<entity>/<id>").
	DocID string `json:"docId"`
	// Version is the aggregate version assigned by the last materialization
	// event; 0 until the quiet-window snapshot lands a relational row.
	Version int64 `json:"version"`
	// Snapshot is the merged CRDT state as a column-keyed JSON object.
	Snapshot json.RawMessage `json:"snapshot"`
}

type CrdtUpdate struct {
	// Index is the update's ordinal position in the Sync page (0-based).
	Index int `json:"index"`
	// Size is the byte length of the encoded update blob.
	Size int `json:"size"`
	// Preview is a base64 preview of the first bytes of the blob.
	Preview string `json:"preview"`
}

type CrdtUpdatePage struct {
	// DocID is the document id the log belongs to.
	DocID string `json:"docId"`
	// HighWaterSeq is the highest log seq folded into this page.
	HighWaterSeq int64 `json:"highWaterSeq"`
	// HasSnapshot reports whether a compacted snapshot preceded the tail
	// updates (older updates have been folded away).
	HasSnapshot bool `json:"hasSnapshot"`
	// Items lists the tail updates (post-snapshot).
	Items []CrdtUpdate `json:"items"`
}

type CreateEntityTypeInput struct {
	Type    string              `json:"type"`
	Columns []SchemaColumnInput `json:"columns"`
	Indexes []SchemaIndexInput  `json:"indexes,omitempty"`
}

type CreateFolderInput struct {
	// ParentID is the destination folder id; "" creates at root.
	ParentID string `json:"parentId,omitempty"`
	// Name is the new folder's name (required).
	Name string `json:"name"`
}

type DDLResult struct {
	OK       bool   `json:"ok"`
	Executed string `json:"executed"`
}

type DSN struct {
	Transport string
	TLS       bool
	Host      string
	Port      string
	BasePath  string
	Tenant    string
	Key       string
	Version   int
}

type DigestChild struct {
	ID          string `json:"id"`
	Kind        string `json:"kind"`
	Summary     string `json:"summary"`
	ContentHash string `json:"contentHash"`
	SemHash     string `json:"semHash"`
}

type DigestMap struct {
	// RootID is the stable id of the tenant (L2) root: "digest:2:tenant".
	RootID string       `json:"rootId"`
	Nodes  []DigestNode `json:"nodes"`
}

type DigestNode struct {
	ID    string `json:"id"`
	Level int    `json:"level"`
	Kind  string `json:"kind"`
	// Scope is the scope value an L1 scope node summarizes (empty otherwise).
	Scope string `json:"scope,omitempty"`
	// ContentHash is the Merkle freshness key (changes when the subtree changes).
	ContentHash string `json:"contentHash"`
	// SemHash is the 16-hex SimHash fingerprint of the node's summary embedding.
	SemHash string `json:"semHash"`
	// Summary is the node's summary text when surfaced; usually empty in the
	// map (see DigestMap) — use GetDigestNode for full text.
	Summary string `json:"summary,omitempty"`
}

type DigestView struct {
	Node     DigestNode    `json:"node"`
	Summary  string        `json:"summary"`
	Children []DigestChild `json:"children"`
}

type DriftEntity struct {
	Entity  string `json:"entity"`
	Table   string `json:"table"`
	Dynamic bool   `json:"dynamic"`
	InSync  bool   `json:"inSync"`
	// Missing lists columns expected by the registry but absent physically.
	Missing []string `json:"missing"`
	// Extra lists columns present physically but not in the registry.
	Extra []string `json:"extra"`
	// Error is set when this entity's table could not be introspected.
	Error string `json:"error,omitempty"`
}

type EntityPage struct {
	Items      []EntityRecord `json:"items"`
	NextCursor string         `json:"nextCursor"`
}

type EntityRecord struct {
	ID   string         `json:"id"`
	Type string         `json:"type"`
	Data map[string]any `json:"data"`
}

type EntitySchema struct {
	Type   string        `json:"type"`
	Fields []SchemaField `json:"fields"`
}

type EntityWriteInput struct {
	// Type is the registered dynamic entity type name (e.g. "product").
	Type string `json:"type"`
	// Data is the column-keyed payload written to the row.
	Data map[string]any `json:"data"`
}

type Event struct {
	ID                   string          `json:"id"`
	Aggregate            string          `json:"aggregate"`
	AggID                string          `json:"aggId"`
	Version              int64           `json:"version"`
	Type                 string          `json:"type"`
	At                   string          `json:"at"`
	PayloadSchemaVersion int             `json:"payloadSchemaVersion"`
	Published            bool            `json:"published"`
	StreamID             string          `json:"streamId,omitempty"`
	Payload              json.RawMessage `json:"payload"`
}

type EventFacets struct {
	Aggregates []string `json:"aggregates"`
	Types      []string `json:"types"`
}

type EventPage struct {
	Items      []Event `json:"items"`
	NextCursor string  `json:"nextCursor"`
}

type EventsBacklog struct {
	Unpublished int64 `json:"unpublished"`
}

type FileListPage struct {
	Items []FileNode `json:"items"`
}

type FileNode struct {
	// ID is the fs_node aggregate id.
	ID string `json:"id"`
	// Name is the node's name within its folder.
	Name string `json:"name"`
	// Kind is "folder" or "file".
	Kind string `json:"kind"`
	// Size is the byte size for files; 0 for folders.
	Size int64 `json:"size"`
	// ContentType is the file's MIME type; empty for folders.
	ContentType string `json:"contentType"`
	// ParentID is the parent folder's id; "" for root-level nodes.
	ParentID string `json:"parentId"`
	// UpdatedAt is the last-modified timestamp in RFC 3339, when known.
	UpdatedAt string `json:"updatedAt,omitempty"`
}

type GetCrdtUpdatesParams struct {
	// DocID is the document id ("<entity>/<id>").
	DocID string
	// Limit caps the number of returned tail updates (server default 100,
	// capped server-side). Zero omits the query param and defers to the
	// server default.
	Limit int
}

type GraphData struct {
	Nodes []GraphNode `json:"nodes"`
	Edges []GraphEdge `json:"edges"`
}

type GraphEdge struct {
	From  string         `json:"from"`
	To    string         `json:"to"`
	Rel   string         `json:"rel"`
	Props map[string]any `json:"props,omitempty"`
}

type GraphNeighborsParams struct {
	// Type is the node's primary label / entity type (e.g. "product").
	Type string
	// ID is the id of the node to expand.
	ID string
	// Limit caps the number of 1-hop relationships expanded (server default
	// 50). Zero omits the query param and defers to the server default.
	Limit int
}

type GraphNode struct {
	ID    string         `json:"id"`
	Type  string         `json:"type,omitempty"`
	Label string         `json:"label,omitempty"`
	Props map[string]any `json:"props,omitempty"`
}

type GraphQueryInput struct {
	// Cypher is the read-only openCypher query to run.
	Cypher string `json:"cypher"`
	// Params are optional named parameters referenced as $name in the query.
	Params map[string]any `json:"params,omitempty"`
}

type GraphQueryResult struct {
	Columns []string `json:"columns"`
	Rows    [][]any  `json:"rows"`
}

type GraphTraverseInput struct {
	// Type is the node's primary label / entity type (e.g. "product").
	Type string `json:"type"`
	// ID is the id of the root node to traverse from.
	ID string `json:"id"`
	// Depth is the BFS hop count (1-3); values outside the range are clamped
	// server-side.
	Depth int `json:"depth"`
	// Limit caps the number of nodes returned (server default/maximum 200).
	Limit int `json:"limit,omitempty"`
}

type InstanceCapabilities struct {
	Relational bool `json:"relational"`
	Graph      bool `json:"graph"`
	Vector     bool `json:"vector"`
	Spatial    bool `json:"spatial"`
	Search     bool `json:"search"`
	CRDT       bool `json:"crdt"`
	Files      bool `json:"files"`
	Distill    bool `json:"distill"`
	Timeseries bool `json:"timeseries"`
}

type ListEntitiesParams struct {
	// Type is the registered dynamic entity type name (e.g. "product").
	Type string
	// Limit caps the page size (server default 50, max 200). Zero omits the
	// query param and defers to the server default.
	Limit int
	// Cursor resumes a previous listing (server emits this as
	// EntityPage.NextCursor). Empty starts from the first page.
	Cursor string
}

type ListEventsParams struct {
	// Aggregate matches any of these aggregate types (OR / SQL IN).
	Aggregate []string
	// Type matches any of these event types (OR / SQL IN).
	Type []string
	// AggID filters to a single aggregate instance id.
	AggID string
	// Published filters to published (true) or unpublished (false) events.
	// Nil omits the filter.
	Published *bool
	// Limit caps the page size (server default 50, max 200). Zero omits the
	// query param and defers to the server default.
	Limit int
	// Cursor resumes a previous listing (server emits this as
	// EventPage.NextCursor). Empty starts from the first page.
	Cursor string
}

type ListFilesParams struct {
	// Parent is the folder id whose children to list; "" lists the root.
	Parent string
	// Limit caps the page size (server default 100, capped server-side).
	// Zero omits the query param and defers to the server default.
	Limit int
	// Offset paginates past earlier results. Zero omits the query param.
	Offset int
}

type Meta struct {
	Name         string   `json:"name"`
	Version      string   `json:"version"`
	Capabilities []string `json:"capabilities"`
	// Tenant is the resolved tenant id echoed back when X-Tenant-ID is sent.
	// Empty for unauthenticated or tenant-agnostic callers.
	Tenant string `json:"tenant,omitempty"`
}

type MigrationGroupStatus struct {
	Name    string          `json:"name"`
	Applied []MigrationInfo `json:"applied"`
	Pending []MigrationInfo `json:"pending"`
}

type MigrationInfo struct {
	Name    string `json:"name"`
	Version string `json:"version"`
	Group   string `json:"group"`
	Comment string `json:"comment"`
	Applied bool   `json:"applied"`
	// AppliedAt is empty when the migration has not been applied.
	AppliedAt string `json:"appliedAt,omitempty"`
}

type MigrationJob struct {
	ID string `json:"id"`
	// Kind is "up" or "down".
	Kind string `json:"kind"`
	// State is "running", "done", or "failed".
	State     string   `json:"state"`
	Names     []string `json:"names,omitempty"`
	Error     string   `json:"error,omitempty"`
	StartedAt string   `json:"startedAt"`
	// EndedAt is empty while the job is running.
	EndedAt string `json:"endedAt,omitempty"`
}

type MigrationJobHandle struct {
	JobID string `json:"jobId"`
}

type MigrationScaffold struct {
	Filename string `json:"filename"`
	Content  string `json:"content"`
}

type MigrationScaffoldInput struct {
	Name    string `json:"name"`
	Version string `json:"version"`
	// Up/Down are optional forward/reverse DDL statements (one per element);
	// omitted, the generated file carries TODO placeholders.
	Up   []string `json:"up,omitempty"`
	Down []string `json:"down,omitempty"`
}

type MigrationStatus struct {
	Groups []MigrationGroupStatus `json:"groups"`
}

type Option func(*Client)

type ProjectionDrift struct {
	Entity           string `json:"entity"`
	AggID            string `json:"aggId"`
	TruthVersion     int64  `json:"truthVersion"`
	ProjectedVersion int64  `json:"projectedVersion"`
}

type ProjectionRebuildResult struct {
	Projection string `json:"projection"`
	OldTarget  string `json:"oldTarget"`
	NewTarget  string `json:"newTarget"`
}

type ProjectionReconcileResult struct {
	Projection string            `json:"projection"`
	Repaired   bool              `json:"repaired"`
	DriftCount int               `json:"driftCount"`
	Drifts     []ProjectionDrift `json:"drifts"`
}

type ProjectionStatus struct {
	Name string `json:"name"`
	// Status is the blue-green pointer state: live | building | soaking | abandoned.
	Status string `json:"status"`
	// ModelVersion is the _v{N} generation bumped by rebuilds.
	ModelVersion int `json:"modelVersion"`
	// EventVersion is the last applied event ULID (stream position); empty
	// when nothing has been applied through the projection engine.
	EventVersion string `json:"eventVersion"`
	// TargetName is the engine target currently receiving applies (e.g.
	// tenant_<id>_v2); empty when the default live target is used.
	TargetName string `json:"targetName"`
}

type ProjectionsInfo struct {
	Projections []ProjectionStatus `json:"projections"`
	// Backlog is the unpublished outbox depth — a proxy for projection lag.
	Backlog int64 `json:"backlog"`
}

type QueryInput struct {
	// SQL is a single read-only SELECT or WITH statement. Statement stacking
	// (multiple ;-separated statements) is rejected server-side.
	SQL string `json:"sql"`
	// Args are positional query parameters substituted into SQL.
	Args []any `json:"args,omitempty"`
}

type QueryResult struct {
	Columns   []string         `json:"columns"`
	Rows      []map[string]any `json:"rows"`
	RowCount  int              `json:"rowCount"`
	Truncated bool             `json:"truncated"`
	ElapsedMs int64            `json:"elapsedMs"`
}

type RecallItem struct {
	Entity string          `json:"entity"`
	ID     string          `json:"id"`
	Row    json.RawMessage `json:"row"`
	Score  float64         `json:"score"`
	Source []string        `json:"source"`
	Tokens int             `json:"tokens"`
}

type RecallPack struct {
	Items    []RecallItem `json:"items"`
	Omitted  int          `json:"omitted"`
	Tokens   int          `json:"tokens"`
	Warnings []string     `json:"warnings"`
}

type RecallRequest struct {
	// Query is the free-text recall query. Required; an empty query yields
	// an *APIError with Status 400.
	Query string `json:"query"`
	// Entities scopes recall to these dynamic entity types. When omitted the
	// server defaults to every registered dynamic (schema-backed) entity type.
	Entities []string `json:"entities,omitempty"`
	// Budget is the token budget for the assembled context pack. Zero defers
	// to the server default.
	Budget int `json:"budget,omitempty"`
	// K is the per-channel candidate count fed into RRF fusion. Zero defers
	// to the server default.
	K int `json:"k,omitempty"`
	// Hops is the graph-expansion depth for the graph channel. Zero defers
	// to the server default.
	Hops int `json:"hops,omitempty"`
}

type RememberInput struct {
	Entity string    `json:"entity"`
	Op     CommandOp `json:"op"`
	// AggID identifies the aggregate. Required for update/delete/upsert; a
	// ULID is minted server-side for create when omitted.
	AggID string `json:"aggId,omitempty"`
	// Payload is the column-keyed body (create/update/upsert). Ignored for delete.
	Payload map[string]any `json:"payload,omitempty"`
	// ExpectedVersion enables optimistic concurrency — a mismatch is a 409.
	ExpectedVersion *int64 `json:"expectedVersion,omitempty"`
}

type SchemaColumnInput struct {
	Name string `json:"name"`
	// Kind is one of: string, number, boolean, time, object.
	Kind     string `json:"kind"`
	Required bool   `json:"required"`
	// Default is a SQL default expression. Allowed forms: a number,
	// true/false/null, now(), or a single-quoted string literal. Empty omits
	// the field.
	Default string `json:"default,omitempty"`
}

type SchemaDrift struct {
	Entities []DriftEntity `json:"entities"`
}

type SchemaField struct {
	// Name is the column name.
	Name string `json:"name"`
	// Kind is the simplified field kind: string, number, boolean, time, or object.
	Kind string `json:"kind"`
	// Required reports whether the column is NOT NULL.
	Required bool `json:"required"`
}

type SchemaIndexInput struct {
	Name    string   `json:"name"`
	Columns []string `json:"columns"`
	Unique  bool     `json:"unique,omitempty"`
}

type SearchPage struct {
	Items []EntityRecord `json:"items"`
}

type SearchTextParams struct {
	// Type is the registered dynamic entity type name (e.g. "product"). Must
	// be search-indexed.
	Type string
	// Query is the full-text query string.
	Query string
	// Limit caps the page size (server default 25, capped server-side). Zero
	// omits the query param and defers to the server default.
	Limit int
	// Offset paginates past earlier results. Zero omits the query param.
	Offset int
	// Sort is an indexed column, optionally suffixed " DESC". Empty omits
	// the query param and defers to relevance-score ordering.
	Sort string
	// Filter is a set of equality filters over indexed fields, AND-ed. Each
	// entry is sent as a repeated ?filter=field:value query param.
	Filter map[string]string
}

type SpatialMatch struct {
	ID        string         `json:"id"`
	DistanceM float64        `json:"distanceM,omitempty"`
	Lng       *float64       `json:"lng,omitempty"`
	Lat       *float64       `json:"lat,omitempty"`
	Data      map[string]any `json:"data,omitempty"`
}

type SpatialResult struct {
	Matches []SpatialMatch `json:"matches"`
}

type SpatialWithinInput struct {
	// Entity is the registered dynamic entity type name (e.g. "place").
	Entity string `json:"entity"`
	// Lng is the centre longitude (X), degrees, WGS84.
	Lng float64 `json:"lng"`
	// Lat is the centre latitude (Y), degrees, WGS84.
	Lat float64 `json:"lat"`
	// RadiusM is the search radius in metres.
	RadiusM float64 `json:"radiusM"`
	// Limit caps the number of returned matches (server default 25). Zero
	// defers to the server default.
	Limit int `json:"limit,omitempty"`
}

type TypeCapabilities struct {
	Relational bool `json:"relational"`
	Vector     bool `json:"vector"`
	Search     bool `json:"search"`
	Spatial    bool `json:"spatial"`
	CRDT       bool `json:"crdt"`
	Graph      bool `json:"graph"`
}

type TypeCapabilitiesResult struct {
	Type         string           `json:"type"`
	Capabilities TypeCapabilities `json:"capabilities"`
}

type UploadFileInput struct {
	// ParentID is the destination folder id; "" creates at root.
	ParentID string `json:"parentId,omitempty"`
	// Name is the new file's name (required).
	Name string `json:"name"`
	// ContentType is the file's MIME type (optional).
	ContentType string `json:"contentType,omitempty"`
	// Data is the raw file body; UploadFile base64-encodes it into the
	// request's dataBase64 field.
	Data []byte `json:"-"`
}

type VectorDeleteByMetaInput struct {
	// Entity is the registered entity whose embeddings are targeted.
	Entity string `json:"entity"`
	// Filter is an AND-of-equals over embedding meta. An empty filter would
	// delete every embedding for the entity, so it is rejected server-side
	// unless All is set.
	Filter map[string]string `json:"filter,omitempty"`
	// All must be explicitly true to opt into the wipe-all (empty-filter) path.
	All bool `json:"all,omitempty"`
}

type VectorDeleteResult struct {
	Deleted bool `json:"deleted"`
}

type VectorEmbeddingInfo struct {
	Entity  string    `json:"entity"`
	ID      string    `json:"id"`
	Dims    int       `json:"dims"`
	Norm    float64   `json:"norm"`
	Preview []float32 `json:"preview"`
}

type VectorMatch struct {
	ID    string         `json:"id"`
	Score float64        `json:"score"`
	Data  map[string]any `json:"data,omitempty"`
}

type VectorSearchInput struct {
	// Type is the registered dynamic entity type name (e.g. "product").
	Type string `json:"type"`
	// Query is the free-text query for TEXT mode. Requires a configured
	// server-side embedder.
	Query string `json:"query,omitempty"`
	// ID selects SIMILAR-TO-ENTITY mode: find rows similar to this stored
	// embedding.
	ID string `json:"id,omitempty"`
	// K caps the number of returned matches (server default 10).
	K int `json:"k,omitempty"`
	// Filter restricts matches to embeddings whose meta contains all of
	// these key=value pairs (AND-ed). Optional; empty means no meta filter.
	Filter map[string]string `json:"filter,omitempty"`
}

type VectorSearchPage struct {
	Matches []VectorMatch `json:"matches"`
}

type WritePolicy struct {
	Allow map[string][]string `json:"allow"`
}