@ixo/topic-protocol 0.2.0 → 0.4.0

package/README.md

@@ -9,7 +9,7 @@ identity of a discussion.
 
 ## Status
 
-**Version:** 0.2.0
+**Version:** 0.4.0
 
 **Maturity:** Draft implementation candidate  
 **Execution source of truth:** [Linear Topic Protocol project](https://linear.app/ixo-world/project/topic-protocol-4ea58bc7910d)
@@ -39,7 +39,8 @@ key-value adapter at its integration boundary.
 
 The package includes:
 
-- strict Draft 2020-12 validation for all 15 contracts;
+- 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;
@@ -49,6 +50,12 @@ The package includes:
 - 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:
 
 ```bash
@@ -88,6 +95,11 @@ 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:
 
 ```bash

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

@@ -3,13 +3,14 @@
     "$id": "https://topic-protocol.ixo.world/schemas/topic-capsule.schema.json",
     "title": "Topic Capsule",
     "type": "object",
-    "required": ["topicId", "anchor", "stateRevision", "participants", "acceptedMemory", "capabilities", "runtimePolicy"],
+    "required": ["topicId", "anchor", "stateRevision", "participants", "attachments", "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" } },
+        "attachments": { "type": "array", "items": { "$ref": "https://topic-protocol.ixo.world/schemas/topic-file-attachment.schema.json" } },
         "acceptedMemory": { "type": "array", "items": { "type": "object" } },
         "relevantEvents": { "type": "array", "items": { "type": "object" } },
         "capabilities": { "type": "array", "items": { "type": "object" } },

package/dist/schemas/topic-file-attachment.schema.json

@@ -0,0 +1,23 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "https://topic-protocol.ixo.world/schemas/topic-file-attachment.schema.json",
+    "title": "Pinned Topic VFS file reference",
+    "type": "object",
+    "required": ["provider", "resource", "fileId", "version", "cid", "contentHash", "path", "name", "mimeType", "size"],
+    "properties": {
+        "provider": { "const": "ixo.vfs" },
+        "resource": { "type": "string", "pattern": "^ixo:filesystem/.+" },
+        "fileId": { "type": "string", "minLength": 1 },
+        "version": { "type": "integer", "minimum": 1 },
+        "cid": { "type": "string", "minLength": 1 },
+        "contentHash": { "type": "string", "pattern": "^[0-9a-f]{64}$" },
+        "path": { "type": "string", "pattern": "^/(?!.*(?:^|/)\\.\\.(?:/|$)).+" },
+        "name": { "type": "string", "minLength": 1 },
+        "mimeType": { "type": "string", "minLength": 1 },
+        "size": { "type": "integer", "minimum": 0 },
+        "attachedBy": { "type": "string", "minLength": 1 },
+        "attachedAt": { "type": "string", "format": "date-time" },
+        "operationId": { "type": "string", "minLength": 1 }
+    },
+    "additionalProperties": false
+}

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

@@ -8,10 +8,43 @@
         "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": "^\\$" },
+        "title": { "type": "string", "minLength": 1, "maxLength": 280 },
+        "currentState": { "type": "string", "minLength": 1, "maxLength": 280 },
         "status": { "type": "string" },
+        "kind": { "type": "string", "enum": ["discussion", "question", "decision", "proposal", "task", "incident", "flow"] },
+        "domain": {
+            "type": "object",
+            "required": ["id"],
+            "properties": {
+                "id": { "type": "string", "minLength": 1 },
+                "name": { "type": "string", "minLength": 1 }
+            },
+            "additionalProperties": false
+        },
+        "context": {
+            "type": "array",
+            "items": {
+                "type": "object",
+                "required": ["type", "id"],
+                "properties": {
+                    "type": { "type": "string", "minLength": 1 },
+                    "id": { "type": "string", "minLength": 1 }
+                },
+                "additionalProperties": false
+            }
+        },
+        "sourceKinds": {
+            "type": "array",
+            "uniqueItems": true,
+            "items": { "type": "string", "enum": ["message", "flow", "decision", "artifact", "notification", "other"] }
+        },
         "latestActivityAt": { "type": "string", "format": "date-time" },
+        "latestEventId": { "type": "string", "pattern": "^\\$" },
+        "participated": { "type": "boolean" },
+        "unread": { "type": "string", "enum": ["unread", "read", "unknown"] },
         "notificationMode": { "type": "string", "enum": ["follow", "default", "mute"] },
-        "completeness": { "type": "string", "enum": ["complete", "partial-history", "metadata-pending", "decryption-pending"] }
+        "completeness": { "type": "string", "enum": ["complete", "partial-history", "metadata-pending", "decryption-pending"] },
+        "indexedAt": { "type": "string", "format": "date-time" }
     },
     "additionalProperties": true
 }

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

