Adopt shared PersonaState contract
This commit is contained in:
parent
c48dac69a6
commit
a1ec7ace5d
9 changed files with 1386 additions and 68 deletions
|
|
@ -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
|
||||
|
|
|
|||
89
examples/persona-state.call-of-the-void.oz.json
Normal file
89
examples/persona-state.call-of-the-void.oz.json
Normal 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"
|
||||
}
|
||||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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",
|
||||
|
|
|
|||
1024
schemas/gamecult.persona_state.v0.schema.json
Normal file
1024
schemas/gamecult.persona_state.v0.schema.json
Normal file
File diff suppressed because it is too large
Load diff
|
|
@ -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."}
|
||||
|
|
|
|||
|
|
@ -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"}
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
197
tools/validate_persona_state.py
Normal file
197
tools/validate_persona_state.py
Normal 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())
|
||||
Loading…
Reference in a new issue