@ixo/topic-protocol 0.1.0

package/README.md

@@ -0,0 +1,133 @@
+# Topic Protocol
+
+The Topic Protocol defines a **Qi Topic** as the durable unit of context,
+continuity, discovery, authority, collaboration, and outcome for IXO.
+
+It uses native Matrix threads as a federated conversation transport without
+making a Matrix event ID, a model session, or a chat transcript the canonical
+identity of a discussion.
+
+## Status
+
+**Version:** 0.1.0  
+**Maturity:** Draft implementation candidate  
+**Execution source of truth:** [Linear Topic Protocol project](https://linear.app/ixo-world/project/topic-protocol-4ea58bc7910d)
+
+This repository is a protocol baseline, not evidence that the M0 runtime and
+security gates have passed. In particular, complete cold-cache thread discovery,
+E2EE agent participation, encrypted index migration, UCAN replay protection,
+and external action execution require their dedicated conformance evidence.
+
+## Read this first
+
+- [Architecture decisions](docs/adr/README.md)
+- [Protocol chapters](docs/protocol/README.md)
+- [Machine-readable contracts](contracts/README.md)
+- [Reference implementation](docs/reference-implementation.md)
+- [ixo-portal integration plan](docs/implementation/ixo-portal.md)
+- [Conformance and release gates](docs/conformance.md)
+- [Source recovery and provenance](docs/source-recovery.md)
+- [Linear issue map](docs/tracking/linear-source-of-truth.md)
+
+## npm runtime
+
+`@ixo/topic-protocol` is the client-neutral runtime for Portal, mobile, Jambo,
+MCP servers, and other Matrix clients. It has no dependency on
+`matrix-js-sdk`; each client supplies a small transport and persistent
+key-value adapter at its integration boundary.
+
+The package includes:
+
+- strict Draft 2020-12 validation for all 13 contracts;
+- deterministic Topic projection from a root and authorised operations;
+- relation-free Matrix root and canonical native `m.thread` event builders;
+- restart-safe two-event Topic creation with duplicate suppression;
+- append-only Matrix operation parsing and room-upgrade anchor selection;
+- explicit conflict, duplicate-delivery, unauthorised, and unreachable handling;
+- immutable caller inputs and typed protocol errors.
+
+Install it in a client:
+
+```bash
+npm install @ixo/topic-protocol
+```
+
+Create a Topic with a client-specific transport and durable pending store:
+
+```ts
+import {
+  JsonPendingTopicStore,
+  TopicRuntime,
+  createTopicId,
+} from "@ixo/topic-protocol";
+
+const runtime = new TopicRuntime({
+  transport: matrixTransport,
+  pendingStore: new JsonPendingTopicStore(keyValueStorage),
+});
+
+await runtime.createTopic({
+  roomId,
+  root: {
+    version: 1,
+    id: createTopicId(),
+    title: "Evidence policy",
+    status: "active",
+    createdBy: actorId,
+    createdAt: new Date().toISOString(),
+  },
+  firstMessage: { msgtype: "m.text", body: "Let’s decide the policy." },
+});
+```
+
+The transport must return the server-assigned Matrix event ID. The runtime
+never binds a Topic to a temporary local-echo ID. Pending storage contains only
+the room ID, Topic ID, root event ID, and creation timestamp; clients must back
+it with durable local storage to make restart recovery effective.
+
+Install development dependencies and run the complete quality gate:
+
+```bash
+npm install
+npm run check
+```
+
+See the [reference implementation guide](docs/reference-implementation.md) for
+the public API, trust boundary, and Portal integration notes.
+
+## Validate protocol artifacts
+
+The static artifact validator remains dependency-free:
+
+```bash
+python3 scripts/validate_protocol.py
+```
+
+The validator checks the documented inventory, JSON syntax, schema/vector
+pairing, required contract fields, unique API operation/tool names, local
+Markdown links, and the checksum manifest.
+
+## Core invariant
+
+> Every human message, agent response, agent run, artifact, decision, and
+> executable action occurs in the context of a Topic.
+
+Matrix rooms remain the membership, confidentiality, federation, and encryption
+boundary. A Topic can restrict action authority with UCANs, but it cannot claim
+to hide content from members of its Matrix room. A smaller confidential audience
+requires a separate encrypted room.
+
+## Repository layout
+
+```text
+docs/adr/             Architecture decisions
+docs/protocol/        Human-readable protocol chapters
+docs/implementation/  ixo-portal integration plan
+schemas/              JSON Schema Draft 2020-12 contracts
+examples/             Valid reference vectors
+api/                  OpenAPI and MCP contract surfaces
+scripts/              Dependency-free validation and integrity tooling
+checksums/            Reproducible SHA-256 manifest
+src/                  TypeScript contract and projection reference library
+test/                 TDD contract, behavior, and edge-case tests
+```

package/dist/schemas/action-receipt.schema.json

@@ -0,0 +1,18 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "https://topic-protocol.ixo.world/schemas/action-receipt.schema.json",
+    "title": "Action receipt",
+    "type": "object",
+    "required": ["receiptId", "topicId", "action", "actor", "status", "idempotencyKey", "createdAt"],
+    "properties": {
+        "receiptId": { "type": "string", "minLength": 1 },
+        "topicId": { "type": "string", "pattern": "^ixo:topic:[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$" },
+        "action": { "type": "string", "minLength": 1 },
+        "actor": { "type": "string", "minLength": 1 },
+        "status": { "type": "string", "enum": ["requested", "confirmed", "succeeded", "failed", "rejected"] },
+        "idempotencyKey": { "type": "string", "minLength": 1 },
+        "createdAt": { "type": "string", "format": "date-time" },
+        "capability": { "type": "string" }
+    },
+    "additionalProperties": true
+}

