HigherGraphen

HigherGraphen is an AI-native higher-structure framework for products and tools whose primary operator may be an AI agent rather than a human using screens and forms.

Most software products have been shaped around human cognitive limits: UI screens, CRUD flows, dashboards, reports, tickets, and workflows. Those are still useful human projections, but they are not the only useful product model when AI agents can operate structured concepts directly.

HigherGraphen generalizes ordinary graphs into spaces of cells, complexes, contexts, morphisms, invariants, obstructions, completions, projections, and interpretation packages. These higher-order concepts become first-class operational objects for AI agents.

What This Is

HigherGraphen is a structural substrate for AI-operated software development. It is not a UI framework, ticket tracker, knowledge base, or architecture diagramming tool by itself. It is the layer underneath those products that turns domain material into AI-operable structure:

• Cases and work graphs.
• Evidence, provenance, confidence, and review status.
• Invariants that must be preserved.
• Obstructions that explain why a change, interpretation, or workflow cannot safely proceed.
• Completion candidates that represent plausible missing structure without silently promoting them to accepted fact.
• Projections for humans, AI agents, audits, and other consumers.
• Interpretation packages that map a domain onto the shared higher-structure core.

The practical goal is to let AI agents operate on the structure directly while humans receive reports, dashboards, and review surfaces as projections.

Higher-Order Concepts

HigherGraphen uses the following product-level concepts as AI-operable objects:

• Space: the bounded structural world under analysis, such as a codebase, project, incident, contract, feed, or research corpus.
• Cell: a unit inside that world. A cell may represent an entity, relation, observation, constraint, or higher-order relation.
• Complex: an organized structure of cells and incidences. It represents relationships that are richer than ordinary node-edge graphs.
• Context: a local region where vocabulary, validity, or rules apply. This lets the system represent cases where local structures are valid but do not compose cleanly into a global structure.
• Morphism: a structure-preserving or structure-transforming map, such as a lift, projection, migration, interpretation, or comparison.
• Invariant: a property that should remain true across changes or interpretations.
• Obstruction: a structured reason that something cannot hold, proceed, or be accepted safely.
• CompletionCandidate: a plausible missing structure proposed by a system or AI agent, kept separate from accepted fact until review.
• Projection: a purpose-specific view for humans, AI agents, audits, CLI output, or other consumers, with declared information loss.
• InterpretationPackage: the domain-specific meaning layer that maps a product domain onto the shared higher-structure core.

These are not only internal implementation types. They are product concepts that an AI agent can inspect, operate, validate, and pass through workflows.

Mathematical Influences

HigherGraphen does not require users to know advanced mathematics. The project borrows structural ideas from several fields and turns them into engineering objects that AI agents can inspect and operate.

• Graphs and hypergraphs inform how ordinary relations and simultaneous multi-entity relations are represented.
• Cell complexes and simplicial complexes inform how points, edges, faces, higher-dimensional cells, boundaries, and holes can be modeled.
• Category theory and morphisms inform transformations, composition, preservation, distortion, and loss between structures.
• Sheaf-inspired local-to-global modeling informs how locally valid contexts can fail to glue into a consistent global picture.
• Topology and obstruction theory inform how missing regions, holes, impossibility, and blocked progress are represented structurally.
• Type theory, contracts, and invariants inform how invalid states are prevented or detected.
• Provenance and evidence modeling inform the distinction between observation, claim, AI inference, reviewable candidate, and accepted conclusion.

The detailed theory-to-engineering mapping lives in docs/concepts/theoretical-foundations.md.

Why HigherGraphen Exists

AI agents can read documents, logs, code, tickets, API responses, and tabular data. Reading is not enough when the target world contains:

• Problems that emerge only from three or more entities at once.
• Local structures that are individually valid but globally inconsistent.
• Meaning or constraints that are lost during transformation.
• Invariants that must remain true after change.
• Unverified or undefined regions of a state space.
• Concepts whose meaning changes by context.
• Structural analogies rather than surface-level similarity.
• Mixed observations, human claims, AI-generated inferences, and accepted conclusions.

