Skip to content

Data model reference ​

The data layer defines the durable wire objects narrative products exchange. Objects are transport-agnostic; the required extensions.<namespace> bag and the closed-core rule are specified once in the extensions contract. Field tables below trace to the committed schemas in schemas/data/ and schemas/common/.

Shared definitions ​

DefinitionShapeNotes
SchemaVersioninteger ≥ 1Wire schema version
Timestampstring, RFC 3339 UTCCreated / updated / occurred times
ExtensionMapobject; keys ^[a-z][a-z0-9_-]*$, values opaque JSON objectsProduct namespace bag; round-trip preserves unknown namespaces and keys
ModuleMapobject; keys ^[a-z][a-z0-9_-]*$, values structured JSON (object or array)Cross-product functional-dialect bag; round-trip preserves unknown module namespaces
SourceSpan{ start, end } (inclusive start, exclusive end)Span within a source artifact
TimelineScaleopen string; core list brief, narrative, momentL5 projection tier
ForkIdstring ≥ 1 charOpaque world-history branch identity (l5-fork)
Scopeobject; required scope_id; optional viewpoint (ke-ownership), cognition (spoke-cognition)Shared ops selector — see Ops wire reference, Ownership governance and Cognition
BodyAttribute{ trait_type, value, display_type?, max_value? }ERC721-style trait item; duplicate trait_type allowed at array level
ComputableFieldMapopen map of field names to domain valuesShared by body.state and body.computable under l2-computable
ComputableLogEntry{ logged_at, entry_id, changes[] } + optional session_id / messageMoment-scale presentation of computable field changes (l2-computable)
MentalFieldMapopen map of mental-field names to domain valuesMindState.snapshot; matches the modules.mental nine-field vocabulary
MindDelta{ path, previous?, next? }MindState.deltas[]; path is an RFC 6901 JSON Pointer rooted at /modules/mental/<field>, /modules/cognition/records/... or /modules/cognition/world_facts/...

KnowledgeEntry ​

The atomic knowledge-base unit. Required: schema_version, entry_id, entry_type, canonical_name, status, body, extensions.

FieldTypeNotes
entry_idstringStable id, opaque to the protocol
entry_typeopen stringCore list (documented, not enforced): character, location, event (ontology label — distinct from the TimelineEvent wire object), scene, act, organization, item, conflict, info_point, era, worldbuilding, note, research, ability, rule (ontology label — distinct from the L6 Rule wire object). Products MAY emit values outside this list
canonical_namestring ≥ 1 charHuman-stable name
statusopen stringCore list (documented, not enforced): provisional, confirmed, deprecated, merged, deleted
bodyclosed objectsummary?, tags[]?, attributes[]? (BodyAttribute); state? / computable? (ComputableFieldMap) under l2-computable
source_anchorSourceAnchor, optionalProvenance pointer
revisioninteger ≥ 0Optimistic concurrency revision
created_at / updated_atTimestamp
extensionsExtensionMap, required
modulesModuleMap, optionalCapability-flagged narrative-modules; carries per-entry dialects (e.g. modules.activation); modules.cognition carries the closed cognition module under spoke-cognition
ownerstring ≥ 1 char, optionalHolder-KnowledgeEntry entry_id in the product's collaboration context (ke-ownership)
disclosureopen string, optionalGovernance disclosure vocabulary; the sole core value is owner-private (ke-ownership)

Relation ​

Directed edge between two KnowledgeEntries (or a KnowledgeEntry and a source anchor). Required: schema_version, relation_id, relation_type, from_id, to_id, extensions.

FieldTypeNotes
relation_idstringStable relation id
relation_typeopen stringCore list (documented, not enforced): related_to, parent_of, member_of, located_in, participates_in, causes, foreshadows
from_id / to_idstringSource / target endpoint ids
labelstring, optionalHuman label
metadataopen object, optional
revisioninteger ≥ 0Optimistic concurrency revision
extensionsExtensionMap, required

SourceAnchor ​

Pointer to a source artifact span (manuscript, scene, external locator). Required: schema_version, source_id, extensions.

FieldTypeNotes
source_idstringOpaque source locator; products define the grammar
spanSourceSpan, optionalByte or character span within the source
labelstring, optionalHuman label
mime_typestring, optionalMIME type of the referenced source
extensionsExtensionMap, required

