Framework Common Spec¶
The documents in this directory describe the Framework's common public contract. Each document defines the inputs, state, normal flow, and failure/completion conditions required by its implementation and contract tests.
This directory and the per-language interfaces are the single authority for the Framework public contract. The documents in this directory form two layers (the "Layer" column in the topic tables below). The contract layer defines the behavior the application observes, and the implementation spec layer defines the common structural decisions that every language's service runtime follows to deliver that contract with the same result. A single document can carry both layers, in which case each sentence states which one it is. The implementation spec adds no new public behavior, but it is normative for runtimes — breaking a decision changes what the application observes. A conflict between the two layers is a defect. The implementation spec is corrected against the contract; if the contract itself must change, the public contract procedure is followed first.
The rule for isolating verification runners so that samples and E2E suites for multiple language implementations of the same contract can run concurrently on one host belongs to the verification environment, not to this spec — see the sample runner isolation standard and the E2E runner execution contract.
What This Spec Answers¶
| Topic | Reader's Question | Entry Document |
|---|---|---|
| foundation | What rules does this spec as a whole follow, and what common vocabulary and API registration does it use | 00-foundation/README.en.md |
| execution | When and in what order does a handler run, and what structure guarantees completion, cancellation, and concurrency | 01-execution/README.en.md |
| channel-transport | How are the physical connections between MeshNodes and the paths that send messages over a Channel structured | 02-channel-transport/README.en.md |
| spot-actor | What are Spot and Actor, and what path does a message take to reach one | 03-spot-actor/README.en.md |
| session | How is one external connection (a session) tied to an Actor, and what is guaranteed when it disconnects or moves | 04-session/README.en.md |
| location-relocation | How is the current location of an Actor or Spot found, and what is preserved when it moves to another node | 05-location-relocation/README.en.md |
| observability | What does an operator use to check the Framework's current state and the cause of a failure | 06-observability/README.en.md |
Reading Order¶
First-time reader (new to this spec as a whole)
- foundation
- channel-transport
- spot-actor
- session
- location-relocation
- observability
- execution — only when needed, to check implementation detail
New-language porting owner (implementing a new service runtime)
- foundation
- execution
- channel-transport
- spot-actor
- session
- location-relocation
- observability
Application developer (using the Framework through an existing language binding)
- foundation
- channel-transport
- spot-actor
- session
- observability
- location-relocation — only when calling Host relocation directly
- execution — usually not needed. Implementation detail is already reflected in the contract
Topics¶
00-foundation¶
Covers the contract-ownership rules, vocabulary, top-level model, interaction targets and completion semantics, message/response/error shapes, language-neutral registration API, and runtime layering boundaries shared by the whole Framework. Every other topic assumes this topic's vocabulary and rules.
| Document | Question It Answers | Layer |
|---|---|---|
| 01. public-contract-governance | What procedure must a change to the Framework public contract follow | Contract |
| 02. glossary | What exactly does each term that recurs throughout this spec mean | Contract |
| 03. overview | What layer is the Framework, and what does each language implement separately | Contract |
| 04. interaction-model | What is a Framework operation's target, and when is it considered complete | Contract |
| 05. message-model | What shape and rules do a sent message and its response/error follow | Contract |
| 06. framework-api | What must an application register at the root to start the Framework | Contract |
| 07. framework-error-model | What common error does an application receive when Send/Request fails | Contract |
| 08. layering | What pieces does runtime code split into, and what values must never be merged | Implementation spec |
01-execution¶
Covers the full execution path from submit through handler execution, completion, cancellation, execution serialization, and payload ownership — everything from an accepted call to its arrival at and completion in the handler. Most of it is implementation spec that every language's service runtime must follow in common.
| Document | Question It Answers | Layer |
|---|---|---|
| 01. submit-and-completion | When is a call accepted, and what completes it | Contract+Implementation |
| 02. handler-turn-and-execution-gate | Why is state safe even though the handler has no synchronization code | Contract+Implementation |
| 03. cancellation-and-shutdown | How do cancellation and shutdown treat work already accepted | Contract |
| 10. spot-timer | When does a Spot timer run, and what happens to a late tick | Contract+Implementation |
| 04. application-job-queue-and-backpressure | Under overload, what is blocked first, and what does the application observe | Contract+Implementation |
| 05. payload-ownership-and-codec | How many times are a message's bytes copied from the socket to the handler | Contract+Implementation |
The shared-permit rule carried over from the session topic is owned as a
single contract sentence by 05's "Ordinary ingress permit order" section.
02-channel-transport¶
Covers the physical connections (RouteMesh, ClientServer, listener identity), how Node-direct and Channel select-one choose a target over them, connection liveness checks, and the byte/command format on the wire.
| Document | Question It Answers | Layer |
|---|---|---|
| 01. channel-topology | How are RouteMesh's physical connections and ChannelName's logical membership structured | Contract |
| 02. channel-messaging | How do Node-direct and ChannelName select-one each choose a target | Contract |
| 03. client-server-channel | How does a Server respond through a handler to a request initiated by a Client | Contract |
| 04. network-listener-identity | Why do a listener's bind address and advertised address differ, and when is each used | Contract |
| 05. transport-liveness | How is a remote connection's liveness checked, and how is it reconnected when it drops | Contract+Implementation |
| 06. wire-protocol | What bytes and commands actually pass between nodes | Implementation spec |
03-spot-actor¶
Covers the three Spot kinds (Entry, User, Instance) and Actor identity, membership, and relocation, together with the two paths a message takes to reach one (Spot-direct, Logical Multicast) and when the Location Store is re-queried.
| Document | Question It Answers | Layer |
|---|---|---|
| 01. spot-model | When is each Entry/User/Instance Spot created, what do they have in common, and how do they differ | Contract |
| 02. spot-messaging | What path does a message sent to a Spot take to reach the actual Spot | Contract |
| 03. mesh-node | What is a MeshNode's identity, its object-placement conditions, and its startup order | Contract |
| 04. actor-model | How are an Actor's identity, location, message queue, and lifecycle defined | Contract |
| 05. spot-actor-membership | How is an Actor created, and in what order do Spot membership and relocation happen | Contract |
| 06. spot-address-messaging | How is a global SpotId created and looked up, and how is that Spot invoked directly | Contract |
| 07. stage-wrapper-on-spot | How is a higher-level execution model such as room or stage built on top of the Spot contract | Contract |
| 08. routing | When does a message to a Spot or Actor re-query location, and when not | Contract+Implementation |
| 09. object-lifecycle | How does code distinguish the three Spot kinds, and when is a missing object created | Implementation spec |
04-session¶
Covers the registration, acceptance, codec, and error boundary of a single STREAM connection (a session), and the Session's responsibility during binding, rebinding, disconnect, and relocation of the connection to an Actor.
| Document | Question It Answers | Layer |
|---|---|---|
| 01. stream-session | Once a connection is accepted, what path does a packet take to reach the callback | Contract |
| 02. session-actor-binding | How is a Session tied to an Actor, and what is guaranteed while the connection is being replaced or moved | Contract+Implementation |
05-location-relocation¶
Covers how the current location of an Actor or Spot is found (the Location Store), how a request completing after relocation is recovered (the Relocation Store), the common order for a planned move (Host relocation, Actor Join, and so on), and the scope of automatic failover.
| Document | Question It Answers | Layer |
|---|---|---|
| 01. location-runtime | How does the Framework find an object's current location and move it to another node | Contract |
| 02. location-store-redis | What must a direct implementation of the Location Store guarantee | Contract |
| 03. relocation-store-redis | What must a direct implementation of relocation-related payload storage guarantee | Contract |
| 04. relocation-flow | In what order do owner and message change while moving an Actor or Spot to another node | Contract+Implementation |
| 05. host-relocation-flow | In what order does Host Relocate move workloads, and what does Shutdown clean up |
Contract |
| 06. failure-failover-policy | When a failure occurs, how far does the Framework automatically continue the same work | Contract |
06-observability¶
Covers how an operator queries the current state, aggregates values over time, and traces the progress of a single message and a business flow chained across several messages. The order for chasing an intermittent failure is defined by README "4. The Order For Chasing An Intermittent Failure", and the cost rule for leaving tracing on is defined by 03. message-flow-tracing "5. Changing The Record Level At Runtime And The Cost Rule".
| Document | Question It Answers | Layer |
|---|---|---|
| 01. runtime-monitoring | How does an operator query the Framework runtime's current state and find the cause in the logs | Contract |
| 02. runtime-metrics | What are the names, units, and labels of the metrics for throughput, waiting, and failure | Contract |
| 03. message-flow-tracing | How does one confirm how far a single message got and where it failed | Contract |
| 04. flow-correlation | How are a request and its reply, or a business flow chained across several messages, identified | Contract |
Per-Language Interfaces¶
The public types, signatures, and asynchronous representation each language uses for the common server contract are owned by the following documents.
HTTP Client¶
- HTTP client spec table of contents
- 12 HTTP client integration contract
- Per-language HTTP client contract
Stream Connector¶
Citation Convention¶
A citation uses the section title. Clicking the link jumps straight to that section.
Do not cite by line number. A §123 form only lands at the top of the
document, forcing the reader to search again, and it goes stale the moment
the cited document changes by even one line. A section title breaks only when
that section disappears or is renamed, and link checking catches that.
The anchor is the title lowercased with spaces joined by -. Verify with:
Where Old Documents Went¶
This spec reorganized the old layout, where every document carried one global
number (00 through 52), into topic directories. A link or memory keyed on
an old number finds the new location in the table below. Where an old
document split across several new documents, the section ranges are given.