Adopt shared PersonaState contract

This commit is contained in:
Meta Vens 2026-05-29 16:09:25 +01:00
commit a1ec7ace5d
9 changed files with 1386 additions and 68 deletions

View file

@ -1,98 +1,102 @@
# CultNet Shared Agent-State Contract
# CultNet Shared Persona-State Contract
Ghostlight owns the first cross-runtime agent-state payload contract.
Ghostlight no longer treats `ghostlight.agent_state.v0` as the cross-runtime
person-state contract. That schema still belongs here, but it owns scene,
world, relationship, event, and dialogue-context state for storytelling.
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.
The portable person-shaped contract is now `gamecult.persona_state.v0`.
## Canonical Payload
The first shared payload contract is:
The shared payload contract is:
- schema id:
`https://github.com/GameCult/Ghostlight/schemas/agent-state.schema.json`
`https://gamecult.dev/cultnet/gamecult.persona_state.v0.schema.json`
- schema version:
`ghostlight.agent_state.v0`
- canonical file:
`schemas/agent-state.schema.json`
`gamecult.persona_state.v0`
- Ghostlight mirror:
`schemas/gamecult.persona_state.v0.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:
The same schema is mirrored by Epiphany and VoidBot so Faces, repo
representatives, and Ghostlight characters can cross runtime boundaries without
each repo inventing its own local person-shaped blob.
- `world`
- `agents`
- `relationships`
- `events`
- `scenes`
## Ownership
If another runtime wants to carry socially persistent agent state without
inventing its own private folk religion, this is the first house shape.
Ghostlight keeps owning the story machine:
- world state
- scenes
- events
- relationships
- perceived overlays
- dialogue context packs
PersonaState owns the portable public-person projection:
- presentation
- values
- activation profile
- thought memory
- agency pressure
- candidate actions
- affect
- source provenance
That projection can be generated from Ghostlight scene agents, VoidBot repo Face
state, or Epiphany Face state. The projection does not erase native state. It is
the wire shape, not a throne.
## Wire Envelope
CultNet should carry the Ghostlight payload as a typed document replication
message, not as a one-off ad hoc blob.
CultNet should carry PersonaState as a typed document replication message.
Current expected document envelope:
- `documentType`: `gamecult.persona-state`
- `documentKey`: stable runtime-defined persona key
- `payloadSchemaVersion`: `gamecult.persona_state.v0`
- `payload`: exact PersonaState document
Native Ghostlight scene payloads may still travel separately with:
- `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:
Those are different contracts. One carries a story world. One carries a
portable Persona.
- repo: `GameCult/cultnet-ts`
## Epiphany Boundary
Its job is not merely to make pipes pretty. It owns:
Epiphany public Faces use PersonaState when they need full persistent
personhood. Epiphany work organs do not. A work organ such as Imagination can
have a light organ state without affect, social bonds, public presentation, or
candidate actions.
- 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.
This prevents the old muddle where every useful subsystem was tempted to dress
up as a whole person. Useful machines do not all need faces.
## Contract Discipline
Ghostlight remains the source of truth for the payload shape.
The schema lives in multiple repos for local validation, but the contract must
move as one:
That means:
- Epiphany keeps the primary CultNet schema copy.
- VoidBot mirrors it and emits PersonaState from repo Face reads.
- Ghostlight mirrors it and validates PersonaState examples.
- Native storage may stay richer than PersonaState.
- Importers must preserve unknown extension data when possible.
- Consumers must treat `provenance.authority` seriously.
- 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
Prompt projection may differ. Storage engines may differ. Story scenes may
carry more structure. The shared person-state payload does not drift just
because a runtime got clever at midnight.
## 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.
- Ghostlight character projections for scene/story tooling
- VoidBot repo Face MCP reads and social memory interop
- Epiphany public Face state
- future CultNet replication and inspection tools

View file