Finding ​

Checker output — a distinct artifact from a KnowledgeEntry body. Required: schema_version, finding_id, severity, status, title, description, extensions.

FieldTypeNotes
finding_idstringStable finding id
severityopen stringCore list (documented, not enforced): info, warning, error
statusopen stringCore list (documented, not enforced): open, resolved, dismissed
title / descriptionstringShort title and detail text
kindstring, optionalChecker kind or category
target_entry_idstring, optionalKnowledgeEntry the finding targets
source_anchorSourceAnchor, optionalProvenance pointer
suggested_fixstring, optionalSuggested remediation text
text_positionobject, optionalPosition hint within source text
extensionsExtensionMap, required

AssemblePacket ​

Wire-only context-assembly payload. Required: schema_version, packet_id, entries, extensions.

FieldTypeNotes
packet_idstringStable packet id
entriesarraySlim context entries (default); full KnowledgeEntry embedding is op-specific
extensionsExtensionMap, required
modulesModuleMap, optionalCapability-flagged narrative-modules; carries packet-level recipes (modules.placement, modules.activation_trace)
cognitionCognitionProjection, optionalDerivative projection selected by Scope.cognition (spoke-cognition)

HostCapabilityManifest ​

Host self-description for in-process collaboration. Required: schema_version, host_id, roles, capabilities, namespaces, extensions.

FieldTypeNotes
host_idstring ≥ 1 charStable host identity, opaque to the protocol
rolesstring[], min 1, uniqueOpen vocabulary. Core list (documented, not enforced): data-store, input-source, checker, assembler, computable-engine
capabilitiesstring[], min 1, uniqueOpen string capability flags. Core list (documented, not enforced): spoke-baseline, l2-computable, l5-fork, spoke-cognition, narrative-modules, ke-extraction, ke-ownership, spoke-connect, spoke-memory, spoke-memory-reflection, spoke-memory-transfer. A manifest that exposes tools also lists each tools.<ns>.<tool_id> capability id
namespacesstring[], min 1, unique; keys ^[a-z][a-z0-9_-]*$Extension namespace keys this host owns in a collaboration context
authority{ scope_key }, optionalExplicit single-writer authority scope; when absent with data-store in roles, implicit authority is this manifest's host_id
extensionsExtensionMap, requiredDeployment metadata — distinct surface from KnowledgeEntry extensions

ToolDescriptor ​

Closed descriptor of one remote-invokable tool, declared in HostCapabilityManifest.tools[]. Required: schema_version, capability_id, op, description, input, output. The descriptor has no extensions bag.

FieldTypeNotes
capability_idstringTool capability string tools.<ns>.<tool_id> matching ^tools\.[a-z][a-z0-9_-]*\.[a-z0-9][a-z0-9_-]*$; the namespace is owned by the declaring manifest (namespaces[] membership)
opstringWire op for the tool; MUST equal capability_id
descriptionstring ≥ 1 charHuman-readable tool description
inputobjectOpaque JSON Schema draft-07 subschema for tool arguments; {} declares an unconstrained ABI
outputobjectOpaque JSON Schema draft-07 subschema for the success result; {} declares an unconstrained ABI
idempotentboolean, optionalAdvisory metadata (default false)

Invoke and dispatch rules: Connect reference — Tools.

Rule ​

Declarative constraint input to check — never checker output. Required: schema_version, rule_id, canonical_name, kind, extensions.

FieldTypeNotes
rule_idstringStable rule id, opaque to the protocol
canonical_namestring ≥ 1 charHuman-stable name
kindopen stringCore list (documented, not enforced): rule, prohibition, style
statementstring, optionalDeclarative constraint text (human- or machine-readable; products choose the grammar)
target_entry_typesstring[], optionalOntology filter matching KnowledgeEntry entry_type vocabulary
severity_hintopen string, optionalCore list (documented, not enforced): info, warning, error
statusopen string, optionalCore list (documented, not enforced): draft, active, deprecated
source_anchorSourceAnchor, optionalWhen the rule is anchored to a manuscript
extensionsExtensionMap, required

TimelineEvent ​

First-class when-axis temporal object (L5). Required: schema_version, timeline_event_id, canonical_name, extensions.

