Morphism Architecture Overview

Source: overview.md (ingested 2026-03-28)

type: reference authority: canonical audience: [agents, contributors, integrators] last-verified: 2026-03-22 scope: architecture status: authoritative owner: platform-architecture code-paths:

apps/morphism/package.json
packages/cli/package.json
packages/sdk/package.json
packages/mcp-server/package.json
packages/agentic-math/package.json
packages/shared/package.json
packages/design-tokens/package.json
src/morphism/cli/main.py
src/morphism/review/engine.py
src/morphism/bridge/python_bridge.py
scripts/verify_pipeline.py
scripts/policy_check.py runtime-surfaces:
apps/morphism
packages/cli
packages/sdk
packages/mcp-server
packages/agentic-math
packages/shared
packages/design-tokens
src/morphism depends-on:
Clerk
Supabase
Stripe
Sentry
Vercel

Architecture Overview

Use this page for module boundaries and checked-in architecture contracts. For current provider inventory or dashboard-verified account state, use ../reference/integrations/platform-services.md.

Decision Rule

Only treat architecture claims here as authoritative when they are grounded in checked-in packages, routes, workflows, or schema. Adjacent tooling such as Pinecone indexing scripts is not part of the current product runtime unless it is also represented in the canonical integration docs.

System Overview

Morphism is a categorical governance framework split into:

Python core (src/morphism/) — governance engine, metrics, drift detection, healing
TypeScript packages (packages/) — CLI, SDK, MCP servers, math library, shared utilities, design tokens, plugin bundle
Next.js app (apps/morphism/) — dashboard, API routes, Clerk auth
Governance scripts (scripts/) — CI gates, validators, structural enforcement; verify_pipeline.py now matches required workflow actions by pattern (for example actions/checkout@vN) so the pipeline gate tracks presence without hardcoding a single stale major, and policy_check.py runs governance/delivery_surface_review.py --check in pre-push and CI orchestration

