Consolidate CultNet schema contracts into CultLib/contracts/cultnet

REC-032 commit 1: move the canonical 33 TS + witness-artifact-bundle
schema files (34 total) into runtime-neutral CultLib/contracts/cultnet,
move the interop-note schema (and delete the zero-consumer discovery-*
schemas per D3, tagged parked/cultnet-discovery-contracts) into
contracts/cultnet/interop, and delete the 27 C# and 24 Rust duplicate
copies after confirming byte-for-byte equivalence (only
cultnet.snapshot-request differs: TS carries shardId/shardEpoch, a
known drift already resolved in favor of the TS shape).

Rewrite every $id from https://github.com/GameCult/cultnet-ts/contracts/
and .../cultnet-ts/integration/contracts/ to
https://github.com/GameCult/CultLib/contracts/cultnet/(interop/); give
the two shard-catalog schemas URL ids per D1, replacing the bare
cultnet.shard_catalog_*.v0 identifiers; leave ghostlight.agent-state's
Ghostlight-owned $id untouched per D5.

Repoint every runtime's load path and id literal at the new location:
C# csproj EmbeddedResource + LogicalName, Rust include_str! paths,
TS contracts.ts imports + swarm-contracts manifest/tooling + package.json
files/prepack, and the id/path literals in the C#, Rust, Python and
Kotlin interop tests and peers. Python and Kotlin still build their own
schema JSON in-process (D2); only their base constants, id literals,
and (for Kotlin) contentHash literals were swapped. Every Kotlin
contentHash was recomputed from the final canonical files using the
runtime's own stable-stringify + SHA-256 function; all matched the
planner's precomputed values except cultnet.schema-catalog-response,
where the planner's proposed value did not match recomputation and the
freshly computed value was used instead.

REC-032, decisions D1/D2/D3/D5.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
This commit is contained in:
Meta Vens 2026-09-13 17:27:41 +02:00
commit fcc49cffa0
107 changed files with 145 additions and 3198 deletions

View file