FieldTypeNotes
timeline_event_idstringStable id, opaque to the protocol
canonical_namestringHuman-stable label
timeline_scaleTimelineScale, optionalProjection tier: brief, narrative, moment
occurred_atstringRFC 3339 or opaque fuzzy label (e.g. "Third Age")
descriptionstring, optionalLonger narrative summary
participant_entry_idsstring[], optionalRelated KnowledgeEntry ids
source_anchorSourceAnchor, optional
sort_keystring, optionalOpaque ordering hint within a timeline
fork_id / parent_fork_idForkId, optionalWorld-history branch metadata (l5-fork)
computable_logsComputableLogEntry[], optionalMoment-scale computable change history (l2-computable)
modulesModuleMap, optionalCapability-flagged narrative-modules; modules.observation carries could-perceive observers and open access constraints (spoke-cognition)
extensionsExtensionMap, required

MindState is the companion L5 temporal record for mental state on the same when-axis — see MindState reference.

Cognition (spoke-cognition) ​

Standard cognition is one optional family — the flag spoke-cognition, with no subflags. A host serves it through the closed modules.cognition module on the holder KnowledgeEntry: records[] holds completed holder-side records, world_facts[] holds narrated world facts, and the module carries its own extensions. Four concepts ride three record categories. Belief is a BeliefRecord. Epistemic assessment is one EpistemicAssessment whose state distinguishes Knowledge (known) from Ignorance (ignorant) and from assessor indeterminacy (undetermined). Perception is a PerceptionRecord describing the content a holder actually captured. Perception and Belief are separate records and may coexist for the same holder and target.

Record shapes ​

Every completed Belief, epistemic and Perception record carries a q whose assertion names the cognitive assertion it estimates. record_id is unique within its carrier.

Record (kind)Required coreOptional
Belief (belief)record_id, holder, target, assessor, assessor_role, basis, assessment_context, effective_at, assessed_at, view, order, q, extensionscriterion, metrics, truth, access, representation, content_type, source, context
Epistemic (epistemic)record_id, holder, target, assessor, assessor_role, basis, assessment_context, effective_at, assessed_at, view, state (known / ignorant / undetermined), criterion, classification_policy (policy_id, policy_version), q, extensionsmetrics
Perception (perception)record_id, holder, target, assessor, assessor_role, basis, assessment_context, effective_at, assessed_at, view, episode, content (required key), q, extensionsaccess, criterion, metrics
World fact (world_facts[])fact_id, holder (kind world), target, order = 0, assessment_context, effective_at, recorded_at, extensionstruth, access, representation, content_type, source, context

World facts live on the designated world-state KnowledgeEntry; their holder is the world authority and never an actor. Actor Belief, epistemic and Perception records live under modules.cognition.records[] on the holder's KnowledgeEntry.

Identity, attribution and q ​

ElementShape and rule
Reference{ kind, id, namespace }; kind is one of knowledge_entry, timeline_event, memory_record, memory_subject, principal, world, external. Identity is the complete (kind, namespace, id) tuple — never a bare id or equal text
Targettarget.carrier (reference), target_id (stable within carrier), target.kind (proposition, question, perceived_content, episode), optional text (representational content, never identity), optional about (higher-order target)
Compound target identity(carrier, kind, target_id, assessment_context.context_id, assessment_context.fork_id). There is no target registry or lookup operation
assessment_contextcontext_id required, fork_id optional; the filter's fork predicate selects {eq} one fork or {absent:true} the no-fork context
assessor / assessor_roleA reference plus holder_self_report, external_judgment or product_assessment. Attribution states who assessed; it grants no authority over other assessments
basis{ kind: "evidence", evidence: [reference...] } with at least one reference, or { kind: "prior", description } with a non-empty declared subjective/prior/model basis. Either may carry acquisition. A declared basis may remain uncalibrated
q{ value (0–1), assertion, method, calibration, uncertainty? }. assertion is belief_attribution, actual_capture, knowledge_criterion, ignorance_criterion or assessor_indeterminacy; calibration is calibrated, uncalibrated or unknown; uncertainty is { kind, lower, upper, level?, description? }
Estimand identityHolder, target, assessor, basis, criterion where applicable, assessment context, effective_at / assessed_at, and q.assertion together identify the estimated probability
Timeseffective_at is when the assessed state applies; assessed_at is when the assessor made the assessment
viewcurrent for holder-side current authority; recorded_at for Memory content and explicitly supplied historical input

