package dwbase:core;
interface engine {
type atom-id = string;
type world-key = string;
type worker-key = string;
type observe-handle = u64;
record tool-error {
code: string,
message: string,
details-json: option<string>,
}
record health-snapshot {
status: string, // "ready" | "degraded"
message: string, // human-readable
storage-ok: bool,
index-ok: bool,
disk-used-bytes: u64,
disk-free-bytes: u64,
disk-total-bytes: u64,
disk-used-percent: f32,
disk-pressure: string, // "unknown" | "ok" | "warn" | "degraded"
sync-lag-ms: u64,
quarantine-count: u64,
}
enum atom-kind {
observation,
reflection,
plan,
action,
message,
}
type timestamp = string;
type importance = f32;
record atom {
id: atom-id,
world-key: world-key,
worker: worker-key,
kind: atom-kind,
timestamp: timestamp,
importance: importance,
payload-json: string,
vector: option<list<f32>>,
flags-list: list<string>,
labels: list<string>,
links: list<atom-id>,
}
record atom-filter {
world-key: option<world-key>,
kinds: list<atom-kind>,
labels: list<string>,
flag-filter: list<string>,
since: option<timestamp>,
until: option<timestamp>,
limit: option<u32>,
}
record new-atom {
world-key: world-key,
worker: worker-key,
kind: atom-kind,
timestamp: timestamp,
importance: importance,
payload-json: string,
vector: option<list<f32>>,
flags-list: list<string>,
labels: list<string>,
links: list<atom-id>,
}
record question {
world-key: world-key,
text: string,
filter: option<atom-filter>,
}
record answer {
world-key: world-key,
text: string,
supporting-atoms: list<atom>,
}
record answer-v2 {
world-key: world-key,
text: string,
supporting-atoms: list<atom>,
warnings: list<string>,
}
record observe-stats-snapshot {
handle: observe-handle,
queued-count: u64,
dropped-count: u64,
last-event-ms: u64,
warnings: list<string>,
}
record metric-label {
key: string,
value: string,
}
record metric-point {
name: string,
labels: list<metric-label>,
value: f64,
}
record histogram-bucket {
le: f64,
count: f64,
}
record histogram-metric {
name: string,
labels: list<metric-label>,
buckets: list<histogram-bucket>,
sum: f64,
count: f64,
}
record metrics-snapshot-data {
format: string,
prometheus: string,
counters: list<metric-point>,
gauges: list<metric-point>,
histograms: list<histogram-metric>,
}
remember: func(atom: new-atom) -> atom-id;
ask: func(question: question) -> answer;
observe: func(atom: atom);
replay: func(target-world: world-key, filter: atom-filter) -> list<atom>;
/// Start an observe stream for a given filter. For safety and performance, callers should provide `world-key` in the filter.
observe-start: func(filter: atom-filter) -> observe-handle;
/// Poll up to `max` atoms from the stream.
observe-poll: func(handle: observe-handle, max: u32) -> list<atom>;
/// Stop and release an observe stream handle.
observe-stop: func(handle: observe-handle);
/// Inspect per-handle observe statistics (best-effort; non-throwing).
observe-stats: func(handle: observe-handle) -> observe-stats-snapshot;
/// Health snapshot for operators/hosts.
health: func() -> health-snapshot;
/// V2 ops: structured errors and warnings (preferred for flows).
remember-v2: func(atom: new-atom) -> result<atom-id, tool-error>;
ask-v2: func(question: question) -> result<answer-v2, tool-error>;
observe-start-v2: func(filter: atom-filter) -> result<observe-handle, tool-error>;
observe-poll-v2: func(handle: observe-handle, max: u32) -> result<list<atom>, tool-error>;
observe-stop-v2: func(handle: observe-handle) -> result<bool, tool-error>;
observe-stats-v2: func(handle: observe-handle) -> result<observe-stats-snapshot, tool-error>;
health-v2: func() -> result<health-snapshot, tool-error>;
metrics-snapshot: func() -> result<metrics-snapshot-data, tool-error>;
}
world core {
export engine;
}