@ -0,0 +1,89 @@
{
"schemaVersion": "gamecult.persona_state.v0",
"provenance": {
"sourceSystem": "ghostlight",
"sourceDocumentId": "examples/agent-state.call-of-the-void.json#agents/oz",
"sourceUpdatedAt": "2026-05-29T00:00:00Z",
"exportedAt": "2026-05-29T00:00:00Z",
"authority": "projection"
},
"personaId": "oz",
"publicName": "Oz",
"publicDescription": "A hostage negotiator carrying pressure, empathy, and tactical restraint into an impossible room.",
"presentation": {
"voiceSummary": "Oz speaks with controlled warmth, plain stakes, and a careful refusal to let urgency become panic.",
"defaultRenderer": "scene",
"homeContext": {
"kind": "scene",
"id": "call-of-the-void",
"label": "Call of the Void"
},
"jurisdiction": "Lucent hostage negotiation scene"
},
"privateNotes": [
"Ghostlight owns scene-local truth; PersonaState is the portable character projection."
],
"values": [
{
"id": "preserve-life",
"label": "Preserve life without surrendering agency",
"priority": 0.95,
"summary": "Keep everyone alive while preserving the person's ability to choose a way back."
}
],
"activationProfile": {
"underlyingOrganization": {},
"stableDispositions": {},
"behavioralDimensions": {},
"presentationStrategy": {},
"voiceStyle": {},
"situationalState": {}
},
"thoughtMemory": {
"shortTerm": [],
"memories": [
{
"id": "oz-memory-room-pressure",
"status": "active",
"target": {
"kind": "scene",
"id": "call-of-the-void",
"label": "Call of the Void"
},
"summary": "The room is not a puzzle box. It is a living pressure system with frightened people inside it.",
"claim": "A tactical win that humiliates the subject can still lose the person.",
"tension": "Delay has risk, but speed can become coercion wearing a heroic mask.",
"actionImplication": "Speak in ways that lower pressure while keeping real choices visible.",
"intensity": 0.86,
"createdAt": "2026-05-29T00:00:00Z",
"updatedAt": "2026-05-29T00:00:00Z",
"tags": [
"ghostlight",
"call-of-the-void",
"negotiation"
],
"extensions": {
"ghostlight": {
"sourceSchemaVersion": "ghostlight.agent_state.v0"
}
}
}
],
"incubation": []
},
"agencyPressure": {
"pressures": []
},
"candidateActions": {
"actions": []
},
"affect": {
"needs": [],
"socialBonds": [],
"statusReads": [],
"moodDimensions": [],
"socialBiases": [],
"doctrineStances": []
},
"updatedAt": "2026-05-29T00:00:00Z"
}

View file

@ -344,7 +344,7 @@ readiness or reference-only value, not accepted broad corpus fixtures.
## Warnings
- Keep persistent state small. Git history and artifacts own chronology.
- Treat `ghostlight.agent_state.v0` as the first shared cross-runtime payload contract. If another runtime needs to move agent state over a wire, it should carry the Ghostlight payload unchanged inside a typed CultNet document envelope instead of quietly forking the ontology.
- Treat `gamecult.persona_state.v0` as the shared cross-runtime public-person payload contract. `ghostlight.agent_state.v0` remains Ghostlight's scene/world contract, not the portable Persona schema.
- Do not let notes, map, handoff, and evidence become four versions of the same brain.
- Do not train on coordinator-repaired responder prose unless the repair is labeled.
- Do not accept branch fixtures without branch compiler notes and IF artifact review.

View file

