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.4.0

Maturity: Draft implementation candidate
Execution source of truth: Linear Topic Protocol project

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
• Protocol chapters
• Machine-readable contracts
• Reference implementation
• ixo-portal integration plan
• Conformance and release gates
• Source recovery and provenance
• Linear issue map

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 17 contracts;
• deterministic Topic-index reconciliation, structured search, and personal ranking;
• deterministic Topic projection from a root and authorised operations;
• singular accepted Overview projection with deterministic conflict handling;
• relation-free Matrix root and canonical native m.thread event builders;
• validated ixo.topic.record and ixo.topic.source message-card 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.

Topics retain a singular conversational kind while linking any number of typed subject contexts. They also project pinned VFS file references without copying bytes into Matrix or granting VFS access. A CID, content hash, and snapshot metadata are visible to Topic members; the VFS grant remains the authority for the file bytes.

Install it in a client:

npm install @ixo/topic-protocol

Create a Topic with a client-specific transport and durable pending store:

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.

Topic index snapshots are plaintext only while in trusted process memory. A client persistence adapter must encrypt them at rest. Portal uses Matrix Secret Storage, while follow, mute, pin, and mark-unread flags remain room account data rather than shared Topic state.

Install development dependencies and run the complete quality gate:

npm install
npm run check

See the reference implementation guide for the public API, trust boundary, and Portal integration notes.

Validate protocol artifacts

The static artifact validator remains dependency-free:

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

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