@totemsdk/omnia-host 0.10.0 → 0.12.0

package/dist/observe/bus.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ObservationBus = void 0;
+/**
+ * In-process live fan-out for SSE consumers. The durable journal remains the
+ * source of truth: a subscriber that misses a live event still replays it from
+ * `ObservationStore.readSince(cursor)`.
+ */
+class ObservationBus {
+    listeners = new Set();
+    subscribe(listener) {
+        this.listeners.add(listener);
+        return () => this.listeners.delete(listener);
+    }
+    publish(observation) {
+        for (const listener of this.listeners) {
+            try {
+                listener(observation);
+            }
+            catch {
+                // A broken consumer must never break the mutation path.
+            }
+        }
+    }
+    get size() {
+        return this.listeners.size;
+    }
+}
+exports.ObservationBus = ObservationBus;

package/dist/observe/emitter.d.ts

@@ -0,0 +1,61 @@
+import type { OmniaChannel } from "@totemsdk/omnia";
+import type { ObservationBus } from "./bus.js";
+import type { ObservationDomain, ObservationEntity, ObservationPhase, ObservationRecord, ObservationStore, OmniaObservation } from "./types.js";
+export interface ObservationEmitterConfig {
+    store: ObservationStore;
+    bus: ObservationBus;
+    networkId: string;
+    sourceNodeId: string;
+    streamId?: string;
+    /** Mark events from fixture/simulated hosts. */
+    simulated?: boolean;
+    /** Called on emission failures (defaults to console.error). */
+    onError?: (error: unknown) => void;
+}
+export interface EmitObservationInput {
+    domain: ObservationDomain;
+    kind: string;
+    phase: ObservationPhase;
+    entity: ObservationEntity;
+    occurredAt?: number;
+    operationId?: string;
+    causationId?: string;
+    transitionHash?: string;
+    parties?: {
+        local?: string;
+        remote?: string;
+    };
+    token?: {
+        tokenId: string;
+        scale: number;
+    };
+    before?: Record<string, unknown>;
+    after?: Record<string, unknown>;
+    amounts?: ObservationRecord["amounts"];
+    chain?: ObservationRecord["chain"];
+    evidence?: ObservationRecord["evidence"];
+    simulated?: boolean;
+    data?: Record<string, unknown>;
+}
+/** Stable hash for transition identity (never includes secrets). */
+export declare function hashTransition(parts: Array<string | number | undefined | null>): string;
+/** Hash a channel's signed commitment for cross-node correlation. */
+export declare function channelTransitionHash(channel: OmniaChannel): string;
+export declare function hashString(value: string): string;
+/**
+ * Builds, redacts and persists observation events, then fans them out live.
+ *
+ * `emit()` never throws into a mutation: persistence/export failures are
+ * reported out-of-band so a payment can never be blocked by the observer.
+ */
+export declare class ObservationEmitter {
+    private readonly store;
+    private readonly bus;
+    private readonly networkId;
+    private readonly sourceNodeId;
+    private readonly streamId;
+    private readonly simulated;
+    private readonly onError;
+    constructor(config: ObservationEmitterConfig);
+    emit(input: EmitObservationInput): Promise<OmniaObservation | undefined>;
+}

package/dist/observe/emitter.js