@ -7,7 +7,8 @@
"state:status": "\"C:\\Users\\Meta\\.cache\\codex-runtimes\\codex-primary-runtime\\dependencies\\python\\python.exe\" .\\tools\\ghostlight_state.py status",
"state:prepare-compaction": "\"C:\\Users\\Meta\\.cache\\codex-runtimes\\codex-primary-runtime\\dependencies\\python\\python.exe\" .\\tools\\ghostlight_prepare_compaction.py",
"agent-state:validate": "\"C:\\Users\\Meta\\.cache\\codex-runtimes\\codex-primary-runtime\\dependencies\\python\\python.exe\" .\\tools\\validate_agent_state.py",
"schema:validate": "npm run agent-state:validate && npm run projection:validate && npm run projected-context:validate && npm run lore-grounding:validate && npm run coordinator:validate && npm run responder-packets:validate && npm run responder-outputs:validate && npm run training-loop:validate && npm run initiative:validate && npm run ink:validate && npm run coverage:status",
"persona-state:validate": "\"C:\\Users\\Meta\\.cache\\codex-runtimes\\codex-primary-runtime\\dependencies\\python\\python.exe\" .\\tools\\validate_persona_state.py",
"schema:validate": "npm run agent-state:validate && npm run persona-state:validate && npm run projection:validate && npm run projected-context:validate && npm run lore-grounding:validate && npm run coordinator:validate && npm run responder-packets:validate && npm run responder-outputs:validate && npm run training-loop:validate && npm run initiative:validate && npm run ink:validate && npm run coverage:status",
"projection:validate": "\"C:\\Users\\Meta\\.cache\\codex-runtimes\\codex-primary-runtime\\dependencies\\python\\python.exe\" .\\tools\\validate_projection_examples.py",
"projected-context:validate": "\"C:\\Users\\Meta\\.cache\\codex-runtimes\\codex-primary-runtime\\dependencies\\python\\python.exe\" .\\tools\\validate_projected_contexts.py",
"lore-grounding:validate": "\"C:\\Users\\Meta\\.cache\\codex-runtimes\\codex-primary-runtime\\dependencies\\python\\python.exe\" .\\tools\\validate_lore_grounding.py",

File diff suppressed because it is too large Load diff

View file

@ -65,5 +65,6 @@
{"note": "VoidBot's new routine should become Ghostlight's cast swarm timing and memory substrate: characters take scene turns through heartbeat initiative, offstage agents use slower rumination/sleep turns for consolidation, canonical state moves toward CultCache-style MessagePack with JSON projections, and memory resonance/incubation/dream state should be backed by Qdrant vectors. Captured the plan in docs/architecture/voidbot-routine-adoption-plan.md.", "status": "ok", "ts": "2026-05-06T00:25:00+00:00", "type": "architecture"}
{"note": "Ghostlight began migrating machine-managed persistent state behind cultcache-py: branch and evidence records now route through a registered CultCache seam with readable JSON exports kept for diffability and compatibility.", "status": "accepted", "ts": "2026-05-06T03:46:41+00:00", "type": "architecture"}
{"note": "CultCache wire contract clarified: DatabaseEntry payloads must be MessagePack arrays indexed by explicit field keys with nil gaps for reserved/deleted slots; cultcache-py now exposes define_database_entry_type for that contract and CultLib generator was patched to preserve sparse key slots.", "status": "accepted", "ts": "2026-05-06T03:57:10+00:00", "type": "architecture"}
{"ts": "2026-05-06T04:49:20+00:00", "type": "architecture", "status": "accepted", "note": "Ghostlight agent-state schema is now the first shared cross-runtime payload contract. CultNet clients should carry ghostlight.agent_state.v0 unchanged inside typed document envelopes, with CultLib-style auth/session semantics handled by the transport layer rather than bespoke per-repo glue."}
{"note": "Ghostlight agent-state schema is now the first shared cross-runtime payload contract. CultNet clients should carry ghostlight.agent_state.v0 unchanged inside typed document envelopes, with CultLib-style auth/session semantics handled by the transport layer rather than bespoke per-repo glue.", "status": "accepted", "ts": "2026-05-06T04:49:20+00:00", "type": "architecture"}
{"ts": "2026-05-06T13:32:30+00:00", "type": "implementation", "status": "ok", "note": "Ghostlight now has a local Epiphany heartbeat bridge: tools/ghostlight_epiphany_heartbeat.mjs derives scene participants from existing initial/agent-state fixtures, invokes Epiphany's Rust epiphany-heartbeat-store ghostlight-scene profile, writes typed MessagePack scene heartbeat state, and emits validator-accepted scene_turn initiative receipts. This replaces the need for a parallel Ghostlight scheduler for the first scene-heartbeat slice."}
{"ts": "2026-05-29T15:07:33+00:00", "type": "architecture", "status": "accepted", "note": "Ghostlight no longer treats ghostlight.agent_state.v0 as the shared person-state wire contract. It mirrors gamecult.persona_state.v0 for portable Persona projections while keeping ghostlight.agent_state.v0 as the scene/world/story state contract."}