@ -1,173 +0,0 @@
# CultNet Distributed Database Notes
CultNet's distributed database path is a typed realtime database over CultCache
documents. The design should borrow proven distributed-systems ideas without
copying their entire machine or laundering vague consistency through impressive
words.
## Prior Art To Keep
- RethinkDB changefeeds: subscriptions should emit old/new document views and
support point, table/schema, and filtered watches.
- Firebase Realtime Database: client ergonomics should make realtime sync feel
like the default path, but presence, disconnect handling, and server-side
authority still need explicit ownership.
- Dynamo: partitioning, replication metadata, vector-ish causality, hinted
recovery, and application-visible conflict resolution are useful. "Always
writeable" is not the first CultNet promise.
- Raft: primary authority per shard is the first understandable consistency
model. Leader election/log replication can come later if the cluster needs
automatic failover.
- SWIM: peer membership and failure suspicion should be gossip-shaped when the
mesh grows beyond small static clusters.
- CRDTs: offline multi-writer documents are valid only for types with declared,
deterministic merge semantics.
- Hashgraph: gossip-about-gossip is interesting for compact event provenance
and fair ordering research. CultNet should not adopt public-ledger machinery
or crypto-token assumptions as a shortcut to database correctness.
## Current Cut
Implemented:
- `CultNetDatabase`: database-style facade over a `CultCache`
- primary-shard write checks
- typed R3 watch streams
- raw CultNet put/delete application through shard policy
- `CultNetDatabaseServer`: schema-v0 bridge for snapshot, put, and delete
- `Client` and `Server` schema-v0 dispatch hooks
- `CultNetHost.Database` and `CultNetHost.DatabaseServer`
- subscription request/cancel/change messages
- server-side live change fanout for schema/key-filtered subscriptions
- shard catalog request/response messages
- shard descriptors with owner runtime id, epoch, schema filters, key prefix,
primary endpoints, replica endpoints, read replica endpoints, and region
- epoch-aware raw put/delete messages
- routing hints on shard authority errors
- injectable non-primary write forwarding policy
- schema-v0 write forwarder that dials advertised `rudp://host:port` primary
endpoints, while keeping `cultnet://host:port` as the LiteNetLib compatibility
lane
- in-memory per-shard mutation logs with sequence numbers, epochs, mutation
kind, schema id, key, and document references
- mutation-log catch-up by last seen sequence
- wire-level shard log request/response messages
- raw put/delete representation for accepted mutation-log entries
- replica-side shard log application with epoch checks, gap rejection, and
idempotent replay
- shard log replicator that pulls non-primary shards from catalog-advertised
primary endpoints
- schema-v0 shard log fetcher for `rudp://host:port` endpoints, while keeping
`cultnet://host:port` as the LiteNetLib compatibility lane
- restart-safe replica cursor store, including a local MessagePack file-backed
implementation
- durable authoritative shard-log storage behind
`ICultNetShardMutationLogStore`, including a per-shard MessagePack file
implementation
- shard-log compaction watermarks; requests for compacted history return
`ResyncRequired` with `reason = "compacted_history"`
- shard-bounded snapshots with shard id, epoch, and represented log sequence
- replica snapshot recovery after compacted history, including local shard
replacement and cursor advancement
- CultMesh node option for file-backed authoritative shard logs with a default
`.cultmesh/shard-logs` path beside the cache file
- schema-v0 Verse catalog request/response messages
- CultMesh Verse discovery server bridge over the local Verse catalog
- schema-v0 peer exchange request/response messages
- CultMesh peer cards, peer catalog, peer exchange server bridge, and peer
exchange client
- CultMesh authority leases and lease catalog checks for peer role/shard
authorization
- client-authority scopes for locally predicted input documents
- predicted and reconciled database change kinds for client-side prediction
- simulation witness observations for mesh-side opinions about frame facts
- deterministic consensus candidates derived from witness observations
- committed CultMesh simulation fact documents written from quorum candidates
through shard authority
- gameplay-facing CultMesh session facade for prediction, observations,
catalogs, peer exchange, and quorum fact commits
- schema-v0 simulation observation and consensus candidate messages
- reactive simulation observation hub that receives witness gossip and emits
consensus candidates
- server-side observation bridge that accepts observation messages and replies
with current candidate messages
Not implemented yet:
- SWIM-style membership/failure detection beyond Python's hello-level health
monitor
- leader election or automatic shard failover
- cross-runtime scheduled peer-to-peer snapshot fanout beyond Python's local
fanout loop
- cross-runtime scheduled peer-to-peer fanout for observation gossip and
candidate propagation beyond Python's local fanout loop
- cross-runtime rollback/resimulation helpers for simulation frames
- declared CRDT merge policies
## Live Invariants
- CultCache owns document schema, identity, local indexes, and local diffing.
- CultNet owns transport, shard authority, remote mutation delivery, and
subscription fanout.
- One primary owns writes for a shard until a stronger policy exists.
- Non-owner writes are rejected or explicitly forwarded. They are not silently
applied.
- Raw snapshot/put/delete messages must pass through `CultNetDatabase`, not
bypass shard policy.
- The accepted shard log is stored in replica catch-up wire form. Object logs
are for local inspection; wire logs are the durable replication authority.
- Log retention is part of the replication contract. A replica asking before
the compaction watermark must resync from a snapshot before applying newer
log entries.
- A shard snapshot represents a log sequence. Applying it replaces the local
shard view and advances the replica cursor to that sequence.
- Realtime subscriptions publish domain changes, not storage envelopes.
- Client-owned input documents may be predicted locally only inside explicit
`CultNetClientAuthorityScope` declarations.
- Predicted input state is not authoritative shared state. The shard log still
decides the committed ordering and emits reconciliation when it corrects or
confirms local prediction.
- Witness observations are immutable reports about a shard epoch, frame,
subject, claim kind, and claim hash.
- Consensus candidates are derived from observations. They may inform the
authoritative commit path, but they are not themselves committed world state
until a shard owner writes them into the log.
- `CultMeshSimulationFact` is the committed form of a quorum candidate. It is
written through `CultNetDatabase`, so normal shard authority and replication
rules still apply.
- `CultMeshGameSession` composes common gameplay surfaces. It does not create a
second authority path; all committed state still flows through shard-owned
database writes.
- Peer cards are contact candidates. They can advertise roles and authority
lease ids, but they do not grant authority without Verse-specific validation.
- Authority leases bind peer id, Verse id, roles, optional shard scope, issuer,
validity window, and signature. They are the first trust boundary above peer
exchange.
## Next Coherent Slice
Add discovery fanout and operational polish:
- standardize periodic gossip fanout over known peer cards beyond Python's
local schedulers and health monitor
- standardize cross-runtime authority lease signature algorithms beyond the
package-local Python HMAC verifier
- standardize cross-runtime simulation-frame rollback/resimulation helpers beyond
Python's local pending-prediction rollback surface
- standardize cross-runtime scheduled peer-to-peer snapshot fanout beyond
Python's local fanout loop
- standardize cross-runtime scheduled peer-to-peer fanout for observation gossip
and candidate propagation beyond Python's local fanout loop
The log is wire-readable, replicas can apply it explicitly, a pull loop can
drive non-primary shards from primary endpoints, and replica cursors can survive
restart. Client-owned input documents can now be predicted locally and
reconciled when the authoritative log arrives. Nodes can also aggregate witness
observations into deterministic consensus candidates for simulation facts like
"who shot first," and those reports now have schema-v0 wire contracts. The next
useful layer is making Verse discovery and operator defaults first-class.
Membership and leader election should wait until basic replica catch-up is
boring. Authoritative mutation logs can now survive process restart through
`ICultNetShardMutationLogStore`; compaction now has an honest resync boundary,
and the shard replicator can recover from that boundary through snapshot
replacement.

View file

@ -1,24 +0,0 @@
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://github.com/GameCult/cultnet-ts/contracts/cultnet.database-change-raw.schema.json",
"title": "CultNet Raw Database Change Message",
"type": "object",
"required": ["schemaVersion", "messageId", "subscriptionId", "changeKind"],
"additionalProperties": false,
"properties": {
"schemaVersion": { "const": "cultnet.database_change_raw.v0" },
"messageId": { "type": "string", "minLength": 1 },
"subscriptionId": { "type": "string", "minLength": 1 },
"changeKind": { "enum": ["added", "updated", "removed"] },
"document": { "$ref": "./cultnet.raw-document-record.schema.json" },
"recordKey": { "type": "string", "minLength": 1 },
"schemaId": { "type": "string", "minLength": 1 }
},
"allOf": [
{
"if": { "properties": { "changeKind": { "const": "removed" } } },
"then": { "required": ["recordKey", "schemaId"] },
"else": { "required": ["document"] }
}
]
}

View file

@ -1,19 +0,0 @@
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://github.com/GameCult/cultnet-ts/contracts/cultnet.database-subscribe.schema.json",
"title": "CultNet Database Subscribe Message",
"type": "object",
"required": ["schemaVersion", "messageId", "subscriptionId", "includeSnapshot"],
"additionalProperties": false,
"properties": {
"schemaVersion": { "const": "cultnet.database_subscribe.v0" },
"messageId": { "type": "string", "minLength": 1 },
"subscriptionId": { "type": "string", "minLength": 1 },
"schemaIds": { "type": "array", "items": { "type": "string", "minLength": 1 } },
"recordKeys": { "type": "array", "items": { "type": "string", "minLength": 1 } },
"includeSnapshot": { "type": "boolean" },
"consumerRuntimeId": { "type": "string", "minLength": 1 },
"bodyIds": { "type": "array", "items": { "type": "string", "minLength": 1 } },
"supportedBodyTransports": { "type": "array", "items": { "type": "string", "minLength": 1 } }
}
}