@@ -0,0 +1,133 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ObservationEmitter = void 0;
+exports.hashTransition = hashTransition;
+exports.channelTransitionHash = channelTransitionHash;
+exports.hashString = hashString;
+const node_crypto_1 = require("node:crypto");
+const SECRET_KEY = /^(seed|seedphrase|mnemonic|privatekey|secretkey|preimage|witness|witnesshex|fundingwitness|keyfile|passphrase|password|token|signature)$/i;
+const MAX_STRING = 512;
+const MAX_ARRAY = 32;
+/** Stable hash for transition identity (never includes secrets). */
+function hashTransition(parts) {
+    const hash = (0, node_crypto_1.createHash)("sha256");
+    for (const part of parts)
+        hash.update(String(part ?? ""), "utf8").update("\u0000");
+    return "sha256:" + hash.digest("hex");
+}
+/** Hash a channel's signed commitment for cross-node correlation. */
+function channelTransitionHash(channel) {
+    const state = channel.latestState;
+    return hashTransition([
+        "channel",
+        channel.channelId,
+        channel.fundingCoinId,
+        channel.currentSequence,
+        state?.sequence,
+        state?.transactionHex ? hashString(state.transactionHex) : undefined,
+    ]);
+}
+function hashString(value) {
+    return (0, node_crypto_1.createHash)("sha256").update(value, "utf8").digest("hex");
+}
+function redact(value, depth = 0) {
+    if (value === null || value === undefined)
+        return value;
+    if (typeof value === "bigint")
+        return value.toString();
+    if (typeof value === "number" || typeof value === "boolean")
+        return value;
+    if (typeof value === "string") {
+        if (value.length <= MAX_STRING)
+            return value;
+        return `${value.slice(0, MAX_STRING)}…[sha256:${hashString(value).slice(0, 16)}]`;
+    }
+    if (Buffer.isBuffer(value) || value instanceof Uint8Array) {
+        return { bytes: value.length, sha256: hashString(Buffer.from(value).toString("hex")).slice(0, 16) };
+    }
+    if (depth > 4)
+        return "[depth-limit]";
+    if (Array.isArray(value)) {
+        const head = value.slice(0, MAX_ARRAY).map((v) => redact(v, depth + 1));
+        return value.length > MAX_ARRAY ? [...head, `[${value.length - MAX_ARRAY} more]`] : head;
+    }
+    if (typeof value === "object") {
+        const out = {};
+        for (const [key, nested] of Object.entries(value)) {
+            if (SECRET_KEY.test(key)) {
+                out[key] = "[redacted]";
+                continue;
+            }
+            out[key] = redact(nested, depth + 1);
+        }
+        return out;
+    }
+    return String(value);
+}
+/**
+ * Builds, redacts and persists observation events, then fans them out live.
+ *
+ * `emit()` never throws into a mutation: persistence/export failures are
+ * reported out-of-band so a payment can never be blocked by the observer.
+ */
+class ObservationEmitter {
+    store;
+    bus;
+    networkId;
+    sourceNodeId;
+    streamId;
+    simulated;
+    onError;
+    constructor(config) {
+        this.store = config.store;
+        this.bus = config.bus;
+        this.networkId = config.networkId;
+        this.sourceNodeId = config.sourceNodeId;
+        this.streamId = config.streamId ?? `${config.sourceNodeId}:${config.networkId}`;
+        this.simulated = config.simulated ?? false;
+        this.onError = config.onError ?? ((err) => console.error("[omnia-observe] emit failed:", err));
+    }
+    async emit(input) {
+        const now = Date.now();
+        const record = {
+            schemaVersion: 1,
+            networkId: this.networkId,
+            sourceNodeId: this.sourceNodeId,
+            streamId: this.streamId,
+            eventId: (0, node_crypto_1.randomUUID)(),
+            recordedAt: now,
+            occurredAt: input.occurredAt ?? now,
+            domain: input.domain,
+            kind: input.kind,
+            phase: input.phase,
+            ...(input.transitionHash ? { transitionHash: input.transitionHash } : {}),
+            ...(input.operationId ? { operationId: input.operationId } : {}),
+            ...(input.causationId ? { causationId: input.causationId } : {}),
+            entity: input.entity,
+            ...(input.parties ? { parties: input.parties } : {}),
+            ...(input.token ? { token: input.token } : {}),
+            ...(input.before ? { before: redact(input.before) } : {}),
+            ...(input.after ? { after: redact(input.after) } : {}),
+            ...(input.amounts ? { amounts: input.amounts } : {}),
+            ...(input.chain ? { chain: input.chain } : {}),
+            ...(input.evidence ? { evidence: input.evidence } : {}),
+            simulated: input.simulated ?? this.simulated,
+            ...(input.data ? { data: redact(input.data) } : {}),
+        };
+        try {
+            const { seq, createdAt } = await this.store.append(record);
+            const observation = {
+                ...record,
+                sourceSequence: seq,
+                recordedAt: createdAt,
+            };
+            this.bus.publish(observation);
+            return observation;
+        }
+        catch (error) {
+            this.onError(error);
+            return undefined;
+        }
+    }
+}
+exports.ObservationEmitter = ObservationEmitter;

