@metamynd/mmt-graph 0.2.0

package/mmt-graph.types.mjs

@@ -0,0 +1,207 @@
+/**
+ * The mutation-event vocabulary the engine consumes. Anchor-compatible from day one: a
+ * discriminated `{op, ...}` envelope (matching magp-hcs2's convention) carrying only the
+ * fields the projector needs — not full DB rows — the same additive-only discipline
+ * evidence leaves already follow (see evidence-batch.ts's canonical()). Where an event
+ * comes from (a Postgres trigger, a migration script, HCS replay) is Phase 2/3, not here.
+ *
+ * These map onto real `Policy`/`AgentIdentity`/`Principal` rows one-for-one — see
+ * docs/design/metamynd-trust-ontology.md domains A/C for the grounding. Notably, a
+ * delegated mandate is NOT a separate concept from a root mandate: `Policy` carries
+ * delegation fields (`delegatedFromPolicyId`, `delegationDepth`) on the same row as the
+ * mandate itself, so `MandateGranted` carries them as optional fields rather than being a
+ * distinct event type.
+ */
+
+/**
+ * `principalDid` on AgentRegistered is the agent's HOME organisation (AgentIdentity.
+ * organizationPrincipalId in accountability.ts) — a structural fact independent of any
+ * mandate, distinct from `mmt:actsFor` (which domain A already defines as the root
+ * mandate's principalDid). Phase 5's fifth slice (mmt-graph.accountability.mjs) projects
+ * this onto `mmt:memberOf`, reusing the exact relationship the fourth slice's
+ * organization/unit cohorts already established for the same underlying field — see that
+ * slice's note in mmt-graph.project.mjs for why memberOf and actsFor must not be conflated.
+ */
+/** @typedef {{ op: 'agent-registered', agentDid: string, kind?: string, principalDid?: string }} AgentRegistered */
+/**
+ * The verification/`authorizedRepUserId` fields are a snapshot of the Principal row at
+ * event time, not a separate lifecycle event — the same "current-state field on a
+ * recording event" shape evidenceRecorded/batchAnchored already use for anchorStatus,
+ * chosen for the same reason: this package proves graph shape, not full temporal
+ * event-sourcing of every state transition.
+ */
+/**
+ * @typedef {{
+ *   op: 'principal-registered',
+ *   principalDid: string,
+ *   principalType?: string,
+ *   verificationStatus?: string,
+ *   assuranceLevel?: string,
+ *   verificationExpiresAt?: string,
+ *   authorizedRepUserId?: string,
+ * }} PrincipalRegistered
+ */
+/**
+ * `expiresAt`, added in Phase 5's sixth slice, is Policy.expiresAt — needed for
+ * blast-radius.ts's live/expired split (`isLive`), which the earlier slices never needed
+ * (evidence-path and accountability don't gate on mandate liveness). Absent means no
+ * expiry, not expired — same rule as the real `isLive`.
+ */
+/**
+ * @typedef {{
+ *   op: 'mandate-granted',
+ *   policyId: string,
+ *   agentDid: string,
+ *   principalDid?: string,          // set on a root mandate (Policy.principalDid)
+ *   delegatedFromPolicyId?: string, // set on a delegated mandate (Policy.delegatedFromPolicyId)
+ *   delegationDepth?: number,       // set alongside delegatedFromPolicyId, 1..MAX_DELEGATION_DEPTH
+ *   expiresAt?: string,             // Policy.expiresAt, ISO — absent means no expiry
+ * }} MandateGranted
+ */
+/** @typedef {{ op: 'mandate-revoked', policyId: string }} MandateRevoked */
+
+/**
+ * Domain H (runtime activity/evidence) — Phase 5's first slice, proving the engine can
+ * answer evidence-path.ts's "independently verifiable" question, not a full replacement
+ * of it (see mmt-graph.evidence-path.mjs's header). Grounded in the real fields
+ * evidence-path.ts/evidence.model.ts actually use, same additive-only discipline as the
+ * other event types above — not the full DB row.
+ */
+/**
+ * `agentDid`, added in Phase 5's fifth slice, is the decision's actor — the edge
+ * accountability.ts's own graph builder already calls `decided-for`, adopted here as
+ * `mmt:decidedFor` since Domain H names no equivalent predicate (see
+ * mmt-graph.accountability.mjs).
+ */
+/** @typedef {{ op: 'decision-recorded', decisionId: string, decisionDigest?: string, agentDid?: string }} DecisionRecorded */
+/** @typedef {{ op: 'evidence-recorded', eventId: string, decisionDigest?: string, anchorStatus?: string }} EvidenceRecorded */
+/** @typedef {{ op: 'batch-anchored', batchId: string, memberEventIds: string[], anchorStatus?: string }} BatchAnchored */
+
+/**
+ * Domain F (governance) — Phase 5's second slice, proving the engine can answer
+ * contagion.ts's cohort-specificity question (see mmt-graph.contagion.mjs's header).
+ * `sop`/`standard` share one pattern in the real algorithm (`buildKeyed` in contagion.ts,
+ * keyed via a junction table). `organization`/`unit` (Phase 5's fourth slice) use a
+ * different shape (`buildSingle`, keyed off
+ * AgentIdentity.organizationPrincipalId/operatingUnitId — a direct FK, not a junction
+ * table) but the SAME event/projector mechanism — see mmt-graph.project.mjs's
+ * projectCohortShared for why `organization`/`unit` additionally assert `mmt:memberOf`,
+ * the real Domain A relationship, alongside the mechanical `mmt:sharesCohort` edge.
+ */
+/** @typedef {{ op: 'cohort-shared', agentDid: string, kind: 'sop' | 'standard' | 'organization' | 'unit', key: string, label: string, version?: number }} CohortShared */
+
+/**
+ * Domain A — Phase 5's fifth slice, proving the engine can answer accountability.ts's "who
+ * is answerable" question (see mmt-graph.accountability.mjs's header). `mmt:Human` is named
+ * in domain A's actor taxonomy but was `[PROPOSED]`/unimplemented until now; humans have no
+ * DID, so `userId` mints a synthetic IRI the same way `mandateIri`/`decisionIri` do for
+ * their own non-DID identifiers.
+ */
+/** @typedef {{ op: 'human-registered', userId: string, email: string, firstName?: string, lastName?: string }} HumanRegistered */
+
+/**
+ * Domain A/B — Phase 5's sixth slice, proving the engine can answer blast-radius.ts's
+ * "who does this issuer's tier depend on, and what breaks if it lapses" question (see
+ * mmt-graph.blast-radius.mjs's header). `mmt:Issuer` is the one genuinely new class this
+ * package adds — the W3C VC Data Model's own term, not invented, since `issuer.model.ts`'s
+ * `did` field means an issuer is exactly as IRI-able as an agent or a principal. `did` is
+ * required, not `issuerId`: same reasoning as agentIri/principalIri using the DID itself as
+ * the node's IRI rather than minting a synthetic one.
+ */
+/** @typedef {{ op: 'issuer-registered', did: string, name?: string, principalDid?: string }} IssuerRegistered */
+
+const COHORT_KINDS = ['sop', 'standard', 'organization', 'unit'];
+
+/** The bound this engine enforces on delegationDepth — mirrors policy-core/delegation.ts's MAX_DELEGATION_DEPTH. */
+export const MAX_DELEGATION_DEPTH = 3;
+
+function requireFields(event, fields) {
+  const missing = fields.filter((f) => event[f] === undefined || event[f] === null);
+  if (missing.length > 0) throw new Error(`${event.op}: missing required field(s): ${missing.join(', ')}`);
+}
+
+/** @returns {AgentRegistered} */
+export function agentRegistered({ agentDid, kind, principalDid }) {
+  const ev = { op: 'agent-registered', agentDid, kind, principalDid };
+  requireFields(ev, ['agentDid']);
+  return ev;
+}
+
+/** @returns {PrincipalRegistered} */
+export function principalRegistered({
+  principalDid,
+  principalType,
+  verificationStatus,
+  assuranceLevel,
+  verificationExpiresAt,
+  authorizedRepUserId,
+}) {
+  const ev = { op: 'principal-registered', principalDid, principalType, verificationStatus, assuranceLevel, verificationExpiresAt, authorizedRepUserId };
+  requireFields(ev, ['principalDid']);
+  return ev;
+}
+
+/** @returns {MandateGranted} */
+export function mandateGranted({ policyId, agentDid, principalDid, delegatedFromPolicyId, delegationDepth, expiresAt }) {
+  const ev = { op: 'mandate-granted', policyId, agentDid, principalDid, delegatedFromPolicyId, delegationDepth, expiresAt };
+  requireFields(ev, ['policyId', 'agentDid']);
+  if (delegatedFromPolicyId && (delegationDepth === undefined || delegationDepth === null)) {
+    throw new Error(`mandate-granted for ${policyId}: delegatedFromPolicyId set without delegationDepth`);
+  }
+  if (delegationDepth !== undefined && (delegationDepth < 1 || delegationDepth > MAX_DELEGATION_DEPTH)) {
+    throw new Error(`mandate-granted for ${policyId}: delegationDepth ${delegationDepth} outside 1..${MAX_DELEGATION_DEPTH}`);
+  }
+  return ev;
+}
+
+/** @returns {MandateRevoked} */
+export function mandateRevoked({ policyId }) {
+  const ev = { op: 'mandate-revoked', policyId };
+  requireFields(ev, ['policyId']);
+  return ev;
+}
+
+/** @returns {DecisionRecorded} */
+export function decisionRecorded({ decisionId, decisionDigest, agentDid }) {
+  const ev = { op: 'decision-recorded', decisionId, decisionDigest, agentDid };
+  requireFields(ev, ['decisionId']);
+  return ev;
+}
+
+/** @returns {EvidenceRecorded} */
+export function evidenceRecorded({ eventId, decisionDigest, anchorStatus }) {
+  const ev = { op: 'evidence-recorded', eventId, decisionDigest, anchorStatus };
+  requireFields(ev, ['eventId']);
+  return ev;
+}
+
+/** @returns {BatchAnchored} */
+export function batchAnchored({ batchId, memberEventIds, anchorStatus }) {
+  const ev = { op: 'batch-anchored', batchId, memberEventIds, anchorStatus };
+  requireFields(ev, ['batchId', 'memberEventIds']);
+  return ev;
+}
+
+/** @returns {CohortShared} */
+export function cohortShared({ agentDid, kind, key, label, version }) {
+  const ev = { op: 'cohort-shared', agentDid, kind, key, label, version };
+  requireFields(ev, ['agentDid', 'kind', 'key', 'label']);
+  if (!COHORT_KINDS.includes(kind)) {
+    throw new Error(`cohort-shared: kind must be one of ${COHORT_KINDS.join(', ')} (got "${kind}")`);
+  }
+  return ev;
+}
+
+/** @returns {HumanRegistered} */
+export function humanRegistered({ userId, email, firstName, lastName }) {
+  const ev = { op: 'human-registered', userId, email, firstName, lastName };
+  requireFields(ev, ['userId', 'email']);
+  return ev;
+}
+
+/** @returns {IssuerRegistered} */
+export function issuerRegistered({ did, name, principalDid }) {
+  const ev = { op: 'issuer-registered', did, name, principalDid };
+  requireFields(ev, ['did']);
+  return ev;
+}