HigherGraphen exists because AI-operated products can expose these structures directly. A human-facing report becomes a projection from the structure, not the whole system model.

What You Can Build With HigherGraphen

HigherGraphen is not limited to one product category. It is a substrate for turning domain material into AI-operable structures: cases, evidence, invariants, obstructions, completions, projections, and interpretation packages.

Examples of products that can be built on top of it:

• Architecture review products that lift design documents and code structure into components, boundaries, invariants, violations, obstructions, completion candidates, and review projections.
• AI coding governance tools that track AI-performed changes as cases with evidence, decisions, blockers, review state, and invariant checks instead of treating code diffs as the only durable record.
• Incident analysis products that connect logs, metrics, deploys, investigation notes, candidate causes, missing evidence, and prevention actions.
• Research and knowledge synthesis tools that separate observations, claims, AI inferences, contradictions, correspondence, and accepted conclusions.
• Contract and policy review products that represent obligations, exceptions, undefined terms, conflicts, risks, and reviewable completion candidates.
• Project and roadmap reasoning tools that expose goals, tasks, decisions, dependencies, blockers, and verification evidence as an agent-operable case graph.
• Feed and signal intelligence products that treat feeds, news, issues, notifications, and other source material as source-contexted observations with correspondences, gaps, obstructions, and projections.

In each case, the human-facing product may still look like a report, review screen, dashboard, or CLI output. The difference is that those surfaces are projections from a richer structure that an AI agent can inspect and operate.

Operator Paradigm

The central product shift is:

Human-operated product:
  Product model is constrained by what humans can manually inspect and operate.

AI-operated product:
  Product model can expose higher-order structure directly, then project it
  into human views when needed.

This is why HigherGraphen treats concepts such as Invariant, Obstruction, CompletionCandidate, Morphism, Context, and Projection as product-level objects rather than hidden implementation details.

Release And Install

The latest release is v0.4.1. It includes Darwin arm64 binaries for:

• casegraphen
• highergraphen

Cargo packages are configured for registry packaging. After the package publication step, install the CLI surfaces with:

cargo install highergraphen-cli
cargo install casegraphen

Library consumers can depend on the workspace crates directly, for example:

[dependencies]
higher-graphen-core = "0.4.1"
higher-graphen-runtime = "0.4.1"

Publish reusable crates before dependent crates and CLI tools:

cargo publish -p higher-graphen-core
cargo publish -p higher-graphen-structure
cargo publish -p higher-graphen-projection
cargo publish -p higher-graphen-evidence
cargo publish -p higher-graphen-reasoning
cargo publish -p higher-graphen-interpretation
cargo publish -p higher-graphen-runtime
cargo publish -p casegraphen
cargo publish -p highergraphen-cli

The example workspace packages remain unpublished validation fixtures. To build locally from source, use Cargo from the repository root:

cargo build --workspace --release --locked

What You Can Run Today

The repository already includes a Rust workspace, core crates, schemas, reference examples, and two CLI surfaces:

cargo run -q -p highergraphen-cli -- \
  architecture smoke direct-db-access --format json

This emits a deterministic Architecture Product report showing an invariant violation, obstruction, completion candidate, provenance, and projections.

cargo run -q -p casegraphen -- \
  workflow reason \
  --input schemas/casegraphen/workflow.graph.example.json \
  --format json

This emits a CaseGraphen workflow reasoning report over a structured workflow graph.

Native CaseGraphen case management is also available through the repo-owned casegraphen CLI:

cargo run -q -p casegraphen -- \
  case import \
  --store /tmp/casegraphen-native-store \
  --input schemas/casegraphen/native.case.space.example.json \
  --revision-id revision:native-reference-imported \
  --format json

After import, derive native reasoning views from the replayed CaseSpace plus MorphismLog:

