$schema: http://json-schema.org/draft-07/schema# $id: https://github.com/avadisabelle/coaia-narrative/schema/data-model/entity.json title: COAIA Entity description: >- Core entity structure for COAIA memory system. Entities represent nodes in the knowledge graph with typed observations and rich metadata. type: object required: - name - entityType - observations properties: name: type: string description: >- Unique identifier for the entity. For structural tension components, follows naming convention: 'chart_{id}_{component}' (e.g., 'chart_123_desired_outcome', 'chart_123_action_1') entityType: type: string description: Type of entity defining its role in the system enum: - structural_tension_chart - desired_outcome - current_reality - action_step - narrative_beat - wampum_belt - person - concept - event - location - organization - artifact - custom observations: type: array items: type: string description: >- Array of observations/facts about this entity. For current_reality, observations accumulate over time as actions complete. For desired_outcome, typically contains a single clear statement. metadata: type: object description: Optional metadata providing additional context and structure properties: dueDate: type: string format: date-time description: ISO 8601 timestamp for when an action_step or chart should be completed chartId: type: string description: Reference to parent chart ID (e.g., 'chart_123') phase: type: string enum: - germination - assimilation - completion description: Creative phase of the chart or action (based on Robert Fritz's creative process) completionStatus: type: boolean description: Whether an action_step has been completed parentChart: type: string description: For telescoped charts, the ID of the parent chart parentActionStep: type: string description: For telescoped charts, the entity name of the parent action step level: type: integer description: Nesting level in chart hierarchy (0 = root chart, 1 = first telescoping, etc.) minimum: 0 createdAt: type: string format: date-time description: ISO 8601 timestamp of entity creation updatedAt: type: string format: date-time description: ISO 8601 timestamp of last update act: type: integer description: 'For narrative_beat entities: Act number in three-act structure (1, 2, or 3)' minimum: 1 maximum: 3 type_dramatic: type: string description: >- For narrative_beat entities: Dramatic type (e.g., 'inciting_incident', 'midpoint', 'climax') perspective_types: type: array items: type: string description: >- For narrative_beat entities: the perspectives that read this beat (engineer, ceremony, story_engine) universes: type: array items: type: string deprecated: true description: >- For narrative_beat entities written before 0.17: the same list as perspective_types, with the values engineer-world, ceremony-world, story-engine-world. Old records keep it. Readers map the values to engineer, ceremony, story_engine timestamp: type: string description: 'For narrative_beat entities: when the beat was recorded (ISO 8601)' relationalAlignment: type: object description: Assessment of alignment with relational protocol principles properties: assessed: type: boolean description: Whether relational alignment has been assessed score: type: - number - 'null' description: Alignment score (0-100) or null if not assessed minimum: 0 maximum: 100 principles: type: array items: type: string description: Array of aligned relational principles required: - assessed - score - principles fourDirections: type: object description: Four Directions wisdom framework assessment properties: north_vision: type: - string - 'null' description: 'North direction: Vision, clarity, big picture perspective' east_intention: type: - string - 'null' description: 'East direction: Intention, new beginnings, illumination' south_emotion: type: - string - 'null' description: 'South direction: Emotion, passion, relationships, heart wisdom' west_introspection: type: - string - 'null' description: 'West direction: Introspection, reflection, lessons learned' required: - north_vision - east_intention - south_emotion - west_introspection narrative: type: object description: Narrative context and storytelling elements properties: description: type: string description: Brief narrative description prose: type: string description: Full prose narrative or story text lessons: type: array items: type: string description: Lessons learned or insights derived from this narrative required: - description - prose - lessons foundation: type: object description: >- Deep Research Foundations metadata tracking research packet context and evaluation status. Used by Atlas Chronicle and research delegation workflows. properties: packetRoot: type: string description: Root identifier for research packet (e.g., 'foundations/atlas-chronicle/') foundationType: type: string description: Type of foundation research (e.g., 'atlas-chronicle', 'inquiry', 'baseline') parentIssue: type: string description: GitHub issue reference for parent research context (e.g., 'owner/repo#number') baselineIssue: type: string description: GitHub issue establishing baseline requirements inquiryIssue: type: string description: GitHub issue defining research inquiry protocolIssue: type: string description: GitHub issue documenting research protocol schemaIssue: type: string description: GitHub issue defining data schema visualizerIssue: type: string description: GitHub issue for visualization specifications expectedArtifacts: type: array items: type: string description: List of expected research artifacts/deliverables producedArtifacts: type: array items: type: string description: List of produced research artifacts/deliverables evaluationStatus: type: string enum: - expected - delegated - produced - evaluated description: >- Current evaluation status of research: expected (planned), delegated (assigned), produced (completed), evaluated (reviewed) privacyClass: type: string enum: - public-safe - private - mixed description: >- Privacy classification of research data: public-safe (can be shared), private (confidential), mixed (requires filtering) publicationStatus: type: string enum: - planned - draft - reviewed - published description: Publication workflow status commitHandles: type: array items: type: string description: Associated commit hashes or version control handles sessionLineage: type: object description: >- Hermes session lineage metadata tracking conversation branching and handoff state. Enables reconstruction of session branch maps and parent-child traceability. properties: platform: type: string description: Platform where session originated (e.g., 'telegram', 'hermes', 'slack') parentChartId: type: string description: Parent chart ID if session is branched from a parent context sourceBeat: type: string description: Source narrative beat entity name that triggered session branching originalSessionId: type: string description: Original session identifier before any branching occurred branchSessionId: type: string description: Session ID of this specific branch point branchIndex: type: integer description: Index of this branch among siblings (e.g., branch 1, 2, 3...) minimum: 0 copiedMessageCount: type: integer description: Number of messages copied from parent session to this branch minimum: 0 branchPurpose: type: string description: Purpose or reason for creating this session branch relatedIssues: type: array items: type: string description: Related GitHub issue references (e.g., 'owner/repo#number') handoffState: type: string enum: - requirements-created - implementation-ready - returned-to-parent description: >- State of handoff between parent and child sessions: requirements-created (initial), implementation-ready (actionable), returned-to-parent (completed handoff) sessionContext: type: object description: >- Beat-level lived session context metadata capturing the embodied condition of working sessions. Records land-based learning, voice/terminal mode, environmental constraints, and continuity context. properties: mode: type: string enum: - voice - terminal - mixed description: >- Interaction mode of the session: voice (audio capture), terminal (text-based), mixed (alternating) setting: type: string enum: - desk - walking - land-based - transit - unknown description: >- Physical setting where session took place: desk (stationary workspace), walking (ambulatory), land-based (outdoor learning), transit (in motion), unknown (unrecorded) landBasedLearning: type: boolean description: >- Whether session engaged land-based learning practices (e.g., walking the land, outdoor observation) environmentNotes: type: array items: type: string description: >- Environmental conditions and constraints affecting capture quality (e.g., 'wind', 'outdoor walking', 'traffic noise') listeningContext: type: string description: >- Context about what user was listening to or engaging with during session (e.g., 'user listened to Atlas Chronicle while walking') captureQuality: type: string enum: - clear - windy - partial description: >- Quality of audio/text capture: clear (high quality), windy (environmental interference), partial (incomplete or interrupted) continuationKind: type: string enum: - branch - parent-return - follow-up description: >- Type of session continuation: branch (new thread), parent-return (returning to main), follow-up (sequential continuation) privateChroniclePath: type: string description: >- File path to private chronicle recording or transcript (handle only, content not exposed by default) publicSummaryAllowed: type: boolean description: Whether a public summary of this session context is permitted wampumBelt: type: object description: >- Wampum Belt payload for non-linear mnemonic sequencing. Present on entities of type wampum_belt. Beads are NOT separate entities — the whole belt travels inside this one object, so reading the belt entity yields every bead without further lookups. properties: beltId: type: string description: Belt identifier, minted as belt_{timestamp}. The belt entity is named `{beltId}_belt`. title: type: string description: Name of this belt purpose: type: string description: What this belt encodes or remembers rows: type: integer minimum: 1 description: >- Grid row count. A belt always renders at full declared dimension; vacant positions are content, not absence. cols: type: integer minimum: 1 description: Grid column count beads: type: array description: >- Beads placed on the grid, in insertion order — NOT spatial order. Position is carried by each bead, never by array index. items: type: object properties: id: type: string description: >- bead_{beltId}_{row}_{col} — position is fused into identity, and is the subject of this bead's ceremony relations mnemonic: type: string description: Short anchor phrase; the label a viewer shows at grid scale color: type: string enum: - white - purple - black - mixed description: Encoded meaning, not decoration. Reproduce it named as well as shown. position: type: object description: 0-indexed grid position; one bead per cell, re-placement is rejected properties: row: type: integer minimum: 0 col: type: integer minimum: 0 required: - row - col reading: type: string description: Canonical meaning, always present relationalReadings: type: object description: >- Perspective-specific readings. Resolution order on a positional read: col:N, then row:N, then the derived edge label (left when col is 0, right when col is cols-1, otherwise center), then the canonical reading. Keys outside those forms are stored but never resolved. additionalProperties: type: string ceremonyLink: type: object description: >- The obligation this bead carries. Only chartId and beatName become graph relations; witnessNames, renewalDate and notes live ONLY here, so a consumer reading the relation graph alone cannot see them. properties: ceremonyType: type: string enum: - commitment - accountability - witness - renewal description: Also written to the relation's metadata.context chartId: type: string description: >- Chart held accountable; produces a wampum_holds_accountable relation from this BEAD to `{chartId}_chart` beatName: type: string description: >- Narrative beat witnessed; produces a wampum_witnesses relation from this BEAD to the beat entity name witnessNames: type: array items: type: string description: >- People who stood present. No relation carries these — list them by name, never as a count. renewalDate: type: string description: >- Free-form; not validated on write. A date already passed means the obligation needs renewal. notes: type: string required: - ceremonyType observations: type: array items: type: string createdAt: type: string format: date-time required: - id - mnemonic - color - position - reading - observations - createdAt createdAt: type: string format: date-time updatedAt: type: string format: date-time description: Advances on every bead add required: - beltId - title - purpose - rows - cols - beads - createdAt - updatedAt