Documentation
¶
Index ¶
- Constants
- Variables
- func DecodeJSON(r io.Reader) (any, error)
- func ErrorKind(err error) error
- func ErrorName(err error) string
- func MarshalWire(value any) ([]byte, error)
- func NewCLI(reader io.Reader, writer, errWriter io.Writer) *cli.Command
- func NewMCPServer(db *DB, options MCPOptions) *mcp.Server
- func RunCLI(ctx context.Context, args []string, reader io.Reader, ...) error
- func RunMCP(ctx context.Context, db *DB, options MCPOptions) error
- type ApplySummary
- type AttributeInfo
- type AttributeObservation
- type BytesValue
- type Clock
- type DB
- func (db *DB) Add(ctx context.Context, data any, options ...TxOption) (TxReport, error)
- func (db *DB) Apply(ctx context.Context, reader io.Reader) (reports []TxReport, resultErr error)
- func (db *DB) ApplySchemaManifest(ctx context.Context, manifest SchemaManifest, options ...TxOption) (TxReport, error)
- func (db *DB) ApplySummary(ctx context.Context, reader io.Reader) (ApplySummary, error)
- func (db *DB) At(ctx context.Context, value any) (*DB, error)
- func (db *DB) AtInstant(ctx context.Context, micros int64) (*DB, error)
- func (db *DB) Attributes(ctx context.Context, prefix string, includeSystem bool) ([]AttributeInfo, error)
- func (db *DB) Backup(ctx context.Context, destination string) (resultErr error)
- func (db *DB) Changes(ctx context.Context, since int64, until ...int64) (Diff, error)
- func (db *DB) CheckSchemaManifest(ctx context.Context, manifest SchemaManifest) (SchemaManifestCheck, error)
- func (db *DB) Close() error
- func (db *DB) Datoms(ctx context.Context, options DatomOptions) (DatomPage, error)
- func (db *DB) Declare(ctx context.Context, attr string, options ...DeclareOption) (TxReport, error)
- func (db *DB) DeclareShape(ctx context.Context, name string, definition ShapeDefinition, ...) (TxReport, error)
- func (db *DB) Diff(ctx context.Context, from, to int64) (Diff, error)
- func (db *DB) Doctor(ctx context.Context, repair ...bool) (result DoctorReport, resultErr error)
- func (db *DB) Entity(ctx context.Context, ref any, depth ...int) (map[string]any, error)
- func (db *DB) EventRecords(ctx context.Context, since int64, through ...int64) ([]map[string]any, error)
- func (db *DB) Excise(ctx context.Context, ref any, options ...TxOption) (result TxReport, resultErr error)
- func (db *DB) Explain(ctx context.Context, query Q, args map[string]any) (ExplainPlan, error)
- func (db *DB) ExplainJSON(ctx context.Context, value any, args map[string]any) (ExplainPlan, error)
- func (db *DB) Follow(ctx context.Context, options FollowOptions) <-chan FollowEvent
- func (db *DB) History(ctx context.Context, ref any, attr ...string) ([]Fact, error)
- func (db *DB) Pull(ctx context.Context, ref any, pattern []any) (map[string]any, error)
- func (db *DB) Qry(ctx context.Context, query Q, args map[string]any) (Result, error)
- func (db *DB) Query(ctx context.Context, query Q, args map[string]any) (Result, error)
- func (db *DB) QueryJSON(ctx context.Context, value any, args map[string]any) (Result, error)
- func (db *DB) RawFacts(ctx context.Context, includeGenesis bool) ([][]any, error)
- func (db *DB) Receipt(ctx context.Context, tx int64) (EventReceipt, error)
- func (db *DB) Restore(ctx context.Context, reader io.Reader) error
- func (db *DB) Retract(ctx context.Context, ref any, args ...any) (TxReport, error)
- func (db *DB) Schema(ctx context.Context, prefix string, includeSystem bool) (SchemaSnapshot, error)
- func (db *DB) SchemaManifest(ctx context.Context) (SchemaManifest, error)
- func (db *DB) Search(ctx context.Context, options SearchOpts) (SearchResult, error)
- func (db *DB) Snapshot(ctx context.Context, writer io.Writer) error
- func (db *DB) Speculate(ctx context.Context, callback func(*DB) error) (resultErr error)
- func (db *DB) Stats(ctx context.Context) (Stats, error)
- func (db *DB) Tail(ctx context.Context, writer io.Writer, since int64) error
- func (db *DB) Transact(ctx context.Context, data any, options ...TxOption) (result TxReport, resultErr error)
- func (db *DB) Undo(ctx context.Context, target int64, options ...TxOption) (TxReport, error)
- func (db *DB) Validate(ctx context.Context, selectors ...any) (ValidationReport, error)
- func (db *DB) ViewAt(ctx context.Context, value any) (*DB, error)
- func (db *DB) Why(ctx context.Context, ref any, attr ...string) ([]Fact, error)
- type Datom
- type DatomOptions
- type DatomPage
- type DeclareOption
- type DeclaredAttribute
- type Diff
- type DoctorReport
- type E
- type EffectiveAttribute
- type Embedder
- type Error
- type EventIDFactory
- type EventReceipt
- type ExplainClause
- type ExplainPlan
- type ExportTx
- type Fact
- type Field
- type FollowEvent
- type FollowOptions
- type InstantValue
- type JSONValue
- type MCPOptions
- type Object
- type OpenOption
- type Q
- type RefValue
- type Result
- type SchemaAttribute
- type SchemaManifest
- type SchemaManifestAttribute
- type SchemaManifestChange
- type SchemaManifestCheck
- type SchemaSnapshot
- type SearchHit
- type SearchOpts
- type SearchResult
- type ShapeDefinition
- type ShapeInfo
- type Stats
- type Tag
- type TempID
- type TxOption
- type TxReport
- type ValidationReport
- type ValidationViolation
- type VectorValue
Constants ¶
const ( ApplicationID = 0x66677261 FormatVersion = 2 BlobThreshold = 256 MaxValueBytes = 1_048_576 MaxJSONDepth = 64 MaxJSONDocumentDepth = 80 GenesisTx = 64 GenesisFactCount = 39 FirstUserID = 65 Version = "1.0.4" DefaultQueryBudget = 100_000 MaxMCPOutputBytes = 256 << 10 )
Variables ¶
var ( ErrNotFound = errors.New("NotFound") ErrConflict = errors.New("Conflict") ErrSchema = errors.New("SchemaError") ErrType = errors.New("TypeError") ErrQuery = errors.New("QueryError") ErrFormat = errors.New("FormatError") ErrReadOnly = errors.New("ReadOnly") ErrTooLarge = errors.New("TooLarge") ErrUnsupported = errors.New("Unsupported") )
Functions ¶
func MarshalWire ¶
MarshalWire converts convenience wrappers to the normative JSON wire form.
func NewMCPServer ¶
func NewMCPServer(db *DB, options MCPOptions) *mcp.Server
Types ¶
type ApplySummary ¶
type AttributeInfo ¶
type AttributeInfo struct {
Dims *int64 `json:"dims,omitempty"`
Doc *string `json:"doc,omitempty"`
VectorModel *string `json:"vector_model,omitempty"`
Name string `json:"name"`
Types []string `json:"types"`
Facts int64 `json:"facts"`
Many bool `json:"many"`
Unique bool `json:"unique"`
NoHistory bool `json:"nohistory"`
}
type AttributeObservation ¶
type DB ¶
type DB struct {
// contains filtered or unexported fields
}
DB is a concurrency-safe connection or an immutable as-of view over one.
func (*DB) Apply ¶
Apply idempotently applies a portable event/1 NDJSON stream. The whole stream commits or rolls back as one SQLite write transaction.
func (*DB) ApplySchemaManifest ¶
func (*DB) ApplySummary ¶
func (*DB) Attributes ¶
func (db *DB) Attributes(ctx context.Context, prefix string, includeSystem bool) ([]AttributeInfo, error)
Attributes returns the effective schema and observed logical types for application attributes. System attributes are opt-in so discovery remains useful for normal application modeling.
func (*DB) CheckSchemaManifest ¶
func (db *DB) CheckSchemaManifest(ctx context.Context, manifest SchemaManifest) (SchemaManifestCheck, error)
func (*DB) DeclareShape ¶
func (db *DB) DeclareShape( ctx context.Context, name string, definition ShapeDefinition, options ...TxOption, ) (TxReport, error)
DeclareShape creates or replaces one named shape. The replacement is a single transaction so readers never observe a partially updated definition.
func (*DB) EventRecords ¶
func (db *DB) EventRecords(ctx context.Context, since int64, through ...int64) ([]map[string]any, error)
EventRecords returns portable event/1 records after since and through an optional inclusive local transaction boundary. Historical views clamp the boundary to their pinned basis.
func (*DB) ExplainJSON ¶
func (*DB) Follow ¶
func (db *DB) Follow(ctx context.Context, options FollowOptions) <-chan FollowEvent
func (*DB) Receipt ¶
Receipt returns durable event metadata without replaying the transaction. On a historical view, tx and read_basis_tx are both bounded by that view.
func (*DB) Restore ¶
Restore atomically installs a portable retained-state snapshot into a pristine database. Apply is the merge primitive for non-pristine stores.
func (*DB) SchemaManifest ¶
func (db *DB) SchemaManifest(ctx context.Context) (SchemaManifest, error)
func (*DB) Search ¶
func (db *DB) Search(ctx context.Context, options SearchOpts) (SearchResult, error)
func (*DB) Snapshot ¶
Snapshot writes a portable retained-state snapshot/1 stream. Unlike Backup, this format is canonical NDJSON and can be restored by every runtime.
type Datom ¶
type Datom struct {
E any `json:"e"`
V any `json:"v"`
A string `json:"a"`
Tx int64 `json:"tx"`
FactID int64 `json:"fact_id"`
Added bool `json:"added"`
}
func (Datom) MarshalJSON ¶
type DatomOptions ¶
type DatomPage ¶
type DatomPage struct {
NextCursor string `json:"-"`
Items []Datom `json:"items"`
BasisTx int64 `json:"basis_tx"`
}
func (DatomPage) MarshalJSON ¶
type DeclareOption ¶
type DeclareOption func(*declareOptions)
func Dims ¶
func Dims(n int64) DeclareOption
func Doc ¶
func Doc(text string) DeclareOption
func Many ¶
func Many(value ...bool) DeclareOption
func NoHistory ¶
func NoHistory(value ...bool) DeclareOption
func Ref ¶
func Ref() DeclareOption
func Type ¶
func Type(name string) DeclareOption
func Unique ¶
func Unique(value ...bool) DeclareOption
func VectorModel ¶
func VectorModel(model string) DeclareOption
type DeclaredAttribute ¶
type DeclaredAttribute struct {
Type *string `json:"type,omitempty"`
Many *bool `json:"many,omitempty"`
Unique *bool `json:"unique,omitempty"`
NoHistory *bool `json:"nohistory,omitempty"`
Dims *int64 `json:"dims,omitempty"`
Doc *string `json:"doc,omitempty"`
VectorModel *string `json:"vector_model,omitempty"`
}
DeclaredAttribute preserves presence separately from value. In particular, an explicit false declaration is different from no declaration at all.
type DoctorReport ¶
type DoctorReport struct {
Integrity string `json:"integrity"`
Problems []string `json:"problems"`
FTSRows int64 `json:"fts_rows"`
ExpectedFTSRows int64 `json:"expected_fts_rows"`
OrphanedBlobs int64 `json:"orphaned_blobs"`
FTSRowsRebuilt int64 `json:"fts_rows_rebuilt"`
OrphanedBlobsRemoved int64 `json:"orphaned_blobs_removed"`
UnverifiableEvents int64 `json:"unverifiable_event_hashes"`
SchemaProblems int64 `json:"schema_problems"`
ShapeViolations int64 `json:"shape_violations"`
OK bool `json:"ok"`
RepairNeeded bool `json:"repair_needed"`
Repaired bool `json:"repaired"`
}
type EffectiveAttribute ¶
type EffectiveAttribute struct {
Type *string `json:"type"`
Dims *int64 `json:"dims"`
Doc *string `json:"doc"`
VectorModel *string `json:"vector_model"`
Many bool `json:"many"`
Unique bool `json:"unique"`
NoHistory bool `json:"nohistory"`
}
EffectiveAttribute is total: nullable values are emitted as JSON null so agents can introspect the schema without guessing which fields exist.
func (EffectiveAttribute) MarshalJSON ¶
func (attribute EffectiveAttribute) MarshalJSON() ([]byte, error)
type Error ¶
Error gives every public failure a stable cross-language name while keeping errors.Is useful to Go callers.
type EventIDFactory ¶
EventIDFactory returns a canonical UUID for the next committed event. It is injectable so deterministic replicas and tests do not depend on randomness.
type EventReceipt ¶
type EventReceipt struct {
By *string `json:"by,omitempty"`
Source *string `json:"source,omitempty"`
OperationID *string `json:"operation_id"`
RequestHash *string `json:"request_hash"`
ImportedAt *int64 `json:"imported_at,omitempty"`
Meta *any `json:"meta,omitempty"`
EventHash string `json:"event_hash"`
Event string `json:"event"`
Facts []Fact `json:"facts"`
ReadBasisTx int64 `json:"read_basis_tx"`
BasisTx int64 `json:"basis_tx"`
Tx int64 `json:"tx"`
At int64 `json:"at"`
}
EventReceipt is the durable control-plane metadata for one committed event. Hashes use the explicit sha256:<lowercase-hex> wire representation.
func (EventReceipt) MarshalJSON ¶
func (receipt EventReceipt) MarshalJSON() ([]byte, error)
type ExplainClause ¶
type ExplainClause struct {
Kind string `json:"kind"`
Access string `json:"access"`
Bound []string `json:"bound"`
Ordinal int `json:"ordinal"`
}
func (ExplainClause) MarshalJSON ¶
func (clause ExplainClause) MarshalJSON() ([]byte, error)
type ExplainPlan ¶
type ExplainPlan struct {
Source string `json:"source"`
Clauses []ExplainClause `json:"clauses"`
Warnings []string `json:"warnings"`
BasisTx int64 `json:"basis_tx"`
WorkLimit int `json:"work_limit"`
}
func (ExplainPlan) MarshalJSON ¶
func (plan ExplainPlan) MarshalJSON() ([]byte, error)
type Fact ¶
type Fact struct {
V any `json:"v"`
E any `json:"e"`
Rx *int64 `json:"rx"`
Provenance map[string]any `json:"provenance,omitempty"`
RxSource string `json:"rx_source,omitempty"`
By string `json:"by,omitempty"`
Source string `json:"source,omitempty"`
RxBy string `json:"rx_by,omitempty"`
A string `json:"a"`
Snippet string `json:"snippet,omitempty"`
Tag Tag `json:"-"`
Tx int64 `json:"tx"`
ID int64 `json:"id"`
At int64 `json:"at,omitempty"`
RxAt int64 `json:"rx_at,omitempty"`
SnippetTruncated bool `json:"snippet_truncated,omitempty"`
ValueTruncated bool `json:"value_truncated,omitempty"`
// contains filtered or unexported fields
}
func (Fact) MarshalJSON ¶
type FollowEvent ¶
type FollowOptions ¶
type InstantValue ¶
type InstantValue struct{ Micros int64 }
func Instant ¶
func Instant(micros int64) InstantValue
type MCPOptions ¶
type Object ¶
type Object struct{ Fields []Field }
Object retains duplicate-safe decoded members; consumers apply canonical key ordering.
type OpenOption ¶
type OpenOption func(*openConfig)
func WithClock ¶
func WithClock(clock Clock) OpenOption
func WithEventIDFactory ¶
func WithEventIDFactory(factory EventIDFactory) OpenOption
func WithQueryBudget ¶
func WithQueryBudget(budget int) OpenOption
func WithReadOnly ¶
func WithReadOnly() OpenOption
type Q ¶
type Q struct {
Limit *int `json:"limit,omitempty"`
Source string `json:"source,omitempty"`
Find []any `json:"find"`
Where []any `json:"where"`
In []string `json:"in,omitempty"`
Order []any `json:"order,omitempty"`
Rules []any `json:"rules,omitempty"`
Offset int `json:"offset,omitempty"`
}
func ParseQuery ¶
type SchemaAttribute ¶
type SchemaAttribute struct {
Name string `json:"name"`
Declared DeclaredAttribute `json:"declared"`
Effective EffectiveAttribute `json:"effective"`
Observed AttributeObservation `json:"observed"`
}
type SchemaManifest ¶
type SchemaManifest struct {
FGraph string `json:"fgraph"`
Digest string `json:"digest"`
Attributes []SchemaManifestAttribute `json:"attributes"`
Shapes []ShapeInfo `json:"shapes"`
}
type SchemaManifestAttribute ¶
type SchemaManifestAttribute struct {
Declared DeclaredAttribute `json:"declared"`
Name string `json:"name"`
}
type SchemaManifestChange ¶
type SchemaManifestCheck ¶
type SchemaManifestCheck struct {
CurrentDigest string `json:"current_digest"`
DesiredDigest string `json:"desired_digest"`
Changes []SchemaManifestChange `json:"changes"`
BasisTx int64 `json:"basis_tx"`
Valid bool `json:"valid"`
}
type SchemaSnapshot ¶
type SchemaSnapshot struct {
Digest string `json:"digest"`
Attributes []SchemaAttribute `json:"attributes"`
Shapes []ShapeInfo `json:"shapes"`
BasisTx int64 `json:"basis_tx"`
}
type SearchOpts ¶
type SearchResult ¶
type ShapeDefinition ¶
type ShapeDefinition struct {
Required []string `json:"required,omitempty"`
Allowed []string `json:"allowed,omitempty"`
Closed bool `json:"closed,omitempty"`
}
ShapeDefinition describes the required and allowed attributes for entities assigned to a shape. Closed shapes implicitly allow every required attribute, matching the validation invariant enforced at commit time.
type Stats ¶
type Stats struct {
ApplicationID int64 `json:"application_id"`
Entities int64 `json:"entities"`
Attributes int64 `json:"attributes"`
Facts int64 `json:"facts"`
LiveFacts int64 `json:"live_facts"`
Transactions int64 `json:"transactions"`
Blobs int64 `json:"blobs"`
Size int64 `json:"size"`
FormatVersion int64 `json:"format_version"`
}
type TxOption ¶
type TxOption func(*txOptions)
func IfBasis ¶
IfBasis requires the current committed basis to equal tx. The check is made under SQLite's single-writer lock before allocation, time, or UUID sampling.
func WithBasisTx ¶
func WithOperationID ¶
WithOperationID makes a transaction safely retryable. Reusing the same id with the same canonical request returns the original receipt; different input fails with ErrConflict.
func WithSource ¶
func WithTxFacts ¶
type TxReport ¶
type TxReport struct {
IDs map[string]int64 `json:"ids"`
Status string `json:"status"`
EventID string `json:"event,omitempty"`
Asserted []Fact `json:"asserted"`
Retracted []Fact `json:"retracted"`
BasisTx int64 `json:"basis_tx"`
Tx int64 `json:"tx"`
At int64 `json:"at,omitempty"`
}
func (TxReport) MarshalJSON ¶
type ValidationReport ¶
type ValidationReport struct {
Violations []ValidationViolation `json:"violations"`
BasisTx int64 `json:"basis_tx"`
Valid bool `json:"valid"`
}
type ValidationViolation ¶
type VectorValue ¶
type VectorValue []float32
func Vector ¶
func Vector(value []float32) VectorValue