Foundation¶
Spec index · Next: 01. Public Contract Governance
This topic covers the eight foundations shared across this entire spec: contract ownership; the meaning of common terms; what Framework does at the upper layer; how an operation's target and completion are determined; the form of a message; the public API family; common errors; and runtime layering boundaries.
1. What This Covers¶
Every other topic (execution, channel-transport, spot-actor, session, location-relocation, observability) assumes what this topic defines. It defines who owns the public contract and the procedure for changing it, exactly what the domain terms shared across the whole spec mean, what Framework does in the upper layer that each language implements independently, how a single message picks its target and when it is treated as complete, what shape the typed payload, metadata, and codec of that message take, what an application host must register at root, what common error an application receives when send or request fails, and how runtime code is divided into chunks and which values must not be merged into one.
This topic defines "what the contract covers." The channel-transport and spot-actor topics respectively define "how that contract is physically delivered" (connection topology, wire framing) and "how a Spot — a logical instance with an address and state — or Actor operates on top of that contract" (creation, relocation).
2. Documents in This Topic¶
| Document | Covers |
|---|---|
| 01. Public Contract Governance | Definition of the public contract, the four ownership categories, what to pin down for a new contract, the 7-step public contract procedure, per-language representation principles, design review criteria |
| 02. Framework Messaging Glossary | The single authority defining the domain terms (Spot, Actor, owner, generation, authority, …) shared across this entire spec |
| 03. Framework Overview | What Framework does, MeshName·ChannelName·RouteMesh — the names identifying mesh and channel scopes, plus the physical connection scope itself —, message target selection, execution owner, connection management, what Framework hides |
| 04. Interaction Model | The common model for Operation target selection and completion, send/request, Spot Logical Multicast, classic fanout, STREAM session, the effect of handler failure and termination |
| 05. Message Model | Typed messages, MessageContext, ActorRef/SpotRef JSON, the framework-json-v1 typed payload profile, application metadata, ownership and size limits |
| 06. Framework API | The language-neutral public API family — root registration, RouteMesh registration, messaging API, handler registration and filters, codec, Store registration, Spot·Actor·STREAM owner registration, startup validation |
| 07. Framework Error Model | The common ErrorKind, the completion/failure boundary of Send·Request, CapacityExceeded vs Unavailable, retry decisions |
| 08. Layering Boundaries and Identifiers | The binding boundary every language runtime follows, the shutdown procedure and cleanup order, when registration declarations are validated, the criteria for keeping identifiers separate (implementation spec) |
3. Find by Question¶
| Question | Where the answer is |
|---|---|
| Why are these spec documents split the way they are, and how are contract and implementation distinguished | Public Contract Governance "1. What the Public Contract Is" · "2. Contract Ownership" |
| What procedure is followed to add or change a public contract | Public Contract Governance "5. Public Contract Procedure" |
| What exactly do the terms that recur throughout this spec (Spot, Actor, owner, generation, …) mean | Framework Messaging Glossary |
| What role does Framework play, and what does each language implement independently | Framework Overview "1. What the Framework Does" |
| What does each of MeshName·ChannelName·RouteMesh refer to | Framework Overview "2. MeshName·ChannelName·RouteMesh" |
| When a message is sent, how is the target decided, and when is it considered "complete" | Interaction Model "1. Common Model — Target Selection and Completion" |
| What is the difference between send and request, and under what conditions does each fail | Interaction Model "4. Send and Request" |
| How do Logical Multicast and classic fanout differ from each other | Framework Overview "4. Logical Multicast and Classic Fanout" · Interaction Model "5. Spot Logical Multicast" · "6. Classic Fanout" |
| What rules apply to a sent message's typed payload, metadata, and reply | Message Model "1. Typed Messages" |
What are the JSON representation and codec rules for ActorRef·SpotRef |
Message Model "4. Global Object Reference JSON" · "5. framework-json-v1 Typed Payload Profile" |
| What must an application host register at root for Framework to start | Framework API "2. Root Registration" |
| What key is a handler registered under, and when is a filter applied | Framework API "9. Handler Registration and Dispatch" · "10. Handler Filter" |
| What common error does an application receive when Send·Request fails | Framework Error Model |
How are CapacityExceeded and Unavailable distinguished |
Framework Error Model "5. Request Completion and Failure" |
| How is runtime code divided, and which values must not be merged into one | Layering Boundaries and Identifiers "6. Identifiers Are Not Merged" |
| How does startup validation differ from runtime validation | Framework API "22. Startup Validation" · Layering Boundaries and Identifiers "5. Registration Declarations Are Validated Only Once, at Startup" |
4. Reading Order¶
Developer reading for the first time
- Get the scope of this topic from §1 of this document.
- Read Framework Overview for what Framework does in the upper layer and the concepts of MeshName·ChannelName·RouteMesh and execution owner.
- Read Interaction Model "1. Common Model" through "4. Send and Request" for message target selection and completion conditions.
- Check the precise definition in the glossary whenever an unfamiliar term appears.
Developer porting to a new language — the documents below contain the public contract and implementation decisions that every runtime must follow using the same structure, so they must be read before language-specific implementation begins.
- All of Public Contract Governance — the contract ownership boundary and public contract procedure must be understood first to know where to record the per-language interface of the new language.
- All of Framework API — the public API family and registration rules make up the largest part of this topic and define the standard already implemented by every other language runtime.
- All of Framework Error Model — the common
ErrorKindand completion boundary are a contract that the language-specific exception and result representation must follow as-is. - All of Layering Boundaries and Identifiers — the binding boundary, shutdown procedure, and identifier separation are the implementation spec, and include the verification requirement (§7).
Application developer
- Get the whole picture from Framework Overview.
- Read Framework API "2. Root Registration" through "6. Messaging API Family" for root registration and the public API for sending messages.
- Check the common error received on failure in Framework Error Model.
5. What This Topic Does Not Define¶
| Content | Owning document |
|---|---|
| RouteMesh·ClientServer physical connections, wire framing, transport liveness | channel-transport topic |
| Spot·Actor creation, membership, and relocation procedure | spot-actor topic |
| The detailed procedures for STREAM session and Actor binding | Session topic |
| The source and target execution flow of Actor·Spot relocation | location-relocation topic |
| Runtime monitoring, message flow tracing, flow correlation | observability topic |
| Completion races for Send·Request, execution turn, detailed backpressure rules | execution topic |