View file

@ -1,13 +0,0 @@
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://github.com/GameCult/cultnet-ts/contracts/cultnet.database-unsubscribe.schema.json",
"title": "CultNet Database Unsubscribe Message",
"type": "object",
"required": ["schemaVersion", "messageId", "subscriptionId"],
"additionalProperties": false,
"properties": {
"schemaVersion": { "const": "cultnet.database_unsubscribe.v0" },
"messageId": { "type": "string", "minLength": 1 },
"subscriptionId": { "type": "string", "minLength": 1 }
}
}

View file

@ -1,19 +0,0 @@
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://github.com/GameCult/cultnet-ts/contracts/cultnet.document-delete.schema.json",
"title": "CultNet Document Delete Message",
"type": "object",
"required": [
"schemaVersion",
"messageId",
"schemaId",
"recordKey"
],
"additionalProperties": false,
"properties": {
"schemaVersion": { "const": "cultnet.document_delete.v0" },
"messageId": { "type": "string", "minLength": 1 },
"schemaId": { "type": "string", "minLength": 1 },
"recordKey": { "type": "string", "minLength": 1 }
}
}

View file

@ -1,40 +0,0 @@
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://github.com/GameCult/cultnet-ts/contracts/cultnet.document-mutation-contract.schema.json",
"title": "CultNet Document Mutation Contract",
"type": "object",
"required": [
"documentType",
"operations",
"authority"
],
"additionalProperties": false,
"properties": {
"documentType": { "type": "string", "minLength": 1 },
"payloadSchemaVersion": { "type": "string", "minLength": 1 },
"operations": {
"type": "array",
"minItems": 1,
"items": {
"type": "string",
"enum": ["snapshot", "documentPut", "documentDelete", "intentSubmit", "receiptWatch"]
}
},
"authority": {
"type": "string",
"enum": ["readOnly", "localUser", "coordinator", "runtime", "denied"]
},
"intentDocumentTypes": {
"type": "array",
"items": { "type": "string", "minLength": 1 }
},
"receiptDocumentTypes": {
"type": "array",
"items": { "type": "string", "minLength": 1 }
},
"notes": {
"type": "array",
"items": { "type": "string", "minLength": 1 }
}
}
}

View file

@ -1,19 +0,0 @@
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://github.com/GameCult/cultnet-ts/contracts/cultnet.document-put-raw.schema.json",
"title": "CultNet Raw Document Put Message",
"type": "object",
"required": [
"schemaVersion",
"messageId",
"document"
],
"additionalProperties": false,
"properties": {
"schemaVersion": { "const": "cultnet.document_put_raw.v0" },
"messageId": { "type": "string", "minLength": 1 },
"document": {
"$ref": "./cultnet.raw-document-record.schema.json"
}
}
}

View file

@ -1,19 +0,0 @@
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://github.com/GameCult/cultnet-ts/contracts/cultnet.document-put.schema.json",
"title": "CultNet Document Put Message",
"type": "object",
"required": [
"schemaVersion",
"messageId",
"document"
],
"additionalProperties": false,
"properties": {
"schemaVersion": { "const": "cultnet.document_put.v0" },
"messageId": { "type": "string", "minLength": 1 },
"document": {
"$ref": "./cultnet.document-record.schema.json"
}
}
}

View file

@ -1,26 +0,0 @@
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://github.com/GameCult/cultnet-ts/contracts/cultnet.document-record.schema.json",
"title": "CultNet Document Record",
"type": "object",
"required": [
"schemaId",
"recordKey",
"storedAt",
"payload"
],
"additionalProperties": false,
"properties": {
"schemaId": { "type": "string", "minLength": 1 },
"recordKey": { "type": "string", "minLength": 1 },
"storedAt": { "type": "string", "minLength": 1 },
"payload": {},
"sourceRuntimeId": { "type": "string", "minLength": 1 },
"sourceAgentId": { "type": "string", "minLength": 1 },
"sourceRole": { "type": "string", "minLength": 1 },
"tags": {
"type": "array",
"items": { "type": "string", "minLength": 1 }
}
}
}

View file

@ -1,15 +0,0 @@
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://github.com/GameCult/cultnet-ts/contracts/cultnet.error.schema.json",
"title": "CultNet Error Message",
"type": "object",
"required": [
"schemaVersion",
"error"
],
"additionalProperties": false,
"properties": {
"schemaVersion": { "const": "cultnet.error.v0" },
"error": { "type": "string", "minLength": 1 }
}
}

View file

@ -1,41 +0,0 @@
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://github.com/GameCult/cultnet-ts/contracts/cultnet.hello.schema.json",
"title": "CultNet Hello Message",
"type": "object",
"required": [
"schemaVersion",
"runtimeId",
"runtimeKind"
],
"additionalProperties": false,
"properties": {
"schemaVersion": { "const": "cultnet.hello.v0" },
"runtimeId": { "type": "string", "minLength": 1 },
"runtimeKind": { "type": "string", "minLength": 1 },
"agentId": { "type": "string", "minLength": 1 },
"role": { "type": "string", "minLength": 1 },
"displayName": { "type": "string", "minLength": 1 },
"supportedDocumentTypes": {
"type": "array",
"items": { "type": "string", "minLength": 1 }
},
"supportedMutationContracts": {
"type": "array",
"items": {
"$ref": "./cultnet.document-mutation-contract.schema.json"
}
},
"supportedMessageVersions": {
"type": "array",
"items": { "type": "string", "minLength": 1 }
},
"transportProfiles": {
"type": "array",
"items": {
"$ref": "./cultnet.transport-profile.schema.json"
}
},
"supportsSchemaCatalog": { "type": "boolean" }
}
}

View file

