This is the fast onboarding glossary for Wesley.
Use it when you need to answer three questions quickly:
- What are the main nouns in Wesley?
- Which layer does each noun belong to?
- Where does Wesley stop and project-specific meaning begin?
Wesley is a schema-first compiler kernel with a surrounding assurance toolchain.
The core compiler turns authored GraphQL into module-selected targets. The toolchain can package, witness, and project those outputs.
Wesley brings the GraphQL -> half. External modules bring the whatever.
Domain or product meaning belongs outside the Wesley repo.
The generic base platform.
This layer is project-agnostic. It provides the engines and entry points that modules and projects build on top of.
It includes:
- the Wesley compiler core
- Holmes and Watson verification and witness tooling
- Moriarty judgment and prediction tooling
- BLADE certification and release-readiness orchestration
- generic CLI, hosts, and shared plumbing
These are the main package families inside the Wesley repo today.
Packages and commands that expose Wesley to humans and scripts.
Examples:
crates/wesley-cli- native
wesley ...command surfaces - legacy
pnpm wesley ...migration surfaces
Packages that emit generic target artifacts from Wesley IR.
Examples:
@wesley/generator-js
Historical product and database generators still present in this repo are extraction debt. They should move into their owning module repos.
Legacy compatibility packages that provide environment-specific runtime services for historical JavaScript Wesley surfaces. They are not the Rust-native product front door.
Examples:
@wesley/host-node@wesley/host-browser@wesley/host-deno@wesley/host-bun
Generic runtime-side helpers that are not themselves the compiler core.
Examples:
@wesley/runtime-node
Packages and commands that evaluate, summarize, certify, or gate bounded claims around compiler outputs.
Examples:
@wesley/holmes- witness and realization verification commands
- plan and rehearse flows
- BLADE command surfaces
Packages that support scheduling, planning, fixtures, or internal shared operations.
Examples:
@wesley/tasks@wesley/test-fixtures
Early project templates or packaged starting points built on Wesley outputs.
Examples:
@wesley/scaffold-multitenant
Domain-specific stacks still present in this repo are extraction debt. Stacks with database or product assumptions should live outside Wesley.
The extension layer above the base platform.
Modules extend Wesley through explicit hooks rather than by contaminating the base platform.
An extension module may add:
- custom GraphQL directives
- generator plugins
- witness scopes or verification profiles
- judgment or policy rules
- certification profiles
- bundle or projection behavior
- BLADE environment setup and additional test suites
Examples:
- external target modules
- external policy or witness modules
- project-specific custom modules
Generic modules should not be forced to implement product-specific surfaces. Observer-facing contracts, database migration semantics, and runtime substrate conventions belong to external modules.
The user's actual working project.
This layer contains:
- authored schemas
- project config
- project-specific tests and policies
- generated outputs
- local custom modules
- deployment machinery owned by the project, not by Wesley
An ordinary project should usually only need to provide:
- authored schemas
- selected module(s)
- module configuration
- optional project tests
- optional BLADE environment setup and extra test hooks
If a project is being asked to hand-author witness scopes, publication boundaries, consumer projections, and judgment profiles directly, the module boundary is probably wrong.
The schema-first compiler engine at the center of the base platform.
Wesley parses authored GraphQL, lowers it into IR, and drives generator plugins to emit target artifacts.
A verification and evidence tool.
Holmes evaluates bounded properties around proposed or emitted change and produces machine-readable evidence about what passed, failed, or needs attention.
A witness and verification companion surface.
Watson is part of the bounded proof story: it helps turn authored source, emitted artifacts, and realization shells into explicit witness material rather than vague confidence.
A policy, judgment, and prediction tool.
Moriarty evaluates rules, risk, gates, or counterfactuals that go beyond raw compilation and beyond simple artifact coherence.
The certification and release-readiness orchestrator.
BLADE composes compiler outputs, witness/evidence results, tests, and judgments into a tested, certified, deployable bundle or readiness verdict.
BLADE stops short of deployment. Deployment belongs to the project or operator layer.
Projects may extend BLADE with environment setup, additional tests, and custom gate behavior without turning Wesley itself into a deployment system.
A domain- or ecosystem-specific extension family built on Wesley base platform. Product and database modules live outside the Wesley repo.
A module may extend compilation, witness, judgment, certification, or bundle behavior without contaminating the base platform.
A narrower capability family inside a broader module.
Examples:
- a target emitter inside a language module
- a dialect package inside an external database module
A bounded authored GraphQL contract slice that is versioned, compiled, witnessed, and released as one unit.
A family is the authored unit, not the proof claim and not the consumer view.
A named claim boundary for what a witness or certification act is proving about a family.
A consumer-facing emitted view derived from a family.
The rule set that says where a family is allowed to live and where its generated projections are allowed to land.
Its job is to prevent shadow authored homes and stray generated artifacts from becoming peer authorities.
The base platform may provide enforcement machinery, but modules should supply the actual policy.
Observer-facing nouns belong only to external product modules.
Those may include:
- product-authored GraphQL families
- observer state codec artifacts compiled from those families
- hosted observer runtime contracts in product runtimes that later produce values conforming to those families
Generic Wesley and non-product modules should use simpler read-side nouns such as reports, projections, inspections, summaries, and certification results.
The authored GraphQL source file.
In Wesley, the schema is the sovereign source of truth. Generated outputs are derived from it and should not become peer authorities.
The schema is an input, not an extension point.
Structured GraphQL syntax that adds meaning to the schema.
Directives are one of Wesley's main extension points. They let a schema express extra compilation intent without abandoning GraphQL as the authored surface.
Intermediate Representation.
This is the compiler's internal, normalized form of the authored schema. Generators compile from IR, not directly from raw SDL text.
A pluggable emitter that takes Wesley IR and produces one or more target artifacts. Generic emitters may live in Wesley. Domain emitters live in external module repos.
Examples include TS/Zod, Vue, and externally supplied target generators.
A requested output family or emission leg.
A target answers the question: "What kind of thing should Wesley emit from this schema?"
Examples:
- TypeScript types
- Zod validators
- language bindings
- externally supplied runtime artifacts
- externally supplied database artifacts
A concrete emitted file or structured output produced by a generator.
An artifact is generated truth derived from authored truth. It is useful and inspectable, but it is not the governing source.
A bounded authored GraphQL family that is versioned, compiled, witnessed, and released as one unit.
A contract family is authored truth. Wesley compiles artifacts for it. Tools and runtimes later may produce actual values that conform to it.
An actual execution-time value later produced by a runtime or tool using Wesley outputs.
Examples:
- a product runtime value emitted by a product runtime
- a database result value emitted by a database host
- a Holmes, Watson, Moriarty, or BLADE report value
Wesley does not emit runtime values. Wesley emits compiled artifacts.
The command-line entry surface for Wesley.
The CLI is not the compiler core itself. It is the main human-facing ingress that invokes the compiler and related toolchain operations.
The concrete emitted output set for a compile act.
If the schema is authored truth, realization is the physically emitted leg of that truth.
The packaging boundary around emitted artifacts.
It exists so Wesley can track source identity, output identity, and bounded claims about what was emitted, without pretending the emitted files are now the authority.
A bounded proof artifact produced by Wesley about a specific claimed property.
A witness does not mean "everything is true." It means Wesley has certified a named property under a named scope.
A named boundary for what a witness or toolchain action is claiming.
A scope answers the question: "What exactly are we certifying or packaging here?"
A versioned, portable package that groups together the outputs and metadata needed for a consumer to use a released contract family.
A bundle may include emitted artifacts, realization metadata, witness material, and consumer projection information.
A named toolchain preset.
A profile provides policy defaults for packaging, witness, sync, or other higher-level operations. Profiles are not compiler core; they are workflow sugar.
A downstream repo, runtime, or host project that receives or uses Wesley outputs.
Examples include app repos, runtime repos, protocol consumers, or database/application hosts consuming generated contracts.
A consumer-shaped emitted view of a released contract family.
Projection is about where and how a released family lands in a consumer environment.
A package that lets Wesley run in a specific execution environment.
Host adapters handle environment-shaped concerns such as filesystem access, process execution, or browser-safe operation without changing compiler truth.
A supporting package that helps generated or compiled outputs operate inside a runtime environment.
This sits outside the pure compiler core but can still be generic and reusable.
A toolchain surface that evaluates proposed changes or emitted artifacts against declared rules.
In this repo, Holmes and Moriarty are the main examples.
A starter package or template that helps initialize a project using Wesley-generated outputs and conventions.
Scaffolds are consumers of Wesley, not the compiler itself.
A higher-level packaged composition of schema, generated outputs, app wiring, and host assumptions.
Stacks are closer to product delivery than to compiler infrastructure.
A domain- or ecosystem-specific extension family built on the Wesley base platform.
Modules extend the compiler, witness, judgment, or certification surfaces through explicit extension points.
A narrower extension family inside a module.
Examples:
- a dialect package inside an external database module
- a runtime projection inside an external product module
The external family of extensions that teaches Wesley about database-facing generation, planning, verification, or certification concerns.
This module lives outside Wesley, for example in wesley-postgres.
An external family of extensions that teaches Wesley about product-specific schema families, projections, witness scopes, judgments, and certification behavior.
This module lives in the owning product repo or in a product-owned module repo.
The environment that runs Wesley or hosts its generated outputs.
Examples:
- the local Node CLI
- a browser host
- a repo-local workspace bootstrap flow
A host-project bootstrap and workspace concept owned by a product or runtime repo.
It is not Wesley core. It is a project-level orchestration surface that invokes Wesley.
A product-owned orchestration tool.
It should sit above Wesley. It decides how a workspace is initialized, which shared families are materialized, and how Wesley is invoked as part of that process.
The module and profile surface owned by a domain or product repo.
It is not compiler core. It extends Wesley from outside the Wesley repo.
When you are confused, ask this in order:
- Is this authored source?
- Is this compiler internals?
- Is this emitted output?
- Is this packaging/witness/toolchain metadata?
- Is this project-specific policy living above Wesley?
That question usually tells you which layer a noun belongs to.
If you only remember one picture, remember this:
Project workspace
-> extension modules add domain meaning
-> Wesley base platform compiles, verifies, judges, and certifies
-> project-owned deployment and runtime layers consume the resulting bundles and artifacts
Wesley is strongest when those layers stay separate.