cargo run -q -p casegraphen -- case reason --store /tmp/casegraphen-native-store --case-space-id case_space:native-case-management-contract --format json
cargo run -q -p casegraphen -- case close-check --store /tmp/casegraphen-native-store --case-space-id case_space:native-case-management-contract --base-revision-id revision:native-reference-imported --validation-evidence-id evidence:native-schema-json-valid --format json

The DDD diagnostic example uses the same native report surface to review a Sales/Billing Customer domain model decision:

cargo run -q -p casegraphen -- \
  case import \
  --store /tmp/casegraphen-ddd-store \
  --input examples/casegraphen/ddd/domain-model-design/sales-billing-customer.case.space.json \
  --revision-id revision:ddd-sales-billing-imported \
  --format json

Then run:

cargo run -q -p casegraphen -- case reason --store /tmp/casegraphen-ddd-store --case-space-id case_space:ddd-sales-billing-demo --format json

The expected result is a blocked domain model decision with boundary semantic loss, missing accepted evidence, unreviewed completion candidates, and projection loss represented as successful JSON report data.

CaseGraphen As The First Real Case

CaseGraphen is the first concrete system built inside this repository from the HigherGraphen thesis. It is not only an example file format or a side utility; it is a real intermediate tool for representing complex, evidence-heavy, decision-rich work as case graphs and workflow graphs.

AI-operated software development is the first reference domain, but the abstraction is not limited to software development. CaseGraphen fits work where goals, tasks, decisions, evidence, unresolved questions, blockers, completions, reviews, and future projections need to remain inspectable over time.

CaseGraphen makes the product thesis inspectable:

• tools/casegraphen/ provides a CLI that reasons over cases, evidence, tasks, blockers, completions, projections, and workflow state.
• schemas/casegraphen/ defines the structured contracts that make those concepts machine-checkable.
• skills/casegraphen/SKILL.md gives AI agents an operating protocol for reading and authoring CaseGraphen workspaces.
• examples/casegraphen/reference/ shows a runnable reference workflow graph and report.
• examples/casegraphen/native/ shows the native CaseSpace plus MorphismLog case management flow.
• examples/casegraphen/ddd/domain-model-design/ remains the legacy fixture that motivates the product-facing DDD review workflow.
• skills/highergraphen-ddd/SKILL.md gives AI agents an operating protocol for highergraphen ddd review reports.

This matters because it demonstrates the intended direction of HigherGraphen: complex work is not reduced to a human-facing issue list, document, dashboard, or command history. Goals, decisions, evidence, obstructions, completions, reviews, and future projections become first-class structures that an AI agent can inspect and operate directly.

The current CaseGraphen surface is specified in docs/specs/intermediate-tools/casegraphen.md, docs/specs/intermediate-tools/casegraphen-workflow-contracts.md, docs/specs/intermediate-tools/casegraphen-feature-completion-contract.md, and docs/specs/intermediate-tools/casegraphen-native-case-management.md.

Status

This repository is an early public implementation. It contains the core Rust workspace, package boundaries, report schemas, CLI contracts, reference product packages, public examples, native CaseGraphen case management, and CaseGraphen CLI and skill surfaces.

The implementation is still evolving. The most stable entry point is the reference Architecture Product smoke report. The broader goal is to make the case, evidence, obstruction, completion, projection, and interpretation-package surfaces robust enough for AI agents to use directly.

How To Read This Repository

If you are new to HigherGraphen, start here:

1. Read this README for the product model and current runnable surfaces.
2. Read docs/concepts/ai-operator-paradigm.md for the reason HigherGraphen is shaped around AI operators.
3. Run the Architecture Product smoke command above and inspect the JSON report.
4. Run the CaseGraphen workflow reasoning command above and inspect examples/casegraphen/reference/.
5. Run the native CaseGraphen examples when you want to see CaseSpace and MorphismLog in action, or run the highergraphen ddd workflow when you want DDD evidence boundaries, completion candidates, projection loss, and closeability in a product CLI report.
6. Use docs/index.md when you want the full specification reading order.