User / CI / MCP client
        |
        v
  +-- CLI / MCP Server (TS) --+
  |                            |
  |  morphism validate         |
  |  morphism review --gate    |
  |  MCP: governance_validate  |
  |                            |
  +------- calls --------+----+
                          |
                          v
            Python core (src/morphism/)
            +---------------------------+
            |  review/engine.py         | <-- orchestrator
            |    -> governance_category | <-- categorical validation
            |    -> healing/scanner     | <-- drift scan
            |    -> convergence         | <-- kappa computation
            |  governance/kernel.py     | <-- SSOT for constants
            |  metrics/governance_metric| <-- formal metric
            |  healing/drift_healer     | <-- auto-repair
            +---------------------------+
                     |
                     v
            .morphism/ (artifacts)
            +---------------------------+
            |  proofs/*.json            | <-- proof witnesses
            |  config.yaml              | <-- agent config
            |  ARTIFACT_REGISTRY.json   | <-- tracked artifacts
            |  evidence_ledger.json     | <-- evidence entries
            +---------------------------+

Module Map

Python Core (`src/morphism/`)

| Module | Responsibility | |--------|---------------| | governance/kernel.py | SSOT for all enforcement constants: objects, weights, thresholds, invariants, constraint types, verdict logic | | convergence.py | Kappa computation (weighted L-inf metric), convergence checks, robustness delta | | governance_category.py | 7 governance objects, 8 morphisms, categorical validation, naturality, sheaf analysis | | review/engine.py | Orchestrates validation + drift scan into unified ReviewResult; computes verdict | | review/models.py | Pydantic models: Severity, Verdict (PASS/WARN/HEDGE/FAIL), EvidenceRef, ReviewIssue, ReviewResult, GateResult | | review/formatters.py | Output formatting for CLI (text, JSON, Mermaid) | | healing/scanner.py | DriftScanner: detects 5 drift types (frontmatter, stale dates, broken links, missing invariant refs, encoding) | | healing/drift_healer.py | DriftHealer: confidence-gated auto-repair with adaptive thresholds | | healing/cech_complex.py | Cech complex and H1 cohomology for sheaf drift analysis | | metrics/governance_metric.py | GovernanceState, GovernanceMetric, kappa, delta, entropy, maturity levels, convergence certificates | | governance/extended_compliance_functor.py | Formal functor F: Governance -> Verification with law verification | | agents/classifier.py | Maps files to owning agents via glob patterns from config.yaml | | engine/naturality_bridge.py | Checks naturality squares for governance morphisms | | engine/functors.py | Category theory primitives: Functor, Morphism | | sheaf/cech_complex.py | Sheaf cohomology computation | | bridge/python_bridge.py | JSON-RPC bridge for TS -> Python calls | | bridge/crypto_signer.py | Ed25519 signing/verification for witness payloads | | cli/main.py | Python-side CLI entry point |

TypeScript Packages

| Package | Modules | Purpose | |---------|---------|---------| | @morphism-systems/cli | validate, score, doctor, status, diff, scaffold, entropy, init, dashboard | User-facing CLI wrapping Python backend; the scaffold command now derives its default project name from the current working-directory basename so path handling stays consistent across Windows and POSIX shells | | @morphism-systems/sdk | client, validation, scoring, helpers | Programmatic SDK surface for integrating Morphism into external tools and apps | | @morphism-systems/mcp-server | server, governance-loop, governance-tools, tools/{kappa,delta,entropy,score,ssot,validate} | MCP server exposing governance tools to AI agents | | @morphism-systems/agentic-math | categorical-encoder, naturality-bridge, proof-artifact, witness-compressor, crypto-signer, engine/{convergence,functor,morphism,natural-transformation} | Category theory math library + MCP math server | | @morphism-systems/shared | types, schemas, supabase, csrf, encryption, rate-limit, stripe, ai | Shared utilities for Next.js app | | @morphism-systems/design-tokens | 10 themes, registry, types | Design token system | | @morphism-systems/plugin-bundle | installers/{config,hooks,mcp} | Plugin installer for IDE integration |

Next.js App (`apps/morphism/`)

| Layer | Key files | |-------|-----------| | Dashboard pages | (dashboard)/dashboard/{page,governance/{page,drift/page,proofs/page},agents/page,assessments/page,policies/page,settings/page,billing/page} | | API routes | api/governance/{route,heal/route,proofs/route}, api/agents/route, api/assessments/route, api/keys/route, api/billing/{checkout,portal}/route | | Auth | Clerk middleware, @clerk/nextjs/server auth() guards on protected routes | | Components | governance-score.tsx, ui/{card,badge,button} |

Current app-level verification scripts in apps/morphism/package.json:

npm run test:e2e builds once, then runs the built-server Playwright suite
npm run test:e2e:live builds once, then runs the gated live Clerk + Stripe verifier

Data Flow: Governance Gate

A morphism review --gate call follows this path:

CLI (packages/cli/src/commands/validate.ts) spawns Python subprocess
Python ReviewEngine.gate() is invoked
Engine calls full_categorical_validation(root) which:
- Enumerates 7 governance objects and 8 morphisms
- Runs runtime verification predicates per object
- Builds governance vector s in [0,1]^7
- Computes kappa = d_inf(s, ideal)
- Checks naturality squares
- Runs sheaf (Cech complex) H1 cohomology
- Returns {kappa, governance_vector, naturality, sheaf, categorical_errors, all_valid}
Engine calls scan_repo(root) for drift detection
All findings merged into list[ReviewIssue], each tagged with:
- source (drift/categorical/naturality/sheaf)
- severity (low/medium/high/critical)
- evidence (EvidenceRef with kind + location)
- agents (owning agents from classifier)
_compute_verdict() applies kernel rules:
- FAIL if any critical issue OR kappa > ceiling
- HEDGE if confidence < 2.0 (low confidence)
- WARN if issues within bounds
- PASS if all_valid and no issues
GateResult returned with exit_code (0=pass, 1=fail, 2=error)

Key Constants (from `governance/kernel.py`)

| Constant | Value | Purpose | |----------|-------|---------| | GOVERNANCE_OBJECTS | 7 (Policy, GitHook, CIWorkflow, SSOTAtom, Document, SecurityGate, Runbook) | Dimensions of governance vector | | GOVERNANCE_WEIGHTS | Policy=1.5, SecurityGate=1.5, GitHook=1.2, CIWorkflow=1.2, SSOTAtom=1.0, Runbook=0.9, Document=0.8 | L-inf metric weights | | THRESHOLD_KAPPA | low=1.5, medium=1.0, high=0.5, critical=0.25 | Gate thresholds | | HEDGE_CONFIDENCE_THRESHOLD | 2.0 | Below this -> HEDGE verdict | | KERNEL_INVARIANTS | I-1..I-7 | Seven kernel invariants |

Verdict Semantics

| Verdict | Meaning | Gate behavior | |---------|---------|---------------| | PASS | Clean, all valid | exit_code=0 | | WARN | Issues found but within threshold | exit_code=0 | | HEDGE | Low confidence, needs additional verification | exit_code=0 | | FAIL | Critical issue or kappa ceiling breach | exit_code=1 |

Constraint Classification

| Type | Examples | Gate effect | |------|----------|-------------| | HARD | Critical severity, kappa ceiling, sheaf incompatibility | Always FAIL | | SOFT | Issues within bounds, categorical invalid, low confidence | WARN or HEDGE |

Current Runtime And Adjacent Services

| Service | Integration | |---------|------------| | Clerk | Auth for API routes and dashboard | | Supabase | Agent, assessment, policy, billing-linked, and storage metadata surfaces with RLS context helpers | | Stripe | Billing checkout, portal, and webhook-driven plan state | | Sentry | Runtime error capture and release-time observability when DSN is configured | | Vercel | Preview, staging, and production hosting plus deploy automation | | Pinecone | Adjacent/historical governance indexing scripts exist under scripts/governance/, but this is not part of the current app runtime contract |

Morphism Architecture Overview

Morphism Architecture Overview

Architecture Overview

Decision Rule

System Overview

Module Map

Python Core (src/morphism/)

TypeScript Packages

Next.js App (apps/morphism/)

Data Flow: Governance Gate

Key Constants (from governance/kernel.py)

Verdict Semantics

Constraint Classification

Current Runtime And Adjacent Services

Python Core (`src/morphism/`)

Next.js App (`apps/morphism/`)

Key Constants (from `governance/kernel.py`)