@ -1,17 +0,0 @@
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://github.com/GameCult/cultnet-ts/contracts/cultnet.login-success.schema.json",
"title": "CultNet Login Success Message",
"type": "object",
"required": [
"schemaVersion",
"nonce",
"session"
],
"additionalProperties": false,
"properties": {
"schemaVersion": { "const": "cultnet.login_success.v0" },
"nonce": { "type": "string", "minLength": 1 },
"session": { "type": "string", "minLength": 1 }
}
}

View file

@ -1,19 +0,0 @@
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://github.com/GameCult/cultnet-ts/contracts/cultnet.login.schema.json",
"title": "CultNet Login Message",
"type": "object",
"required": [
"schemaVersion",
"nonce",
"auth",
"password"
],
"additionalProperties": false,
"properties": {
"schemaVersion": { "const": "cultnet.login.v0" },
"nonce": { "type": "string", "minLength": 1 },
"auth": { "type": "string", "minLength": 1 },
"password": { "type": "string", "minLength": 1 }
}
}

View file

@ -1,19 +0,0 @@
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://github.com/GameCult/cultnet-ts/contracts/cultnet.operation-request.schema.json",
"title": "CultNet Operation Request",
"type": "object",
"required": ["schemaVersion", "messageId", "serviceId", "operation", "payloadSchema", "payload"],
"additionalProperties": false,
"properties": {
"schemaVersion": { "const": "cultnet.operation_request.v0" },
"messageId": { "type": "string", "minLength": 1 },
"serviceId": { "type": "string", "minLength": 1 },
"operation": { "type": "string", "minLength": 1 },
"payloadSchema": { "type": "string", "minLength": 1 },
"payloadEncoding": { "const": "messagepack-base64" },
"payload": { "type": "string", "minLength": 1, "contentEncoding": "base64" },
"sourceRuntimeId": { "type": "string", "minLength": 1 },
"targetRuntimeId": { "type": "string", "minLength": 1 }
}
}

View file

@ -1,20 +0,0 @@
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://github.com/GameCult/cultnet-ts/contracts/cultnet.operation-response.schema.json",
"title": "CultNet Operation Response",
"type": "object",
"required": ["schemaVersion", "messageId", "serviceId", "operation", "status", "payloadSchema", "payload"],
"additionalProperties": false,
"properties": {
"schemaVersion": { "const": "cultnet.operation_response.v0" },
"messageId": { "type": "string", "minLength": 1 },
"serviceId": { "type": "string", "minLength": 1 },
"operation": { "type": "string", "minLength": 1 },
"status": { "type": "string", "minLength": 1 },
"payloadSchema": { "type": "string", "minLength": 1 },
"payloadEncoding": { "const": "messagepack-base64" },
"payload": { "type": "string", "minLength": 1, "contentEncoding": "base64" },
"diagnostics": { "type": "array", "items": { "type": "string" } },
"sourceRuntimeId": { "type": "string", "minLength": 1 }
}
}

View file

@ -1,32 +0,0 @@
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://github.com/GameCult/cultnet-ts/contracts/cultnet.raw-document-record.schema.json",
"title": "CultNet Raw Document Record",
"type": "object",
"required": [
"schemaId",
"recordKey",
"storedAt",
"payloadEncoding",
"payload"
],
"additionalProperties": false,
"properties": {
"schemaId": { "type": "string", "minLength": 1 },
"recordKey": { "type": "string", "minLength": 1 },
"storedAt": { "type": "string", "minLength": 1 },
"payloadEncoding": { "const": "messagepack" },
"payload": {
"type": "string",
"contentEncoding": "base64",
"x-cult-runtime-type": "bytes"
},
"sourceRuntimeId": { "type": "string", "minLength": 1 },
"sourceAgentId": { "type": "string", "minLength": 1 },
"sourceRole": { "type": "string", "minLength": 1 },
"tags": {
"type": "array",
"items": { "type": "string", "minLength": 1 }
}
}
}

View file

@ -1,21 +0,0 @@
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://github.com/GameCult/cultnet-ts/contracts/cultnet.register.schema.json",
"title": "CultNet Register Message",
"type": "object",
"required": [
"schemaVersion",
"nonce",
"email",
"password",
"name"
],
"additionalProperties": false,
"properties": {
"schemaVersion": { "const": "cultnet.register.v0" },
"nonce": { "type": "string", "minLength": 1 },
"email": { "type": "string", "minLength": 1 },
"password": { "type": "string", "minLength": 1 },
"name": { "type": "string", "minLength": 1 }
}
}

View file

@ -1,15 +0,0 @@
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://github.com/GameCult/cultnet-ts/contracts/cultnet.sample-change-name.schema.json",
"title": "CultNet Sample Change Name Message",
"type": "object",
"required": [
"schemaVersion",
"name"
],
"additionalProperties": false,
"properties": {
"schemaVersion": { "const": "cultnet.sample.change_name.v0" },
"name": { "type": "string", "minLength": 1 }
}
}

View file

@ -1,15 +0,0 @@
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://github.com/GameCult/cultnet-ts/contracts/cultnet.sample-chat.schema.json",
"title": "CultNet Sample Chat Message",
"type": "object",
"required": [
"schemaVersion",
"text"
],
"additionalProperties": false,
"properties": {
"schemaVersion": { "const": "cultnet.sample.chat.v0" },
"text": { "type": "string", "minLength": 1 }
}
}

View file

@ -1,31 +0,0 @@
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://github.com/GameCult/cultnet-ts/contracts/cultnet.schema-catalog-request.schema.json",
"title": "CultNet Schema Catalog Request Message",
"type": "object",
"required": [
"schemaVersion",
"messageId"
],
"additionalProperties": false,
"properties": {
"schemaVersion": { "const": "cultnet.schema_catalog_request.v0" },
"messageId": { "type": "string", "minLength": 1 },
"includeSchemaJson": { "type": "boolean" },
"schemaIds": {
"type": "array",
"items": { "type": "string", "minLength": 1 }
},
"kinds": {
"type": "array",
"items": {
"type": "string",
"enum": [
"wire_message",
"document_payload",
"shared_contract"
]
}
}
}
}

