@metamynd/mmt-graph 0.2.0

package/mmt-graph.auditor.mjs

@@ -0,0 +1,129 @@
+/**
+ * Phase 6: the public verification tooling `docs/design/metamynd-trust-ontology.md` Appendix C
+ * describes — "extend the `magp-evidence` auditor pattern so a third party can verify a
+ * tenant's HCS-anchored graph state with MetaMynd fully offline." Same posture as that
+ * package's `auditor.mjs`/`magp-evidence.mjs`: zero MetaMynd-server dependency, node:crypto +
+ * fetch only, a regulator or disputing party runs this standalone against a disclosure
+ * package a tenant (self-hosted or MetaMynd-operated) opened.
+ *
+ * Two disclosure shapes, because a graph gives a verifier something a flat evidence leaf
+ * doesn't: one event's inclusion in an anchored batch (mirrors magp-evidence exactly), OR a
+ * whole disclosed event log, independently REPLAYED and validated — not just hash-checked.
+ * A regulator asking "was this tenant's authority chain ever actually broken" can rebuild the
+ * graph from the raw log and run the real §3 invariant check themselves, with MetaMynd
+ * offline — that's the point of a queryable graph over an opaque evidence trail.
+ */
+
+import { MmtGraphEngine } from './mmt-graph.engine.mjs';
+import { eventLeaf, buildChangelogBatch } from './mmt-graph.changelog.mjs';
+import { verifyMerkleProof } from './mmt-graph.merkle.mjs';
+import { MMT_GRAPH_BATCH_ROOT_OP } from './mmt-graph.anchor.mjs';
+
+const mirrorBase = (network) => (network === 'mainnet' ? 'https://mainnet.mirrornode.hedera.com' : 'https://testnet.mirrornode.hedera.com');
+
+/**
+ * Confirm `root` was anchored on the mmt-graph changelog topic (op: MMT_GRAPH_BATCH_ROOT_OP)
+ * by reading a public Hedera mirror node — MetaMynd offline. Mirrors
+ * magp-evidence.mjs's verifyRootAnchored exactly, same injected `fetchImpl` test seam,
+ * different op name.
+ */
+export async function verifyBatchAnchored(root, topicId, opts = {}) {
+  const fetchImpl = opts.fetchImpl ?? fetch;
+  const url = `${mirrorBase(opts.network ?? 'testnet')}/api/v1/topics/${topicId}/messages?limit=${opts.limit ?? 200}&order=asc`;
+  let body = null;
+  try {
+    body = await fetchImpl(url).then((r) => (r.ok ? r.json() : null));
+  } catch {
+    return { anchored: false, consensusTimestamp: null, sequenceNumber: null };
+  }
+  for (const m of body?.messages ?? []) {
+    try {
+      const op = JSON.parse(Buffer.from(m.message, 'base64').toString('utf8'));
+      if (op.op === MMT_GRAPH_BATCH_ROOT_OP && op.root === root) {
+        return { anchored: true, consensusTimestamp: m.consensus_timestamp ?? null, sequenceNumber: m.sequence_number ?? null };
+      }
+    } catch {
+      /* skip non-JSON */
+    }
+  }
+  return { anchored: false, consensusTimestamp: null, sequenceNumber: null };
+}
+
+/**
+ * Verify ONE disclosed event's inclusion in an anchored batch. Shape:
+ *   { event, proof: [{sibling, position}, …], root, leaf? }
+ * Mirrors magp-evidence's verifyDisclosure for a single record — the leaf reproduces the
+ * SAME way eventLeaf() does in mmt-graph.changelog.mjs, not a fresh hash scheme.
+ */
+export function verifyEventInclusion(pkg, { anchoredRoot } = {}) {
+  const checks = [];
+  const leaf = eventLeaf(pkg.event);
+  const leafMatches = pkg.leaf == null || pkg.leaf === leaf;
+  checks.push({ check: 'leaf reproduced from the disclosed event', ok: leafMatches });
+
+  const inclusionValid = verifyMerkleProof(leaf, pkg.proof, pkg.root);
+  checks.push({ check: 'Merkle inclusion proof reproduces the batch root', ok: inclusionValid });
+
+  let rootAnchored = true;
+  if (anchoredRoot != null) {
+    rootAnchored = pkg.root === anchoredRoot;
+    checks.push({ check: 'batch root matches the on-chain anchored root', ok: rootAnchored });
+  }
+
+  const valid = leafMatches && inclusionValid && rootAnchored;
+  return { valid, leafMatches, inclusionValid, rootAnchored, leaf, checks };
+}
+
+/**
+ * The graph-specific verification magp-evidence's flat records can't offer: replay a
+ * disclosed RAW EVENT LOG through a fresh engine and check two independent things —
+ * (1) the batch root it recomputes matches what was claimed/anchored, so the disclosed log
+ * is exactly what was committed to, not a doctored subset or superset; (2) the REPLAYED
+ * graph itself validates — the same SHACL shapes and §3 authority-chain invariant
+ * `MmtGraphEngine#validate()` runs internally, run here by a third party who never trusted
+ * MetaMynd to have run it correctly the first time.
+ */
+export async function verifyReplayedLog(events, claimedRoot) {
+  const checks = [];
+  const recomputedRoot = buildChangelogBatch(events).root;
+  const rootMatches = recomputedRoot === claimedRoot;
+  checks.push({ check: 'recomputed batch root matches the claimed/anchored root', ok: rootMatches });
+
+  const engine = new MmtGraphEngine();
+  engine.replay(events);
+  const report = await engine.validate();
+  checks.push({ check: 'replayed graph has no SHACL shape violations', ok: report.shapeViolations.length === 0 });
+  checks.push({ check: 'every agent with a mandate reaches an authoritative Principal (§3 invariant)', ok: report.unreachableAgents.length === 0 });
+
+  return {
+    valid: rootMatches && report.conforms,
+    rootMatches,
+    recomputedRoot,
+    graphValid: report.conforms,
+    shapeViolations: report.shapeViolations,
+    unreachableAgents: report.unreachableAgents,
+    checks,
+  };
+}
+
+/**
+ * Top-level verdict for a disclosure package. Detects the shape: `pkg.events` (an array) runs
+ * the full-log replay; `pkg.event` (singular) runs single-event inclusion — mirroring
+ * magp-evidence.mjs's verifyDisclosure entry point, extended for the two shapes this graph
+ * can disclose. `anchor: { topicId, network }`, when present, also confirms on-chain
+ * anchoring via a public mirror node (needs network — kept separate from the pure checks
+ * above, same separation magp-evidence.mjs's own header describes).
+ */
+export async function verifyDisclosure(pkg, opts = {}) {
+  const result = Array.isArray(pkg.events) ? await verifyReplayedLog(pkg.events, pkg.root) : verifyEventInclusion(pkg);
+
+  let anchorCheck = null;
+  if (pkg.anchor?.topicId) {
+    const a = await verifyBatchAnchored(pkg.root, pkg.anchor.topicId, { network: pkg.anchor.network, fetchImpl: opts.fetchImpl });
+    anchorCheck = { check: 'batch root anchored on the mmt-graph changelog topic', ok: a.anchored, ...a };
+  }
+
+  const checks = anchorCheck ? [...result.checks, anchorCheck] : result.checks;
+  const valid = result.valid && (anchorCheck ? anchorCheck.ok : true);
+  return { ...result, valid, checks, anchor: anchorCheck };
+}