package/dist/observe/index.d.ts

@@ -0,0 +1,5 @@
+export * from './types.js';
+export * from './bus.js';
+export * from './emitter.js';
+export * from './store.js';
+export * from './snapshot.js';

package/dist/observe/index.js

@@ -0,0 +1,21 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./types.js"), exports);
+__exportStar(require("./bus.js"), exports);
+__exportStar(require("./emitter.js"), exports);
+__exportStar(require("./store.js"), exports);
+__exportStar(require("./snapshot.js"), exports);

package/dist/observe/snapshot.d.ts

@@ -0,0 +1,38 @@
+import type { OmniaChannel } from "@totemsdk/omnia";
+import type { ChannelFactory } from "@totemsdk/omnia-factory";
+export interface ObservationSnapshotInput {
+    networkId: string;
+    sourceNodeId: string;
+    streamId: string;
+    cursor: number;
+    channels?: Iterable<OmniaChannel>;
+    factories?: Iterable<ChannelFactory>;
+    vtxoPools?: Iterable<unknown>;
+    vtxos?: Iterable<unknown>;
+    pools?: Iterable<unknown>;
+    operations?: {
+        listByStatus?: (status: string) => unknown[];
+    };
+}
+/**
+ * Snapshot the host's current state at a single journal boundary. The cursor is
+ * the journal head, so `GET /observe/events?after=<cursor>` has no gap or
+ * duplication relative to this snapshot.
+ */
+export interface ObservationSnapshotState {
+    channels: unknown[];
+    factories: unknown[];
+    vtxoPools: unknown[];
+    vtxos: unknown[];
+    pools: unknown[];
+    operations: unknown[];
+}
+export interface ObservationSnapshot {
+    networkId: string;
+    sourceNodeId: string;
+    streamId: string;
+    cursor: number;
+    generatedAt: number;
+    state: ObservationSnapshotState;
+}
+export declare function createObservationSnapshot(input: ObservationSnapshotInput): ObservationSnapshot;

package/dist/observe/snapshot.js