@@ -0,0 +1,39 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "https://topic-protocol.ixo.world/schemas/topic-index.schema.json",
+    "title": "Encrypted Topic index plaintext snapshot",
+    "type": "object",
+    "required": ["version", "updatedAt", "entries", "tombstones"],
+    "properties": {
+        "version": { "const": 1 },
+        "updatedAt": { "type": "string", "format": "date-time" },
+        "entries": {
+            "type": "array",
+            "items": {
+                "allOf": [
+                    { "$ref": "https://topic-protocol.ixo.world/schemas/topic-index-entry.schema.json" },
+                    {
+                        "type": "object",
+                        "required": ["participated", "unread", "indexedAt"],
+                        "properties": {
+                            "status": { "type": "string", "enum": ["draft", "active", "waiting", "blocked", "resolved", "archived", "redirected"] }
+                        }
+                    }
+                ]
+            }
+        },
+        "tombstones": {
+            "type": "array",
+            "items": {
+                "type": "object",
+                "required": ["roomId", "removedAt"],
+                "properties": {
+                    "roomId": { "type": "string", "minLength": 1 },
+                    "removedAt": { "type": "string", "format": "date-time" }
+                },
+                "additionalProperties": false
+            }
+        }
+    },
+    "additionalProperties": false
+}

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

@@ -8,7 +8,7 @@
         "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", "update-overview", "link-context", "unlink-context", "record-decision", "redirect", "branch", "merge", "resolve-conflict"] },
+        "type": { "type": "string", "enum": ["rename", "change-status", "update-overview", "link-context", "unlink-context", "attach-files", "detach-files", "record-decision", "redirect", "branch", "merge", "resolve-conflict"] },
         "previousRevision": { "type": "string", "minLength": 1 },
         "actor": { "type": "string", "minLength": 1 },
         "createdAt": { "type": "string", "format": "date-time" },

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

@@ -12,7 +12,19 @@
         "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" } } } },
+        "context": {
+            "type": "array",
+            "uniqueItems": true,
+            "items": {
+                "type": "object",
+                "required": ["type", "id"],
+                "properties": {
+                    "type": { "type": "string", "minLength": 1 },
+                    "id": { "type": "string", "minLength": 1 }
+                },
+                "additionalProperties": false
+            }
+        },
         "overview": {
             "type": "object",
             "required": ["summary"],

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

@@ -3,7 +3,7 @@
     "$id": "https://topic-protocol.ixo.world/schemas/topic-state.schema.json",
     "title": "Projected Topic state",
     "type": "object",
-    "required": ["topicId", "revision", "status", "basedOnEvents", "conflicts"],
+    "required": ["topicId", "revision", "status", "attachments", "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 },
@@ -24,6 +24,15 @@
         "acceptedFacts": { "type": "array", "items": { "type": "object" } },
         "decisions": { "type": "array", "items": { "type": "object" } },
         "unresolvedQuestions": { "type": "array", "items": { "type": "object" } },
+        "attachments": {
+            "type": "array",
+            "items": {
+                "allOf": [
+                    { "$ref": "https://topic-protocol.ixo.world/schemas/topic-file-attachment.schema.json" },
+                    { "type": "object", "required": ["attachedBy", "attachedAt", "operationId"] }
+                ]
+            }
+        },
         "basedOnEvents": { "type": "array", "items": { "type": "string", "pattern": "^\\$" } },
         "conflicts": { "type": "array", "items": { "type": "string" } }
     },

package/dist/src/contracts/schemas.d.ts

@@ -197,6 +197,12 @@ export declare const SCHEMA_REGISTRY: Readonly<{
                     type: string;
                 };
             };
