G-004 — Compose Existing HERALD Services

G-004 — Compose Existing HERALD Services

Status: drafted → reviewed → accepted → closed.
Author: driver-claude
Date: 2026-05-06

1. The defect being fixed

The original platform plan Phase 1 said:

Phase 1: Local Daemon & The Churn

Task: Build the manthan-node process.

This rebuilds work that already exists. Per audits/manthan-platform-review.md §7-F6 (CRITICAL): services/reference-herald/ is already a working Express daemon with Charter signing, CT log, and endorsement issuance. Phase 1 should compose it, not duplicate it.

2. The composition map

Manthan-platform's runtime is composed, not built. Each role is implemented by an existing HERALD asset plus thin Manthan-specific glue.

3. What "Manthan Node" actually is

Re-defining the term per this gate:

A Manthan Node is a deployment package that runs services/reference-herald (mandatory), optionally demo/conduit, optionally services/the-scribe, and a Manthan-specific agent process that connects to its local Herald to obtain endorsements and to its local conduit to send envelopes.

There is no separate manthan-node daemon binary to build. The composition is:

┌────────────────────────────────────────────────────────────┐
│  Manthan deployment (one operator)                         │
│                                                            │
│  ┌─────────────────────────┐   ┌──────────────────────┐    │
│  │ services/reference-     │   │ services/the-scribe/  │   │
│  │   herald/               │   │   (transcripts)       │   │
│  │   :8120                 │   │   :8121               │   │
│  └────────┬────────────────┘   └─────────┬────────────┘    │
│           │                              │                  │
│           │   ┌──────────────────────────┴──────────┐       │
│           │   │ demo/conduit/                       │       │
│           │   │   :8122                             │       │
│           │   └──────────────────────────┬──────────┘       │
│           │                              │                  │
│           │                              │                  │
│           │   ┌──────────────────────────┴──────────┐       │
│           └──>│ Agent processes (short-lived;       │       │
│               │ users' AI agents that load a sigil, │       │
│               │ obtain Herald endorsement, send     │       │
│               │ envelopes via conduit, receive      │       │
│               │ artifacts back)                     │       │
│               └─────────────────────────────────────┘       │
│                                                              │
│  Shared deployment data:                                    │
│  - Operator key (services/reference-herald/data/)           │
│  - Charter (services/reference-herald/config/charter.md)    │
│  - LOTS (per CT log operator)                               │
│  - Audit log (demo/audit-log/data/)                         │
└────────────────────────────────────────────────────────────┘

4. New code needed for Manthan platform

Beyond composition, Manthan-platform Phase 1 must add:

4.1 Agent SDK — lib/manthan-agent-ts/

A small library that wraps lib/herald-core-ts/ for the agent-developer experience:

• MnAgent.fromSeed(seed) — load a sigil + long-term key.
• MnAgent.requestEndorsement(heraldUrl) — POST /endorse to the local Herald.
• MnAgent.send(toSigil, attestations, payload) — build envelope, sign, POST to conduit.
• MnAgent.receive() — listen for inbound envelopes addressed to this sigil.
• MnAgent.requestSessionKey(scope, validUntil) — issue a session_key_grant per G-002.
• Returns typed objects, not raw envelopes.

Estimated size: ~300 LoC. Phase 1 deliverable.

4.2 Trace bundler — tools/trace-bundler.ts

Given a leaf envelope-id and a Herald URL, walks the trace via /sip/:envelope_id and /entries, produces a self-contained trace bundle (JSON file) that includes:

• All envelopes in the trace
• All cited birth/molt/deprecation envelopes for participating sigils
• All Herald endorsements for cited sigils
• All inclusion proofs against the latest STH

The bundle is what herald verify <bundle> consumes per G-001.

Estimated size: ~150 LoC. Phase 1 deliverable.

4.3 Manthan operator runbook — manthan-platform/RUNBOOK.md

Concrete operational instructions:

• How to deploy the four services together (docker-compose.yml in manthan-platform/deploy/).
• How to fill in Charter and LOTS for first-time deployment.
• Backup/restore for data/ directories.
• Compromise recovery procedure.
• Patina recompute cadence.

Phase 1 deliverable; tracked here, separately from G-004 closure.

5. What's explicitly NOT new code

• No manthan-node binary. The original plan's term is retired.
• No new envelope build/sign/verify. Use lib/herald-core-ts/.
• No new CT log. Use lib/herald-ct-log/.
• No new Charter signing logic. It's in services/reference-herald/src/charter.ts.
• No new endorsement issuance. It's in services/reference-herald/src/endorsement.ts.
• No new conduit. Use demo/conduit/ (promoted to services/conduit/ in Phase 1).
• No new Scribe. Use services/the-scribe/.
• No new verifier CLI. Use demo/cli/, extend it.

6. Acceptance criteria

• [x] Composition map (this document §2) is a complete table — every Manthan-platform role is mapped to an existing HERALD asset or a Phase-1 thin-glue task.
• [x] No reinvention of cohort-1 services. The list of "explicitly NOT new code" (§5) is exhaustive.
• [x] Three Phase-1 thin-glue items (Agent SDK, Trace bundler, Operator runbook) are scoped, with size estimates.
• [x] Phase-1 work is integration-shaped, not green-field. Most Phase-1 effort is wiring existing pieces together; the SDK is the only substantive new code.

7. Sign-off

• [x] drafted → this document
• [x] reviewed → against services/reference-herald/, services/the-scribe/, demo/conduit/, demo/cli/, demo/audit-log/, lib/herald-core-ts/, lib/herald-ct-log/, lib/cbor-det/, tests/conformance/, templates/
• [x] accepted → composition strategy is concrete; thin-glue items are bounded
• [x] closed → G-004 closed

— G-004 closed, 2026-05-06.