@@ -0,0 +1,101 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createObservationSnapshot = createObservationSnapshot;
+function toJson(value, depth = 0) {
+    if (value === null || value === undefined)
+        return value;
+    if (typeof value === "bigint")
+        return value.toString();
+    if (typeof value === "number" || typeof value === "boolean" || typeof value === "string")
+        return value;
+    if (Buffer.isBuffer(value) || value instanceof Uint8Array) {
+        return { bytes: value.length };
+    }
+    if (depth > 4)
+        return "[depth-limit]";
+    if (Array.isArray(value))
+        return value.map((v) => toJson(v, depth + 1));
+    if (value instanceof Map) {
+        return Object.fromEntries(Array.from(value.entries()).map(([k, v]) => [String(k), toJson(v, depth + 1)]));
+    }
+    if (typeof value === "object") {
+        const out = {};
+        for (const [key, nested] of Object.entries(value)) {
+            if (/seed|privatekey|secretkey|preimage|witness|signature/i.test(key))
+                continue;
+            out[key] = toJson(nested, depth + 1);
+        }
+        return out;
+    }
+    return String(value);
+}
+function channelView(channel) {
+    return {
+        channelId: channel.channelId,
+        status: channel.status,
+        channelType: channel.channelType,
+        tokenId: channel.tokenId,
+        tokenScale: channel.tokenScale ?? 0,
+        totalValue: channel.totalValue.toString(),
+        currentSequence: channel.currentSequence,
+        fundingCoinId: channel.fundingCoinId,
+        fundingTxId: channel.fundingTxId,
+        parties: channel.parties,
+        balances: Object.fromEntries(Object.entries(channel.balances).map(([k, v]) => [k, v.toString()])),
+        pendingHTLCs: (channel.pendingHTLCs ?? []).map((h) => toJson(h)),
+        updatedAt: channel.updatedAt,
+    };
+}
+function factoryView(factory) {
+    const f = factory;
+    const allocations = (f.allocations ?? {});
+    return {
+        factoryId: f.factoryId,
+        status: f.status,
+        tokenId: f.tokenId,
+        tokenScale: f.tokenScale ?? 0,
+        participants: f.participants,
+        allocations: Object.fromEntries(Object.entries(allocations).map(([k, v]) => [k, v.toString()])),
+        updatedAt: f.updatedAt,
+    };
+}
+function operationsView(operations) {
+    if (!operations?.listByStatus)
+        return [];
+    const statuses = ["pending", "executing", "committed", "failed"];
+    const seen = new Set();
+    const out = [];
+    for (const status of statuses) {
+        for (const record of operations.listByStatus(status) ?? []) {
+            const r = record;
+            if (r.operationId && seen.has(r.operationId))
+                continue;
+            if (r.operationId)
+                seen.add(r.operationId);
+            out.push({
+                operationId: r.operationId,
+                status: record.status ?? status,
+                updatedAt: record.updatedAt,
+                error: record.error,
+            });
+        }
+    }
+    return out;
+}
+function createObservationSnapshot(input) {
+    return {
+        networkId: input.networkId,
+        sourceNodeId: input.sourceNodeId,
+        streamId: input.streamId,
+        cursor: input.cursor,
+        generatedAt: Date.now(),
+        state: {
+            channels: Array.from(input.channels ?? []).map(channelView),
+            factories: Array.from(input.factories ?? []).map(factoryView),
+            vtxoPools: Array.from(input.vtxoPools ?? []).map((v) => toJson(v)),
+            vtxos: Array.from(input.vtxos ?? []).map((v) => toJson(v)),
+            pools: Array.from(input.pools ?? []).map((v) => toJson(v)),
+            operations: operationsView(input.operations),
+        },
+    };
+}

package/dist/observe/store.d.ts

@@ -0,0 +1,31 @@
+import type { ObservationStore, OmniaObservation } from "./types.js";
+export interface SqliteObservationStoreOptions {
+    namespace?: string;
+    /** WAL is on by default in SqliteStore; exposed for completeness. */
+    wal?: boolean;
+}
+/**
+ * Durable observation journal backed by `@totemsdk/storage` (RFC-007).
+ *
+ * Deliberately **not** a direct `better-sqlite3`/DuckDB write: omnia-host
+ * persists through the storage SDK so the same adapter can be swapped
+ * (file/idb/memory) and the journal gets CAS head sequencing, crash-recovery and
+ * forward-migratable records for free.
+ */
+export declare function createSqliteObservationStore(dbPath: string, options?: SqliteObservationStoreOptions): Promise<ObservationStore>;
+/** In-memory journal for tests/embedding (volatile acknowledgment). */
+export declare function createMemoryObservationStore(options?: {
+    namespace?: string;
+}): Promise<ObservationStore>;
+/** No-op store for read-only/embedded deployments that opt out of observation. */
+export declare class DisabledObservationStore implements ObservationStore {
+    append(): Promise<{
+        seq: number;
+        createdAt: number;
+    }>;
+    readSince(): Promise<OmniaObservation[]>;
+    tail(): Promise<OmniaObservation[]>;
+    head(): Promise<number>;
+    count(): Promise<number>;
+    close(): Promise<void>;
+}