package/dist/schemas/agent-run.schema.json

@@ -0,0 +1,18 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "https://topic-protocol.ixo.world/schemas/agent-run.schema.json",
+    "title": "Agent run",
+    "type": "object",
+    "required": ["runId", "topicId", "agentId", "capsuleRevision", "status", "startedAt"],
+    "properties": {
+        "runId": { "type": "string", "minLength": 1 },
+        "topicId": { "type": "string", "pattern": "^ixo:topic:[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$" },
+        "agentId": { "type": "string", "minLength": 1 },
+        "capsuleRevision": { "type": "string", "minLength": 1 },
+        "status": { "type": "string", "enum": ["running", "completed", "failed", "cancelled"] },
+        "startedAt": { "type": "string", "format": "date-time" },
+        "finishedAt": { "type": "string", "format": "date-time" },
+        "outputs": { "type": "array", "items": { "type": "object" } }
+    },
+    "additionalProperties": true
+}

package/dist/schemas/external-session-binding.schema.json

@@ -0,0 +1,24 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "https://topic-protocol.ixo.world/schemas/external-session-binding.schema.json",
+    "title": "External session binding",
+    "type": "object",
+    "required": ["bindingId", "topicId", "provider", "sessionReference", "actor", "createdAt", "policy"],
+    "properties": {
+        "bindingId": { "type": "string", "minLength": 1 },
+        "topicId": { "type": "string", "pattern": "^ixo:topic:[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$" },
+        "provider": { "type": "string", "minLength": 1 },
+        "sessionReference": { "type": "string", "minLength": 1 },
+        "actor": { "type": "string", "minLength": 1 },
+        "createdAt": { "type": "string", "format": "date-time" },
+        "policy": {
+            "type": "object",
+            "required": ["privateByDefault"],
+            "properties": {
+                "privateByDefault": { "type": "boolean" }
+            },
+            "additionalProperties": true
+        }
+    },
+    "additionalProperties": true
+}

package/dist/schemas/room-policy.schema.json

@@ -0,0 +1,15 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "https://topic-protocol.ixo.world/schemas/room-policy.schema.json",
+    "title": "Topic room policy",
+    "type": "object",
+    "required": ["version", "mode", "generalEnabled", "allowTopicsInDirectRooms"],
+    "properties": {
+        "version": { "const": 1 },
+        "mode": { "type": "string", "enum": ["required", "optional", "general_only", "object_attached"] },
+        "generalEnabled": { "type": "boolean" },
+        "allowTopicsInDirectRooms": { "type": "boolean" },
+        "authorisedRoles": { "type": "array", "items": { "type": "string" } }
+    },
+    "additionalProperties": true
+}

package/dist/schemas/topic-capsule.schema.json