package/package.json

@@ -0,0 +1,75 @@
+{
+  "name": "@metamynd/mmt-graph",
+  "version": "0.2.0",
+  "type": "module",
+  "description": "Reference trust-graph engine (Oxigraph/SPARQL + SHACL) + HCS-anchor contract: apply mutation events, validate the MMTO §3 authority-chain invariant, batch the changelog into a Merkle root ready to anchor, and verify a disclosed tenant graph with MetaMynd fully offline. Hosting-mode-agnostic — no MetaMynd backend, no Postgres, no MetaMynd credentials anywhere in the code path. See docs/design/metamynd-trust-ontology.md Appendix C.",
+  "main": "mmt-graph.engine.mjs",
+  "exports": {
+    ".": "./mmt-graph.engine.mjs",
+    "./types": "./mmt-graph.types.mjs",
+    "./project": "./mmt-graph.project.mjs",
+    "./changelog": "./mmt-graph.changelog.mjs",
+    "./anchor": "./mmt-graph.anchor.mjs",
+    "./evidence-path": "./mmt-graph.evidence-path.mjs",
+    "./contagion": "./mmt-graph.contagion.mjs",
+    "./accountability": "./mmt-graph.accountability.mjs",
+    "./blast-radius": "./mmt-graph.blast-radius.mjs",
+    "./auditor": "./mmt-graph.auditor.mjs"
+  },
+  "bin": {
+    "mmt-graph-auditor": "mmt-graph.auditor-cli.mjs"
+  },
+  "files": [
+    "mmt-graph.types.mjs",
+    "mmt-graph.project.mjs",
+    "mmt-graph.shapes.ttl",
+    "mmt-graph.engine.mjs",
+    "mmt-graph.merkle.mjs",
+    "mmt-graph.changelog.mjs",
+    "mmt-graph.anchor.mjs",
+    "mmt-graph.anchor-live-demo.mjs",
+    "mmt-graph.evidence-path.mjs",
+    "mmt-graph.contagion.mjs",
+    "mmt-graph.accountability.mjs",
+    "mmt-graph.blast-radius.mjs",
+    "mmt-graph.auditor.mjs",
+    "mmt-graph.auditor-cli.mjs",
+    "mmt-graph.self-host-quickstart.mjs",
+    "README.md"
+  ],
+  "scripts": {
+    "spike": "node mmt-graph.spike.mjs",
+    "test": "node mmt-graph.test.mjs && node mmt-graph.merkle.test.mjs && node mmt-graph.changelog.test.mjs && node mmt-graph.anchor.test.mjs && node mmt-graph.evidence-path.test.mjs && node mmt-graph.contagion.test.mjs && node mmt-graph.accountability.test.mjs && node mmt-graph.blast-radius.test.mjs && node mmt-graph.auditor.test.mjs",
+    "anchor-live-demo": "node mmt-graph.anchor-live-demo.mjs",
+    "auditor": "node mmt-graph.auditor-cli.mjs",
+    "self-host-quickstart": "node mmt-graph.self-host-quickstart.mjs"
+  },
+  "dependencies": {
+    "@zazuko/env-node": "^3.1.0",
+    "oxigraph": "^0.5.5",
+    "rdf-validate-shacl": "^0.6.5"
+  },
+  "devDependencies": {
+    "@hashgraph/sdk": "^2.81.0",
+    "dotenv": "^17.4.2"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "metamynd",
+    "trust-graph",
+    "rdf",
+    "sparql",
+    "shacl",
+    "ontology",
+    "mmto",
+    "hedera",
+    "hcs",
+    "agent-governance",
+    "self-hosted",
+    "verifiable"
+  ],
+  "author": "MetaMynd",
+  "license": "MIT"
+}