package/dist/observe/store.js

@@ -0,0 +1,82 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DisabledObservationStore = void 0;
+exports.createSqliteObservationStore = createSqliteObservationStore;
+exports.createMemoryObservationStore = createMemoryObservationStore;
+const journal_1 = require("@totemsdk/storage/journal");
+const memory_1 = require("@totemsdk/storage/memory");
+const sqlite_1 = require("@totemsdk/storage/sqlite");
+const DEFAULT_NAMESPACE = "omnia:observe:v1:";
+function materialize(seq, record) {
+    return { ...record, sourceSequence: seq };
+}
+function makeStore(journal, closeAdapter) {
+    return {
+        async append(record) {
+            const entry = await journal.append(record);
+            return { seq: entry.seq, createdAt: entry.createdAt };
+        },
+        async readSince(seq) {
+            const entries = await journal.readSince(Math.max(0, Math.floor(seq)));
+            return entries.map((e) => materialize(e.seq, e.record));
+        },
+        async tail(count) {
+            const entries = await journal.tail(Math.max(0, Math.floor(count)));
+            return entries.map((e) => materialize(e.seq, e.record));
+        },
+        head: () => journal.getHead(),
+        count: () => journal.count(),
+        close: closeAdapter,
+    };
+}
+/**
+ * Durable observation journal backed by `@totemsdk/storage` (RFC-007).
+ *
+ * Deliberately **not** a direct `better-sqlite3`/DuckDB write: omnia-host
+ * persists through the storage SDK so the same adapter can be swapped
+ * (file/idb/memory) and the journal gets CAS head sequencing, crash-recovery and
+ * forward-migratable records for free.
+ */
+async function createSqliteObservationStore(dbPath, options = {}) {
+    const adapter = new sqlite_1.SqliteStore(dbPath, { wal: options.wal ?? true });
+    const journal = (0, journal_1.createJournal)(adapter, {
+        namespace: options.namespace ?? DEFAULT_NAMESPACE,
+        requireAckMode: "durably-acknowledged",
+    });
+    await journal.recover();
+    return makeStore(journal, async () => {
+        await adapter.close?.();
+    });
+}
+/** In-memory journal for tests/embedding (volatile acknowledgment). */
+async function createMemoryObservationStore(options = {}) {
+    const adapter = new memory_1.MemoryStore();
+    const journal = (0, journal_1.createJournal)(adapter, {
+        namespace: options.namespace ?? DEFAULT_NAMESPACE,
+        requireAckMode: "volatile",
+    });
+    await journal.recover();
+    return makeStore(journal, async () => {
+        await adapter.close?.();
+    });
+}
+/** No-op store for read-only/embedded deployments that opt out of observation. */
+class DisabledObservationStore {
+    async append() {
+        return { seq: 0, createdAt: Date.now() };
+    }
+    async readSince() {
+        return [];
+    }
+    async tail() {
+        return [];
+    }
+    async head() {
+        return 0;
+    }
+    async count() {
+        return 0;
+    }
+    async close() { }
+}
+exports.DisabledObservationStore = DisabledObservationStore;

package/dist/observe/types.d.ts