View file

@ -1,22 +0,0 @@
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://github.com/GameCult/cultnet-ts/contracts/cultnet.schema-catalog-response.schema.json",
"title": "CultNet Schema Catalog Response Message",
"type": "object",
"required": [
"schemaVersion",
"messageId",
"schemas"
],
"additionalProperties": false,
"properties": {
"schemaVersion": { "const": "cultnet.schema_catalog_response.v0" },
"messageId": { "type": "string", "minLength": 1 },
"schemas": {
"type": "array",
"items": {
"$ref": "./cultnet.schema-descriptor.schema.json"
}
}
}
}

View file

@ -1,39 +0,0 @@
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://github.com/GameCult/cultnet-ts/contracts/cultnet.schema-descriptor.schema.json",
"title": "CultNet Schema Descriptor",
"type": "object",
"required": [
"schemaId",
"kind",
"wireContracts",
"contentHash"
],
"additionalProperties": false,
"properties": {
"schemaId": { "type": "string", "minLength": 1 },
"kind": {
"type": "string",
"enum": [
"wire_message",
"document_payload",
"shared_contract"
]
},
"schemaVersion": { "type": "string", "minLength": 1 },
"documentType": { "type": "string", "minLength": 1 },
"title": { "type": "string", "minLength": 1 },
"wireContracts": {
"type": "array",
"items": {
"type": "string",
"enum": [
"cultnet.schema.v0",
"gamecult.networking.v0"
]
}
},
"contentHash": { "type": "string", "minLength": 1 },
"schemaJson": { "type": "string", "minLength": 1 }
}
}

View file

@ -1,23 +0,0 @@
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://github.com/GameCult/cultnet-ts/contracts/cultnet.snapshot-request.schema.json",
"title": "CultNet Snapshot Request Message",
"type": "object",
"required": [
"schemaVersion",
"messageId"
],
"additionalProperties": false,
"properties": {
"schemaVersion": { "const": "cultnet.snapshot_request.v0" },
"messageId": { "type": "string", "minLength": 1 },
"schemaIds": {
"type": "array",
"items": { "type": "string", "minLength": 1 }
},
"recordKeys": {
"type": "array",
"items": { "type": "string", "minLength": 1 }
}
}
}

View file

@ -1,22 +0,0 @@
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://github.com/GameCult/cultnet-ts/contracts/cultnet.snapshot-response-raw.schema.json",
"title": "CultNet Raw Snapshot Response Message",
"type": "object",
"required": [
"schemaVersion",
"messageId",
"documents"
],
"additionalProperties": false,
"properties": {
"schemaVersion": { "const": "cultnet.snapshot_response_raw.v0" },
"messageId": { "type": "string", "minLength": 1 },
"documents": {
"type": "array",
"items": {
"$ref": "./cultnet.raw-document-record.schema.json"
}
}
}
}

View file

@ -1,22 +0,0 @@
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://github.com/GameCult/cultnet-ts/contracts/cultnet.snapshot-response.schema.json",
"title": "CultNet Snapshot Response Message",
"type": "object",
"required": [
"schemaVersion",
"messageId",
"documents"
],
"additionalProperties": false,
"properties": {
"schemaVersion": { "const": "cultnet.snapshot_response.v0" },
"messageId": { "type": "string", "minLength": 1 },
"documents": {
"type": "array",
"items": {
"$ref": "./cultnet.document-record.schema.json"
}
}
}
}

View file

@ -1,100 +0,0 @@
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://github.com/GameCult/cultnet-ts/contracts/cultnet.transport-profile.schema.json",
"title": "CultNet Transport Profile",
"type": "object",
"required": [
"schemaVersion",
"runtimeId",
"transports"
],
"additionalProperties": false,
"properties": {
"schemaVersion": { "const": "cultnet.transport_profile.v0" },
"runtimeId": { "type": "string", "minLength": 1 },
"transports": {
"type": "array",
"items": {
"type": "object",
"required": [
"transportId",
"protocol",
"channels"
],
"additionalProperties": false,
"properties": {
"transportId": { "type": "string", "minLength": 1 },
"protocol": {
"type": "string",
"enum": [
"tcp_framed",
"litenetlib",
"websocket",
"rudp"
]
},
"host": { "type": "string", "minLength": 1 },
"port": { "type": "integer", "minimum": 1, "maximum": 65535 },
"path": { "type": "string", "minLength": 1 },
"discoveryGroup": { "type": "string", "minLength": 1 },
"wireContracts": {
"type": "array",
"items": { "type": "string", "minLength": 1 }
},
"reconnectPolicy": {
"type": "object",
"required": [
"schemaVersion",
"policyId",
"baseDelayMs",
"maxDelayMs",
"maxJitterMs"
],
"additionalProperties": false,
"properties": {
"schemaVersion": { "const": "cultnet.reconnect_policy.v0" },
"policyId": { "type": "string", "minLength": 1 },
"baseDelayMs": { "type": "integer", "minimum": 0 },
"maxDelayMs": { "type": "integer", "minimum": 0 },
"maxJitterMs": { "type": "integer", "minimum": 0 },
"maxAttempts": { "type": "integer", "minimum": 1 }
}
},
"channels": {
"type": "array",
"items": {
"type": "object",
"required": [
"channelId",
"delivery",
"ordering"
],
"additionalProperties": false,
"properties": {
"channelId": { "type": "string", "minLength": 1 },
"delivery": {
"type": "string",
"enum": [
"reliable",
"unreliable"
]
},
"ordering": {
"type": "string",
"enum": [
"ordered",
"unordered",
"sequenced"
]
},
"maxPayloadBytes": { "type": "integer", "minimum": 1 },
"maxFragmentBytes": { "type": "integer", "minimum": 1 },
"maxPendingReliablePackets": { "type": "integer", "minimum": 1 }
}
}
}
}
}
}
}
}

