Manthan Runtime Demo (Phase 2)

Phase 2 deliverable per the Manthan platform tracker §8: a long-running node composed from existing HERALD services and libraries, using scoped session signatures and a durable local ledger.

What this demonstrates

Two long-running Manthan agents (Alice and Bob) running in one Node process:

1. Each agent has a persistent SQLite ledger (per G-010 schema; WAL mode, idempotent state machine).
2. Each agent issues a session-key grant under tool_sandbox scope at startup (per G-002 — not an ephemeral molt).
3. Alice sends Bob a periodic ping (one envelope every 5 seconds).
4. Bob replies with a typed handoff_receipt per G-007.
5. Both agents persist all envelopes through the ledger state machine (seen → verified).
6. The runtime exits cleanly after 25 seconds (or stays alive with MANTHAN_RUN_FOREVER=1).
7. Re-running the demo against the same data/ directory resumes from prior state (the ledger holds it; this proves G-010 §4 crash-recovery contract works).

This is the wedge between "MVP one-shot demo" (Phase 1) and "real always-on agent" (Phase 4).

Run

cd demo/manthan-runtime
node --experimental-strip-types src/runtime.ts

By default the demo reuses data/ so restart behavior is observable. To start from a clean ledger:

MANTHAN_RESET_DATA=1 node --experimental-strip-types src/runtime.ts

To write demo ledgers outside the repo:

MANTHAN_DATA_DIR=/tmp/manthan-runtime node --experimental-strip-types src/runtime.ts

Output:

=== Manthan Runtime Demo (Phase 2) ===
Alice  sigil:...
Bob    sigil:...

[grant] Alice session pubkey: ...
[grant] Bob   session pubkey: ...

[tick   1] Alice→Bob ping id=...  Bob→Alice ack id=...
[tick   2] ...
...

=== ledger state ===
Alice  seen:5 verified:6 queued_for_ct:0 submitted:0 inclusion_proven:0 gossiped:0 quarantined:0
Bob    seen:5 verified:6 queued_for_ct:0 submitted:0 inclusion_proven:0 gossiped:0 quarantined:0

The "verified:6" includes 5 outbound envelopes (pings or acks) plus 1 session_key_grant.

Compose with the trace bundler

After running the demo, dump a trace bundle from Alice's ledger:

LEAF=$(node --experimental-strip-types -e '
  import("./lib/manthan-ledger/src/ledger.ts").then(({ ManthanLedger }) => {
    const l = new ManthanLedger({ path: "demo/manthan-runtime/data/alice.sqlite" });
    console.log(l.byState("verified", 100).pop()?.id);
    l.close();
  });
')
node --experimental-strip-types tools/trace-bundler.ts \
  --from-ledger demo/manthan-runtime/data/alice.sqlite "$LEAF" \
  --out /tmp/manthan-trace.json

The output bundle is consumed by herald verify (extending the Phase-1 verifier).

What this is and isn't

This is:

A composition of existing HERALD libraries (no reinvention; per G-004 §5).
A proof that the same protocol that powers the MVP wedge (Phase 1) also powers a long-running runtime.
A working substrate for Phase 3 (controlled gossip test).

This is NOT:

A P2P network — agents talk directly via in-process method calls. P2P is Phase 3 with MWP per G-005 + R-215 per G-006.
A reference Herald — that's services/reference-herald/. The demo could pair with it via heraldUrl: "local-service"; that's a Phase 2.5 integration.
A churn engine emitting research_findings — that's Phase 2+ once lib/manthan-injector/ (G-009) lands.
Patina-aware — the ledger persists envelopes; Patina is computed elsewhere (per G-003 reference Herald /patina/:sigil).

Phase 2 deliverables — checklist

[x] Agent SDK at lib/manthan-agent-ts/ — 7/7 tests pass.
[x] Session-key library at lib/herald-core-ts/src/session-keys.ts — 6/6 tests pass.
[x] SQLite local ledger at lib/manthan-ledger/ — 8/8 tests pass.
[x] Trace bundler at tools/trace-bundler.ts — verified against runtime data.
[x] Long-running runtime demo at demo/manthan-runtime/ — runs end-to-end, 5+ tick cycles.

What unlocks next

Phase 3 (Controlled Gossip Test): the runtime now has long-running agents with durable state, and lib/manthan-mwp/ provides the first tested WebSocket handshake/session layer. The remaining Phase 3 work is wiring 2-3 runtime nodes together with bounded peer exchange and envelope gossip.
Phase 2.5 (Reference-Herald integration): wire the runtime's agents to a real services/reference-herald/ instance via the heraldUrl option already present in the SDK.
Phase 2.6 (Churn engine): plug in lib/manthan-injector/ (G-009) to drive research_finding emission instead of demo pings.

Cross-references

manthan-platform/gates/G-002-key-custody.md — session-key design
manthan-platform/gates/G-004-compose-services.md — composition strategy
manthan-platform/gates/G-007-typed-artifacts.md — handoff_receipt schema
manthan-platform/gates/G-010-storage-ct-recovery.md — ledger schema and state machine
lib/manthan-agent-ts/ — the SDK this demo uses
lib/manthan-ledger/ — the ledger this demo uses
lib/herald-core-ts/src/session-keys.ts — session-key primitives

Manthan Runtime Demo (Phase 2)