package/mmt-graph.blast-radius.mjs

@@ -0,0 +1,166 @@
+/**
+ * Phase 5, sixth slice: proves the engine can answer blast-radius.ts's real question — not
+ * the one originally posed ("which agents hold credentials from this issuer", which cannot
+ * be walked at all: issued VCs are signed and HCS-anchored but never persisted — see that
+ * file's own header) but the one it was rewritten to answer instead: "an issuer's tier
+ * derives from its backing principal; what depends on that same principal, and which live
+ * mandates would start getting blocked with PRINCIPAL_UNVERIFIED if its verification
+ * lapsed?" That reframing is what makes this tractable — this slice does not attempt
+ * credential-holder tracking either, and says so in `coverage`, same as the real code.
+ *
+ * `blockedOnLapse` mirrors blast-radius.ts exactly: `liveMandates.filter(authorizedByPrincipal)`,
+ * a HYPOTHETICAL count ("would block on a lapse"), not gated on whether the principal's
+ * verification is currently in force. Not the same question mmt-graph.accountability.mjs
+ * answers with `principalIsVerified` — deliberately not reused here.
+ *
+ * `authorizedByPrincipal` is a per-MANDATE fact (`Policy.principalDid === principal.did`),
+ * not a per-agent one — `mmt:actsFor` alone (set on the agent node) can't distinguish which
+ * of an agent's several mandates was THIS principal's own root grant, so this slice needed
+ * one new edge on the mandate itself: see `mmt:grantsMandate` in mmt-graph.project.mjs.
+ */
+
+import { MMT, issuerIri, principalIri, mandateIri } from './mmt-graph.project.mjs';
+
+const MANDATE_PREFIX = `${MMT}mandate/`;
+const policyIdFromMandateIri = (iri) => decodeURIComponent(iri.slice(MANDATE_PREFIX.length));
+
+/** Verbatim rule from blast-radius.ts's isLive: absent expiry means no expiry, not expired. */
+function isLive(expiresAt, now) {
+  if (!expiresAt) return true;
+  return new Date(expiresAt).getTime() > now.getTime();
+}
+
+/**
+ * @param engine {import('./mmt-graph.engine.mjs').MmtGraphEngine}
+ * @param issuerDid {string}
+ * @param now {Date}
+ * @returns {{
+ *   issuerDid: string,
+ *   principalDid: string | null,
+ *   agents: { agentDid: string, mandates: number }[],
+ *   mandates: { policyId: string, agentDid: string, expiresAt: string | null, live: boolean, authorizedByPrincipal: boolean }[],
+ *   siblingIssuers: { did: string, name: string | null }[],
+ *   impact: { agents: number, liveMandates: number, expiredMandates: number, siblingIssuers: number, blockedOnLapse: number },
+ *   coverage: { issuedCredentials: 'not-tracked' },
+ * }}
+ */
+export function resolveBlastRadius(engine, issuerDid, now = new Date()) {
+  const issuer = issuerIri(issuerDid).value;
+  const coverage = { issuedCredentials: 'not-tracked' };
+
+  const principalRow = [
+    ...engine.query(`
+      PREFIX mmt: <${MMT}>
+      SELECT ?principal WHERE {
+        <${issuer}> mmt:backedBy ?principal .
+        ?principal a mmt:Organization .
+      }
+    `),
+  ][0];
+  const principalDid = principalRow?.get('principal')?.value ?? null;
+
+  // An issuer with no accountable entity has an empty radius BY CONSTRUCTION, not by
+  // accident — same rule as buildIssuerBlastRadius's early return: nothing verified is
+  // behind it, so there is nothing to lapse and nothing downstream to lapse with it.
+  if (!principalDid) {
+    return {
+      issuerDid,
+      principalDid: null,
+      agents: [],
+      mandates: [],
+      siblingIssuers: [],
+      impact: { agents: 0, liveMandates: 0, expiredMandates: 0, siblingIssuers: 0, blockedOnLapse: 0 },
+      coverage,
+    };
+  }
+
+  const mandateRows = [
+    ...engine.query(`
+      PREFIX mmt: <${MMT}>
+      SELECT DISTINCT ?mandate ?agent ?expiresAt WHERE {
+        ?mandate a mmt:Mandate ; mmt:grantedTo ?agent .
+        OPTIONAL { ?mandate mmt:expiresAt ?expiresAt }
+        {
+          <${principalDid}> mmt:grantsMandate ?mandate .
+        }
+        UNION
+        {
+          ?agent mmt:memberOf <${principalDid}> .
+        }
+      }
+    `),
+  ];
+
+  const mandateCountByAgent = new Map();
+  const mandates = mandateRows.map((row) => {
+    const mandateIriValue = row.get('mandate').value;
+    const agentDid = row.get('agent').value;
+    const expiresAtTerm = row.get('expiresAt');
+    const expiresAt = expiresAtTerm ? expiresAtTerm.value : null;
+    const authorizedByPrincipal = engine.query(`
+      PREFIX mmt: <${MMT}>
+      ASK { <${principalDid}> mmt:grantsMandate <${mandateIriValue}> }
+    `);
+
+    mandateCountByAgent.set(agentDid, (mandateCountByAgent.get(agentDid) ?? 0) + 1);
+
+    return { policyId: policyIdFromMandateIri(mandateIriValue), agentDid, expiresAt, live: isLive(expiresAt, now), authorizedByPrincipal };
+  });
+
+  // Every agent whose home organisation IS this principal, PLUS any agent reached only via
+  // a mandate this principal directly granted — the real code's step 4: "an agent can hold
+  // a mandate from this principal without being mapped to it as an organisation."
+  const agentRows = [
+    ...engine.query(`
+      PREFIX mmt: <${MMT}>
+      SELECT DISTINCT ?agent WHERE {
+        {
+          ?agent mmt:memberOf <${principalDid}> .
+          ?agent a mmt:AIAgent .
+        }
+        UNION
+        {
+          ?mandate a mmt:Mandate ; mmt:grantedTo ?agent .
+          <${principalDid}> mmt:grantsMandate ?mandate .
+        }
+      }
+    `),
+  ];
+  const agents = agentRows.map((row) => {
+    const agentDid = row.get('agent').value;
+    return { agentDid, mandates: mandateCountByAgent.get(agentDid) ?? 0 };
+  });
+
+  const siblingRows = [
+    ...engine.query(`
+      PREFIX mmt: <${MMT}>
+      SELECT ?sibling ?name WHERE {
+        ?sibling a mmt:Issuer ; mmt:backedBy <${principalDid}> .
+        OPTIONAL { ?sibling mmt:name ?name }
+        FILTER(?sibling != <${issuer}>)
+      }
+    `),
+  ];
+  const siblingIssuers = siblingRows.map((row) => ({ did: row.get('sibling').value, name: row.get('name')?.value ?? null }));
+
+  const liveMandates = mandates.filter((m) => m.live);
+
+  return {
+    issuerDid,
+    principalDid,
+    agents,
+    mandates,
+    siblingIssuers,
+    impact: {
+      agents: agents.length,
+      liveMandates: liveMandates.length,
+      expiredMandates: mandates.length - liveMandates.length,
+      siblingIssuers: siblingIssuers.length,
+      blockedOnLapse: liveMandates.filter((m) => m.authorizedByPrincipal).length,
+    },
+    coverage,
+  };
+}
+
+/** Exported for tests that want to construct these IRIs without importing project.mjs directly. */
+export { issuerIri, principalIri, mandateIri };