+            attachments: {
+                type: string;
+                items: {
+                    $ref: string;
+                };
+            };
             acceptedMemory: {
                 type: string;
                 items: {
@@ -221,6 +227,67 @@ export declare const SCHEMA_REGISTRY: Readonly<{
         };
         additionalProperties: boolean;
     };
+    "topic-file-attachment": {
+        $schema: string;
+        $id: string;
+        title: string;
+        type: string;
+        required: string[];
+        properties: {
+            provider: {
+                const: string;
+            };
+            resource: {
+                type: string;
+                pattern: string;
+            };
+            fileId: {
+                type: string;
+                minLength: number;
+            };
+            version: {
+                type: string;
+                minimum: number;
+            };
+            cid: {
+                type: string;
+                minLength: number;
+            };
+            contentHash: {
+                type: string;
+                pattern: string;
+            };
+            path: {
+                type: string;
+                pattern: string;
+            };
+            name: {
+                type: string;
+                minLength: number;
+            };
+            mimeType: {
+                type: string;
+                minLength: number;
+            };
+            size: {
+                type: string;
+                minimum: number;
+            };
+            attachedBy: {
+                type: string;
+                minLength: number;
+            };
+            attachedAt: {
+                type: string;
+                format: string;
+            };
+            operationId: {
+                type: string;
+                minLength: number;
+            };
+        };
+        additionalProperties: boolean;
+    };
     "topic-index-entry": {
         $schema: string;
         $id: string;
@@ -240,13 +307,79 @@ export declare const SCHEMA_REGISTRY: Readonly<{
                 type: string;
                 pattern: string;
             };
+            title: {
+                type: string;
+                minLength: number;
+                maxLength: number;
+            };
+            currentState: {
+                type: string;
+                minLength: number;
+                maxLength: number;
+            };
             status: {
                 type: string;
             };
+            kind: {
+                type: string;
+                enum: string[];
+            };
+            domain: {
+                type: string;
+                required: string[];
+                properties: {
+                    id: {
+                        type: string;
+                        minLength: number;
+                    };
+                    name: {
+                        type: string;
+                        minLength: number;
+                    };
+                };
+                additionalProperties: boolean;
+            };
+            context: {
+                type: string;
+                items: {
+                    type: string;
+                    required: string[];
+                    properties: {
+                        type: {
+                            type: string;
+                            minLength: number;
+                        };
+                        id: {
+                            type: string;
+                            minLength: number;
+                        };
+                    };
+                    additionalProperties: boolean;
+                };
+            };
+            sourceKinds: {
+                type: string;
+                uniqueItems: boolean;
+                items: {
+                    type: string;
+                    enum: string[];
+                };
+            };
             latestActivityAt: {
                 type: string;
                 format: string;
             };
+            latestEventId: {
+                type: string;
+                pattern: string;
+            };
+            participated: {
+                type: string;
+            };
+            unread: {
+                type: string;
+                enum: string[];
+            };
             notificationMode: {
                 type: string;
                 enum: string[];
@@ -255,6 +388,66 @@ export declare const SCHEMA_REGISTRY: Readonly<{
                 type: string;
                 enum: string[];
             };
+            indexedAt: {
+                type: string;
+                format: string;
+            };
+        };
+        additionalProperties: boolean;
+    };
+    "topic-index": {
+        $schema: string;
+        $id: string;
+        title: string;
+        type: string;
+        required: string[];
+        properties: {
+            version: {
+                const: number;
+            };
+            updatedAt: {
+                type: string;
+                format: string;
+            };
+            entries: {
+                type: string;
+                items: {
+                    allOf: ({
+                        $ref: string;
+                        type?: never;
+                        required?: never;
+                        properties?: never;
+                    } | {
+                        type: string;
+                        required: string[];
+                        properties: {
+                            status: {
+                                type: string;
+                                enum: string[];
+                            };
+                        };
+                        $ref?: never;
+                    })[];
+                };
+            };
+            tombstones: {
+                type: string;
+                items: {
+                    type: string;
+                    required: string[];
+                    properties: {
+                        roomId: {
+                            type: string;
+                            minLength: number;
+                        };
+                        removedAt: {
+                            type: string;
+                            format: string;
+                        };
+                    };
+                    additionalProperties: boolean;
+                };
+            };
         };
         additionalProperties: boolean;
     };
@@ -529,17 +722,21 @@ export declare const SCHEMA_REGISTRY: Readonly<{
             };
             context: {
                 type: string;
+                uniqueItems: boolean;
                 items: {
                     type: string;
                     required: string[];
                     properties: {
                         type: {
                             type: string;
+                            minLength: number;
                         };
                         id: {
                             type: string;
+                            minLength: number;
                         };
                     };
+                    additionalProperties: boolean;
                 };
             };
             overview: {
@@ -644,6 +841,20 @@ export declare const SCHEMA_REGISTRY: Readonly<{
                     type: string;
                 };
             };
+            attachments: {
+                type: string;
+                items: {
+                    allOf: ({
+                        $ref: string;
+                        type?: never;
+                        required?: never;
+                    } | {
+                        type: string;
+                        required: string[];
+                        $ref?: never;
+                    })[];
+                };
+            };
             basedOnEvents: {
                 type: string;
                 items: {
@@ -782,4 +993,4 @@ export declare const SCHEMA_REGISTRY: Readonly<{
     };
 }>;
 export type ContractName = keyof typeof SCHEMA_REGISTRY;
-export declare const CONTRACT_NAMES: readonly ("action-receipt" | "agent-run" | "external-session-binding" | "room-policy" | "topic-capsule" | "topic-index-entry" | "topic-message" | "topic-operation" | "topic-preferences" | "topic-record" | "topic-record-message" | "topic-relation" | "topic-root" | "topic-state" | "topic-source-message")[];
+export declare const CONTRACT_NAMES: readonly ("action-receipt" | "agent-run" | "external-session-binding" | "room-policy" | "topic-capsule" | "topic-file-attachment" | "topic-index-entry" | "topic-index" | "topic-message" | "topic-operation" | "topic-preferences" | "topic-record" | "topic-record-message" | "topic-relation" | "topic-root" | "topic-state" | "topic-source-message")[];

package/dist/src/contracts/schemas.js

@@ -3,7 +3,9 @@ import agentRun from "../../schemas/agent-run.schema.json" with { type: "json" }
 import externalSessionBinding from "../../schemas/external-session-binding.schema.json" with { type: "json" };
 import roomPolicy from "../../schemas/room-policy.schema.json" with { type: "json" };
 import topicCapsule from "../../schemas/topic-capsule.schema.json" with { type: "json" };
+import topicFileAttachment from "../../schemas/topic-file-attachment.schema.json" with { type: "json" };
 import topicIndexEntry from "../../schemas/topic-index-entry.schema.json" with { type: "json" };
+import topicIndex from "../../schemas/topic-index.schema.json" with { type: "json" };
 import topicMessage from "../../schemas/topic-message.schema.json" with { type: "json" };
 import topicOperation from "../../schemas/topic-operation.schema.json" with { type: "json" };
 import topicPreferences from "../../schemas/topic-preferences.schema.json" with { type: "json" };
@@ -19,7 +21,9 @@ export const SCHEMA_REGISTRY = Object.freeze({
     "external-session-binding": externalSessionBinding,
     "room-policy": roomPolicy,
     "topic-capsule": topicCapsule,
+    "topic-file-attachment": topicFileAttachment,
     "topic-index-entry": topicIndexEntry,
+    "topic-index": topicIndex,
     "topic-message": topicMessage,
     "topic-operation": topicOperation,
     "topic-preferences": topicPreferences,

package/dist/src/contracts/schemas.js.map

@@ -1 +1 @@
-{"version":3,"file":"schemas.js","sourceRoot":"","sources":["../../../src/contracts/schemas.ts"],"names":[],"mappings":"AAAA,OAAO,aAAa,MAAM,0CAA0C,CAAC,OAAO,IAAI,EAAE,MAAM,EAAE,CAAC;AAC3F,OAAO,QAAQ,MAAM,qCAAqC,CAAC,OAAO,IAAI,EAAE,MAAM,EAAE,CAAC;AACjF,OAAO,sBAAsB,MAAM,oDAAoD,CAAC,OAAO,IAAI,EAAE,MAAM,EAAE,CAAC;AAC9G,OAAO,UAAU,MAAM,uCAAuC,CAAC,OAAO,IAAI,EAAE,MAAM,EAAE,CAAC;AACrF,OAAO,YAAY,MAAM,yCAAyC,CAAC,OAAO,IAAI,EAAE,MAAM,EAAE,CAAC;AACzF,OAAO,eAAe,MAAM,6CAA6C,CAAC,OAAO,IAAI,EAAE,MAAM,EAAE,CAAC;AAChG,OAAO,YAAY,MAAM,yCAAyC,CAAC,OAAO,IAAI,EAAE,MAAM,EAAE,CAAC;AACzF,OAAO,cAAc,MAAM,2CAA2C,CAAC,OAAO,IAAI,EAAE,MAAM,EAAE,CAAC;AAC7F,OAAO,gBAAgB,MAAM,6CAA6C,CAAC,OAAO,IAAI,EAAE,MAAM,EAAE,CAAC;AACjG,OAAO,WAAW,MAAM,wCAAwC,CAAC,OAAO,IAAI,EAAE,MAAM,EAAE,CAAC;AACvF,OAAO,kBAAkB,MAAM,gDAAgD,CAAC,OAAO,IAAI,EAAE,MAAM,EAAE,CAAC;AACtG,OAAO,aAAa,MAAM,0CAA0C,CAAC,OAAO,IAAI,EAAE,MAAM,EAAE,CAAC;AAC3F,OAAO,SAAS,MAAM,sCAAsC,CAAC,OAAO,IAAI,EAAE,MAAM,EAAE,CAAC;AACnF,OAAO,UAAU,MAAM,uCAAuC,CAAC,OAAO,IAAI,EAAE,MAAM,EAAE,CAAC;AACrF,OAAO,kBAAkB,MAAM,gDAAgD,CAAC,OAAO,IAAI,EAAE,MAAM,EAAE,CAAC;AAEtG,MAAM,CAAC,MAAM,eAAe,GAAG,MAAM,CAAC,MAAM,CAAC;IAC3C,gBAAgB,EAAE,aAAa;IAC/B,WAAW,EAAE,QAAQ;IACrB,0BAA0B,EAAE,sBAAsB;IAClD,aAAa,EAAE,UAAU;IACzB,eAAe,EAAE,YAAY;IAC7B,mBAAmB,EAAE,eAAe;IACpC,eAAe,EAAE,YAAY;IAC7B,iBAAiB,EAAE,cAAc;IACjC,mBAAmB,EAAE,gBAAgB;IACrC,cAAc,EAAE,WAAW;IAC3B,sBAAsB,EAAE,kBAAkB;IAC1C,gBAAgB,EAAE,aAAa;IAC/B,YAAY,EAAE,SAAS;IACvB,aAAa,EAAE,UAAU;IACzB,sBAAsB,EAAE,kBAAkB;CAC3C,CAAC,CAAC;AAIH,MAAM,CAAC,MAAM,cAAc,GAAG,MAAM,CAAC,MAAM,CACzC,MAAM,CAAC,IAAI,CAAC,eAAe,CAAC,CAAC,IAAI,EAAoB,CACtD,CAAC"}
+{"version":3,"file":"schemas.js","sourceRoot":"","sources":["../../../src/contracts/schemas.ts"],"names":[],"mappings":"AAAA,OAAO,aAAa,MAAM,0CAA0C,CAAC,OAAO,IAAI,EAAE,MAAM,EAAE,CAAC;AAC3F,OAAO,QAAQ,MAAM,qCAAqC,CAAC,OAAO,IAAI,EAAE,MAAM,EAAE,CAAC;AACjF,OAAO,sBAAsB,MAAM,oDAAoD,CAAC,OAAO,IAAI,EAAE,MAAM,EAAE,CAAC;AAC9G,OAAO,UAAU,MAAM,uCAAuC,CAAC,OAAO,IAAI,EAAE,MAAM,EAAE,CAAC;AACrF,OAAO,YAAY,MAAM,yCAAyC,CAAC,OAAO,IAAI,EAAE,MAAM,EAAE,CAAC;AACzF,OAAO,mBAAmB,MAAM,iDAAiD,CAAC,OAAO,IAAI,EAAE,MAAM,EAAE,CAAC;AACxG,OAAO,eAAe,MAAM,6CAA6C,CAAC,OAAO,IAAI,EAAE,MAAM,EAAE,CAAC;AAChG,OAAO,UAAU,MAAM,uCAAuC,CAAC,OAAO,IAAI,EAAE,MAAM,EAAE,CAAC;AACrF,OAAO,YAAY,MAAM,yCAAyC,CAAC,OAAO,IAAI,EAAE,MAAM,EAAE,CAAC;AACzF,OAAO,cAAc,MAAM,2CAA2C,CAAC,OAAO,IAAI,EAAE,MAAM,EAAE,CAAC;AAC7F,OAAO,gBAAgB,MAAM,6CAA6C,CAAC,OAAO,IAAI,EAAE,MAAM,EAAE,CAAC;AACjG,OAAO,WAAW,MAAM,wCAAwC,CAAC,OAAO,IAAI,EAAE,MAAM,EAAE,CAAC;AACvF,OAAO,kBAAkB,MAAM,gDAAgD,CAAC,OAAO,IAAI,EAAE,MAAM,EAAE,CAAC;AACtG,OAAO,aAAa,MAAM,0CAA0C,CAAC,OAAO,IAAI,EAAE,MAAM,EAAE,CAAC;AAC3F,OAAO,SAAS,MAAM,sCAAsC,CAAC,OAAO,IAAI,EAAE,MAAM,EAAE,CAAC;AACnF,OAAO,UAAU,MAAM,uCAAuC,CAAC,OAAO,IAAI,EAAE,MAAM,EAAE,CAAC;AACrF,OAAO,kBAAkB,MAAM,gDAAgD,CAAC,OAAO,IAAI,EAAE,MAAM,EAAE,CAAC;AAEtG,MAAM,CAAC,MAAM,eAAe,GAAG,MAAM,CAAC,MAAM,CAAC;IAC3C,gBAAgB,EAAE,aAAa;IAC/B,WAAW,EAAE,QAAQ;IACrB,0BAA0B,EAAE,sBAAsB;IAClD,aAAa,EAAE,UAAU;IACzB,eAAe,EAAE,YAAY;IAC7B,uBAAuB,EAAE,mBAAmB;IAC5C,mBAAmB,EAAE,eAAe;IACpC,aAAa,EAAE,UAAU;IACzB,eAAe,EAAE,YAAY;IAC7B,iBAAiB,EAAE,cAAc;IACjC,mBAAmB,EAAE,gBAAgB;IACrC,cAAc,EAAE,WAAW;IAC3B,sBAAsB,EAAE,kBAAkB;IAC1C,gBAAgB,EAAE,aAAa;IAC/B,YAAY,EAAE,SAAS;IACvB,aAAa,EAAE,UAAU;IACzB,sBAAsB,EAAE,kBAAkB;CAC3C,CAAC,CAAC;AAIH,MAAM,CAAC,MAAM,cAAc,GAAG,MAAM,CAAC,MAAM,CACzC,MAAM,CAAC,IAAI,CAAC,eAAe,CAAC,CAAC,IAAI,EAAoB,CACtD,CAAC"}

package/dist/src/errors.d.ts

@@ -1,4 +1,4 @@
-export type TopicProtocolErrorCode = "ANCHOR_CONFLICT" | "ANCHOR_CYCLE" | "AUTHORIZATION_FAILED" | "CONTRACT_VALIDATION_FAILED" | "DUPLICATE_OPERATION" | "FIRST_MESSAGE_FAILED" | "INVALID_ANCHOR" | "INVALID_MATRIX_EVENT" | "INVALID_OPERATION_PAYLOAD" | "INVALID_SERVER_EVENT_ID" | "NON_CANONICAL_CONFLICT_SELECTION" | "PENDING_ROOT_UNRESOLVED" | "ROOT_CREATION_FAILED" | "ROOT_DISCOVERY_FAILED" | "STORAGE_FAILED" | "TOPIC_ROOT_NOT_FOUND" | "TOPIC_MISMATCH" | "UNKNOWN_CONFLICT" | "UNKNOWN_CONTRACT";
+export type TopicProtocolErrorCode = "ANCHOR_CONFLICT" | "ANCHOR_CYCLE" | "AUTHORIZATION_FAILED" | "CONTRACT_VALIDATION_FAILED" | "DUPLICATE_OPERATION" | "FIRST_MESSAGE_FAILED" | "INVALID_ANCHOR" | "INVALID_CONTEXT_TYPE" | "INVALID_MATRIX_EVENT" | "INVALID_OPERATION_PAYLOAD" | "INVALID_SERVER_EVENT_ID" | "NON_CANONICAL_CONFLICT_SELECTION" | "PENDING_ROOT_UNRESOLVED" | "ROOT_CREATION_FAILED" | "ROOT_DISCOVERY_FAILED" | "STORAGE_FAILED" | "TOPIC_ROOT_NOT_FOUND" | "TOPIC_MISMATCH" | "UNKNOWN_CONFLICT" | "UNKNOWN_CONTRACT";
 export declare class TopicProtocolError extends Error {
     readonly code: TopicProtocolErrorCode;
     readonly details: Readonly<Record<string, unknown>>;

package/dist/src/errors.js.map

@@ -1 +1 @@
-{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/errors.ts"],"names":[],"mappings":"AAqBA,MAAM,OAAO,kBAAmB,SAAQ,KAAK;IAClC,IAAI,CAAyB;IAC7B,OAAO,CAAoC;IAEpD,YACE,IAA4B,EAC5B,OAAe,EACf,UAA6C,EAAE,EAC/C,OAAsB;QAEtB,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QACxB,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAC;QACjC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;IACzB,CAAC;CACF"}
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/errors.ts"],"names":[],"mappings":"AAsBA,MAAM,OAAO,kBAAmB,SAAQ,KAAK;IAClC,IAAI,CAAyB;IAC7B,OAAO,CAAoC;IAEpD,YACE,IAA4B,EAC5B,OAAe,EACf,UAA6C,EAAE,EAC/C,OAAsB;QAEtB,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QACxB,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAC;QACjC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;IACzB,CAAC;CACF"}

package/dist/src/index.d.ts

@@ -9,5 +9,9 @@ export { isTopicInfrastructureEvent, parseTopicRootEvent, projectMatrixTopic, }
 export { JsonPendingTopicStore, MemoryPendingTopicStore, type TopicKeyValueStore, } from "./matrix/pending.js";
 export { TopicRuntime, type TopicRuntimeOptions } from "./matrix/runtime.js";
 export { MATRIX_ROOM_MESSAGE, TOPIC_ANCHOR_KEY, TOPIC_METADATA_KEY, TOPIC_OPERATION_EVENT_TYPE, type CanonicalTopicAnchor, type MatrixEventContent, type MatrixSendRequest, type MatrixTopicProjection, type MatrixTopicProjectionInput, type ParsedTopicRoot, type PendingTopicCreation, type PendingTopicStore, type RejectedTopicEvent, type RejectedTopicEventReason, type TopicAnchorConflict, type TopicCreationInput, type TopicCreationResult, type TopicFirstMessageFactory, type TopicMatrixEvent, type TopicMatrixTransport, type TopicRootContentOptions, } from "./matrix/types.js";
-export { TOPIC_KINDS, TOPIC_STATUSES, type IgnoredOperation, type IgnoredOperationReason, type MatrixAnchor, type ProjectedTopicRelation, type ProjectionInput, type TopicContext, type TopicDecision, type TopicKind, type TopicNextStep, type TopicOperation, type TopicOperationType, type TopicProjection, type ProjectedTopicOverview, type TopicOverview, type TopicProjectionConflict, type TopicRelationType, type TopicRoot, type TopicStatus, } from "./projector/types.js";
+export { TOPIC_KINDS, TOPIC_CONTEXT_TYPES, TOPIC_STATUSES, TOPIC_VFS_FILE_PROVIDER, type IgnoredOperation, type IgnoredOperationReason, type MatrixAnchor, type ProjectedTopicRelation, type ProjectionInput, type TopicContext, type TopicContextType, type TopicFileAttachmentIdentity, type TopicDecision, type TopicKind, type TopicNextStep, type TopicOperation, type TopicOperationType, type TopicProjection, type ProjectedTopicAttachment, type ProjectedTopicOverview, type TopicOverview, type TopicProjectionConflict, type TopicRelationType, type TopicRoot, type TopicStatus, type TopicVfsFileReference, isCanonicalTopicContextType, } from "./projector/types.js";
 export { TOPIC_RECORD_KINDS, type TopicRecord, type TopicRecordKind, } from "./records/types.js";
+export { emptyTopicIndexSnapshot, reconcileTopicIndex } from "./indexing/reconcile.js";
+export { searchTopicIndex } from "./indexing/search.js";
+export { rankTopicIndex } from "./indexing/rank.js";
+export { TOPIC_INDEX_COMPLETENESS, TOPIC_INDEX_RANK_REASONS, TOPIC_INDEX_STORAGE_STATES, TOPIC_INDEX_UNREAD_STATES, TOPIC_NOTIFICATION_MODES, type RankedTopicIndexEntry, type TopicAttentionSignalMap, type TopicAttentionSignals, type TopicIndexCompleteness, type TopicIndexDomain, type TopicIndexEntry, type TopicIndexObservation, type TopicIndexRankReason, type TopicIndexReconciliation, type TopicIndexSearchFilters, type TopicIndexSnapshot, type TopicIndexStorageState, type TopicIndexTombstone, type TopicIndexUnreadState, type TopicNotificationMode, type TopicPreference, type TopicPreferenceMap, } from "./indexing/types.js";

package/dist/src/index.js

@@ -9,6 +9,10 @@ export { isTopicInfrastructureEvent, parseTopicRootEvent, projectMatrixTopic, }
 export { JsonPendingTopicStore, MemoryPendingTopicStore, } from "./matrix/pending.js";
 export { TopicRuntime } from "./matrix/runtime.js";
 export { MATRIX_ROOM_MESSAGE, TOPIC_ANCHOR_KEY, TOPIC_METADATA_KEY, TOPIC_OPERATION_EVENT_TYPE, } from "./matrix/types.js";
-export { TOPIC_KINDS, TOPIC_STATUSES, } from "./projector/types.js";
+export { TOPIC_KINDS, TOPIC_CONTEXT_TYPES, TOPIC_STATUSES, TOPIC_VFS_FILE_PROVIDER, isCanonicalTopicContextType, } from "./projector/types.js";
 export { TOPIC_RECORD_KINDS, } from "./records/types.js";
+export { emptyTopicIndexSnapshot, reconcileTopicIndex } from "./indexing/reconcile.js";
+export { searchTopicIndex } from "./indexing/search.js";
+export { rankTopicIndex } from "./indexing/rank.js";
+export { TOPIC_INDEX_COMPLETENESS, TOPIC_INDEX_RANK_REASONS, TOPIC_INDEX_STORAGE_STATES, TOPIC_INDEX_UNREAD_STATES, TOPIC_NOTIFICATION_MODES, } from "./indexing/types.js";
 //# sourceMappingURL=index.js.map

package/dist/src/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,cAAc,GAEf,MAAM,wBAAwB,CAAC;AAChC,OAAO,EACL,cAAc,EACd,gBAAgB,GAGjB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EACL,kBAAkB,GAEnB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AACtD,OAAO,EAAE,0BAA0B,EAAE,MAAM,qBAAqB,CAAC;AACjE,OAAO,EACL,kBAAkB,EAClB,kBAAkB,EAClB,mBAAmB,EACnB,yBAAyB,EACzB,wBAAwB,EACxB,0BAA0B,EAC1B,qBAAqB,EACrB,aAAa,EACb,sBAAsB,GACvB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,gBAAgB,EAChB,oBAAoB,EACpB,gBAAgB,EAChB,kBAAkB,EAClB,oBAAoB,EACpB,+BAA+B,EAC/B,+BAA+B,EAC/B,8BAA8B,EAC9B,8BAA8B,GAS/B,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,0BAA0B,EAC1B,mBAAmB,EACnB,kBAAkB,GACnB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACL,qBAAqB,EACrB,uBAAuB,GAExB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,YAAY,EAA4B,MAAM,qBAAqB,CAAC;AAC7E,OAAO,EACL,mBAAmB,EACnB,gBAAgB,EAChB,kBAAkB,EAClB,0BAA0B,GAkB3B,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,WAAW,EACX,cAAc,GAmBf,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,kBAAkB,GAGnB,MAAM,oBAAoB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,cAAc,GAEf,MAAM,wBAAwB,CAAC;AAChC,OAAO,EACL,cAAc,EACd,gBAAgB,GAGjB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EACL,kBAAkB,GAEnB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AACtD,OAAO,EAAE,0BAA0B,EAAE,MAAM,qBAAqB,CAAC;AACjE,OAAO,EACL,kBAAkB,EAClB,kBAAkB,EAClB,mBAAmB,EACnB,yBAAyB,EACzB,wBAAwB,EACxB,0BAA0B,EAC1B,qBAAqB,EACrB,aAAa,EACb,sBAAsB,GACvB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,gBAAgB,EAChB,oBAAoB,EACpB,gBAAgB,EAChB,kBAAkB,EAClB,oBAAoB,EACpB,+BAA+B,EAC/B,+BAA+B,EAC/B,8BAA8B,EAC9B,8BAA8B,GAS/B,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,0BAA0B,EAC1B,mBAAmB,EACnB,kBAAkB,GACnB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACL,qBAAqB,EACrB,uBAAuB,GAExB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,YAAY,EAA4B,MAAM,qBAAqB,CAAC;AAC7E,OAAO,EACL,mBAAmB,EACnB,gBAAgB,EAChB,kBAAkB,EAClB,0BAA0B,GAkB3B,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,WAAW,EACX,mBAAmB,EACnB,cAAc,EACd,uBAAuB,EAuBvB,2BAA2B,GAC5B,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,kBAAkB,GAGnB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,uBAAuB,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AACvF,OAAO,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AACxD,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACpD,OAAO,EACL,wBAAwB,EACxB,wBAAwB,EACxB,0BAA0B,EAC1B,yBAAyB,EACzB,wBAAwB,GAkBzB,MAAM,qBAAqB,CAAC"}

package/dist/src/indexing/rank.d.ts

@@ -0,0 +1,2 @@
+import type { RankedTopicIndexEntry, TopicAttentionSignalMap, TopicIndexEntry, TopicPreferenceMap } from "./types.js";
+export declare function rankTopicIndex(entries: readonly TopicIndexEntry[], preferences?: TopicPreferenceMap, signals?: TopicAttentionSignalMap): RankedTopicIndexEntry[];

package/dist/src/indexing/rank.js

@@ -0,0 +1,31 @@
+import { compareText } from "../shared/compare.js";
+const REASON_RANK = {
+    pinned: 0,
+    "direct-attention": 1,
+    "followed-unread": 2,
+    participated: 3,
+    recent: 4,
+};
+function reasonFor(entry, preferences, signals) {
+    const preference = preferences[entry.topicId];
+    if (preference?.pinned)
+        return "pinned";
+    if (signals[entry.topicId]?.directAttention)
+        return "direct-attention";
+    if (preference?.notificationMode === "follow" && entry.unread === "unread")
+        return "followed-unread";
+    if (entry.participated)
+        return "participated";
+    return "recent";
+}
+function compareRanked(left, right) {
+    return REASON_RANK[left.reason] - REASON_RANK[right.reason]
+        || compareText(right.entry.latestActivityAt, left.entry.latestActivityAt)
+        || compareText(left.entry.topicId, right.entry.topicId);
+}
+export function rankTopicIndex(entries, preferences = {}, signals = {}) {
+    return entries
+        .map((entry) => ({ entry, reason: reasonFor(entry, preferences, signals) }))
+        .sort(compareRanked);
+}
+//# sourceMappingURL=rank.js.map

package/dist/src/indexing/rank.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rank.js","sourceRoot":"","sources":["../../../src/indexing/rank.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AASnD,MAAM,WAAW,GAAyC;IACxD,MAAM,EAAE,CAAC;IACT,kBAAkB,EAAE,CAAC;IACrB,iBAAiB,EAAE,CAAC;IACpB,YAAY,EAAE,CAAC;IACf,MAAM,EAAE,CAAC;CACV,CAAC;AAEF,SAAS,SAAS,CAAC,KAAsB,EAAE,WAA+B,EAAE,OAAgC;IAC1G,MAAM,UAAU,GAAG,WAAW,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IAC9C,IAAI,UAAU,EAAE,MAAM;QAAE,OAAO,QAAQ,CAAC;IACxC,IAAI,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,EAAE,eAAe;QAAE,OAAO,kBAAkB,CAAC;IACvE,IAAI,UAAU,EAAE,gBAAgB,KAAK,QAAQ,IAAI,KAAK,CAAC,MAAM,KAAK,QAAQ;QAAE,OAAO,iBAAiB,CAAC;IACrG,IAAI,KAAK,CAAC,YAAY;QAAE,OAAO,cAAc,CAAC;IAC9C,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED,SAAS,aAAa,CAAC,IAA2B,EAAE,KAA4B;IAC9E,OAAO,WAAW,CAAC,IAAI,CAAC,MAAM,CAAC,GAAG,WAAW,CAAC,KAAK,CAAC,MAAM,CAAC;WACtD,WAAW,CAAC,KAAK,CAAC,KAAK,CAAC,gBAAgB,EAAE,IAAI,CAAC,KAAK,CAAC,gBAAgB,CAAC;WACtE,WAAW,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,EAAE,KAAK,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;AAC5D,CAAC;AAED,MAAM,UAAU,cAAc,CAC5B,OAAmC,EACnC,cAAkC,EAAE,EACpC,UAAmC,EAAE;IAErC,OAAO,OAAO;SACX,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,SAAS,CAAC,KAAK,EAAE,WAAW,EAAE,OAAO,CAAC,EAAE,CAAC,CAAC;SAC3E,IAAI,CAAC,aAAa,CAAC,CAAC;AACzB,CAAC"}

package/dist/src/indexing/reconcile.d.ts

@@ -0,0 +1,3 @@
+import type { TopicIndexReconciliation, TopicIndexSnapshot } from "./types.js";
+export declare function emptyTopicIndexSnapshot(updatedAt: string): TopicIndexSnapshot;
+export declare function reconcileTopicIndex(snapshot: TopicIndexSnapshot, input: TopicIndexReconciliation): TopicIndexSnapshot;