@metamynd/mmt-graph 0.2.0

package/README.md

@@ -0,0 +1,264 @@
+# @metamynd/mmt-graph — reference trust-graph engine
+
+The MMTO Phase 1/2 reference implementation: apply mutation events to a validated RDF
+graph, and batch the resulting changelog into a Merkle root ready to anchor. See
+[`docs/design/metamynd-trust-ontology.md`](../../docs/design/metamynd-trust-ontology.md)
+Appendix C for the full phased roadmap this package works through.
+
+**No Postgres reads/writes anywhere in this package, no MetaMynd backend required.** The
+MetaMynd-operated hosting mode wires this in as a best-effort, opt-in shadow-write
+(`backend/src/features/trust-graph/mmt-graph.adapter.ts`, gated by `MMT_GRAPH_ENABLED`,
+default off) — but that's one caller among many this package is designed to have, not a
+dependency of it. `npm test` makes no live Hedera calls either — the one exception is
+`mmt-graph.anchor-live-demo.mjs`, a manually-run, not-yet-executed script proving the
+anchor contract against real testnet infrastructure (see "Status" below).
+
+## Self-hosting quickstart (Phase 4)
+
+This package is designed to run identically whether MetaMynd operates it or you do — same
+engine, same event vocabulary, same anchor contract, no MetaMynd credentials or MetaMynd
+backend anywhere in the code path. That split was a Phase 1 design constraint, not a later
+retrofit: `mmt-graph.anchor.mjs` never imports `@hashgraph/sdk`, and nothing in this
+package imports a database driver.
+
+```bash
+npm install @metamynd/mmt-graph
+node node_modules/@metamynd/mmt-graph/mmt-graph.self-host-quickstart.mjs
+```
+
+That script runs the whole lifecycle end to end, offline, with zero setup: register your
+agents/principals/mandates, validate (SHACL + the §3 authority-chain invariant), query
+(it's a real SPARQL 1.1 graph, not a fixed set of report endpoints), batch the event log
+into a Merkle root, anchor it (a stub `submit` by default), and independently verify the
+result — the same replay-and-check the Phase 6 auditor runs for a third party, run here for
+yourself. Read the file; every step is commented with what a real deployment does
+differently.
+
+**To anchor for real**, replace the quickstart's stub `submit` with your own Hedera client
+— `mmt-graph.anchor-live-demo.mjs` is the complete, real worked example (topic creation,
+transaction signing, receipt handling) against your own operator account.
+`anchorBatch(batch, submit)` is the entire seam: `submit` takes the canonical batch-root
+message and returns `{transactionId, status}`; nothing else in the package needs to know
+Hedera exists. Point it at your own topic (a fresh one, or `MMT_GRAPH_TOPIC_ID` if you
+already have one) and your own testnet or mainnet account — this package has no opinion on
+which.
+
+**What self-hosting does NOT give you today**: a way to get your EXISTING historical
+`Policy`/`AgentIdentity`/`Principal` rows into the graph (no backfill mechanism exists in
+this package or the MetaMynd adapter — only new writes since you start applying events are
+ever recorded), and no durability layer of its own (Oxigraph's JS binding is in-memory
+only; your own event log — however you choose to persist it — is the real source of truth,
+and `replay()` is how you rebuild the graph from it on restart). Both are real gaps, not
+hidden ones; see Appendix C of the ontology doc for the intended direction.
+
+Once you have events flowing and a batch anchored, a third party (a regulator, an auditor,
+you) can verify your tenant's graph state with MetaMynd fully offline — see
+`mmt-graph.auditor.mjs`/`mmt-graph.auditor-cli.mjs` below.
+
+## Files, in the order the phases that produced them shipped
+
+- **`mmt-graph.spike.mjs`** (Phase 1 spike, PR #382) — the storage-engine decision record.
+  Proved Oxigraph (RDF/SPARQL, in-process WASM) + `rdf-validate-shacl` works before the
+  real engine was built. Kuzu was disqualified (archived October 2025 after Apple acquired
+  the company behind it); Apache AGE was viable but a Postgres C-extension distribution
+  burden with no SHACL; CozoDB was genuinely close (native persistence, time-travel
+  queries) but Datalog rather than RDF/SPARQL, and pre-1.0 with no storage-compatibility
+  promise. Oxigraph's JS binding is in-memory only — not disqualifying, because the
+  changelog below is the durable source of truth and the store is a materialized view
+  rebuilt from it, not a workaround.
+- **`mmt-graph.types.mjs`, `mmt-graph.project.mjs`, `mmt-graph.shapes.ttl`,
+  `mmt-graph.engine.mjs`** (Phase 1 engine, PR #383) — the real thing. `MmtGraphEngine`
+  applies `{op, ...}` mutation events (`agentRegistered`/`principalRegistered`/
+  `mandateGranted`/`mandateRevoked`, grounded 1:1 against real `Policy`/`AgentIdentity`/
+  `Principal` rows — see the doc's domains A/C), projects them to RDF quads, and
+  `validate()` runs the SHACL shapes plus a SPARQL `ASK` making the §3 authority-chain
+  invariant runnable for every agent with a mandate, root or delegated. `replay()` rebuilds
+  from the event log — the "materialized view from a durable log" story made real.
+- **`mmt-graph.merkle.mjs`, `mmt-graph.changelog.mjs`, `mmt-graph.anchor.mjs`** (Phase 2,
+  PR #384) — turns `MmtGraphEngine#log` into an anchor-ready Merkle batch, and defines
+  the anchor *contract*. `mmt-graph.anchor.mjs` never imports `@hashgraph/sdk` and makes no
+  network call: `anchorBatch(batch, submit)` takes an injected `submit(message) →
+  {transactionId, status}` function, so the actual Hedera client/credentials/topic
+  management stay the hosting operator's problem — a MetaMynd backend wiring in something
+  shaped like `backend/src/features/trust/trust.anchor.ts`, or a self-hosted tenant wiring
+  in their own. That split is what keeps this package identical across both hosting modes.
+  **Fixed post-Phase-5**: `mmt-graph.changelog.mjs`'s `EVENT_LEAF_FIELDS` — the explicit,
+  by-hand field list each event's Merkle leaf is built from — drifted out of sync as Phase
+  5's six slices added fields to existing ops and six wholly new ops, with nothing that
+  actually anchors those events to catch it. `agent-registered`.`principalDid`,
+  `principal-registered`'s verification/rep fields, and `mandate-granted`.`expiresAt` were
+  silently EXCLUDED from their own leaf hash (not a crash — worse: a batch could commit to
+  a leaf that omits a real field); the six new ops would have thrown out of `eventLeaf`
+  entirely. Caught while scoping Phase 6 (a public verifier can't honestly claim to check a
+  tenant's full event log while half the vocabulary is unhashable), fixed with a
+  completeness test that constructs one of every real event op and asserts `eventLeaf`
+  accepts it, plus a regression test proving each previously-dropped field now actually
+  changes the leaf.
+- **`mmt-graph.anchor-live-demo.mjs`** — a real, working `submit` wired
+  against **Hedera testnet**, using `@hashgraph/sdk` as a **devDependency** (never imported
+  by `mmt-graph.anchor.mjs` itself). **Written and offline-test-verified, not yet actually
+  run against testnet** — see "Status: pending first live run" below.
+- **`mmt-graph.evidence-path.mjs`** (Phase 5, first slice) — proves domain H (runtime
+  activity/evidence) can answer `evidence-path.ts`'s core question — "can a third party
+  verify this decision without us?" — as a graph query. New event types
+  (`decisionRecorded`/`evidenceRecorded`/`batchAnchored`) and their projectors, plus
+  `isIndependentlyVerifiable(engine, decisionId)`, which mirrors the real function's exact
+  precedence rule (a batch's anchor status wins over the evidence event's own status when
+  a batch exists — the `FILTER NOT EXISTS` in the SPARQL query is what enforces that,
+  tested explicitly). **Not wired to any live endpoint** — `MMT_GRAPH_ENABLED` is off by
+  default, and even on, nothing backfills historical decisions into the graph yet, so there's
+  no way today for this to answer for the population of existing decisions the way
+  `trust-graph.repository.ts`'s live Postgres queries do. `blast-radius`, `contagion` and
+  `accountability`, initially deferred pending an `Issuer` concept, verified SPARQL
+  aggregate support and a `Human`/person concept respectively, are each covered separately —
+  see `mmt-graph.contagion.mjs`, `mmt-graph.accountability.mjs` and
+  `mmt-graph.blast-radius.mjs` below.
+- **`mmt-graph.contagion.mjs`** (Phase 5, second and fourth slices) — proves domain F
+  (governance) can answer `contagion.ts`'s hard question: not "what does this agent share
+  with others" but "which shares are SPECIFIC enough to mean something," as a SPARQL
+  `COUNT`/`GROUP BY` aggregate query (confirmed Oxigraph supports this before building on
+  it). `isSpecific()` is ported verbatim from `contagion.ts` — same constants
+  (`BROAD_COHORT_MIN = 10`, `BROAD_COHORT_SHARE = 0.5`), same two-condition logic — and
+  tested against the real measured platform-standard case (`isSpecific(57, 92) === false`),
+  built as an actual 92-agent graph, not just the isolated function call. A nice
+  convergence with Phase 3's tenant-isolation fix (PR #387): the `tenantAgents`
+  denominator `isSpecific` needs no longer has to be passed in externally — each
+  `MmtGraphEngine` instance already IS one tenant's data, so counting `mmt:AIAgent` nodes
+  in it gives the right number for free. All four real cohort kinds are covered
+  (`sop`/`standard` from the second slice, `organization`/`unit` from the fourth) even
+  though the real algorithm computes them via two different code shapes — the aggregate
+  query doesn't need to know that, because `mmt:sharesCohort` is emitted uniformly for
+  all four. `organization`/`unit` additionally assert the real, already-speced Domain A
+  relationship `mmt:memberOf` (Agent → `mmt:Organization`/`mmt:AgentGroup`, both named in
+  the doc, neither implemented until now) — deliberately two predicates, not one, because
+  sharing a SOP and belonging to an organization are different kinds of fact and blurring
+  them for query convenience would undo a distinction the ontology already drew (tested
+  explicitly: `organization`/`unit` assert `mmt:memberOf`, `sop`/`standard` do not).
+- **`mmt-graph.accountability.mjs`** (Phase 5, fifth slice) — proves domain A (actors) can
+  answer `accountability.ts`'s core question, "who is ultimately answerable for this
+  decision?", for its load-bearing core: `decision -> agent -> organization -> human`, and
+  the four gap codes that determine `answerable` itself (`agent-unresolved`,
+  `no-organization`, `organization-unverified`, `no-authorized-representative`). Closes the
+  `mmt:Human` gap the first slice's investigation flagged — humans get a synthetic IRI (no
+  DID; the `User` table has none), reached via `mmt:operatedBy` (Organization → Human,
+  domain A's own relationship list, never implemented until now). `principalIsVerified` is
+  ported verbatim from `backend/src/features/principal/principal.verification.ts`, and the
+  tests use `accountability.test.ts`'s exact fixture values (`org-1`/`agent-1`/`user-rep`/
+  "Ada Rep"), including its lapsed-KYB case. Deliberately NOT attempted, the same kind of
+  scope split as `contagion`'s two slices: the operating-unit hop (`unit-org-mismatch`),
+  the delegation-root distinction (the mandate's authorising principal, when it differs
+  from the agent's home organisation), and human review/approval linkage
+  (`review-unlinked`) — real parts of `accountability.ts`'s full output shape, but
+  refinements on top of the answerable/not-answerable determination this slice targets.
+- **`mmt-graph.blast-radius.mjs`** (Phase 5, sixth and final slice) — answers
+  `blast-radius.ts`'s actual question, not the one originally posed. "Which agents hold
+  credentials from this issuer" cannot be walked at all — issued VCs are signed and
+  HCS-anchored but never persisted, per that file's own header — so it answers what the
+  real code was rewritten to answer instead: an issuer's tier derives from its backing
+  principal, so what depends on that principal, and which LIVE mandates would start getting
+  blocked with `PRINCIPAL_UNVERIFIED` if its verification lapsed (`blockedOnLapse` is a
+  hypothetical count, not gated on whether verification is currently in force — mirrored
+  exactly, not conflated with `mmt-graph.accountability.mjs`'s `principalIsVerified`).
+  `mmt:Issuer` is the one genuinely new class this package adds (the W3C VC Data Model's own
+  term, grounded in `issuer.model.ts`'s real `did`), plus a new `mmt:backedBy` (Issuer →
+  Organization, adopted from the real edge-kind name, same precedent as `mmt:decidedFor`).
+  Everything else reuses vocabulary already built: `mmt:memberOf` is exactly "agents whose
+  accountable organisation is this principal," and the previously-unimplemented
+  `mmt:grantsMandate` (named since Phase 0, Domain C) gives `authorizedByPrincipal` the
+  per-mandate precision `mmt:actsFor` alone can't (it lives on the agent node, not the
+  mandate). Tested against `blast-radius.test.ts`'s real fixture values
+  (`iss-1`/`p-1`/`Acme Holdings`). **All four Platform Governance §7 questions now have a
+  graph-query proof** — none wired to a live endpoint; see "Not in scope here" below for why.
+- **`mmt-graph.auditor.mjs`, `mmt-graph.auditor-cli.mjs`** (Phase 6) — the public
+  verification tooling: same zero-MetaMynd-server posture as
+  `integrations/magp-evidence`'s `auditor.mjs`/`magp-evidence.mjs` (node:crypto + fetch
+  only), extended for what a graph can disclose that a flat evidence leaf can't. Two
+  shapes: `{ event, proof, root }` mirrors `magp-evidence` exactly (reproduce the leaf,
+  verify the Merkle proof, optionally confirm on-chain anchoring against a public Hedera
+  mirror node); `{ events: [...], root }` REPLAYS a whole disclosed log through a fresh
+  `MmtGraphEngine` and checks the recomputed root against what was claimed AND that the
+  replayed graph itself validates — the same SHACL shapes and §3 authority-chain invariant
+  `validate()` runs internally, now run by a third party who never trusted MetaMynd to have
+  run it correctly the first time. CLI: `npm run auditor -- <disclosure.json> [--topic
+  0.0.x] [--network testnet|mainnet]`, same flags and VALID/INVALID verdict shape as
+  `magp-evidence`'s `auditor.mjs`. **Fixed post-Phase-5, before building this on top of
+  it**: `mmt-graph.changelog.mjs`'s `EVENT_LEAF_FIELDS` — the explicit field list each
+  event's Merkle leaf is built from — had drifted out of sync as Phase 5's six slices
+  extended event schemas. Three existing ops (`agent-registered`, `principal-registered`,
+  `mandate-granted`) had new fields silently EXCLUDED from their own leaf hash (not a
+  crash — worse, a batch could commit to a leaf that omits a real field); six new ops had
+  no field list at all and would have thrown out of `eventLeaf`. Caught with `impact()`
+  showing zero real callers (nothing anchors Phase 5's proof-only events yet), fixed with a
+  completeness test (one of every real event op, asserts `eventLeaf` accepts it) and a
+  regression test proving each previously-dropped field now actually changes the leaf.
+
+## Vocabulary note
+
+The spike originally used `mmt:actsFor` for Mandate→Agent. Domain A of the MMTO draft
+defines `mmt:actsFor` as Agent→Principal ("the Principal is the actor whose authority the
+agent exercises"), and the source proposal's own worked example uses a separate
+`mmt:grantedTo` for Mandate→Agent. Fixed in both the spike and the engine when the
+inconsistency was found while building Phase 1 — see `mmt-graph.project.mjs`'s header.
+
+## Status: pending first live run
+
+`mmt-graph.anchor-live-demo.mjs` is code-complete and reuses the same dev testnet
+credentials `backend/.env` already has configured (`HEDERA_OPERATOR_ID`/
+`HEDERA_OPERATOR_KEY`/`HEDERA_NETWORK=testnet` — the same ones `trust.anchor.ts` uses) —
+but it has never actually been executed. Running it was blocked by Claude Code's own
+auto-mode safety classifier (an external-network-with-credentials action), and the call
+was made to commit the working code rather than force it through. **Whoever picks this up
+next should run it once** and record the result here:
+
+```bash
+cd integrations/mmt-graph
+MMT_GRAPH_DOTENV_PATH="../../backend/.env" node mmt-graph.anchor-live-demo.mjs
+```
+
+Expect it to print a topic ID, a transaction ID, and a mirror-node URL. If it works, this
+line should be replaced with the actual transaction ID and a ✅. If it doesn't, that's the
+first real signal about what Phase 3's live wiring will actually need to handle.
+
+## What a real `submit` looks like
+
+The live demo script above is the working version. A MetaMynd-backend-shaped equivalent
+would follow `trust.anchor.ts`'s pattern instead of raw `@hashgraph/sdk` calls:
+
+```js
+async function submit(message) {
+  const client = getHederaClient(); // backend/src/features/hedera/hedera.client.js
+  const topicId = await resolveOrCreateMmtGraphTopic(); // this tenant's own topic, Postgres-cached
+  const tx = new TopicMessageSubmitTransaction().setTopicId(topicId).setMessage(message);
+  const resp = await tx.execute(client.getClient());
+  const receipt = await resp.getReceipt(client.getClient());
+  return { transactionId: resp.transactionId.toString(), status: receipt.status.toString() };
+}
+```
+
+## Run it
+
+```bash
+npm install
+npm run spike              # the Phase 1 decision record
+npm test                   # engine + merkle + changelog + anchor-contract + evidence-path + contagion + accountability + blast-radius + auditor, all offline
+npm run anchor-live-demo   # NOT part of npm test — needs real testnet credentials, see above
+npm run auditor -- disclosure.json [--topic 0.0.x] [--network testnet|mainnet]   # Phase 6's public verifier
+```
+
+## Not in scope here
+
+No backend wiring, no new DB tables, no Postgres access anywhere in this package
+(including the live demo — topic resolution there is env-var based, mirroring
+`trust.anchor.ts`'s `TRUST_TOPIC_ID` fallback, not its DB-backed cache). `npm test` makes
+no live Hedera/HCS calls — `mmt-graph.anchor.test.mjs` checks this by inspecting
+`mmt-graph.anchor.mjs`'s actual imports, not just by claiming it in prose; the live demo
+script and the auditor's own mirror-node read (Phase 6, tested via an injected `fetchImpl`,
+never a real call in `npm test`) are the only two exceptions. **All four of Platform
+Governance §7's questions now have a graph-query proof** (Phase 5): `evidence-path`,
+`contagion` (all four cohort kinds), `accountability` (its load-bearing core — see
+`mmt-graph.accountability.mjs`'s header for what's deliberately out of scope: the
+operating-unit hop, the delegation-root distinction, human review linkage), and
+`blast-radius` (see `mmt-graph.blast-radius.mjs`'s header — answers the question the real
+code was rewritten to ask, not the un-walkable original). None are wired to a live endpoint
+— that cutover needs a real backfill/durability design, not attempted anywhere in this
+package.

package/mmt-graph.accountability.mjs

@@ -0,0 +1,128 @@
+/**
+ * Phase 5, fifth slice: proves the engine can answer accountability.ts's core question —
+ * "who is ultimately answerable for this decision?" — as a graph query. Not a replacement of
+ * that file (same "proof not cutover" posture as evidence-path/contagion): this covers the
+ * chain's LOAD-BEARING core, `decision -> agent -> organization -> human`, and the four gap
+ * codes that determine `answerable` itself (`agent-unresolved`, `no-organization`,
+ * `organization-unverified`, `no-authorized-representative`). Deliberately NOT attempted
+ * here: the operating-unit hop (`unit-org-mismatch`), the delegation-root distinction
+ * (`no-delegation-root`/`delegation-root-unresolved`/`delegation-root-differs`), and human
+ * review/approval linkage (`review-unlinked`) — real parts of accountability.ts's full shape,
+ * but refinements on top of the answerable/not-answerable determination this slice targets,
+ * the same kind of scope split contagion's sop/standard-then-organization/unit slices used.
+ *
+ * `principalIsVerified` below is a verbatim port of
+ * backend/src/features/principal/principal.verification.ts's function of the same name —
+ * same three checks (status is verified/renewing, assurance level isn't none, expiry hasn't
+ * passed), same reason as isSpecific/isIndependentlyVerifiable's verbatim ports elsewhere in
+ * this package: the whole point is proving this against the real rule, not a fresh guess at
+ * one.
+ */
+
+import { MMT, agentIri, decisionIri, principalIri, humanIri } from './mmt-graph.project.mjs';
+
+/** Verbatim from backend/src/features/principal/principal.verification.ts. */
+export function principalIsVerified(row, now = new Date()) {
+  if (!row) return false;
+  if (row.verificationStatus !== 'verified' && row.verificationStatus !== 'renewing') return false;
+  if (row.assuranceLevel === 'none') return false;
+  if (row.verificationExpiresAt && new Date(row.verificationExpiresAt).getTime() <= now.getTime()) return false;
+  return true;
+}
+
+export const ACCOUNTABILITY_GAPS = ['agent-unresolved', 'no-organization', 'organization-unverified', 'no-authorized-representative'];
+
+/**
+ * @param engine {import('./mmt-graph.engine.mjs').MmtGraphEngine}
+ * @param decisionId {string}
+ * @param now {Date}
+ * @returns {{
+ *   agentDid: string | null,
+ *   organizationDid: string | null,
+ *   verificationInForce: boolean,
+ *   accountablePerson: { userId: string, name: string, email: string } | null,
+ *   answerable: boolean,
+ *   gaps: { code: string, severity: 'break', detail: string }[],
+ * }}
+ */
+export function resolveAccountability(engine, decisionId, now = new Date()) {
+  const decision = decisionIri(decisionId).value;
+
+  const rows = [
+    ...engine.query(`
+      PREFIX mmt: <${MMT}>
+      SELECT ?agent ?org ?verificationStatus ?assuranceLevel ?verificationExpiresAt ?human ?humanEmail ?humanName WHERE {
+        <${decision}> a mmt:AuthorizationDecision .
+        OPTIONAL {
+          <${decision}> mmt:decidedFor ?agent .
+          ?agent a mmt:AIAgent .
+          OPTIONAL {
+            ?agent mmt:memberOf ?org .
+            ?org a mmt:Organization .
+            OPTIONAL { ?org mmt:verificationStatus ?verificationStatus }
+            OPTIONAL { ?org mmt:assuranceLevel ?assuranceLevel }
+            OPTIONAL { ?org mmt:verificationExpiresAt ?verificationExpiresAt }
+            OPTIONAL {
+              ?org mmt:operatedBy ?human .
+              ?human a mmt:Human .
+              OPTIONAL { ?human mmt:email ?humanEmail }
+              OPTIONAL { ?human mmt:name ?humanName }
+            }
+          }
+        }
+      }
+    `),
+  ];
+
+  const row = rows[0] ?? null;
+  const get = (name) => row?.get(name)?.value ?? null;
+
+  const agentDid = get('agent');
+  const organizationDid = get('org');
+  const humanUserId = get('human') ? decodeURIComponent(get('human').slice(`${MMT}human/`.length)) : null;
+
+  const gaps = [];
+
+  if (!agentDid) {
+    gaps.push({
+      code: 'agent-unresolved',
+      severity: 'break',
+      detail: `No agent is linked to decision ${decisionId} via mmt:decidedFor, so the decision cannot be attributed to anything that acts.`,
+    });
+  }
+
+  if (agentDid && !organizationDid) {
+    gaps.push({
+      code: 'no-organization',
+      severity: 'break',
+      detail: 'The agent is not mapped to an accountable organisation (no mmt:memberOf edge to an mmt:Organization), so the chain stops at the agent itself.',
+    });
+  }
+
+  const verificationInForce = organizationDid
+    ? principalIsVerified({ verificationStatus: get('verificationStatus'), assuranceLevel: get('assuranceLevel'), verificationExpiresAt: get('verificationExpiresAt') }, now)
+    : false;
+  if (organizationDid && !verificationInForce) {
+    gaps.push({
+      code: 'organization-unverified',
+      severity: 'break',
+      detail: `The accountable entity's KYB is not currently in force (${get('verificationStatus') ?? 'unverified'}). Its answer for this action rests on a verification the platform no longer stands behind.`,
+    });
+  }
+
+  const accountablePerson = humanUserId ? { userId: humanUserId, name: get('humanName') ?? get('humanEmail'), email: get('humanEmail') } : null;
+  if (organizationDid && !accountablePerson) {
+    gaps.push({
+      code: 'no-authorized-representative',
+      severity: 'break',
+      detail: 'The organisation names no authorised representative (no mmt:operatedBy edge to an mmt:Human), so the chain ends at a legal entity rather than at a person.',
+    });
+  }
+
+  const answerable = Boolean(agentDid && organizationDid && verificationInForce && accountablePerson);
+
+  return { agentDid, organizationDid, verificationInForce, accountablePerson, answerable, gaps };
+}
+
+/** Exported for tests that want to construct these IRIs without importing project.mjs directly. */
+export { decisionIri, agentIri, principalIri, humanIri };

package/mmt-graph.anchor-live-demo.mjs

@@ -0,0 +1,122 @@
+/**
+ * The one exception to "everything in this package is offline." Wires a real `submit` for
+ * mmt-graph.anchor.mjs's anchorBatch() and submits an actual batch root to Hedera TESTNET.
+ *
+ * NOT run by `npm test` or CI — never add this to an automated test suite. A live network
+ * call to external infrastructure is exactly the kind of thing that shouldn't gate a test
+ * run (flaky, slow, an external dependency CI has no credentials for anyway). Run by hand:
+ *
+ *   HEDERA_OPERATOR_ID=... HEDERA_OPERATOR_KEY=... node mmt-graph.anchor-live-demo.mjs
+ *
+ * or point it at backend/.env's existing dev testnet credentials (see README). Uses
+ * TESTNET HBAR, which has no real-world value — same credentials and network
+ * backend/src/features/trust/trust.anchor.ts already uses for the same kind of anchoring.
+ *
+ * Deliberately does NOT touch Postgres: topic resolution mirrors trust.anchor.ts's
+ * TRUST_TOPIC_ID env-var fallback rather than its DB-backed cache, so this package keeps
+ * no `db` import anywhere — that boundary is what keeps mmt-graph portable to a
+ * self-hosted tenant who has no MetaMynd backend at all.
+ */
+
+import { config as loadEnv } from 'dotenv';
+import {
+  Client,
+  AccountId,
+  PrivateKey,
+  TopicCreateTransaction,
+  TopicMessageSubmitTransaction,
+  TransactionId,
+  Timestamp,
+} from '@hashgraph/sdk';
+
+import { MmtGraphEngine } from './mmt-graph.engine.mjs';
+import { agentRegistered, principalRegistered, mandateGranted } from './mmt-graph.types.mjs';
+import { buildChangelogBatch } from './mmt-graph.changelog.mjs';
+import { anchorBatch } from './mmt-graph.anchor.mjs';
+
+// Loads a local .env by default; MMT_GRAPH_DOTENV_PATH lets it point at an existing one
+// instead (e.g. backend/.env's dev testnet credentials) without copying secrets anywhere.
+loadEnv(process.env.MMT_GRAPH_DOTENV_PATH ? { path: process.env.MMT_GRAPH_DOTENV_PATH } : undefined);
+
+const operatorId = process.env.HEDERA_OPERATOR_ID;
+const operatorKey = process.env.HEDERA_OPERATOR_KEY;
+const network = process.env.HEDERA_NETWORK || 'testnet';
+const mirrorBaseUrl = process.env.HEDERA_MIRROR_NODE_URL || 'https://testnet.mirrornode.hedera.com/api/v1';
+
+if (!operatorId || !operatorKey) {
+  console.error(
+    'HEDERA_OPERATOR_ID and HEDERA_OPERATOR_KEY must be set — this script never falls back to a ' +
+      'default or hardcoded credential. See README.md for how to point it at an existing testnet account.'
+  );
+  process.exit(1);
+}
+
+if (network !== 'testnet') {
+  console.error(`refusing to run against network="${network}" — this demo is testnet-only by design.`);
+  process.exit(1);
+}
+
+/** Raw-hex ECDSA (fallback ED25519) or DER — same detection trust.anchor.ts's client relies on. */
+function parseOperatorKey(raw) {
+  const s = raw.startsWith('0x') ? raw.slice(2) : raw;
+  if (s.startsWith('30')) return PrivateKey.fromStringDer(s);
+  try {
+    return PrivateKey.fromStringECDSA(s);
+  } catch {
+    return PrivateKey.fromStringED25519(s);
+  }
+}
+
+const client = Client.forName(network);
+client.setOperator(AccountId.fromString(operatorId), parseOperatorKey(operatorKey));
+
+async function ensureTopicId() {
+  const fromEnv = process.env.MMT_GRAPH_TOPIC_ID;
+  if (fromEnv) return fromEnv;
+
+  console.log('No MMT_GRAPH_TOPIC_ID set — creating a fresh topic (set this env var to reuse it next time).');
+  const resp = await new TopicCreateTransaction().execute(client);
+  const topicId = (await resp.getReceipt(client)).topicId?.toString();
+  if (!topicId) throw new Error('topic creation succeeded but returned no topicId');
+  return topicId;
+}
+
+/** The `submit` mmt-graph.anchor.mjs's anchorBatch() calls — see its header for the contract. */
+async function submit(message) {
+  const topicId = await ensureTopicId();
+  const tx = new TopicMessageSubmitTransaction().setTopicId(topicId).setMessage(message);
+
+  // Backdate valid-start slightly — Hedera rejects a future start time. Same fix trust.anchor.ts applies.
+  const operatorAccountId = client.operatorAccountId;
+  if (operatorAccountId) {
+    tx.setTransactionId(TransactionId.withValidStart(operatorAccountId, new Timestamp(Math.floor(Date.now() / 1000) - 10, 0)));
+  }
+
+  const resp = await tx.execute(client);
+  const receipt = await resp.getReceipt(client);
+  return { topicId, transactionId: resp.transactionId.toString(), status: receipt.status.toString() };
+}
+
+async function main() {
+  const engine = new MmtGraphEngine();
+  engine.apply(principalRegistered({ principalDid: 'did:hedera:testnet:acme', principalType: 'Organization' }));
+  engine.apply(agentRegistered({ agentDid: 'did:hedera:testnet:agent17' }));
+  engine.apply(mandateGranted({ policyId: 'policy-82', agentDid: 'did:hedera:testnet:agent17', principalDid: 'did:hedera:testnet:acme' }));
+
+  const batch = buildChangelogBatch(engine.log);
+  console.log(`Batched ${batch.size} event(s). Root: ${batch.root}`);
+
+  const receipt = await anchorBatch(batch, submit);
+  console.log('\nAnchored.');
+  console.log(`  topicId:        ${receipt.topicId}`);
+  console.log(`  transactionId:  ${receipt.transactionId}`);
+  console.log(`  status:         ${receipt.status}`);
+  console.log(`  verify:         ${mirrorBaseUrl}/topics/${receipt.topicId}/messages`);
+
+  await client.close();
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exitCode = 1;
+});

package/mmt-graph.anchor.mjs

@@ -0,0 +1,31 @@
+/**
+ * The anchor CONTRACT, not an anchor implementation. This file never imports @hashgraph/sdk
+ * and never makes a network call — it builds the canonical batch-root message and hands it
+ * to an injected `submit` function, the same shape as evidence-batch.ts's single HCS
+ * message per batch (`{op:'evidence-batch-root', root, size}`) but for the trust-graph
+ * changelog.
+ *
+ * Why injected rather than built in: this package is meant to run identically whether
+ * MetaMynd operates it or a tenant self-hosts it (see docs/design/metamynd-trust-ontology.md
+ * Appendix C) — the Hedera client, credentials, and topic management differ by hosting mode,
+ * but what gets anchored and how it's hashed does not. `submit` is the entire seam; who
+ * constructs it (a `trust.anchor.ts`-shaped wrapper, a tenant's own SDK usage) is Phase 3.
+ */
+
+const OP = 'mmt-graph-batch-root';
+
+/**
+ * @param batch {{ root: string, size: number }} from buildChangelogBatch()
+ * @param submit {(message: string) => Promise<{ transactionId: string, status: string }>}
+ * @returns the receipt `submit` returns, unchanged — this function adds nothing to it
+ */
+export async function anchorBatch(batch, submit) {
+  if (typeof submit !== 'function') {
+    throw new Error('anchorBatch: submit must be a function — this package does not talk to Hedera itself');
+  }
+  const message = JSON.stringify({ op: OP, root: batch.root, size: batch.size });
+  return submit(message);
+}
+
+/** Exported so a caller building their own `submit` can parse what they receive back from the mirror without duplicating the op name. */
+export const MMT_GRAPH_BATCH_ROOT_OP = OP;

package/mmt-graph.auditor-cli.mjs

@@ -0,0 +1,41 @@
+#!/usr/bin/env node
+// mmt-graph.auditor-cli.mjs — CLI for the mmt-graph public verifier (Phase 6).
+//
+// A regulator / disputing party runs this against a disclosure package a tenant opened. It
+// verifies — with MetaMynd offline — that the disclosed event(s) were governed, unaltered,
+// and (with --topic) anchored on-chain. Same CLI shape as integrations/magp-evidence's
+// auditor.mjs, extended for mmt-graph's two disclosure shapes:
+//
+//   { event, proof, root }        — one event's inclusion in an anchored batch
+//   { events: [...], root }       — a full raw log, independently replayed and validated
+//
+//   node mmt-graph.auditor-cli.mjs <disclosure.json> [--topic 0.0.x] [--network testnet|mainnet]
+//
+// Exit 0 = VALID, 1 = INVALID/unverifiable.
+import { readFileSync } from 'node:fs';
+import { verifyDisclosure } from './mmt-graph.auditor.mjs';
+
+const args = process.argv.slice(2);
+const file = args.find((a) => !a.startsWith('--'));
+const opt = (name) => {
+  const i = args.indexOf(`--${name}`);
+  return i >= 0 ? args[i + 1] : undefined;
+};
+if (!file) {
+  console.error('usage: node mmt-graph.auditor-cli.mjs <disclosure.json> [--topic 0.0.x] [--network testnet|mainnet]');
+  process.exit(2);
+}
+
+const pkg = JSON.parse(readFileSync(file, 'utf8'));
+const topic = opt('topic');
+if (topic) pkg.anchor = { ...pkg.anchor, topicId: topic, network: opt('network') ?? 'testnet' };
+
+const r = await verifyDisclosure(pkg);
+
+const mode = Array.isArray(pkg.events) ? 'full-log replay' : 'single-event inclusion';
+console.log(`\nmmt-graph public verifier — ${file} (${mode})\n${'─'.repeat(56)}`);
+for (const c of r.checks) console.log(`  ${c.ok ? '✓' : '✗'} ${c.check}`);
+if (!topic) console.log('  · on-chain anchoring not checked (pass --topic to verify)');
+
+console.log(`${'─'.repeat(56)}\n${r.valid ? '✅ VALID' : '❌ INVALID'} — the disclosed record ${r.valid ? 'was governed, unaltered, and matches what was claimed.' : 'did NOT verify.'}\n`);
+process.exit(r.valid ? 0 : 1);