View file

@ -67,3 +67,4 @@
{"key": "2026-05-06T034641Z0000-0065-ea57d8ad2b40", "payload": "eyJub3RlIjogIkdob3N0bGlnaHQgYmVnYW4gbWlncmF0aW5nIG1hY2hpbmUtbWFuYWdlZCBwZXJzaXN0ZW50IHN0YXRlIGJlaGluZCBjdWx0Y2FjaGUtcHk6IGJyYW5jaCBhbmQgZXZpZGVuY2UgcmVjb3JkcyBub3cgcm91dGUgdGhyb3VnaCBhIHJlZ2lzdGVyZWQgQ3VsdENhY2hlIHNlYW0gd2l0aCByZWFkYWJsZSBKU09OIGV4cG9ydHMga2VwdCBmb3IgZGlmZmFiaWxpdHkgYW5kIGNvbXBhdGliaWxpdHkuIiwgInN0YXR1cyI6ICJhY2NlcHRlZCIsICJ0cyI6ICIyMDI2LTA1LTA2VDAzOjQ2OjQxKzAwOjAwIiwgInR5cGUiOiAiYXJjaGl0ZWN0dXJlIn0=", "stored_at": "2026-05-06T03:46:41.487861+00:00", "type": "ghostlight.evidence_record.v0"}
{"key": "2026-05-06T035710Z0000-0066-272010506962", "payload": "eyJub3RlIjogIkN1bHRDYWNoZSB3aXJlIGNvbnRyYWN0IGNsYXJpZmllZDogRGF0YWJhc2VFbnRyeSBwYXlsb2FkcyBtdXN0IGJlIE1lc3NhZ2VQYWNrIGFycmF5cyBpbmRleGVkIGJ5IGV4cGxpY2l0IGZpZWxkIGtleXMgd2l0aCBuaWwgZ2FwcyBmb3IgcmVzZXJ2ZWQvZGVsZXRlZCBzbG90czsgY3VsdGNhY2hlLXB5IG5vdyBleHBvc2VzIGRlZmluZV9kYXRhYmFzZV9lbnRyeV90eXBlIGZvciB0aGF0IGNvbnRyYWN0IGFuZCBDdWx0TGliIGdlbmVyYXRvciB3YXMgcGF0Y2hlZCB0byBwcmVzZXJ2ZSBzcGFyc2Uga2V5IHNsb3RzLiIsICJzdGF0dXMiOiAiYWNjZXB0ZWQiLCAidHMiOiAiMjAyNi0wNS0wNlQwMzo1NzoxMCswMDowMCIsICJ0eXBlIjogImFyY2hpdGVjdHVyZSJ9", "stored_at": "2026-05-06T03:57:10.429056+00:00", "type": "ghostlight.evidence_record.v0"}
{"key": "2026-05-06T044920Z0000-0067-d18749ed9b85", "payload": "eyJub3RlIjogIkdob3N0bGlnaHQgYWdlbnQtc3RhdGUgc2NoZW1hIGlzIG5vdyB0aGUgZmlyc3Qgc2hhcmVkIGNyb3NzLXJ1bnRpbWUgcGF5bG9hZCBjb250cmFjdC4gQ3VsdE5ldCBjbGllbnRzIHNob3VsZCBjYXJyeSBnaG9zdGxpZ2h0LmFnZW50X3N0YXRlLnYwIHVuY2hhbmdlZCBpbnNpZGUgdHlwZWQgZG9jdW1lbnQgZW52ZWxvcGVzLCB3aXRoIEN1bHRMaWItc3R5bGUgYXV0aC9zZXNzaW9uIHNlbWFudGljcyBoYW5kbGVkIGJ5IHRoZSB0cmFuc3BvcnQgbGF5ZXIgcmF0aGVyIHRoYW4gYmVzcG9rZSBwZXItcmVwbyBnbHVlLiIsICJzdGF0dXMiOiAiYWNjZXB0ZWQiLCAidHMiOiAiMjAyNi0wNS0wNlQwNDo0OToyMCswMDowMCIsICJ0eXBlIjogImFyY2hpdGVjdHVyZSJ9", "stored_at": "2026-05-06T04:49:20.304695+00:00", "type": "ghostlight.evidence_record.v0"}
{"key": "2026-05-29T150733Z0000-0068-c7660b1fa54e", "payload": "eyJub3RlIjogIkdob3N0bGlnaHQgbm8gbG9uZ2VyIHRyZWF0cyBnaG9zdGxpZ2h0LmFnZW50X3N0YXRlLnYwIGFzIHRoZSBzaGFyZWQgcGVyc29uLXN0YXRlIHdpcmUgY29udHJhY3QuIEl0IG1pcnJvcnMgZ2FtZWN1bHQucGVyc29uYV9zdGF0ZS52MCBmb3IgcG9ydGFibGUgUGVyc29uYSBwcm9qZWN0aW9ucyB3aGlsZSBrZWVwaW5nIGdob3N0bGlnaHQuYWdlbnRfc3RhdGUudjAgYXMgdGhlIHNjZW5lL3dvcmxkL3N0b3J5IHN0YXRlIGNvbnRyYWN0LiIsICJzdGF0dXMiOiAiYWNjZXB0ZWQiLCAidHMiOiAiMjAyNi0wNS0yOVQxNTowNzozMyswMDowMCIsICJ0eXBlIjogImFyY2hpdGVjdHVyZSJ9", "stored_at": "2026-05-29T15:07:33.580272+00:00", "type": "ghostlight.evidence_record.v0"}

