trellis/dist/core/kernel/trellis-kernel.d.ts

Agentic State Engine — event-sourced causal graph with branching, decision traces, and realtime sync for AI-native applications

/**
 * TrellisKernel — Generic Graph Kernel
 *
 * The composition root for the Trellis semantic kernel. Orchestrates the
 * EAV store, persistence backend, middleware chain, and snapshot lifecycle.
 *
 * The VCS engine (`TrellisVcsEngine`) sits on top of this generic kernel.
 * Non-VCS consumers can use TrellisKernel directly for pure graph CRUD.
 *
 * @module trellis/core
 */
import { EAVStore } from '../store/eav-store.js';
import type { Fact, FactMeta, Link, Atom } from '../store/eav-store.js';
import type { OpProvenance } from '../persist/canonical-op.js';
import type { KernelOp, KernelOpKind, KernelBackend } from '../persist/backend.js';
import type { KernelMiddleware, MiddlewareContext } from './middleware.js';
import { QueryEngine } from '../query/engine.js';
import type { Query } from '../query/types.js';
import type { QueryResult } from '../query/engine.js';
import type { SchemaDefinition, WorkspaceConfig } from '../ontology/types.js';
export interface KernelConfig {
    /** Persistence backend (SQLite or in-memory). */
    backend: KernelBackend;
    /** Agent ID for attributing operations. */
    agentId: string;
    /** Middleware chain applied to every mutation. */
    middleware?: KernelMiddleware[];
    /** Auto-snapshot after this many ops (0 = disabled). */
    snapshotThreshold?: number;
    /** Auto-replay ops from backend on boot (default: true). */
    autoReplay?: boolean;
    /**
     * Fallback provenance for ops minted without a per-call `ctx.provenance`
     * (ADR 0021 §2). Defaults to `{ actorType: 'machine', origin: 'sdk' }` —
     * the honest description of "something called the kernel API directly and
     * did not say who it was".
     *
     * Surfaces that know better (CLI, HTTP, MCP, sync, import) must pass
     * `ctx.provenance` per call rather than relying on this, since one kernel
     * can serve several surfaces at once.
     */
    provenance?: OpProvenance;
}
export interface MutateResult {
    op: KernelOp;
    factsDelta: {
        added: number;
        deleted: number;
    };
    linksDelta: {
        added: number;
        deleted: number;
    };
}
export interface EntityRecord {
    id: string;
    type: string;
    facts: Fact[];
    links: Link[];
}
export declare class TrellisKernel {
    private store;
    private backend;
    private middleware;
    private agentId;
    private snapshotThreshold;
    private opsSinceSnapshot;
    private _booted;
    private ontologies;
    private workspaceConfig;
    private autoReplay;
    private defaultProvenance;
    constructor(config: KernelConfig);
    /**
     * Initialize the backend and replay persisted state.
     * Loads latest snapshot if available, then replays ops after it.
     */
    boot(): {
        opsReplayed: number;
        fromSnapshot: boolean;
    };
    /**
     * Close the backend connection.
     */
    close(): void;
    isBooted(): boolean;
    /**
     * Apply a mutation to the graph. Creates an op, runs it through middleware,
     * decomposes into EAV primitives, persists, and returns the result.
     */
    mutate(kind: KernelOpKind | string, payload: {
        facts?: Fact[];
        links?: Link[];
        deleteFacts?: Fact[];
        deleteLinks?: Link[];
        provenance?: OpProvenance;
    }, ctx?: Partial<MiddlewareContext>): Promise<MutateResult>;
    /**
     * Create a snapshot of the current store state.
     */
    checkpoint(): void;
    /**
     * Get the underlying EAV store for direct queries.
     */
    getStore(): EAVStore;
    /**
     * Get the persistence backend.
     */
    getBackend(): KernelBackend;
    /**
     * Get the agent ID.
     */
    getAgentId(): string;
    /**
     * Read all persisted ops.
     */
    readAllOps(): KernelOp[];
    /**
     * Get the last persisted op.
     */
    getLastOp(): KernelOp | undefined;
    /**
     * Create a QueryEngine bound to this kernel's store.
     */
    createQueryEngine(): QueryEngine;
    /**
     * Execute an EQL-S query, routing through middleware handleQuery hooks.
     * If no middleware intercepts, the query runs directly against the store.
     */
    query(q: Query): Promise<QueryResult>;
    /**
     * Time-travel: reconstruct the store state at a specific op hash.
     * Returns a new EAVStore with state replayed up to (and including) that op.
     */
    timeTravel(opHash: string): EAVStore;
    /**
     * Create a new entity with the given type and attributes.
     * Returns the entity ID.
     */
    createEntity(entityId: string, type: string, attributes?: Record<string, Atom>, links?: Array<{
        attribute: string;
        targetEntityId: string;
    }>, ctx?: Partial<MiddlewareContext>): Promise<MutateResult>;
    /**
     * Get an entity by ID, returning all its facts and links.
     */
    getEntity(entityId: string): EntityRecord | null;
    /**
     * Update an entity's attributes. Deletes old values and adds new ones.
     */
    updateEntity(entityId: string, updates: Record<string, Atom>, ctx?: Partial<MiddlewareContext>): Promise<MutateResult>;
    /**
     * Delete an entity and all its facts and links.
     */
    deleteEntity(entityId: string, ctx?: Partial<MiddlewareContext>): Promise<MutateResult>;
    /**
     * List entities by type, with optional attribute filters.
     */
    listEntities(type?: string, filters?: Record<string, Atom>): EntityRecord[];
    /**
     * Add a link between two entities.
     */
    addLink(sourceId: string, attribute: string, targetId: string, ctx?: Partial<MiddlewareContext>): Promise<MutateResult>;
    /**
     * Remove a link between two entities.
     */
    removeLink(sourceId: string, attribute: string, targetId: string, ctx?: Partial<MiddlewareContext>): Promise<MutateResult>;
    /**
     * Add a fact to an entity.
     */
    addFact(entityId: string, attribute: string, value: Atom, ctx?: Partial<MiddlewareContext>, meta?: FactMeta): Promise<MutateResult>;
    /**
     * Remove a fact from an entity.
     */
    removeFact(entityId: string, attribute: string, value: Atom, ctx?: Partial<MiddlewareContext>): Promise<MutateResult>;
    /**
     * Get an ontology schema by ID.
     */
    getOntology(id: string): SchemaDefinition | undefined;
    /**
     * List all ontologies.
     */
    listOntologies(): SchemaDefinition[];
    /**
     * Create a new ontology schema.
     */
    createOntology(schema: SchemaDefinition): void;
    /**
     * Update an existing ontology schema.
     */
    updateOntology(id: string, updates: Partial<SchemaDefinition>): void;
    /**
     * Delete an ontology schema.
     */
    deleteOntology(id: string): void;
    /**
     * Boot the kernel with a workspace configuration.
     * Loads ontologies, projections, and seed data.
     */
    bootWorkspace(config: WorkspaceConfig): void;
    /**
     * Export the current workspace configuration.
     */
    exportWorkspace(): WorkspaceConfig;
    /**
     * Create a node (alias for createEntity with schema validation).
     */
    createNode(id: string, data: Record<string, Atom>, type: string, ctx?: Partial<MiddlewareContext>): Promise<MutateResult>;
    /**
     * Update a node (alias for updateEntity with schema validation).
     */
    updateNode(id: string, data: Record<string, Atom>, type: string, ctx?: Partial<MiddlewareContext>): Promise<MutateResult>;
    /**
     * Delete a node (alias for deleteEntity).
     */
    deleteNode(id: string, ctx?: Partial<MiddlewareContext>): Promise<MutateResult>;
    /**
     * Link two nodes (alias for addLink).
     */
    link(e1: string, a: string, e2: string, ctx?: Partial<MiddlewareContext>): Promise<MutateResult>;
    /**
     * Unlink two nodes (alias for removeLink).
     */
    unlink(e1: string, a: string, e2: string, ctx?: Partial<MiddlewareContext>): Promise<MutateResult>;
    addMiddleware(mw: KernelMiddleware): void;
    removeMiddleware(name: string): void;
    private _runMiddleware;
    private _replayOp;
}
//# sourceMappingURL=trellis-kernel.d.ts.map