License And Commercial Boundary

HigherGraphen's public core is licensed under the Apache License 2.0.

Copyright 2026 CAPH TECH Inc.

The public repository is intended to contain the shared higher-structure core, baseline intermediate tools, schemas, documentation, public examples, skills, and reference workflows. Production interpretation packages, hosted execution, customer-specific assets, private evaluation datasets, commercial strategy, and private operations material belong outside this public repository unless they are explicitly open-sourced later.

See COMMERCIAL_BOUNDARY.md for the publication boundary.

Documentation

• docs/index.md - Documentation index and reading order
• docs/overview.md - Product overview and positioning
• docs/concepts/ai-operator-paradigm.md - Why AI-operated products can use higher-order structure directly
• docs/concepts/core-concepts.md - Core vocabulary
• docs/concepts/higher-structure-model.md - Structural model
• docs/concepts/theoretical-foundations.md - Theoretical foundations used as engineering primitives
• docs/specs/package-boundaries.md - Package and repository boundaries
• docs/specs/intermediate-tools-map.md - Core packages and intermediate *graphen tools
• docs/specs/intermediate-tools/casegraphen.md - CaseGraphen intermediate tool specification
• docs/specs/intermediate-tools/casegraphen-workflow-contracts.md - CaseGraphen workflow contracts
• docs/specs/intermediate-tools/casegraphen-native-case-management.md - Native CaseGraphen CaseSpace and MorphismLog case management contract
• examples/casegraphen/reference/README.md - CaseGraphen reference workflow example
• examples/casegraphen/native/README.md - Native CaseGraphen reference flow
• examples/casegraphen/ddd/domain-model-design/README.md - Legacy DDD domain model fixture that motivates the HigherGraphen DDD review workflow
• docs/specs/ddd-review-cli-contract.md - HigherGraphen DDD review CLI contract
• docs/specs/ai-agent-integration.md - Skills, plugins, MCP, and marketplace integration strategy
• skills/highergraphen/SKILL.md - Repository-owned CLI skill for the first HigherGraphen report contract
• skills/highergraphen-ddd/SKILL.md - Repository-owned DDD review CLI skill
• skills/casegraphen/SKILL.md - Repository-owned CaseGraphen CLI skill
• skills/release-runner/SKILL.md - Repository-owned release preparation and publication skill
• docs/specs/rust-core-model.md - Rust core data model specification
• docs/specs/engine-traits.md - Engine interface specification
• docs/product-packages/architecture-product.md - Reference Architecture Product
• docs/product-packages/domain-products.md - Additional domain products
• docs/mvp-roadmap.md - MVP scope, roadmap, and success criteria
• docs/source-trace.md - Trace from proposal sections to official documents
• docs/adr/0001-rust-first-polyglot-friendly.md - Architecture decision record
• COMMERCIAL_BOUNDARY.md - Public/commercial repository boundary

Design Principle

HigherGraphen treats each concrete product as an interpretation package over a shared higher-structure core:

Product = Interpretation Package over Higher Structure

The goal is to avoid rebuilding a reasoning foundation for every product. The core supplies structural primitives and engines. Domain packages supply vocabulary, mappings, invariants, completion rules, and projections.

Layer Model

HigherGraphen is organized into three layers:

Level 0: Higher Structure Core
  Space, Cell, Complex, Context, Morphism, Invariant, Obstruction,
  Completion, Projection, and related primitives.

Level 1: Intermediate Abstract Tools
  Case, morphism, context, obstruction, completion, invariant, evidence,
  projection, correspondence, evolution, and interpretation tooling.

Level 2: Domain Products
  Architecture, contract, project, incident, research, governance, feed
  analysis, and other concrete products.

Human-facing UI, reports, dashboards, and summaries should be treated as projections over this structure. Agent-facing CLI, schemas, skills, and future MCP surfaces should preserve the underlying structure so agents can inspect provenance, candidates, obstructions, invariants, and information loss directly.