View file

@ -62,7 +62,8 @@ live_architecture:
- `state/ghostlight-state.cultcache.jsonl` is the current CultCache-backed store for migrated branch and evidence records.
- `state/branches.json` and `state/evidence.jsonl` remain readable export surfaces during migration so humans, diffs, and older validators do not lose the plot.
- New persistent state seams should use `tools/ghostlight_state_store.py` instead of direct file writes.
- `schemas/agent-state.schema.json` is also the first shared cross-runtime payload contract. CultNet clients should move `ghostlight.agent_state.v0` documents unchanged inside typed document envelopes instead of inventing forked state ontologies per repo.
- `schemas/agent-state.schema.json` remains Ghostlight's scene/world state contract; it is no longer the shared person-state wire contract.
- `schemas/gamecult.persona_state.v0.schema.json` mirrors the shared PersonaState contract used by Epiphany public Faces, VoidBot repo Faces, and Ghostlight character projections. CultNet clients should carry PersonaState as `gamecult.persona-state` documents when they need a portable public-person payload.
state_model:
- Layer personality through organization, disposition, behavior, presentation, situational activation, relationships, goals, and values.
- Canonical authored state has no certainty; perceived overlays carry observed activation, attributed disposition, and confidence.

View file

@ -0,0 +1,197 @@
"""Validate GameCult PersonaState examples.
This is a focused dependency-free smoke validator. The JSON Schema remains the
canonical contract; this keeps examples honest in normal repo workflows without
dragging a validator dependency into Ghostlight.
"""
from __future__ import annotations
import argparse
import json
from datetime import datetime
from pathlib import Path
from typing import Any
ROOT = Path(__file__).resolve().parents[1]
DEFAULT_EXAMPLES = sorted((ROOT / "examples").glob("persona-state*.json"))
SCHEMA_VERSION = "gamecult.persona_state.v0"
TARGET_KINDS = {
"person",
"repo",
"scene",
"system",
"room",
"artifact",
"concept",
"relationship",
"self",
"community",
"thread",
"document",
"runtime",
"custom",
}
class ValidationError(Exception):
pass
def load_json(path: Path) -> Any:
with path.open("r", encoding="utf-8") as handle:
return json.load(handle)
def require(condition: bool, message: str) -> None:
if not condition:
raise ValidationError(message)
def require_keys(obj: dict[str, Any], keys: list[str], path: str) -> None:
missing = [key for key in keys if key not in obj]
require(not missing, f"{path} missing required keys: {', '.join(missing)}")
def require_timestamp(value: Any, path: str) -> None:
require(isinstance(value, str) and value, f"{path} must be a timestamp string")
normalized = value[:-1] + "+00:00" if value.endswith("Z") else value
try:
datetime.fromisoformat(normalized)
except ValueError as error:
raise ValidationError(f"{path} must be ISO-8601 parseable: {value}") from error
def require_0_1(value: Any, path: str) -> None:
require(isinstance(value, (int, float)), f"{path} must be numeric")
require(0 <= value <= 1, f"{path} must be between 0 and 1")
def validate_target(obj: Any, path: str) -> None:
require(isinstance(obj, dict), f"{path} must be an object")
require_keys(obj, ["kind", "id"], path)
require(obj["kind"] in TARGET_KINDS, f"{path}.kind is not a shared PersonaState target kind")
if obj["kind"] == "custom":
require(isinstance(obj.get("customKind"), str) and obj["customKind"], f"{path}.customKind is required for custom targets")
def validate_trait_map(obj: Any, path: str) -> None:
require(isinstance(obj, dict), f"{path} must be an object")
for name, vector in obj.items():
vector_path = f"{path}.{name}"
require(isinstance(vector, dict), f"{vector_path} must be an object")
require_keys(vector, ["mean", "plasticity", "currentActivation"], vector_path)
require("current_activation" not in vector, f"{vector_path}.current_activation is a native Ghostlight/VoidBot field; PersonaState uses currentActivation")
for key in ["mean", "plasticity", "currentActivation"]:
require_0_1(vector[key], f"{vector_path}.{key}")
def validate_activation_profile(obj: Any, path: str) -> None:
require(isinstance(obj, dict), f"{path} must be an object")
groups = [
"underlyingOrganization",
"stableDispositions",
"behavioralDimensions",
"presentationStrategy",
"voiceStyle",
"situationalState",
]
require_keys(obj, groups, path)
for group in groups:
validate_trait_map(obj[group], f"{path}.{group}")
def validate_anchored_thought(obj: Any, path: str) -> None:
require(isinstance(obj, dict), f"{path} must be an object")
require_keys(obj, ["id", "status", "target", "summary", "tension", "actionImplication", "createdAt", "updatedAt"], path)
require(obj["status"] in {"draft", "active", "cooling", "crystallized", "resolved", "retired"}, f"{path}.status is invalid")
validate_target(obj["target"], f"{path}.target")
require_timestamp(obj["createdAt"], f"{path}.createdAt")
require_timestamp(obj["updatedAt"], f"{path}.updatedAt")
if "retiredAt" in obj:
require_timestamp(obj["retiredAt"], f"{path}.retiredAt")
if "intensity" in obj:
require_0_1(obj["intensity"], f"{path}.intensity")
if "valence" in obj:
require(isinstance(obj["valence"], (int, float)), f"{path}.valence must be numeric")
require(-1 <= obj["valence"] <= 1, f"{path}.valence must be between -1 and 1")
def validate_candidate_action(obj: Any, path: str) -> None:
require(isinstance(obj, dict), f"{path} must be an object")
require_keys(obj, ["id", "status", "actionType", "readiness", "riskLevel", "target", "summary", "createdAt", "updatedAt"], path)
validate_target(obj["target"], f"{path}.target")
if "deliveryTarget" in obj:
validate_target(obj["deliveryTarget"], f"{path}.deliveryTarget")
require_timestamp(obj["createdAt"], f"{path}.createdAt")
require_timestamp(obj["updatedAt"], f"{path}.updatedAt")
if obj["actionType"] == "custom":
require(isinstance(obj.get("customActionType"), str) and obj["customActionType"], f"{path}.customActionType is required for custom actions")
def validate_document(document: dict[str, Any], source: Path) -> None:
require(document.get("schemaVersion") == SCHEMA_VERSION, f"{source} has wrong schemaVersion")
require_keys(
document,
[
"provenance",
"personaId",
"publicName",
"presentation",
"activationProfile",
"thoughtMemory",
"agencyPressure",
"candidateActions",
"affect",
"updatedAt",
],
str(source),
)
provenance = document["provenance"]
require_keys(provenance, ["sourceSystem", "sourceDocumentId", "sourceUpdatedAt", "exportedAt", "authority"], f"{source}.provenance")
require(provenance["authority"] in {"canonical", "projection", "import"}, f"{source}.provenance.authority is invalid")
require_timestamp(provenance["sourceUpdatedAt"], f"{source}.provenance.sourceUpdatedAt")
require_timestamp(provenance["exportedAt"], f"{source}.provenance.exportedAt")
require_keys(document["presentation"], ["voiceSummary"], f"{source}.presentation")
if "homeContext" in document["presentation"]:
validate_target(document["presentation"]["homeContext"], f"{source}.presentation.homeContext")
validate_activation_profile(document["activationProfile"], f"{source}.activationProfile")
for group_name in ["shortTerm", "memories", "incubation"]:
entries = document["thoughtMemory"].get(group_name)
require(isinstance(entries, list), f"{source}.thoughtMemory.{group_name} must be an array")
for index, thought in enumerate(entries):
validate_anchored_thought(thought, f"{source}.thoughtMemory.{group_name}[{index}]")
for index, pressure in enumerate(document["agencyPressure"].get("pressures", [])):
validate_anchored_thought(pressure, f"{source}.agencyPressure.pressures[{index}]")
for index, action in enumerate(document["candidateActions"].get("actions", [])):
validate_candidate_action(action, f"{source}.candidateActions.actions[{index}]")
if "voidbotProjection" in document:
for index, action in enumerate(document["voidbotProjection"].get("candidateInterventions", [])):
validate_candidate_action(action, f"{source}.voidbotProjection.candidateInterventions[{index}]")
affect = document["affect"]
for key in ["needs", "socialBonds", "statusReads", "moodDimensions", "socialBiases", "doctrineStances"]:
require(isinstance(affect.get(key), list), f"{source}.affect.{key} must be an array")
for index, need in enumerate(affect["needs"]):
validate_anchored_thought(need, f"{source}.affect.needs[{index}]")
require_timestamp(document["updatedAt"], f"{source}.updatedAt")
def main() -> int:
parser = argparse.ArgumentParser(description="Validate GameCult PersonaState examples.")
parser.add_argument("paths", nargs="*", type=Path, help="PersonaState JSON files to validate.")
args = parser.parse_args()
paths = args.paths or DEFAULT_EXAMPLES
require(paths, "No PersonaState examples found.")
for path in paths:
validate_document(load_json(path), path)
print(f"ok: {path}")
return 0
if __name__ == "__main__":
raise SystemExit(main())