diff --git a/docs/architecture/cultnet-shared-agent-state-contract.md b/docs/architecture/cultnet-shared-agent-state-contract.md index bb59a7b..966e672 100644 --- a/docs/architecture/cultnet-shared-agent-state-contract.md +++ b/docs/architecture/cultnet-shared-agent-state-contract.md @@ -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 diff --git a/examples/persona-state.call-of-the-void.oz.json b/examples/persona-state.call-of-the-void.oz.json new file mode 100644 index 0000000..ad211ca --- /dev/null +++ b/examples/persona-state.call-of-the-void.oz.json @@ -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" +} diff --git a/notes/fresh-workspace-handoff.md b/notes/fresh-workspace-handoff.md index 3f3869f..fe88f17 100644 --- a/notes/fresh-workspace-handoff.md +++ b/notes/fresh-workspace-handoff.md @@ -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. diff --git a/package.json b/package.json index 96e90eb..3d16027 100644 --- a/package.json +++ b/package.json @@ -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", diff --git a/schemas/gamecult.persona_state.v0.schema.json b/schemas/gamecult.persona_state.v0.schema.json new file mode 100644 index 0000000..2537628 --- /dev/null +++ b/schemas/gamecult.persona_state.v0.schema.json @@ -0,0 +1,1024 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "$id": "https://gamecult.dev/cultnet/gamecult.persona_state.v0.schema.json", + "title": "GameCult Persona State v0", + "description": "Portable person-state contract for Epiphany Face, VoidBot repo Faces, and Ghostlight characters. Epiphany work organs should not use this unless they are acting as a public Persona.", + "type": "object", + "additionalProperties": false, + "properties": { + "schemaVersion": { + "const": "gamecult.persona_state.v0" + }, + "provenance": { + "$ref": "#/definitions/provenance" + }, + "personaId": { + "type": "string" + }, + "publicName": { + "type": "string" + }, + "publicDescription": { + "type": "string" + }, + "presentation": { + "$ref": "#/definitions/presentation" + }, + "privateNotes": { + "type": "array", + "items": { + "type": "string" + }, + "default": [] + }, + "values": { + "type": "array", + "items": { + "$ref": "#/definitions/value" + }, + "default": [] + }, + "activationProfile": { + "$ref": "#/definitions/activationProfile" + }, + "thoughtMemory": { + "$ref": "#/definitions/thoughtMemory" + }, + "agencyPressure": { + "$ref": "#/definitions/agencyPressure" + }, + "candidateActions": { + "$ref": "#/definitions/candidateActions" + }, + "voidbotProjection": { + "$ref": "#/definitions/voidbotProjection" + }, + "affect": { + "$ref": "#/definitions/personaAffect" + }, + "updatedAt": { + "type": "string", + "format": "date-time" + } + }, + "required": [ + "schemaVersion", + "provenance", + "personaId", + "publicName", + "presentation", + "activationProfile", + "thoughtMemory", + "agencyPressure", + "candidateActions", + "affect", + "updatedAt" + ], + "definitions": { + "provenance": { + "type": "object", + "additionalProperties": false, + "properties": { + "sourceSystem": { + "type": "string" + }, + "sourceDocumentId": { + "type": "string" + }, + "sourceUpdatedAt": { + "type": "string", + "format": "date-time" + }, + "exportedAt": { + "type": "string", + "format": "date-time" + }, + "authority": { + "type": "string", + "enum": [ + "canonical", + "projection", + "import" + ] + } + }, + "required": [ + "sourceSystem", + "sourceDocumentId", + "sourceUpdatedAt", + "exportedAt", + "authority" + ] + }, + "publicHandle": { + "type": "object", + "additionalProperties": false, + "properties": { + "system": { + "type": "string" + }, + "handle": { + "type": "string" + }, + "uri": { + "type": "string", + "format": "uri" + } + }, + "required": [ + "system", + "handle" + ] + }, + "presentation": { + "type": "object", + "additionalProperties": false, + "properties": { + "avatarUri": { + "type": "string", + "format": "uri" + }, + "pronouns": { + "type": "string" + }, + "voiceSummary": { + "type": "string" + }, + "defaultRenderer": { + "type": "string", + "enum": [ + "text", + "chat", + "avatar", + "voice", + "scene", + "repo_face", + "custom" + ] + }, + "customRenderer": { + "type": "string" + }, + "homeContext": { + "$ref": "#/definitions/target" + }, + "jurisdiction": { + "type": "string" + }, + "publicHandles": { + "type": "array", + "items": { + "$ref": "#/definitions/publicHandle" + }, + "default": [] + } + }, + "required": [ + "voiceSummary" + ], + "allOf": [ + { + "if": { + "properties": { + "defaultRenderer": { + "const": "custom" + } + }, + "required": [ + "defaultRenderer" + ] + }, + "then": { + "required": [ + "customRenderer" + ] + } + } + ] + }, + "traitVector": { + "type": "object", + "additionalProperties": false, + "properties": { + "mean": { + "type": "number", + "minimum": 0, + "maximum": 1 + }, + "plasticity": { + "type": "number", + "minimum": 0, + "maximum": 1 + }, + "currentActivation": { + "type": "number", + "minimum": 0, + "maximum": 1 + } + }, + "required": [ + "mean", + "plasticity", + "currentActivation" + ] + }, + "traitMap": { + "type": "object", + "additionalProperties": { + "$ref": "#/definitions/traitVector" + } + }, + "activationProfile": { + "type": "object", + "additionalProperties": false, + "properties": { + "underlyingOrganization": { + "$ref": "#/definitions/traitMap" + }, + "stableDispositions": { + "$ref": "#/definitions/traitMap" + }, + "behavioralDimensions": { + "$ref": "#/definitions/traitMap" + }, + "presentationStrategy": { + "$ref": "#/definitions/traitMap" + }, + "voiceStyle": { + "$ref": "#/definitions/traitMap" + }, + "situationalState": { + "$ref": "#/definitions/traitMap" + } + }, + "required": [ + "underlyingOrganization", + "stableDispositions", + "behavioralDimensions", + "presentationStrategy", + "voiceStyle", + "situationalState" + ] + }, + "value": { + "type": "object", + "additionalProperties": false, + "properties": { + "id": { + "type": "string" + }, + "label": { + "type": "string" + }, + "priority": { + "type": "number", + "minimum": 0, + "maximum": 1 + }, + "summary": { + "type": "string" + } + }, + "required": [ + "id", + "label", + "priority" + ] + }, + "target": { + "type": "object", + "additionalProperties": false, + "properties": { + "kind": { + "type": "string", + "enum": [ + "person", + "repo", + "scene", + "system", + "room", + "artifact", + "concept", + "relationship", + "self", + "community", + "thread", + "document", + "runtime", + "custom" + ] + }, + "id": { + "type": "string" + }, + "label": { + "type": "string" + }, + "customKind": { + "type": "string" + } + }, + "required": [ + "kind", + "id" + ], + "allOf": [ + { + "if": { + "properties": { + "kind": { + "const": "custom" + } + }, + "required": [ + "kind" + ] + }, + "then": { + "required": [ + "customKind" + ] + } + } + ] + }, + "thoughtStatus": { + "type": "string", + "enum": [ + "draft", + "active", + "cooling", + "crystallized", + "resolved", + "retired" + ] + }, + "extensions": { + "type": "object", + "description": "Non-authoritative extension data from source systems. Portable consumers may preserve it, but must not treat it as core PersonaState authority unless they understand the source contract.", + "additionalProperties": true + }, + "anchoredThought": { + "type": "object", + "additionalProperties": false, + "properties": { + "id": { + "type": "string" + }, + "status": { + "$ref": "#/definitions/thoughtStatus" + }, + "target": { + "$ref": "#/definitions/target" + }, + "summary": { + "type": "string" + }, + "claim": { + "type": "string" + }, + "question": { + "type": "string" + }, + "tension": { + "type": "string" + }, + "actionImplication": { + "type": "string" + }, + "intensity": { + "type": "number", + "minimum": 0, + "maximum": 1 + }, + "valence": { + "type": "number", + "minimum": -1, + "maximum": 1 + }, + "createdAt": { + "type": "string", + "format": "date-time" + }, + "updatedAt": { + "type": "string", + "format": "date-time" + }, + "retiredAt": { + "type": "string", + "format": "date-time" + }, + "tags": { + "type": "array", + "items": { + "type": "string" + } + }, + "extensions": { + "$ref": "#/definitions/extensions" + } + }, + "required": [ + "id", + "status", + "target", + "summary", + "tension", + "actionImplication", + "createdAt", + "updatedAt" + ] + }, + "thoughtMemory": { + "type": "object", + "additionalProperties": false, + "properties": { + "shortTerm": { + "type": "array", + "items": { + "$ref": "#/definitions/anchoredThought" + }, + "default": [] + }, + "memories": { + "type": "array", + "items": { + "$ref": "#/definitions/anchoredThought" + }, + "default": [] + }, + "incubation": { + "type": "array", + "items": { + "$ref": "#/definitions/anchoredThought" + }, + "default": [] + } + }, + "required": [ + "shortTerm", + "memories", + "incubation" + ] + }, + "agencyPressure": { + "type": "object", + "additionalProperties": false, + "properties": { + "pressures": { + "type": "array", + "items": { + "$ref": "#/definitions/anchoredThought" + }, + "default": [] + } + }, + "required": [ + "pressures" + ] + }, + "candidateActions": { + "type": "object", + "additionalProperties": false, + "properties": { + "actions": { + "type": "array", + "items": { + "$ref": "#/definitions/candidateAction" + }, + "default": [] + } + }, + "required": [ + "actions" + ] + }, + "candidateAction": { + "type": "object", + "additionalProperties": false, + "properties": { + "id": { + "type": "string" + }, + "status": { + "$ref": "#/definitions/thoughtStatus" + }, + "actionType": { + "type": "string", + "enum": [ + "speak", + "draft", + "ask", + "propose", + "inspect", + "notify", + "wait", + "remember", + "handoff", + "render", + "external_action", + "custom" + ] + }, + "customActionType": { + "type": "string" + }, + "readiness": { + "type": "string", + "enum": [ + "draft", + "ready", + "blocked", + "waiting", + "expired" + ] + }, + "riskLevel": { + "type": "string", + "enum": [ + "none", + "low", + "medium", + "high", + "severe", + "unknown" + ] + }, + "target": { + "$ref": "#/definitions/target" + }, + "deliveryTarget": { + "$ref": "#/definitions/target" + }, + "summary": { + "type": "string" + }, + "rationale": { + "type": "string" + }, + "urgency": { + "type": "number", + "minimum": 0, + "maximum": 1 + }, + "confidence": { + "type": "number", + "minimum": 0, + "maximum": 1 + }, + "constraints": { + "type": "array", + "items": { + "type": "string" + }, + "default": [] + }, + "evidence": { + "type": "array", + "items": { + "$ref": "#/definitions/anchoredThought" + }, + "default": [] + }, + "createdAt": { + "type": "string", + "format": "date-time" + }, + "updatedAt": { + "type": "string", + "format": "date-time" + }, + "expiresAt": { + "type": "string", + "format": "date-time" + }, + "extensions": { + "$ref": "#/definitions/extensions" + } + }, + "required": [ + "id", + "status", + "actionType", + "readiness", + "riskLevel", + "target", + "summary", + "createdAt", + "updatedAt" + ], + "allOf": [ + { + "if": { + "properties": { + "actionType": { + "const": "custom" + } + }, + "required": [ + "actionType" + ] + }, + "then": { + "required": [ + "customActionType" + ] + } + } + ] + }, + "voidbotProjection": { + "type": "object", + "additionalProperties": false, + "properties": { + "candidateInterventions": { + "type": "array", + "description": "VoidBot-flavored projection of candidateActions for repo Face routines. This is not the generic PersonaState action authority.", + "items": { + "$ref": "#/definitions/candidateAction" + }, + "default": [] + } + }, + "required": [ + "candidateInterventions" + ] + }, + "moodDimension": { + "type": "object", + "additionalProperties": false, + "properties": { + "name": { + "type": "string" + }, + "value": { + "type": "number", + "minimum": 0, + "maximum": 1 + }, + "source": { + "type": "string" + }, + "updatedAt": { + "type": "string", + "format": "date-time" + } + }, + "required": [ + "name", + "value", + "updatedAt" + ] + }, + "socialBias": { + "type": "object", + "additionalProperties": false, + "properties": { + "name": { + "type": "string" + }, + "value": { + "type": "number", + "minimum": 0, + "maximum": 1 + }, + "summary": { + "type": "string" + }, + "behavioralPull": { + "type": "string" + }, + "updatedAt": { + "type": "string", + "format": "date-time" + } + }, + "required": [ + "name", + "value", + "summary", + "behavioralPull", + "updatedAt" + ] + }, + "socialBond": { + "type": "object", + "additionalProperties": false, + "properties": { + "id": { + "type": "string" + }, + "status": { + "$ref": "#/definitions/thoughtStatus" + }, + "subject": { + "$ref": "#/definitions/target" + }, + "object": { + "$ref": "#/definitions/target" + }, + "relationshipKind": { + "type": "string", + "enum": [ + "ally", + "friend", + "collaborator", + "mentor", + "ward", + "rival", + "audience", + "community_member", + "self_relation", + "unknown", + "custom" + ] + }, + "customRelationshipKind": { + "type": "string" + }, + "summary": { + "type": "string" + }, + "trust": { + "type": "number", + "minimum": 0, + "maximum": 1 + }, + "tension": { + "type": "number", + "minimum": 0, + "maximum": 1 + }, + "intensity": { + "type": "number", + "minimum": 0, + "maximum": 1 + }, + "lastEvidence": { + "$ref": "#/definitions/anchoredThought" + }, + "updatedAt": { + "type": "string", + "format": "date-time" + }, + "extensions": { + "$ref": "#/definitions/extensions" + } + }, + "required": [ + "id", + "status", + "subject", + "object", + "relationshipKind", + "summary", + "trust", + "tension", + "updatedAt" + ], + "allOf": [ + { + "if": { + "properties": { + "relationshipKind": { + "const": "custom" + } + }, + "required": [ + "relationshipKind" + ] + }, + "then": { + "required": [ + "customRelationshipKind" + ] + } + } + ] + }, + "statusRead": { + "type": "object", + "additionalProperties": false, + "properties": { + "id": { + "type": "string" + }, + "status": { + "$ref": "#/definitions/thoughtStatus" + }, + "target": { + "$ref": "#/definitions/target" + }, + "statusKind": { + "type": "string", + "enum": [ + "attention", + "authority", + "risk", + "trust", + "need", + "conflict", + "mood", + "opportunity", + "uncertainty", + "custom" + ] + }, + "customStatusKind": { + "type": "string" + }, + "summary": { + "type": "string" + }, + "confidence": { + "type": "number", + "minimum": 0, + "maximum": 1 + }, + "intensity": { + "type": "number", + "minimum": 0, + "maximum": 1 + }, + "valence": { + "type": "number", + "minimum": -1, + "maximum": 1 + }, + "lastEvidence": { + "$ref": "#/definitions/anchoredThought" + }, + "updatedAt": { + "type": "string", + "format": "date-time" + }, + "extensions": { + "$ref": "#/definitions/extensions" + } + }, + "required": [ + "id", + "status", + "target", + "statusKind", + "summary", + "confidence", + "updatedAt" + ], + "allOf": [ + { + "if": { + "properties": { + "statusKind": { + "const": "custom" + } + }, + "required": [ + "statusKind" + ] + }, + "then": { + "required": [ + "customStatusKind" + ] + } + } + ] + }, + "doctrineStance": { + "type": "object", + "additionalProperties": false, + "properties": { + "id": { + "type": "string" + }, + "status": { + "$ref": "#/definitions/thoughtStatus" + }, + "target": { + "$ref": "#/definitions/target" + }, + "stanceKind": { + "type": "string", + "enum": [ + "aligned", + "tension", + "rejected", + "uncertain", + "contextual", + "custom" + ] + }, + "customStanceKind": { + "type": "string" + }, + "principle": { + "type": "string" + }, + "summary": { + "type": "string" + }, + "actionImplication": { + "type": "string" + }, + "intensity": { + "type": "number", + "minimum": 0, + "maximum": 1 + }, + "updatedAt": { + "type": "string", + "format": "date-time" + }, + "extensions": { + "$ref": "#/definitions/extensions" + } + }, + "required": [ + "id", + "status", + "target", + "stanceKind", + "principle", + "summary", + "actionImplication", + "updatedAt" + ], + "allOf": [ + { + "if": { + "properties": { + "stanceKind": { + "const": "custom" + } + }, + "required": [ + "stanceKind" + ] + }, + "then": { + "required": [ + "customStanceKind" + ] + } + } + ] + }, + "personaAffect": { + "type": "object", + "additionalProperties": false, + "properties": { + "needs": { + "type": "array", + "items": { + "$ref": "#/definitions/anchoredThought" + }, + "default": [] + }, + "socialBonds": { + "type": "array", + "items": { + "$ref": "#/definitions/socialBond" + }, + "default": [] + }, + "statusReads": { + "type": "array", + "items": { + "$ref": "#/definitions/statusRead" + }, + "default": [] + }, + "moodDimensions": { + "type": "array", + "items": { + "$ref": "#/definitions/moodDimension" + }, + "default": [] + }, + "socialBiases": { + "type": "array", + "items": { + "$ref": "#/definitions/socialBias" + }, + "default": [] + }, + "doctrineStances": { + "type": "array", + "items": { + "$ref": "#/definitions/doctrineStance" + }, + "default": [] + } + }, + "required": [ + "needs", + "socialBonds", + "statusReads", + "moodDimensions", + "socialBiases", + "doctrineStances" + ] + } + } +} diff --git a/state/evidence.jsonl b/state/evidence.jsonl index 99c2208..75695d6 100644 --- a/state/evidence.jsonl +++ b/state/evidence.jsonl @@ -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."} diff --git a/state/ghostlight-state.cultcache.jsonl b/state/ghostlight-state.cultcache.jsonl index 1644bf6..9689fc6 100644 --- a/state/ghostlight-state.cultcache.jsonl +++ b/state/ghostlight-state.cultcache.jsonl @@ -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"} diff --git a/state/map.yaml b/state/map.yaml index 8858fa2..b9e9499 100644 --- a/state/map.yaml +++ b/state/map.yaml @@ -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. diff --git a/tools/validate_persona_state.py b/tools/validate_persona_state.py new file mode 100644 index 0000000..86b4858 --- /dev/null +++ b/tools/validate_persona_state.py @@ -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())