# Architecture Specification > Architectural direction for processkit v1.0. --- LLMS index: [llms.txt](/processkit/v1.x/llms.txt) --- > **Alpha.5 status:** The Rust lifecycle/Python MCP boundary below is > accepted and implemented for local release verification, planning, install, > update, recovery, verification, and uninstall. Online release resolution, > native runtime diagnostics, and Rust-supervised MCP are planned. ## System Role processkit v1.0 is a provider-neutral process and memory substrate. It stores canonical project entities in git-backed files and exposes safe read/write behavior through MCP servers. Agent runtimes are consumers. processkit provides context, process state, governance, and memory; it does not own the agent loop. ## Product Boundary The architecture is intentionally hybrid: | Surface | Ownership | | --- | --- | | Rust CLI | Release verification, deterministic plans, transactional filesystem mutation, recovery, and machine request/result envelopes | | Python MCP | Tool registration, entity validation, lifecycle transitions, routing, indexing, and process workflows | | Visible content | Skills, schemas, state machines, processes, templates, packages, and harness adapters | | Project state | Entities, configuration, local overrides, and audit history owned by each consuming project | There is no planned wholesale rewrite of MCP servers in Rust. A future Rust `mcp` command may supervise the installed Python gateway, but Python remains authoritative. The repository boundary is equally strict: - `context/` is processkit's installed dogfood consumer state. - `src/context/` is the producer-curated release deliverable. Dogfooding is acceptance evidence. It does not make the two trees redundant, and project-owned entities must never leak into the release payload. ## Canonical Model The v1.0 ontology follows the RFC's T/P/D/C framing: - `T`: terminology and shared fragments without their own lifecycle - `P`: persistent primitives with schema and lifecycle - `D`: discriminator variants of primitives - `C`: compositions of primitives and terminology fragments The RFC target is 89 concepts. Alpha.3 completed the planned ontology breadth; subsequent work is intentionally focused on lifecycle usability, trust, migration, runtime diagnostics, and proven user journeys rather than further default-ontology expansion. The detailed inventory is captured in [Ontology Reference](./ontology-reference.md). The product release version and entity API version are independent. The v1.0 release keeps `apiVersion: processkit.projectious.work/v2`; changing that value requires a separate, explicit migration. ## Required Internal Semantics The canonical model must preserve: - stable processkit entity IDs - schema-backed kinds and discriminators - lifecycle state machines - typed Bindings and queryable relations - structured LogEntries - validation modes per kind - generated schemas - MCP tools as the normal write path - interface-aware queries such as `query_by_interface` These semantics must not be collapsed into plain markdown links, free-form notes, or OKF's permissive interchange model. ## Schema Generation The RFC's build-time schema generation remains the preferred direction: - source schemas ship under `context/schemas/src/` - templates and fragments compose schemas - generated flat schemas are committed - runtime tools consume generated schemas - a rebuild endpoint supports full or partial regeneration The required endpoint shape remains: ```text regenerate_schemas(kinds: list | None) -> {rebuilt, unchanged, errors} ``` The generated schema architecture, MCP helper expectations, and index update flow are specified in [Tooling Architecture](./tooling-architecture.md). ## Validation Validation is phase-gated: - migrated kinds use strict validation - migrating kinds use tolerant validation with warnings - validation mode must be visible through MCP - release gates must fail on invalid strict entities ## Indexing And Query The index must support: - full-text search - entity lookup by ID - relation traversal - interface grouping - query by interface - backlinks or cited-by navigation Interface-aware query is a core v1.0 feature because agents should be able to ask for records, decisions, artifacts, logs, or approvals without hard-coding every concrete kind. The implementation should keep the index as a SQLite/FTS5 accelerator over canonical files. It must store declared schema interfaces, typed relations, event subjects, and enough metadata to support `query_by_interface` without replacing the git-backed entity files as the source of truth. ## OKF Boundary OKF is an import/export profile, not the internal canonical model. Exports should: - emit conformant OKF v0.1 bundles - include OKF `type` - preserve `processkit_id`, kind, and interfaces in extension frontmatter - emit normal markdown links for generic OKF consumers - preserve typed relation metadata for processkit-aware consumers Imports should: - mark content as external knowledge - preserve unknown OKF frontmatter - avoid pretending external OKF concepts have full processkit lifecycle semantics ## Runtime Integration processkit should provide examples and integration surfaces for: - LangGraph - Google ADK - OpenAI Agents SDK - Microsoft Agent Framework - coding agents such as OpenHands, SWE-agent, Copilot Agent, and Aider The stable contract should be MCP, files, schemas, and docs, not a framework-specific runtime dependency. In alpha.5, harnesses launch the Python gateway directly through `uv` or an installer-managed projection. Native `processkit doctor` and `processkit mcp` commands are target interfaces, not current commands. ## Testing Architecture Manual dogfooding through a new aibox project is useful, but it is not the correctness strategy for v1.0. The core test suite must run against local fixture projects without requiring aibox and must cover schema generation, MCP contracts, state machines, index updates, migrations, and pk-doctor adversarial fixtures. aibox should be tested as an adapter after the processkit-native suite is green. See [Test Strategy](./test-strategy.md).