@@ -0,0 +1,19 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "https://topic-protocol.ixo.world/schemas/topic-capsule.schema.json",
+    "title": "Topic Capsule",
+    "type": "object",
+    "required": ["topicId", "anchor", "stateRevision", "participants", "acceptedMemory", "capabilities", "runtimePolicy"],
+    "properties": {
+        "topicId": { "type": "string", "pattern": "^ixo:topic:[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$" },
+        "anchor": { "type": "object", "required": ["roomId", "rootEventId"], "properties": { "roomId": { "type": "string" }, "rootEventId": { "type": "string", "pattern": "^\\$" } } },
+        "stateRevision": { "type": "string", "minLength": 1 },
+        "participants": { "type": "array", "items": { "type": "object" } },
+        "linkedContext": { "type": "array", "items": { "type": "object" } },
+        "acceptedMemory": { "type": "array", "items": { "type": "object" } },
+        "relevantEvents": { "type": "array", "items": { "type": "object" } },
+        "capabilities": { "type": "array", "items": { "type": "object" } },
+        "runtimePolicy": { "type": "object" }
+    },
+    "additionalProperties": true
+}

package/dist/schemas/topic-index-entry.schema.json

@@ -0,0 +1,17 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "https://topic-protocol.ixo.world/schemas/topic-index-entry.schema.json",
+    "title": "Topic index entry",
+    "type": "object",
+    "required": ["topicId", "roomId", "rootEventId", "status", "latestActivityAt", "completeness"],
+    "properties": {
+        "topicId": { "type": "string", "pattern": "^ixo:topic:[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$" },
+        "roomId": { "type": "string", "minLength": 1 },
+        "rootEventId": { "type": "string", "pattern": "^\\$" },
+        "status": { "type": "string" },
+        "latestActivityAt": { "type": "string", "format": "date-time" },
+        "notificationMode": { "type": "string", "enum": ["follow", "default", "mute"] },
+        "completeness": { "type": "string", "enum": ["complete", "partial-history", "metadata-pending", "decryption-pending"] }
+    },
+    "additionalProperties": true
+}

package/dist/schemas/topic-message.schema.json

@@ -0,0 +1,18 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "https://topic-protocol.ixo.world/schemas/topic-message.schema.json",
+    "title": "Topic message",
+    "type": "object",
+    "required": ["topicId", "roomId", "rootEventId", "eventId", "sender", "body", "createdAt"],
+    "properties": {
+        "topicId": { "type": "string", "pattern": "^ixo:topic:[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$" },
+        "roomId": { "type": "string", "minLength": 1 },
+        "rootEventId": { "type": "string", "pattern": "^\\$" },
+        "eventId": { "type": "string", "pattern": "^\\$" },
+        "sender": { "type": "string", "minLength": 1 },
+        "body": { "type": "string" },
+        "createdAt": { "type": "string", "format": "date-time" },
+        "inReplyTo": { "type": "string", "pattern": "^\\$" }
+    },
+    "additionalProperties": true
+}

package/dist/schemas/topic-operation.schema.json

@@ -0,0 +1,19 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "https://topic-protocol.ixo.world/schemas/topic-operation.schema.json",
+    "title": "Topic operation",
+    "type": "object",
+    "required": ["version", "operationId", "topicId", "type", "previousRevision", "actor", "createdAt", "payload"],
+    "properties": {
+        "version": { "const": 1 },
+        "operationId": { "type": "string", "minLength": 1 },
+        "topicId": { "type": "string", "pattern": "^ixo:topic:[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$" },
+        "type": { "type": "string", "enum": ["rename", "change-status", "link-context", "unlink-context", "record-decision", "redirect", "branch", "merge", "resolve-conflict"] },
+        "previousRevision": { "type": "string", "minLength": 1 },
+        "actor": { "type": "string", "minLength": 1 },
+        "createdAt": { "type": "string", "format": "date-time" },
+        "payload": { "type": "object" },
+        "capability": { "type": "string" }
+    },
+    "additionalProperties": true
+}

package/dist/schemas/topic-preferences.schema.json

@@ -0,0 +1,13 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "https://topic-protocol.ixo.world/schemas/topic-preferences.schema.json",
+    "title": "Per-user Topic preferences",
+    "type": "object",
+    "required": ["version", "topics", "autoFollow"],
+    "properties": {
+        "version": { "const": 1 },
+        "topics": { "type": "object", "additionalProperties": { "type": "object", "required": ["notificationMode", "pinned"], "properties": { "notificationMode": { "type": "string", "enum": ["follow", "default", "mute"] }, "pinned": { "type": "boolean" }, "markedUnreadFrom": { "type": ["string", "null"] } } } },
+        "autoFollow": { "type": "string", "enum": ["none", "started", "started_or_participated"] }
+    },
+    "additionalProperties": false
+}

