Ghostlight/docs/architecture/cultnet-shared-agent-state-contract.md

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.