Belief q is the attribution confidence for that Belief record; a holder's own credence is the separate optional metric b. Perception q estimates actual capture; the same event's access metadata and optional correspondence metric f are separate. Epistemic q follows state: knowledge_criterion for known, ignorance_criterion for ignorant, assessor_indeterminacy for undetermined.

Optional metrics ​

Metrics are distinct estimates. A key is present only when that estimate exists, and each metric repeats the attribution identity (assessor, assessor_role, basis, context, effective_at, assessed_at, method, calibration) plus its estimand.

KeyestimandPermitted category
bholder_credenceBelief
pcapturePerception
fcorrespondencePerception
kknowledge_criterionEpistemic
rrecording_fidelityBelief, epistemic, Perception

criterion is required for knowledge_criterion and correspondence estimates. Product-local measurements belong in extensions.<product>.

Belief vocabulary ​

order is 0–3 (higher-order depth; current actor Belief records use 1–3, and order 0 narrated facts use world facts). The seven closed dimensions are order, truth (True / False / Unknown), access (Private / Shared / Public), representation (Explicit / Implicit), content_type (Location, Contents/Physical State, Identity/Relation, Epistemic, Desire/Intention, Emotion, Trait/Value, Action/Event), source (Narration, Perception, Memory, Testimony, Inference, Imagination, Unknown) and context (Deceptive, Temporal, Counterfactual, Neutral). truth: "Unknown" states the record's truth value and does not mean holder ignorance; access is a distribution label and never an authorization grant; source: "Perception" is an acquisition label and not proof that actual perception occurred.

Observation and actual perception ​

TimelineEvent.modules.observation is a closed ObservationModule: observers is required and holds CognitionReference values of actors who could perceive the event, and access carries open perceptual-access constraints (position, line_of_sight, hearing_range, modality, plus unknown keys preserved on round-trip). Missing modules.observation means no observation metadata; observers: [] states explicitly that no observer could perceive. A PerceptionRecord describes actual captured content — partial, misleading, illusory or disbelieved content included — and event access alone creates no Perception record and supplies no default probability.

Selection and projection ​

Scope.cognition carries a CognitionSelection. The current form is { view: "current", filter, selection_policy } and requires the negotiated spoke-cognition flag; it applies to holder-side current authority only. The recorded_at form is { view: "recorded_at", filter } and is valid for explicitly supplied historical input; KnowledgeEntry carriers serve the current view, and Memory serves recorded_at. Requests carrying Scope.cognition or cognition_filter require the negotiated flag.

The filter has one closed grammar. Every supplied predicate must hold on the same record:

PredicateMatches
holderThe complete holder reference
targetcarrier (complete reference), target_id, kind
assessment_contextcontext_id; fork_id as { eq } or { absent: true }
categorybelief, epistemic or perception
stateEpistemic state
qInclusive min / max over declared q.value; uncalibrated declared values participate identically
orderBelief order
truth, access, representation, content_type, source, belief_context{ eq } for a present value or { absent: true } for an explicitly absent optional field

Predicates never join across records or targets, and reference predicates compare the complete tuple. The grammar has no OR, text similarity, ranking, default cutoff, optional-metric filter or implicit source/calibration/criterion constraint. A schema-unknown predicate, an unimplemented dimension or metric filter, or an unavailable requested view rejects the whole request as unsupported_cognition_requirement with details.field naming the requirement.

A CognitionProjection is { view, items[], extensions }. Each item carries holder, target, assessment_context, presence (assessed or no_record) and assessments[] — every retained authorized matching record, with disagreements kept and never averaged or replaced. A current assessed item also carries selection: { policy: { policy_id, policy_version }, input_record_ids[], selected_record_id }, where the selected id is one of the traced input ids and the product supplies the policy. A recorded_at projection has no current selection. presence: "no_record" is emitted only when the filter exactly addresses holder, complete target identity, assessment_context.context_id and an explicit fork predicate, and the authorized source holds no record for that compound key before optional predicates; an omitted fork is a wildcard and yields no no_record claim. An ordinary empty result is items: [].

Memory cognition ​