package/mmt-graph.changelog.mjs

@@ -0,0 +1,80 @@
+/**
+ * Turns the engine's mutation log (MmtGraphEngine#log — see mmt-graph.engine.mjs) into an
+ * anchor-ready Merkle batch. Same discipline as backend/src/features/magp/evidence-batch.ts's
+ * evidenceLeaf(): canonical (sorted-key) JSON over an EXPLICITLY listed field set per event
+ * op, never a spread — a spread hashes whatever the caller happens to carry, which is how a
+ * field silently reshaping historical leaves happens in the first place. Adding a field to
+ * mmt-graph.types.mjs does not change any existing leaf until someone edits EVENT_LEAF_FIELDS.
+ */
+
+import { merkleRoot, merkleProof, sha256Hex } from './mmt-graph.merkle.mjs';
+
+/**
+ * Kept in sync BY HAND with every event constructor in mmt-graph.types.mjs — the file
+ * header's whole point is that this is a deliberate, reviewable list, not a spread. It drifted
+ * once already: Phase 5's six slices (evidence-path/contagion/accountability/blast-radius)
+ * each added fields to existing ops (`agent-registered`.principalDid, `principal-registered`'s
+ * verification/rep fields, `mandate-granted`.expiresAt) and six wholly new ops
+ * (`decision-recorded`/`evidence-recorded`/`batch-anchored`/`cohort-shared`/
+ * `human-registered`/`issuer-registered`), and none of it ever touched this file — the new
+ * fields were silently excluded from their own event's Merkle leaf, and the six new ops would
+ * have thrown out of `eventLeaf`. Caught before anything anchored either shape (`impact()`
+ * upstream of `eventLeaf` returns zero real callers today — nothing in this package batches
+ * Phase 5's proof-only events), fixed here rather than left for Phase 6's auditor to discover
+ * the hard way.
+ */
+const EVENT_LEAF_FIELDS = {
+  'agent-registered': ['op', 'agentDid', 'kind', 'principalDid'],
+  'principal-registered': [
+    'op',
+    'principalDid',
+    'principalType',
+    'verificationStatus',
+    'assuranceLevel',
+    'verificationExpiresAt',
+    'authorizedRepUserId',
+  ],
+  'mandate-granted': ['op', 'policyId', 'agentDid', 'principalDid', 'delegatedFromPolicyId', 'delegationDepth', 'expiresAt'],
+  'mandate-revoked': ['op', 'policyId'],
+  'decision-recorded': ['op', 'decisionId', 'decisionDigest', 'agentDid'],
+  'evidence-recorded': ['op', 'eventId', 'decisionDigest', 'anchorStatus'],
+  'batch-anchored': ['op', 'batchId', 'memberEventIds', 'anchorStatus'],
+  'cohort-shared': ['op', 'agentDid', 'kind', 'key', 'label', 'version'],
+  'human-registered': ['op', 'userId', 'email', 'firstName', 'lastName'],
+  'issuer-registered': ['op', 'did', 'name', 'principalDid'],
+};
+
+/** Canonical JSON: keys sorted, missing/undefined normalized to null — so the hash is stable. */
+function canonical(obj) {
+  return JSON.stringify(
+    Object.keys(obj)
+      .sort()
+      .map((k) => [k, obj[k] ?? null])
+  );
+}
+
+/** The reproducible Merkle leaf for one mutation event. */
+export function eventLeaf(event) {
+  const fields = EVENT_LEAF_FIELDS[event.op];
+  if (!fields) throw new Error(`eventLeaf: no leaf field list for event op "${event.op}" — add one to EVENT_LEAF_FIELDS`);
+  const obj = {};
+  for (const f of fields) obj[f] = event[f];
+  return sha256Hex(canonical(obj));
+}
+
+/**
+ * Batch a sequence of mutation events: hash each to a leaf, compute the Merkle root, and
+ * produce a per-event inclusion proof. Only `root` need be anchored (mmt-graph.anchor.mjs);
+ * each `proof` lets a holder later prove one event was in the anchored batch.
+ */
+export function buildChangelogBatch(events) {
+  const leaves = events.map(eventLeaf);
+  const root = merkleRoot(leaves);
+  const entries = events.map((event, index) => ({
+    index,
+    op: event.op,
+    leaf: leaves[index],
+    proof: merkleProof(leaves, index),
+  }));
+  return { root, size: events.length, entries };
+}