package/dist/schemas/topic-record.schema.json

@@ -0,0 +1,18 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "https://topic-protocol.ixo.world/schemas/topic-record.schema.json",
+    "title": "Topic record",
+    "type": "object",
+    "required": ["recordId", "topicId", "kind", "createdBy", "createdAt", "sourceEventIds"],
+    "properties": {
+        "recordId": { "type": "string", "minLength": 1 },
+        "topicId": { "type": "string", "pattern": "^ixo:topic:[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$" },
+        "kind": { "type": "string", "enum": ["fact", "decision", "assumption", "question", "task", "artifact", "outcome", "memory", "failure"] },
+        "createdBy": { "type": "string", "minLength": 1 },
+        "createdAt": { "type": "string", "format": "date-time" },
+        "sourceEventIds": { "type": "array", "items": { "type": "string", "pattern": "^\\$" } },
+        "content": { "type": "object" },
+        "accepted": { "type": "boolean" }
+    },
+    "additionalProperties": true
+}

package/dist/schemas/topic-relation.schema.json

@@ -0,0 +1,16 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "https://topic-protocol.ixo.world/schemas/topic-relation.schema.json",
+    "title": "Topic graph relation",
+    "type": "object",
+    "required": ["relationId", "fromTopicId", "type", "toTopicId", "createdBy", "createdAt"],
+    "properties": {
+        "relationId": { "type": "string", "minLength": 1 },
+        "fromTopicId": { "type": "string", "pattern": "^ixo:topic:[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$" },
+        "type": { "type": "string", "enum": ["branches_from", "merged_into", "redirects_to", "references", "produced"] },
+        "toTopicId": { "type": "string", "pattern": "^ixo:topic:[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$" },
+        "createdBy": { "type": "string", "minLength": 1 },
+        "createdAt": { "type": "string", "format": "date-time" }
+    },
+    "additionalProperties": true
+}

package/dist/schemas/topic-root.schema.json

@@ -0,0 +1,18 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "https://topic-protocol.ixo.world/schemas/topic-root.schema.json",
+    "title": "Topic root envelope",
+    "type": "object",
+    "required": ["version", "id", "title", "status", "createdBy", "createdAt"],
+    "properties": {
+        "version": { "const": 1 },
+        "id": { "type": "string", "pattern": "^ixo:topic:[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$" },
+        "title": { "type": "string", "minLength": 1, "maxLength": 280 },
+        "kind": { "type": "string", "enum": ["discussion", "question", "decision", "proposal", "task", "incident", "flow"] },
+        "status": { "type": "string", "enum": ["draft", "active", "waiting", "blocked", "resolved", "archived", "redirected"] },
+        "createdBy": { "type": "string", "minLength": 1 },
+        "createdAt": { "type": "string", "format": "date-time" },
+        "context": { "type": "array", "items": { "type": "object", "required": ["type", "id"], "properties": { "type": { "type": "string" }, "id": { "type": "string" } } } }
+    },
+    "additionalProperties": true
+}

package/dist/schemas/topic-state.schema.json

@@ -0,0 +1,19 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "https://topic-protocol.ixo.world/schemas/topic-state.schema.json",
+    "title": "Projected Topic state",
+    "type": "object",
+    "required": ["topicId", "revision", "status", "basedOnEvents", "conflicts"],
+    "properties": {
+        "topicId": { "type": "string", "pattern": "^ixo:topic:[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$" },
+        "revision": { "type": "string", "minLength": 1 },
+        "status": { "type": "string", "enum": ["draft", "active", "waiting", "blocked", "resolved", "archived", "redirected"] },
+        "purpose": { "type": "string" },
+        "acceptedFacts": { "type": "array", "items": { "type": "object" } },
+        "decisions": { "type": "array", "items": { "type": "object" } },
+        "unresolvedQuestions": { "type": "array", "items": { "type": "object" } },
+        "basedOnEvents": { "type": "array", "items": { "type": "string", "pattern": "^\\$" } },
+        "conflicts": { "type": "array", "items": { "type": "string" } }
+    },
+    "additionalProperties": true
+}