A domain neutral semantic framework for representing governing instruments (contracts, protocols, agreements, etc) and the obligations, eligibility conditions, and lifecycle behaviours they define, as structured, queryable, versioned graphs.
New to this repository? Getting Started bootstraps a clean clone end to end. The Developer Guide covers every tool and script and when to use it. docs/diagrams/ pictures the whole architecture, five ways.
As a project, Lattice has been organised to allow users to pick and choose the parts they want without depending on everything. Lattice provides ontologies, libraries, deployable services, and control-plane infrastructure the way a framework does, and is not a standalone application.
An adopter is free to take some of it, all of it, or build around it entirely, and the parts they do take, they configure for their own domain and their own operational constraints.
| Part | Purpose |
|---|---|
| Ontology Substrates | The ontologies in the substrate layers can be used together or standalone, to develop domain ontologies with consistent semantics inherited from these upper ontologies. |
| Applied Ontology Layers | Pre-built domain ontologies with a focus on a specifc subject area, industry, or goal/usage |
| Tools | Tools that operate on both the internal substrates (upper ontologies), applied ontologies, and a user's own domain ontologies |
| Platform (design time) | Capabilities that offer design support and administrative tooling for users of Lattice |
| Platform (runtime) | Software infrastructure, services, and applications that support building complex ontology-based solutions on top of Lattice |
MORK (Mapping Ontological & Representational Knowledge) used to map source material — structured data (schemas, records, API specifications, etc) and unstructured wordings (documents, clauses, free text) — onto a target domain ontology's T-box & R-Box, using Formal Concept Analysis over the co-occurrence structure of previously mapped source material to propose alignment. MORK as a general-purpose mapping vocabulary, based on SKOS.
The layers described below are one family of mapping target, but not the only possible one. MORK's semantic vocabulary and target declarations live under ontology/mork/, while its Python implementation lives under tools/mork/. LATTICE uses MORK as the reference way of populating its own layers.
LATTICE (Concept Lattice of Domain Ontology Layers) provides the semantic substrate MORK's output lands in - designed to be extended by particular subject domains in order to be used in industry-specific ways.
SPC (Subject-oriented Process Calculus) provides a formal mechanism for describing orchestration between agents (human, AI, or computational), whose data has been mapped in by MORK and whose roles, obligations, and eligibility are modelled in LATTICE. Where LATTICE's Behaviour layer models what state something is in and what can cause it to change, SPC is concerned with the live, session-typed exchange between agents that drives those changes — giving that exchange a formal contract to align to, grounded in the same ontology, rather than an ad hoc protocol. SPC has a substantial standalone ontology under ontology/spc/, with Python and Erlang implementations under tools/spc/. It is not yet integrated with the layers below: it uses a placeholder namespace and declares no projection/ contract to any of them. Treat it as a separate, pre-integration body of work rather than part of the dependency graph described below.
Persistence (the Data Access Layer, dal:) lets an adopter select, per class or per deployment of their own applied ontology, which of the portable RDF/SPARQL patterns in docs/architecture/rdf-sparql-patterns-guide.md apply: aggregate boundary, concurrency, ordering grain, receipt model, meta topology, and uniqueness. The framework-neutral IRI and Identity Patterns guide defines a future identity-profile dimension for the same configuration model. It is a cross-cutting substrate, not a layer — it targets classes, graphs, and shapes by IRI reference only, and no layer imports it or is imported by it. The vocabulary and SHACL shapes live under ontology/persistence/; a design-time-only compiler (no store SPI, no live backend) that turns a selection into generated SPARQL lives under tools/persistence/. See ADR-A78, ADR-A79, and ADR-A82.
LATTICE is organised as eight layers, each an independent OWL/SHACL/SKOS module:
| Layer | Kind | What it models |
|---|---|---|
| Foundation | Substrate | Identity, versioning, provenance and evidence, governance state, temporal scoping, and a derived-artefact contract aligned with PROV-O (ADR-A92). |
| Vocabulary | Substrate | The governed mechanism by which external, domain-specific concept schemes get bound into the other layers without touching their core specifications, including scoped and time-bounded bindings. The vocabulary and SHACL shapes live under ontology/vocabulary/; a reference resolver for the scoped/temporal binding precedence law lives under tools/vocabulary/. See ADR-A85. |
| Quantification | Substrate | Declared value spaces, quantities, ordered values, bounds, ranges, conversion, granularity, and recurrence — the mechanism behind any magnitude, interval, or ordinal comparison the other layers need. |
| Ledger | Substrate | Amounts consumed and restored over time, and so conserved: account trees ("part of and not in addition to"), merge rules that arbitrate several draws at one position, postings and derived balances (ADR-A131). |
| Party | Substrate | Actors, the roles they occupy, and the direction and composition of obligation between them (e.g., modelling independently capped shares, joint obligation with a right of recourse, delegated accountability, or contingent role occupancy). |
| Eligibility | Substrate | Admissibility criteria (conditions, unresolved questions, and decisions), including concept inclusion and exclusion and evidence bindings that evaluate an applied ontology's own properties. tools/mork_compilers compiles conditions and profiles to SPARQL, SHACL, and SWRL through one IR. See ADR-A87, ADR-A89 and ADR-A91. |
| Behaviour | Substrate | State, transition, trigger, and effect, including a usable Sequential allowance profile. Proportional allowance semantics and reset edge cases remain explicitly deferred. |
| Instrument | Applied domain ontology | A primary domain ontology built on the substrates, giving the generic shape of a governing document, e.g., Provision → Obligation → Qualifier. |
Instrument is a first layer building on the substrates. A different applied domain ontology (e.g., a device's operational lifecycle, access-control entitlement system, asset maintenance schedule, etc) could sit atop Instrument or even replace it, composing with the same Party, Eligibility, and Behaviour mechanisms through its own projection/ contracts, without touching any of the core specifications.
Every mechanism in a layer's specification should be usable without knowing what industry or domain is consuming it. See ontology/examples/ for the worked instances.
Each layer directory follows the same internal template, present in whole or in the parts that layer actually needs:
<layer>/
├── README.md
├── spec/ # normative T-box
├── shapes/
│ ├── structural.ttl # SHACL property shapes — local, per-instance
│ ├── constraints.ttl # SHACL-SPARQL — whole-graph conditions
│ └── rules.ttl # SHACL-SPARQL rules that materialise derived facts
├── vocab/ # mechanism-intrinsic enumerations only, never including business vocabulary
├── projection/ # the layer's declared contracts to/from other layers
├── execution/ # generated runtime artefacts, where a layer needs one,
│ # plus the docs governing how they're regenerated
├── examples/ # single-layer worked examples
└── test/ # the layer's own shape and rule tests
Governance is deliberately separate from every layer it checks — ontology/governance/ runs over the union graph rather than living inside any one module, enforcing scheme-contract compliance, deprecation posture, and cross-layer parity in CI.
Compiled artefacts live under execution/, being generated from spec/, shapes/, vocab/, and projection/ by deterministic, reproducible processes or code (to be regenerated on source change per that layer's invalidation-policy.md).
The tools/ folder holds reference implementations handling compilation. It's licensed separately from everything else in the tree — see Licensing.
lattice/
├── README.md
├── LICENSE # MPL 2.0 — ontology artefacts, tools/
├── LICENSE-DOCS.md # CC BY-SA 4.0 — documentation, specifications
├── CONTRIBUTING.md
├── repository-catalogue.md # Where things live, read by tools (ADR-A121)
├── AGENTS.md # Always-on instructions for AI agents (ADR-A117), imported by CLAUDE.md
├── .claude/skills/ # Agent skills, loaded by task, shared as a plugin by .claude-plugin/
│
├── ontology/catalog-v001.xml # Generated import catalog, every ontology and version IRI (ADR-A88)
├── ontology/foundation/ # Foundation Layers (provenance, versioning)
├── ontology/vocabulary/ # Inclusion of Domain-specific Vocabularies
├── ontology/quantification/ # Value Spaces, Quantities, Ranges, Recurrence
├── ontology/party/ # Parties, Roles, & Participation Modelling
├── ontology/instrument/ # Governing Instrument (Upper Domain Ontology)
├── ontology/eligibility/ # Eligibility Criteria Modelling
├── ontology/wording/ # Contract Wording: structure, text, variables (ADR-A112)
├── ontology/behaviour/ # Behaviour Modelling
│ ├── mork/ # Mapping vocabulary and semantic fixtures
│ ├── spc/ # Orchestration ontology, standalone and unintegrated
│ ├── persistence/ # Data Access Layer (dal:), cross-cutting, no layer dependency
│
├── ontology/governance/ # Cross-layer governance
│ ├── scheme-contracts/
│ ├── parity/
│ └── shapes/
│
├── docs/
│ ├── architecture/
│ └── decisions/
│
├── ontology/examples/ # Cross-layer composition scenarios
│ ├── employment.ttl
│ ├── lending-covenant.ttl
│ ├── saas-subscription.ttl
│ ├── clinical-trial.ttl
│ └── insure-o/ # Applied validation package for insurance-style substrate checks
│
├── contracts/
│ ├── identity/ # Minting recipe and vector schemas, anchor vectors, independent verifier
│ └── authoring/ # Word authoring POC contracts, templates and samples (ADR-A118)
│
├── platform/
│ ├── reasoning-testkit/ # Test-only OWL reasoner harness, never a runtime dependency (ADR-A83)
│ └── authoring-service/ # Word authoring POC service (ADR-A118)
│
├── apps/
│ └── word-authoring-addin/ # Word add-in, proof of concept (ADR-A118)
│
├── deployment/
│ └── compose/
│ └── authoring/ # Word authoring POC compose stack (ADR-A118)
│
├── packages/
│ └── minting/ # Standalone identity minting libraries (Python, Java), no LATTICE dependency
│
├── benchmark/ # Checks that measure, run on demand, never part of `check` (ADR-A124)
│
├── test/ # Whole-graph CI
│
└── tools/ # Reference implementation
└── testing/ # Test-support packages, for tests, checks and benchmarks only (ADR-A125)
foundation
└── vocabulary
└── quantification
└── party
└── eligibility
├── wording
│ └── instrument (also imports behaviour configuration)
└── behaviour configuration
└── behaviour runtime
mork — targets any layer
spc — standalone today; not yet imported by, or importing, any layer above
spc — leverages domain ontology axioms to form session types once a separate integration effort defines the needed contracts
The order is ADR-A01's as its 2026-10-01 addendum amends it (ADR-A112). Wording is authored. Behaviour sits below Instrument, in configuration and runtime documents (ADR-A106). Instrument's own imports of Wording and Behaviour configuration arrive with its rewrite.
A few commmon compositions are worth noting:
- Guard calls Eligibility. A Behaviour transition's guard condition is, in the general case, an Eligibility decision: conditions, unresolved questions, and results.
- Effects write into Instrument or Party. A transition firing can create or modify an Obligation, or populate a Role Occupancy that was contingent until that moment.
- Role Occupancy is itself stateful. The same State/Trigger/Effect apparatus that governs an Obligation's status governs whether a Role is currently occupied at all — this is what allows a party who is not connected to an instrument be bound in later, by the instrument's own design.
mise --version
mise doctor
mise install
mise ls
mise exec -- python --version
mise exec -- node --version
mise exec -- java -version
mise exec -- mvn --version
mise exec -- elixir --version
mise exec -- erl -eval 'io:format("~p~n", [erlang:system_info(otp_release)]), halt().'mise run topology:preflight
test -d ontology
test -d tools
test -d tools/mork
test -d tools/mork_compilers
test -d tools/surface
test -d tools/persistence
test -d tools/proofs
test -d tools/models
test -d tools/reference
test -d tools/spc/python
test -d tools/spc/erlang
test -d workers
test -d platform
test -d apps
test -d contracts
test -d docs/diagramsmise run bootstrapThis installs the root Python dependencies, worker dependencies, Yarn workspace, etc.
mise run checkThis runs:
mise run check:python-root
mise run check:workers
mise run check:java
mise run check:frontend
mise run check:spc
mise run check:persistence
mise run check:vocabulary
mise run check:reference-eligibility
mise run check:mork-compilers
mise run check:ontology-versioning
mise run check:ontology-catalog
mise run check:import-guard
mise run check:reasoning-isolation
mise run check:minting
mise run check:formal-freshness
mise run build:mtp
mise run check:mtpNot included (large, native, or optional toolchains — run manually, see
Getting Started §5):
check:formal-network, check:formal-smoke, check:proofs, check:minting-tables.
mise exec -- yarn check
mise exec -- yarn build
mise exec -- yarn testIf Playwright reports missing browsers:
mise exec -- yarn workspace @lattice/mork-review-workbench exec playwright install
mise exec -- yarn workspace @lattice/surface-contract-studio exec playwright install
mise exec -- yarn testmise exec -- python -m pip install -e tools/mork -e tools/mork_compilers -e tools/surface
mise exec -- python -m pytest tools/mork/src -q
mise exec -- python -m compileall -q tools/mork/src tools/mork_compilers/src tools/surface/srcmise run bootstrap:persistence
mise run check:persistenceCompiles ontology/persistence's own worked examples, runs the resolver/validator/capability/boundary unit tests, the injection corpus, the determinism checks, and the Python architecture-policy checks, and validates every example fixture against ontology/persistence/shapes/constraints.ttl. See tools/persistence/README.md.
mise run bootstrap:reference-eligibility
mise run check:reference-eligibilityRuns the hand-written Python reference for the logic kernel and Eligibility's denotation (laws
L9-L16, formal-methods epic track B1), including exhaustive checks of the kernel's own claims
(TA1, TA2) over its three-valued domain and the 15 adequacy fixtures shared with the Isabelle
kernel. Part of the default check aggregate: no dependency beyond pytest. See
tools/reference/eligibility/README.md, ADR-A-FM3.
mise run bootstrap:formal-native-isabelle
mise run check:proofsBuilds every tools/proofs/<layer>/ Isabelle session natively and runs the proof gate (statement
digests, banned-marker scan). Not part of the default check aggregate: Isabelle is a heavy
native toolchain not every host has installed (same convention as the formal-methods spike's own
tasks). No container image exists for Isabelle in this programme yet. See
tools/proofs/README.md, ADR-A-FM1, ADR-A-FM2.
java -jar <path-to>/alloy.jar exec tools/models/vocabulary-scheme-composition/SchemeComposition.alsAlloy Analyzer (a single MIT-licensed JAR, not tracked in this repository) checks each track C
model and writes a receipt.json with every command's structured result next to the model. Not
wired into mise yet: track C's models are run and their results recorded as evidence for an
ADR, not re-verified continuously by CI. See
tools/models/README.md and
tools/models/vocabulary-scheme-composition/README.md.
mise run bootstrap:reasoning-testkit
mise run check:reasoning-testkit
mise run check:reasoning-isolationBuilds and tests the test-only HermiT harness, and checks that no other module declares a reasoner. With the jar built, mise run check:mork-compilers also checks generated SWRL and OWL under HermiT. See platform/reasoning-testkit/README.md.
mise run bootstrap:minting-python
mise run check:minting
mise run check:minting-tablesVerifies the hand-authored anchor vectors with openssl, runs the Python and Java minting libraries against the anchors and the vectors generated from the compiler's recipes, and checks the pinned Unicode 16.0.0 tables against the Unicode Character Database. See packages/minting/README.md and the identity minting specification.
Not part of the default mise run bootstrap — Ruby/Jekyll are only needed when editing GitHub Pages content under docs/:
mise run bootstrap:jekyll
mise run serve:jekyllbootstrap:jekyll installs an isolated Ruby (via mise, scoped to this task only) and the exact gem set Gemfile.lock pins, into docs/vendor/bundle (gitignored, never committed). mise run clean (or mise run clean:docs alone) removes docs/vendor/, docs/.bundle/, and any local Jekyll build output (docs/_site/, .jekyll-cache/) without touching docs/Gemfile/docs/Gemfile.lock.
mise exec -- python -m pip install -e 'tools/spc/python[dev]'
mise exec -- python -m compileall -q tools/spc/python/srccd tools/spc/erlang
mise exec -- mix deps.get
mise exec -- mix test
cd ../..mise run testmise exec -- mvn -f platform/pom.xml clean verifyFocused Surface regression gate:
mise exec -- mvn -f platform/pom.xml -pl surface-workflow -am testdocker --version
docker compose version
docker compose -f deployment/compose/docker-compose.yml config
mise run services:up
docker compose -f deployment/compose/docker-compose.yml ps
mise run services:downThe service checks confirm container startup and reachability. They do not replace end-to-end integration tests.
mise run authoring:upBuilds the service jar and the add-in, stages the Docker build inputs, and brings up a standalone
compose stack (Fuseki, RabbitMQ, the authoring service and worker, and a Caddy TLS proxy) bound to
127.0.0.1 only. Browse to https://localhost:3443 — it redirects to the
harness, a browser-only stand-in for the real Word task pane backed by the real service. The
browser will warn about the proxy's local certificate. Either accept the warning or run
mise run authoring:ca first and trust .build/authoring/lattice-authoring-root.crt.
mise run check:authoring-stack # starts the stack and runs its end-to-end suite
mise run authoring:down # stop the stack, keep its data
mise run authoring:reset # stop the stack and delete its data and local CASee deployment/compose/authoring/README.md for the
service/port/volume reference. Loading the add-in inside real Word requires sideloading the
manifest — a separate step covered in apps/word-authoring-addin/README.md.
The canonical active documentation locations are plans, status, and review.
Two licences govern the artefacts in the repository:
- Ontology artefacts (
.ttl), code (tools/,platform/,packages/,workers/,benchmark/) and machine-readable contracts (contracts/) — Mozilla Public License 2.0. Derivative works, commercial or otherwise, are permitted with no obligation to share what you build. If you modify one of these files and redistribute the modified version, that modification carries the same licence forward. JSON files cannot carry a licence header, soREUSE.tomldeclares theirs. - Documentation and specifications (
.md) — CC BY-SA 4.0. Use freely, share modifications to the text itself under the same terms.
See CONTRIBUTING.md for the licensing mechanics, the SPDX header convention, and where new content belongs within a layer.
AGENTS.md holds the rules every agent follows here, and .claude/skills/ the procedures
it loads by task (ADR-A117). Claude Code and GitHub Copilot pick both up in this repository with no
setup. To use the skills in another project, with Claude Code run
/plugin marketplace add nebularis/lattice and then /plugin install lattice@nebularis, and for
Copilot run mise run skills:link from a LATTICE checkout. AI-assisted contributions are disclosed as
GENAI_CONTRIBUTION.md requires.
Use mise for repository toolchain setup and task orchestration. See the developer guide, Windows and WSL guidance, and the Phase 0 and 1 validation handoff.
For the current implementation boundaries and reading order, see the platform implementation map. Architecture decisions are indexed in docs/architecture/decisions.