package/mmt-graph.contagion.mjs

@@ -0,0 +1,105 @@
+/**
+ * Phase 5, second and fourth slices: proves the engine can answer contagion.ts's hard
+ * question — not "what does this agent share with others" (an easy join) but "which of
+ * those shares are SPECIFIC enough to mean something" — as a SPARQL aggregate query. All
+ * four real cohort kinds (`sop`, `standard`, `organization`, `unit`) are covered, even
+ * though the real algorithm computes them via two different code shapes
+ * (`buildKeyed`/`buildSingle`) — the aggregate query below doesn't need to know that
+ * distinction, because `mmt:sharesCohort` is emitted uniformly for all four (see
+ * mmt-graph.project.mjs's projectCohortShared for why `organization`/`unit` additionally
+ * assert `mmt:memberOf`, which this query does not need). Not wired to any live endpoint,
+ * same "proof not cutover" posture as mmt-graph.evidence-path.mjs.
+ *
+ * `isSpecific` below is a verbatim port of contagion.ts's function — same constants, same
+ * two-condition logic, not re-derived — because the whole point of that function is a
+ * measured, load-bearing threshold (a real platform standard linked 57 of 92 agents when
+ * it was written) and a fresh guess at the numbers would defeat the purpose of proving
+ * this against the real rule.
+ */
+
+import { MMT, agentIri, cohortIri } from './mmt-graph.project.mjs';
+
+/** Verbatim from backend/src/features/trust-graph/contagion.ts — see that file for why both conditions are required. */
+export const BROAD_COHORT_MIN = 10;
+export const BROAD_COHORT_SHARE = 0.5;
+
+export function isSpecific(sharedBy, tenantAgents) {
+  if (sharedBy < BROAD_COHORT_MIN) return true;
+  if (tenantAgents <= 0) return true;
+  return sharedBy / tenantAgents < BROAD_COHORT_SHARE;
+}
+
+const COHORT_TYPE_TO_KIND = {
+  [`${MMT}SOP`]: 'sop',
+  [`${MMT}Standard`]: 'standard',
+  [`${MMT}Organization`]: 'organization',
+  [`${MMT}AgentGroup`]: 'unit',
+};
+
+/**
+ * @param engine {import('./mmt-graph.engine.mjs').MmtGraphEngine}
+ * @param subjectAgentDid {string}
+ * @returns {{ cohorts: Array<{ kind: string, key: string, label: string, version: number|null, sharedBy: number, tenantAgents: number, specific: boolean, peers: string[] }>, tenantAgents: number }}
+ */
+export function computeCohorts(engine, subjectAgentDid) {
+  const subject = agentIri(subjectAgentDid).value;
+
+  // COUNT(DISTINCT ?peerAgent) is inclusive of the subject itself (the subject is one of
+  // the agents pointing at its own cohort node) — this matches contagion.ts's
+  // `sharedBy = peers.length + 1` (peers excludes the subject, then +1 adds it back)
+  // without needing separate include/exclude arithmetic here.
+  const cohortRows = [
+    ...engine.query(`
+      PREFIX mmt: <${MMT}>
+      SELECT ?cohort ?kindType ?key ?label ?version (COUNT(DISTINCT ?peerAgent) AS ?sharedBy) WHERE {
+        <${subject}> mmt:sharesCohort ?cohort .
+        ?cohort a ?kindType ; mmt:cohortKey ?key ; mmt:cohortLabel ?label .
+        OPTIONAL { ?cohort mmt:cohortVersion ?version }
+        ?peerAgent mmt:sharesCohort ?cohort .
+      }
+      GROUP BY ?cohort ?kindType ?key ?label ?version
+    `),
+  ];
+
+  // Phase 3's per-tenant engine (one MmtGraphEngine instance per ownerId) means this count
+  // is already correctly tenant-scoped for free — no separate tenantAgentCount input needed,
+  // unlike contagion.ts's real signature, which takes it explicitly because Postgres has no
+  // equivalent physical boundary.
+  const tenantAgentsRow = [
+    ...engine.query(`PREFIX mmt: <${MMT}> SELECT (COUNT(DISTINCT ?agent) AS ?count) WHERE { ?agent a mmt:AIAgent }`),
+  ][0];
+  const tenantAgents = Number(tenantAgentsRow.get('count').value);
+
+  const cohorts = cohortRows.map((row) => {
+    const cohortIriValue = row.get('cohort').value;
+    const kindTypeIri = row.get('kindType').value;
+    const kind = COHORT_TYPE_TO_KIND[kindTypeIri] ?? kindTypeIri;
+    const sharedBy = Number(row.get('sharedBy').value);
+    const versionTerm = row.get('version');
+
+    const peerRows = [
+      ...engine.query(`
+        PREFIX mmt: <${MMT}>
+        SELECT DISTINCT ?peerAgent WHERE {
+          ?peerAgent mmt:sharesCohort <${cohortIriValue}> .
+          FILTER(?peerAgent != <${subject}>)
+        }
+      `),
+    ];
+
+    return {
+      kind,
+      key: row.get('key').value,
+      label: row.get('label').value,
+      version: versionTerm ? Number(versionTerm.value) : null,
+      sharedBy,
+      tenantAgents,
+      specific: isSpecific(sharedBy, tenantAgents),
+      peers: peerRows.map((r) => r.get('peerAgent').value),
+    };
+  });
+
+  return { cohorts, tenantAgents };
+}
+
+export { cohortIri };

