Struct Engine 

pub struct Engine {
    pub repo: Repository,
    pub policy: Arc<dyn PolicyGate>,
    pub audit: Arc<dyn AuditSink>,
    pub ref_name: String,
    pub ratify: Option<Arc<dyn RatifyOps>>,
    pub db_path: Option<PathBuf>,
    pub fts: Option<SearchFtsDb>,
}

The top-level ASD engine. Owns an ASG repository, a policy gate, an audit sink, and optional commercial ratify operations. Cheap to construct; shared across CLI, MCP, and library consumers.

Field access

The fields are pub for compatibility with CLI/MCP surface code that accesses repo, ref_name, policy, and audit directly. New callers should prefer the operation methods (append_ledger_entry, etc.) which automatically enforce the policy gate and emit audit events.

Fields

repo: Repository

policy: Arc<dyn PolicyGate>

audit: Arc<dyn AuditSink>

ref_name: String

ratify: Option<Arc<dyn RatifyOps>>

Commercial ratify operations (Team tier). None in the OSS binary — ledger approve/reject/withdraw return a commercial-feature error. Set by asd-pro at startup via Engine::set_ratify_ops.

db_path: Option<PathBuf>

Path to the SQLite backing store, when opened via open_sqlite. None for in-memory engines (tests, etc.). Commands that bypass the git layer for SQLite-cached reads (symbol map, edges) use this.

fts: Option<SearchFtsDb>

Single open connection to the ASD SQLite file. Opened once in open_sqlite and shared (by borrow) across all stores for the lifetime of the command — eliminates per-call Connection::open.

Implementations

impl Engine

pub fn open_sqlite(db_path: &Path) -> Result<Self>

Open (or create) an ASD engine backed by a SQLite file.

If the repository has no symbols and a .asd/v1/ sidecar exists next to the DB file, hydrates automatically — this covers the fresh-clone case without requiring a manual asd hydrate invocation.

pub fn open_in_memory() -> Result<Self>

Open an in-memory engine — mostly for tests.

pub fn set_policy(&mut self, policy: Arc<dyn PolicyGate>)

pub fn load_policy_file(&mut self, path: &Path) -> Result<()>

Load a policy file and install the real PolicyStoreGate backed by agentstategraph-policy. Rules are imported into an isolated in-memory repo at startup; all evaluation is delegated to PolicyStore.

pub fn set_audit_sink(&mut self, sink: Arc<dyn AuditSink>)

pub fn set_ratify_ops(&mut self, ratify: Arc<dyn RatifyOps>)

Install the commercial ratify implementation (Team tier). Called by asd-pro at startup before any subcommand dispatch.

pub fn append_ledger_entry( &self, entry: &LedgerEntry, agent_id: &str, ) -> Result<()>

Append a ledger entry. Evaluates the configured policy gate first; returns an error if the policy denies the operation. On success, emits a ledger.append audit event.

pub fn put_symbol(&self, symbol: &Symbol, agent_id: &str) -> Result<()>

Write a symbol to the index. Policy-neutral (no gate); emits no audit event — indexing is a bulk background operation, not a user action.

pub fn warm_caches(&self) -> Result<CacheWarmSummary>

Plan T: populate the SQLite fast-read caches (asd_symbols_cache, asd_call_edges, and — only if empty — the FTS search table) from the authoritative git trees.

Reads git directly rather than going through AsgIndexStore so a stale cache can never be used as its own source. Called from two places:

• open_sqlite self-heal, when git has symbols but the cache is cold (born-cold hydrate DBs, or a past sync failure such as SQLITE_BUSY);
• asd hydrate, right after loading the sidecar, so hydrate-created DBs are warm before the command exits.

Concurrency: sync_symbols/sync_call_edges are transactional full-replaces on a WAL connection with a busy timeout, and the operation is idempotent — concurrent callers converge on the same rows. In-memory engines (fts: None) return skipped: true and do nothing.