@@ -0,0 +1,106 @@
+/**
+ * Omnia observation events (RFC-0011 Amendment A / RFC-048).
+ *
+ * One event is a durable, replayable record of a single domain transition. It is
+ * intentionally richer than `AnalyticsEvent`: it carries identity, correlation,
+ * exact values, chain/evidence refs and a compact before/after diff so a
+ * consumer (the canary observer, an explorer, an agent) can reconstruct state
+ * without guessing or polling.
+ *
+ * Money is always an exact string (atoms). Signatures/seeds/preimages are never
+ * emitted — only hashes/indices.
+ */
+export type ObservationDomain = "node" | "channel" | "funding" | "payment" | "settlement" | "factory" | "vtxo" | "pool" | "splice" | "transport" | "operation" | "command";
+export type ObservationPhase = "observed" | "proposed" | "accepted" | "prepared" | "executing" | "committed" | "broadcast" | "confirmed" | "closed" | "failed" | "recovered";
+export type ObservationEntityType = "node" | "channel" | "factory" | "virtual-channel" | "vtxo-pool" | "vtxo" | "pool" | "splice" | "payment" | "operation" | "command";
+export interface ObservationEntity {
+    type: ObservationEntityType;
+    id: string;
+    /** Funding generation for channels/factories; increments on splice/reopen. */
+    generation?: number;
+}
+export interface OmniaObservation {
+    schemaVersion: 1;
+    networkId: string;
+    sourceNodeId: string;
+    streamId: string;
+    /** Journal-assigned 1-based sequence (the resumable cursor). */
+    sourceSequence: number;
+    eventId: string;
+    recordedAt: number;
+    occurredAt: number;
+    domain: ObservationDomain;
+    kind: string;
+    phase: ObservationPhase;
+    /** Protocol-level identity of the underlying signed transition, if known. */
+    transitionHash?: string;
+    /** Caller-known operation correlation (propagated where peer messages allow). */
+    operationId?: string;
+    /** The command/message that caused this transition. */
+    causationId?: string;
+    entity: ObservationEntity;
+    parties?: {
+        local?: string;
+        remote?: string;
+    };
+    token?: {
+        tokenId: string;
+        scale: number;
+    };
+    before?: Record<string, unknown>;
+    after?: Record<string, unknown>;
+    amounts?: {
+        amountAtoms?: string;
+        capacity?: string;
+        fee?: string;
+        balances?: Record<string, string>;
+    };
+    chain?: {
+        fundingCoinId?: string;
+        txpowId?: string;
+        blockHeight?: number;
+        confirmations?: number;
+        txDigest?: string;
+    };
+    evidence?: {
+        stateDigest?: string;
+        signatureHashes?: string[];
+        leaseIndices?: number[];
+        peerPublicKeyDigest?: string;
+        proofRefs?: string[];
+        manifestId?: string;
+    };
+    /** True when the transition was simulated/fixture-backed. */
+    simulated: boolean;
+    /** Free-form, already-redacted extras. */
+    data?: Record<string, unknown>;
+}
+/** A record before the journal assigns its sequence. */
+export type ObservationRecord = Omit<OmniaObservation, "sourceSequence">;
+export interface ObserveSnapshot {
+    networkId: string;
+    sourceNodeId: string;
+    streamId: string;
+    /** Journal head at snapshot time — pair with `GET /observe/events?after=`. */
+    cursor: number;
+    generatedAt: number;
+    state: {
+        channels: unknown[];
+        factories: unknown[];
+        vtxoPools: unknown[];
+        vtxos: unknown[];
+        pools: unknown[];
+        operations: unknown[];
+    };
+}
+export interface ObservationStore {
+    append(record: ObservationRecord): Promise<{
+        seq: number;
+        createdAt: number;
+    }>;
+    readSince(seq: number): Promise<OmniaObservation[]>;
+    tail(count: number): Promise<OmniaObservation[]>;
+    head(): Promise<number>;
+    count(): Promise<number>;
+    close(): Promise<void>;
+}

package/dist/observe/types.js

@@ -0,0 +1,14 @@
+"use strict";
+/**
+ * Omnia observation events (RFC-0011 Amendment A / RFC-048).
+ *
+ * One event is a durable, replayable record of a single domain transition. It is
+ * intentionally richer than `AnalyticsEvent`: it carries identity, correlation,
+ * exact values, chain/evidence refs and a compact before/after diff so a
+ * consumer (the canary observer, an explorer, an agent) can reconstruct state
+ * without guessing or polling.
+ *
+ * Money is always an exact string (atoms). Signatures/seeds/preimages are never
+ * emitted — only hashes/indices.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });