cc016ffb55
The contract doc still pointed at the standalone GameCult/cultnet-ts repo, which is being removed. The client is the cultnet-ts package in CultLib. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
98 lines
3.1 KiB
Markdown
98 lines
3.1 KiB
Markdown
# CultNet Shared Agent-State Contract
|
|
|
|
Ghostlight owns the first cross-runtime agent-state payload contract.
|
|
|
|
That contract is not a new ontology. It is the existing Ghostlight state shape
|
|
moving over a wire without turning into bespoke JSON fog in every other repo.
|
|
|
|
## Canonical Payload
|
|
|
|
The first shared payload contract is:
|
|
|
|
- schema id:
|
|
`https://github.com/GameCult/Ghostlight/schemas/agent-state.schema.json`
|
|
- schema version:
|
|
`ghostlight.agent_state.v0`
|
|
- canonical file:
|
|
`schemas/agent-state.schema.json`
|
|
|
|
This is the same state shape already used for Ghostlight fixtures and the same
|
|
top-level shape Epiphany role dossiers adopted. The contract is:
|
|
|
|
- `world`
|
|
- `agents`
|
|
- `relationships`
|
|
- `events`
|
|
- `scenes`
|
|
|
|
If another runtime wants to carry socially persistent agent state without
|
|
inventing its own private folk religion, this is the first house shape.
|
|
|
|
## Wire Envelope
|
|
|
|
CultNet should carry the Ghostlight payload as a typed document replication
|
|
message, not as a one-off ad hoc blob.
|
|
|
|
Current expected document envelope:
|
|
|
|
- `documentType`: `ghostlight.agent-state`
|
|
- `documentKey`: runtime-defined stable key
|
|
- `payloadSchemaVersion`: `ghostlight.agent_state.v0`
|
|
- `payload`: exact Ghostlight state document
|
|
|
|
The current TypeScript client library is:
|
|
|
|
- package: `cultnet-ts`, in `GameCult/CultLib` under `packages/cultnet-ts`
|
|
|
|
Its job is not merely to make pipes pretty. It owns:
|
|
|
|
- direct-pipe MessagePack framing
|
|
- typed message contracts
|
|
- authentication/session semantics compatible with CultLib's `GameCult.Networking`
|
|
- typed replication into CultCache-compatible stores
|
|
|
|
## Authentication Story
|
|
|
|
CultNet inherits the useful security shape from CultLib:
|
|
|
|
- a shared connection key known to client and server/runtime peers
|
|
- AES-GCM encrypted auth/session payloads derived from that key
|
|
- a server-side session-signing secret
|
|
- signed session tokens used for verify/reconnect flows
|
|
|
|
This matters because "shared agent state" is not only a serialization problem.
|
|
It is also a trust boundary problem. We want one family resemblance across C#,
|
|
TypeScript, Rust, and Python instead of four mutually unintelligible little
|
|
shrines to local convenience.
|
|
|
|
## Contract Discipline
|
|
|
|
Ghostlight remains the source of truth for the payload shape.
|
|
|
|
That means:
|
|
|
|
- if `schemas/agent-state.schema.json` changes, CultNet mirrors must update in
|
|
lockstep
|
|
- consumers may add local document metadata around the payload, but should not
|
|
silently mutate the payload contract itself
|
|
- if a runtime needs a narrower projection or local working view, that is a
|
|
derivative contract, not a revision of `ghostlight.agent_state.v0`
|
|
|
|
The rule is simple:
|
|
|
|
- prompt projection may differ
|
|
- storage engines may differ
|
|
- language bindings may differ
|
|
- the shared payload contract does not drift just because another repo got
|
|
lonely
|
|
|
|
## Immediate Consumers
|
|
|
|
The first intended consumers are:
|
|
|
|
- Ghostlight fixture/state tooling
|
|
- EpiphanyAgent role dossiers and heartbeat-adjacent agent state
|
|
- VoidBot companion-state and social memory machinery where the full Ghostlight
|
|
payload is useful
|
|
|
|
More bindings can come later. They do not get to invent a prettier truth.
|