View file

@ -1,17 +0,0 @@
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://github.com/GameCult/cultnet-ts/contracts/cultnet.verify.schema.json",
"title": "CultNet Verify Message",
"type": "object",
"required": [
"schemaVersion",
"nonce",
"session"
],
"additionalProperties": false,
"properties": {
"schemaVersion": { "const": "cultnet.verify.v0" },
"nonce": { "type": "string", "minLength": 1 },
"session": { "type": "string", "minLength": 1 }
}
}

View file

@ -1,120 +0,0 @@
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://github.com/GameCult/cultnet-ts/contracts/cultnet.witness-artifact-bundle.schema.json",
"title": "CultNet Witness Artifact Bundle",
"type": "object",
"required": [
"bundleId",
"witnessKind",
"capturedAt",
"subject",
"contracts",
"artifacts",
"timingWitnesses",
"provenance"
],
"additionalProperties": false,
"properties": {
"bundleId": { "type": "string", "minLength": 1 },
"witnessKind": { "type": "string", "minLength": 1 },
"capturedAt": { "type": "string", "minLength": 1 },
"subject": { "$ref": "#/$defs/subject_pin" },
"contracts": {
"type": "array",
"minItems": 1,
"items": { "$ref": "#/$defs/contract_pin" }
},
"artifacts": {
"type": "array",
"minItems": 1,
"items": { "$ref": "#/$defs/artifact_entry" }
},
"timingWitnesses": {
"type": "array",
"items": { "$ref": "#/$defs/timing_entry" }
},
"provenance": { "$ref": "#/$defs/provenance" }
},
"$defs": {
"subject_pin": {
"type": "object",
"required": [
"documentType",
"subjectId"
],
"additionalProperties": false,
"properties": {
"documentType": { "type": "string", "minLength": 1 },
"subjectId": { "type": "string", "minLength": 1 },
"schemaVersion": { "type": "string", "minLength": 1 },
"schemaId": { "type": "string", "minLength": 1 },
"contentHash": { "type": "string", "minLength": 1 }
}
},
"contract_pin": {
"type": "object",
"required": [
"role",
"schemaId"
],
"additionalProperties": false,
"properties": {
"role": { "type": "string", "minLength": 1 },
"schemaId": { "type": "string", "minLength": 1 },
"schemaVersion": { "type": "string", "minLength": 1 },
"contentHash": { "type": "string", "minLength": 1 }
}
},
"artifact_entry": {
"type": "object",
"required": [
"role",
"uri",
"mediaType"
],
"additionalProperties": false,
"properties": {
"role": { "type": "string", "minLength": 1 },
"uri": { "type": "string", "minLength": 1 },
"mediaType": { "type": "string", "minLength": 1 },
"contentHash": { "type": "string", "minLength": 1 },
"byteLength": { "type": "integer", "minimum": 0 },
"producedAt": { "type": "string", "minLength": 1 }
}
},
"timing_entry": {
"type": "object",
"required": [
"stage",
"startedAt",
"completedAt",
"latencyMs"
],
"additionalProperties": false,
"properties": {
"stage": { "type": "string", "minLength": 1 },
"startedAt": { "type": "string", "minLength": 1 },
"completedAt": { "type": "string", "minLength": 1 },
"latencyMs": { "type": "number", "minimum": 0 },
"witnessArtifactUri": { "type": "string", "minLength": 1 }
}
},
"provenance": {
"type": "object",
"required": [
"pipelineId",
"runId",
"runtimeId"
],
"additionalProperties": false,
"properties": {
"pipelineId": { "type": "string", "minLength": 1 },
"runId": { "type": "string", "minLength": 1 },
"runtimeId": { "type": "string", "minLength": 1 },
"agentId": { "type": "string", "minLength": 1 },
"agentRole": { "type": "string", "minLength": 1 },
"toolVersion": { "type": "string", "minLength": 1 }
}
}
}
}

View file