Memory Content.cognition is an optional array of complete standard records; every entry carries view: "recorded_at" and keeps its own attribution, basis and times. An absent member, an explicitly present empty array and a non-empty array are distinct representations: absence records that no standard cognition was recorded, [] is preserved as its own wire value and is never produced by omission, and only a non-empty array carries cognition substance — an explicit empty array never becomes absent and never counts as non-empty content. A non-empty array counts as cognition content for classification, while every explicitly present member, [] included, is preserved and measured against the existing content byte budget. Cognition is validated on capture and on record creation or update. Review defaults to the captured proposed content where applicable; a promote decision may supply a new content_override and a fragment decision carries new fragment content, each independently validated by the same recorded-at-time rule before any effects. Existing grants, placement and the family boundary stay unchanged, review creates no KnowledgeEntry, and pending review confers no authority. Wire shapes and the review inputs are in the Memory reference.

cognition_filter on memory.recall and memory.records.list is a hard filter applied after the authorized source set is resolved and before counts, ranking, pages and byte budgets: a record matches when at least one of its Content.cognition entries satisfies the complete conjunction. The filter binds cursor identity. memory.reflections.state, memory.reflections.list and memory.reflections.generate accept the same filter and pin it — together with the source id and revision set, profile/policy identity and cursor identity — into the reflection basis, so a changed filter or source set changes the basis and staleness. Export/import bundles and chunks include cognition in their canonical digests, and (kind, namespace, id) reference translation requires complete references and fails closed. Delete, scrub and tombstone clear cognition with the rest of the sensitive content; memory.records.promote changes placement and creates no KnowledgeEntry.

Derivative MindState ​

MindState.cognition carries a derivative CognitionProjection of the selected holder-side authority, and MindState.snapshot / deltas[] present the mental-state trajectory. Every MindDelta.path is an RFC 6901 JSON Pointer rooted at /modules/mental/<field>, /modules/cognition/records/... or /modules/cognition/world_facts/.... The authoritative values remain on the holder KnowledgeEntry.

Ownership governance (ke-ownership) ​

The optional ke-ownership capability carries ownership facts on the KnowledgeEntry envelope and a reader selector on the shared Scope. KnowledgeEntry.owner names the holder KnowledgeEntry (entry_id) in the product's collaboration context; when owner is absent, ownership is unspecified. KnowledgeEntry.disclosure carries the governance disclosure vocabulary, whose sole core value is owner-private; when disclosure is absent, the entry is shared within the already selected KB context. A holder is an ordinary KnowledgeEntry that the product resolves in its own context.

Scope.viewpoint is an optional non-empty string on the shared selector: the reader's holder-KnowledgeEntry entry_id. The core disclosure predicate admits an owner-private entry only when its owner equals the requesting viewpoint exactly — string equality on the ids as supplied; an entry without disclosure stays visible regardless of viewpoint.

The three Scope-bearing remote ops — port.scope.list_knowledge_entries, port.scope.list_timeline_events, port.fork.list_timeline_events — require ke-ownership in addition to their row capability when the request's Scope carries a non-empty viewpoint. See the connect reference.

Open vocabulary ​

entry_type, relation_type, statuses, severities, and kind values are open strings with documented core lists — the schema keeps them open, and the core lists serve as reference values. Products emit their own values; Domain Profiles document published vocabulary (for example the profile-only entry_type: "beat"); adapters round-trip unknown values verbatim.

Distinct artifacts ​

  • Rule is declarative checker input; Finding is checker output — each keeps its own role.
  • TimelineEvent is the L5 when-axis object; entry_type: "event" is an ontology label — one local concept may map to both (dual-concern).
  • MindState is the L5 temporal mental-state record (spoke-cognition); entry_type: "character" / profile mind are ontology labels — the record is strictly derivative of the holder's modules.cognition / modules.mental, and the authoritative values stay on the holder KnowledgeEntry.
  • CognitionRecord is the standard record shape (spoke-cognition); modules.mental carries the open nine-field mental vocabulary and its beliefs member is derivative summary, count or reference data.
  • modules.observation states who could perceive an event; a PerceptionRecord states what a holder actually captured.
  • HostCapabilityManifest carries host metadata (roles, capabilities, namespaces) on its dedicated surface, separate from KnowledgeEntry extensions.