package/mmt-graph.engine.mjs

@@ -0,0 +1,153 @@
+/**
+ * The reference trust-graph engine: apply mutation events, validate the §3 authority-chain
+ * invariant, query the result. In-memory only (Oxigraph's JS binding has no disk
+ * persistence) — Phase 2's HCS-anchored changelog is the intended durable source of truth;
+ * `replay()` is the "rebuild from a durable log" story made real, even though the log
+ * itself doesn't exist yet. No Postgres, no HCS, no backend wiring here — see
+ * docs/design/metamynd-trust-ontology.md Appendix C for what's deferred to which phase.
+ */
+
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import oxigraph from 'oxigraph';
+import rdf from '@zazuko/env-node';
+import SHACLValidator from 'rdf-validate-shacl';
+
+import * as project from './mmt-graph.project.mjs';
+import { MMT, mandateIri } from './mmt-graph.project.mjs';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const SHAPES_TTL = readFileSync(join(__dirname, 'mmt-graph.shapes.ttl'), 'utf8');
+
+/**
+ * An agent's authority is valid if it either acts directly for a Principal (a root
+ * mandate) or its derivesAuthorityFrom chain reaches an agent that does — the §3
+ * invariant, "every executable authority must have an unbroken, currently valid path to
+ * an authoritative Principal," made runnable. `+` is Oxigraph's SPARQL 1.1 property-path
+ * one-or-more operator; a 1-hop delegation and a 3-hop one are the same query.
+ */
+const REACHES_PRINCIPAL = (agentIriValue) => `
+  PREFIX mmt: <${MMT}>
+  ASK {
+    { <${agentIriValue}> mmt:actsFor ?p . ?p a mmt:Organization . }
+    UNION
+    { <${agentIriValue}> mmt:derivesAuthorityFrom+ ?parent . ?parent mmt:actsFor ?p . ?p a mmt:Organization . }
+  }
+`;
+
+const AGENTS_WITH_MANDATES = `
+  PREFIX mmt: <${MMT}>
+  SELECT DISTINCT ?agent WHERE { ?mandate a mmt:Mandate ; mmt:grantedTo ?agent . }
+`;
+
+export class MmtGraphEngine {
+  #store = new oxigraph.Store();
+  #log = [];
+
+  /** @param event {import('./mmt-graph.types.mjs').AgentRegistered | import('./mmt-graph.types.mjs').PrincipalRegistered | import('./mmt-graph.types.mjs').MandateGranted | import('./mmt-graph.types.mjs').MandateRevoked} */
+  apply(event) {
+    const projected = this.#project(event);
+    if (Array.isArray(projected)) {
+      for (const q of projected) this.#store.add(q);
+    } else if (projected?.removeSubject) {
+      for (const q of [...this.#store.match(projected.removeSubject, null, null)]) this.#store.delete(q);
+    }
+    this.#log.push(event);
+  }
+
+  #project(event) {
+    switch (event.op) {
+      case 'agent-registered':
+        return project.projectAgentRegistered(event);
+      case 'principal-registered':
+        return project.projectPrincipalRegistered(event);
+      case 'mandate-granted': {
+        const parentAgentDid = event.delegatedFromPolicyId
+          ? this.#grantedToAgent(event.delegatedFromPolicyId)
+          : null;
+        return project.projectMandateGranted(event, parentAgentDid);
+      }
+      case 'mandate-revoked':
+        return project.projectMandateRevoked(event);
+      case 'decision-recorded':
+        return project.projectDecisionRecorded(event);
+      case 'evidence-recorded': {
+        const matchingDecisionIriValue = event.decisionDigest ? this.#decisionForDigest(event.decisionDigest) : null;
+        return project.projectEvidenceRecorded(event, matchingDecisionIriValue);
+      }
+      case 'batch-anchored':
+        return project.projectBatchAnchored(event);
+      case 'cohort-shared':
+        return project.projectCohortShared(event);
+      case 'human-registered':
+        return project.projectHumanRegistered(event);
+      case 'issuer-registered':
+        return project.projectIssuerRegistered(event);
+      default:
+        throw new Error(`unknown mutation event op: ${event.op}`);
+    }
+  }
+
+  /** Resolves `mmt:grantedTo` for a parent mandate — the value-equality join delegation-created needs. */
+  #grantedToAgent(policyId) {
+    const iri = mandateIri(policyId).value;
+    const rows = [...this.#store.query(`PREFIX mmt: <${MMT}> SELECT ?agent WHERE { <${iri}> mmt:grantedTo ?agent }`)];
+    return rows.length > 0 ? rows[0].get('agent').value : null;
+  }
+
+  /** Resolves the mmt:AuthorizationDecision whose mmt:decisionDigest matches — the value-equality join evidence-recorded needs, mirroring #grantedToAgent. */
+  #decisionForDigest(digest) {
+    const rows = [
+      ...this.#store.query(
+        `PREFIX mmt: <${MMT}> SELECT ?d WHERE { ?d a mmt:AuthorizationDecision ; mmt:decisionDigest ${JSON.stringify(digest)} }`
+      ),
+    ];
+    return rows.length > 0 ? rows[0].get('d').value : null;
+  }
+
+  query(sparql) {
+    return this.#store.query(sparql);
+  }
+
+  /** Rebuilds from empty by re-applying every event in order — the log is the source of truth, the store is derived. */
+  replay(events) {
+    this.#store = new oxigraph.Store();
+    this.#log = [];
+    for (const event of events) this.apply(event);
+  }
+
+  get log() {
+    return [...this.#log];
+  }
+
+  /**
+   * Runs the SHACL shapes plus the §3 reachability ASK for every agent with a mandate.
+   * One combined report so callers don't need to reconcile two different result shapes.
+   */
+  async validate() {
+    const shapesStore = new oxigraph.Store();
+    shapesStore.load(SHAPES_TTL, { format: 'text/turtle' });
+    const shapesDataset = rdf.dataset([...shapesStore.match()]);
+    const dataDataset = rdf.dataset([...this.#store.match()]);
+    const validator = new SHACLValidator(shapesDataset, { factory: rdf });
+    const shapeReport = await validator.validate(dataDataset);
+
+    const unreachableAgents = [];
+    for (const row of this.#store.query(AGENTS_WITH_MANDATES)) {
+      const agentIriValue = row.get('agent').value;
+      if (!this.#store.query(REACHES_PRINCIPAL(agentIriValue))) unreachableAgents.push(agentIriValue);
+    }
+
+    return {
+      conforms: shapeReport.conforms && unreachableAgents.length === 0,
+      shapeViolations: shapeReport.results.map((r) => ({
+        focusNode: r.focusNode.value,
+        message: r.message?.[0]?.value ?? null,
+        path: r.path?.value ?? null,
+      })),
+      unreachableAgents,
+    };
+  }
+}