@ -1,845 +0,0 @@
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://github.com/GameCult/Ghostlight/schemas/agent-state.schema.json",
"title": "Ghostlight Agent State Schema",
"description": "First canonical contract for Ghostlight agent, perception, relationship, event, scene, and dialogue-context state.",
"type": "object",
"required": [
"schema_version",
"world",
"agents",
"relationships",
"events",
"scenes"
],
"additionalProperties": false,
"properties": {
"schema_version": {
"const": "ghostlight.agent_state.v0"
},
"world": {
"$ref": "#/$defs/world_state"
},
"agents": {
"type": "array",
"items": {
"$ref": "#/$defs/agent"
}
},
"relationships": {
"type": "array",
"items": {
"$ref": "#/$defs/relationship"
}
},
"events": {
"type": "array",
"items": {
"$ref": "#/$defs/event"
}
},
"scenes": {
"type": "array",
"items": {
"$ref": "#/$defs/scene"
}
}
},
"$defs": {
"world_state": {
"type": "object",
"required": [
"world_id",
"setting",
"time",
"canon_context"
],
"additionalProperties": false,
"properties": {
"world_id": {
"type": "string"
},
"setting": {
"type": "string"
},
"time": {
"type": "object",
"required": [
"label"
],
"additionalProperties": true,
"properties": {
"label": {
"type": "string"
}
}
},
"canon_context": {
"type": "array",
"items": {
"type": "string"
}
},
"ambient_pressures": {
"type": "array",
"items": {
"$ref": "#/$defs/pressure"
}
}
}
},
"agent": {
"type": "object",
"required": [
"agent_id",
"identity",
"canonical_state",
"goals",
"memories",
"perceived_state_overlays"
],
"additionalProperties": false,
"properties": {
"agent_id": {
"type": "string"
},
"identity": {
"$ref": "#/$defs/identity"
},
"canonical_state": {
"$ref": "#/$defs/canonical_state"
},
"goals": {
"type": "array",
"items": {
"$ref": "#/$defs/goal"
}
},
"memories": {
"$ref": "#/$defs/memory_bundle"
},
"perceived_state_overlays": {
"type": "array",
"items": {
"$ref": "#/$defs/perceived_state_overlay"
}
}
}
},
"identity": {
"type": "object",
"required": [
"name",
"roles",
"origin",
"public_description"
],
"additionalProperties": false,
"properties": {
"name": {
"type": "string"
},
"roles": {
"type": "array",
"items": {
"type": "string"
}
},
"origin": {
"type": "string"
},
"public_description": {
"type": "string"
},
"private_notes": {
"type": "array",
"items": {
"type": "string"
}
}
}
},
"canonical_state": {
"type": "object",
"required": [
"underlying_organization",
"stable_dispositions",
"behavioral_dimensions",
"presentation_strategy",
"voice_style",
"situational_state",
"values"
],
"additionalProperties": false,
"properties": {
"underlying_organization": {
"$ref": "#/$defs/variable_map"
},
"stable_dispositions": {
"$ref": "#/$defs/variable_map"
},
"behavioral_dimensions": {
"$ref": "#/$defs/variable_map"
},
"presentation_strategy": {
"$ref": "#/$defs/variable_map"
},
"situational_state": {
"$ref": "#/$defs/variable_map"
},
"values": {
"type": "array",
"items": {
"$ref": "#/$defs/value_commitment"
}
},
"voice_style": {
"$ref": "#/$defs/variable_map"
}
}
},
"variable_map": {
"type": "object",
"additionalProperties": {
"$ref": "#/$defs/state_variable"
}
},
"state_variable": {
"type": "object",
"required": [
"mean",
"plasticity",
"current_activation"
],
"additionalProperties": false,
"properties": {
"mean": {
"type": "number",
"minimum": 0,
"maximum": 1
},
"plasticity": {
"type": "number",
"minimum": 0,
"maximum": 1
},
"current_activation": {
"type": "number",
"minimum": 0,
"maximum": 1
},
"evidence": {
"type": "array",
"items": {
"type": "string"
}
}
}
},
"value_commitment": {
"type": "object",
"required": [
"value_id",
"label",
"priority",
"unforgivable_if_betrayed"
],
"additionalProperties": false,
"properties": {
"value_id": {
"type": "string"
},
"label": {
"type": "string"
},
"priority": {
"type": "number",
"minimum": 0,
"maximum": 1
},
"unforgivable_if_betrayed": {
"type": "boolean"
}
}
},
"goal": {
"type": "object",
"required": [
"goal_id",
"description",
"scope",
"priority",
"emotional_stake",
"status"
],
"additionalProperties": false,
"properties": {
"goal_id": {
"type": "string"
},
"description": {
"type": "string"
},
"scope": {
"enum": [
"immediate",
"scene",
"case",
"arc",
"life"
]
},
"priority": {
"type": "number",
"minimum": 0,
"maximum": 1
},
"emotional_stake": {
"type": "string"
},
"blockers": {
"type": "array",
"items": {
"type": "string"
}
},
"status": {
"enum": [
"active",
"blocked",
"dormant",
"resolved",
"abandoned"
]
}
}
},
"memory_bundle": {
"type": "object",
"required": [
"episodic",
"semantic",
"relationship_summaries"
],
"additionalProperties": false,
"properties": {
"episodic": {
"type": "array",
"items": {
"$ref": "#/$defs/memory"
}
},
"semantic": {
"type": "array",
"items": {
"$ref": "#/$defs/memory"
}
},
"relationship_summaries": {
"type": "array",
"items": {
"$ref": "#/$defs/memory"
}
}
}
},
"memory": {
"type": "object",
"required": [
"memory_id",
"summary",
"salience",
"confidence"
],
"additionalProperties": false,
"properties": {
"memory_id": {
"type": "string"
},
"summary": {
"type": "string"
},
"salience": {
"type": "number",
"minimum": 0,
"maximum": 1
},
"confidence": {
"type": "number",
"minimum": 0,
"maximum": 1
},
"linked_event_ids": {
"type": "array",
"items": {
"type": "string"
}
},
"linked_relationship_id": {
"type": "string"
}
}
},
"perceived_state_overlay": {
"type": "object",
"required": [
"observer_agent_id",
"target_agent_id",
"perceived_dimensions",
"beliefs",
"distortions"
],
"additionalProperties": false,
"properties": {
"observer_agent_id": {
"type": "string"
},
"target_agent_id": {
"type": "string"
},
"perceived_dimensions": {
"$ref": "#/$defs/inferred_variable_map"
},
"beliefs": {
"type": "array",
"items": {
"$ref": "#/$defs/belief"
}
},
"distortions": {
"type": "array",
"items": {
"enum": [
"hostile_attribution",
"false_reassurance",
"overread_warmth",
"underread_threat",
"false_mask_detection",
"missed_mask_detection",
"status_injury",
"threat_amplification",
"institutional_suspicion_transfer",
"care_underread",
"mask_overfocus"
]
}
}
}
},
"belief": {
"type": "object",
"required": [
"belief_id",
"claim",
"confidence"
],
"additionalProperties": false,
"properties": {
"belief_id": {
"type": "string"
},
"claim": {
"type": "string"
},
"confidence": {
"type": "number",
"minimum": 0,
"maximum": 1
},
"subject_id": {
"type": "string"
},
"claim_type": {
"enum": [
"fact",
"identity_inference",
"motive_inference",
"prediction",
"norm",
"value_read",
"relationship_read"
]
},
"evidence_event_ids": {
"type": "array",
"items": {
"type": "string"
}
},
"visibility": {
"enum": [
"private",
"shared",
"public",
"rumor"
]
},
"emotional_charge": {
"type": "number",
"minimum": 0,
"maximum": 1
}
}
},
"relationship": {
"type": "object",
"required": [
"relationship_id",
"source_id",
"target_id",
"stance",
"summary"
],
"additionalProperties": false,
"properties": {
"relationship_id": {
"type": "string"
},
"source_id": {
"type": "string"
},
"target_id": {
"type": "string"
},
"stance": {
"$ref": "#/$defs/variable_map"
},
"summary": {
"type": "string"
},
"unresolved_incident_ids": {
"type": "array",
"items": {
"type": "string"
}
}
}
},
"event": {
"type": "object",
"required": [
"event_id",
"kind",
"summary",
"participants",
"pressure_tags"
],
"additionalProperties": false,
"properties": {
"event_id": {
"type": "string"
},
"kind": {
"enum": [
"dialogue",
"action",
"memory",
"relationship_shift",
"scene_outcome",
"author_note"
]
},
"summary": {
"type": "string"
},
"participants": {
"type": "array",
"items": {
"type": "string"
}
},
"pressure_tags": {
"type": "array",
"items": {
"type": "string"
}
},
"observed_exchange": {
"type": "array",
"items": {
"$ref": "#/$defs/event_exchange_turn"
}
},
"private_interpretations": {
"type": "array",
"items": {
"$ref": "#/$defs/event_private_interpretation"
}
},
"event_effects": {
"type": "array",
"items": {
"$ref": "#/$defs/event_effect"
}
}
}
},
"scene": {
"type": "object",
"required": [
"scene_id",
"location",
"participants",
"public_stakes",
"hidden_stakes",
"dialogue_context_packs"
],
"additionalProperties": false,
"properties": {
"scene_id": {
"type": "string"
},
"location": {
"type": "string"
},
"participants": {
"type": "array",
"items": {
"type": "string"
}
},
"public_stakes": {
"type": "array",
"items": {
"type": "string"
}
},
"hidden_stakes": {
"type": "array",
"items": {
"type": "string"
}
},
"dialogue_context_packs": {
"type": "array",
"items": {
"$ref": "#/$defs/dialogue_context_pack"
}
}
}
},
"dialogue_context_pack": {
"type": "object",
"required": [
"speaker_agent_id",
"listener_ids",
"speaker_local_truth",
"speaker_beliefs",
"active_memories",
"active_goals",
"presentation_constraints"
],
"additionalProperties": false,
"properties": {
"speaker_agent_id": {
"type": "string"
},
"listener_ids": {
"type": "array",
"items": {
"type": "string"
}
},
"speaker_local_truth": {
"type": "array",
"items": {
"type": "string"
}
},
"speaker_beliefs": {
"type": "array",
"items": {
"type": "string"
}
},
"active_memories": {
"type": "array",
"items": {
"type": "string"
}
},
"active_goals": {
"type": "array",
"items": {
"type": "string"
}
},
"presentation_constraints": {
"type": "array",
"items": {
"type": "string"
}
}
}
},
"pressure": {
"type": "object",
"required": [
"pressure_id",
"label",
"intensity"
],
"additionalProperties": false,
"properties": {
"pressure_id": {
"type": "string"
},
"label": {
"type": "string"
},
"intensity": {
"type": "number",
"minimum": 0,
"maximum": 1
}
}
},
"inferred_variable_map": {
"type": "object",
"additionalProperties": {
"$ref": "#/$defs/inferred_state_variable"
}
},
"inferred_state_variable": {
"type": "object",
"required": [
"observed_activation",
"attributed_disposition",
"confidence"
],
"additionalProperties": false,
"properties": {
"observed_activation": {
"type": "number",
"minimum": 0,
"maximum": 1
},
"attributed_disposition": {
"type": "number",
"minimum": 0,
"maximum": 1
},
"confidence": {
"type": "number",
"minimum": 0,
"maximum": 1
},
"evidence": {
"type": "array",
"items": {
"type": "string"
}
}
}
},
"event_exchange_turn": {
"type": "object",
"required": [
"speaker_id",
"utterance_summary",
"dialogue_function"
],
"additionalProperties": false,
"properties": {
"speaker_id": {
"type": "string"
},
"utterance_summary": {
"type": "string"
},
"dialogue_function": {
"type": "string"
},
"observable_cues": {
"type": "array",
"items": {
"type": "string"
}
}
}
},
"event_private_interpretation": {
"type": "object",
"required": [
"agent_id",
"interpretation",
"confidence"
],
"additionalProperties": false,
"properties": {
"agent_id": {
"type": "string"
},
"interpretation": {
"type": "string"
},
"attributed_motive": {
"type": "string"
},
"appraisal_tags": {
"type": "array",
"items": {
"type": "string"
}
},
"confidence": {
"type": "number",
"minimum": 0,
"maximum": 1
}
}
},
"event_effect": {
"type": "object",
"required": [
"agent_id",
"summary"
],
"additionalProperties": false,
"properties": {
"agent_id": {
"type": "string"
},
"summary": {
"type": "string"
},
"state_deltas": {
"type": "array",
"items": {
"$ref": "#/$defs/state_delta"
}
},
"new_belief_ids": {
"type": "array",
"items": {
"type": "string"
}
},
"memory_update_ids": {
"type": "array",
"items": {
"type": "string"
}
}
}
},
"state_delta": {
"type": "object",
"required": [
"path",
"delta"
],
"additionalProperties": false,
"properties": {
"path": {
"type": "string"
},
"delta": {
"type": "number",
"minimum": -1,
"maximum": 1
}
}
}
}
}

View file

@ -18,6 +18,6 @@
</ItemGroup>
<ItemGroup>
<EmbeddedResource Include="Contracts\*.schema.json" />
<EmbeddedResource Include="..\..\contracts\cultnet\*.schema.json" LogicalName="GameCult.Networking.Contracts.%(Filename)%(Extension)" />
</ItemGroup>
</Project>