---

id: runtime-architecture kind: architecture title: Distributed Runtime Architecture status: active depends_on:

• charter
• data-model
• jazz-mapping
• folder-contract

---

Distributed Runtime Architecture #

Charter is a local control surface over a Jazz-native distributed project runtime.

Shared plane #

The Jazz project graph is shared and authoritative for portable coordination state:

• projects and membership;
• stable source and document identities;
• normalized document content and semantic versions;
• events and work items;
• worker registrations, capabilities, presence, and leases;
• context manifests and packets;
• requests, runs, reports, and provenance.

Each human, controller, and worker uses a distinct Jazz identity. Permissions are granted through project membership and role rows. A worker does not inherit the controller's identity merely because the controller launched or configured it.

Local controller plane #

A controller owns machine-local configuration:

• project ids it has joined;
• local source selections and include/exclude rules;
• mapping from shared source ids to local absolute paths;
• local materialization targets;
• runner adapter configuration and secret references;
• local process state.

This state is not a JSON copy of the project graph. It is a local routing table into the shared graph. It may be stored in a small controller config beside the local Jazz database.

Worker plane #

A worker can run anywhere. It joins the project under its own identity and registers:

• worker id and display name;
• capabilities and accepted work selectors;
• runner/adapter kind;
• endpoint or wake-up metadata when applicable;
• current presence and lease expiry;
• non-secret configuration metadata.

Workers subscribe to matching Jazz queries, claim work with a bounded lease, receive immutable context manifests, and report results into the same project graph. Direct access to a controller's filesystem is optional and adapter-specific, never assumed.

Data flow #

1. A controller joins or creates a stable Jazz project.
2. The user selects local sources.
3. Source adapters normalize selected material into shared document rows.
4. Jazz records the writes, authorship, row versions, and durability state.
5. Charter classifies meaningful changes into semantic events and work.
6. Eligible workers observe work through Jazz subscriptions.
7. One worker claims work with a lease.
8. Charter freezes a context manifest naming exact document/version identities.
9. The worker executes through its local adapter.
10. Reports, evidence, proposals, and resulting events return to Jazz.
11. Controllers and other workers observe the same state without polling a controller-owned HTTP server.

Process boundaries #

The CLI, optional HTTP inspector, future UI, and workers are clients of the runtime. No one long-lived charter watch process is the project's metaphysical center. A controller may be offline while another participant continues work from already-synchronized state.

Durability claims must name the tier actually reached: local, edge, or global. “Saved” without a tier is not a useful statement in a local-first system.