@ixo/topic-protocol 0.4.0 → 0.5.0

package/README.md

@@ -9,7 +9,7 @@ identity of a discussion.
 
 ## Status
 
-**Version:** 0.4.0
+**Version:** 0.5.0
 
 **Maturity:** Draft implementation candidate  
 **Execution source of truth:** [Linear Topic Protocol project](https://linear.app/ixo-world/project/topic-protocol-4ea58bc7910d)
@@ -22,12 +22,12 @@ and external action execution require their dedicated conformance evidence.
 ## Read this first
 
 - [Architecture decisions](docs/adr/README.md)
+- [Why Topics matter](docs/topics-feature-guide.md) — a non-technical feature guide
 - [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
@@ -39,7 +39,7 @@ key-value adapter at its integration boundary.
 
 The package includes:
 
-- strict Draft 2020-12 validation for all 17 contracts;
+- strict Draft 2020-12 validation for all 18 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;

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

@@ -0,0 +1,292 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "https://topic-protocol.ixo.world/schemas/topic-contract-state.schema.json",
+    "title": "Qi Topic Contract state profile v2",
+    "type": "object",
+    "required": ["version", "profile", "schema", "topicId", "anchor", "manifest", "contracts", "projection", "policy", "bindings", "provenance"],
+    "properties": {
+        "version": { "const": 2 },
+        "profile": { "const": "qi.topic-contract-state/v2" },
+        "schema": { "const": "https://topic-protocol.ixo.world/schemas/topic-contract-state.schema.json" },
+        "topicId": { "$ref": "#/$defs/topicId" },
+        "anchor": { "$ref": "#/$defs/anchor" },
+        "manifest": { "$ref": "#/$defs/manifest" },
+        "contracts": { "$ref": "#/$defs/contractHeads" },
+        "projection": { "$ref": "#/$defs/projection" },
+        "policy": { "type": "object" },
+        "bindings": { "$ref": "#/$defs/bindings" },
+        "provenance": { "$ref": "#/$defs/provenance" },
+        "extensions": { "type": "object" }
+    },
+    "additionalProperties": false,
+    "$defs": {
+        "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}$" },
+        "entryId": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$" },
+        "eventId": { "type": "string", "pattern": "^\\$" },
+        "roomId": { "type": "string", "pattern": "^!" },
+        "hash": { "type": "string", "pattern": "^[0-9a-f]{64}$" },
+        "persistedKind": { "type": "string", "enum": ["task", "agent_task", "proposal", "evaluation", "claims", "question", "discussion", "incident"] },
+        "kindRef": {
+            "oneOf": [
+                {
+                    "type": "object",
+                    "required": ["source", "kind"],
+                    "properties": { "source": { "const": "standard" }, "kind": { "$ref": "#/$defs/persistedKind" } },
+                    "additionalProperties": false
+                },
+                {
+                    "type": "object",
+                    "required": ["source", "customId", "label", "baseKind"],
+                    "properties": {
+                        "source": { "const": "custom" },
+                        "customId": { "type": "string", "minLength": 1, "maxLength": 128 },
+                        "label": { "type": "string", "minLength": 1, "maxLength": 80 },
+                        "baseKind": { "$ref": "#/$defs/persistedKind" }
+                    },
+                    "additionalProperties": false
+                }
+            ]
+        },
+        "anchor": {
+            "oneOf": [
+                {
+                    "type": "object",
+                    "required": ["mode", "roomId", "rootEventId", "manifestSource"],
+                    "properties": {
+                        "mode": { "const": "native" },
+                        "roomId": { "$ref": "#/$defs/roomId" },
+                        "rootEventId": { "$ref": "#/$defs/eventId" },
+                        "manifestSource": { "const": "root-event" }
+                    },
+                    "additionalProperties": false
+                },
+                {
+                    "type": "object",
+                    "required": ["mode", "roomId", "rootEventId", "manifestSource"],
+                    "properties": {
+                        "mode": { "const": "adopted" },
+                        "roomId": { "$ref": "#/$defs/roomId" },
+                        "rootEventId": { "$ref": "#/$defs/eventId" },
+                        "manifestSource": { "const": "state-event" }
+                    },
+                    "additionalProperties": false
+                }
+            ]
+        },
+        "manifest": {
+            "type": "object",
+            "required": ["version", "id", "title", "kind", "status", "createdBy", "createdAt"],
+            "properties": {
+                "version": { "const": 2 },
+                "id": { "$ref": "#/$defs/topicId" },
+                "title": { "type": "string", "minLength": 1, "maxLength": 280 },
+                "kind": { "$ref": "#/$defs/persistedKind" },
+                "status": { "type": "string", "enum": ["draft", "active", "waiting", "blocked", "resolved", "archived", "redirected"] },
+                "createdBy": { "type": "string", "minLength": 1 },
+                "createdAt": { "type": "string", "format": "date-time" }
+            },
+            "additionalProperties": true
+        },
+        "provenance": {
+            "type": "object",
+            "required": ["basis", "acceptance", "sourceEventIds"],
+            "properties": {
+                "basis": { "type": "string", "enum": ["explicit", "contextual", "inferred", "suggested", "retrieved"] },
+                "acceptance": { "type": "string", "enum": ["proposed", "accepted", "rejected", "superseded"] },
+                "sourceEventIds": { "type": "array", "uniqueItems": true, "items": { "$ref": "#/$defs/eventId" } },
+                "createdBy": { "type": "string", "minLength": 1 },
+                "createdAt": { "type": "string", "format": "date-time" }
+            },
+            "additionalProperties": false
+        },
+        "statement": {
+            "type": "object",
+            "required": ["id", "text", "provenance"],
+            "properties": {
+                "id": { "$ref": "#/$defs/entryId" },
+                "text": { "type": "string", "minLength": 1, "maxLength": 4000 },
+                "provenance": { "$ref": "#/$defs/provenance" }
+            },
+            "additionalProperties": false
+        },
+        "temporalTarget": {
+            "oneOf": [
+                {
+                    "type": "object",
+                    "required": ["precision", "value", "timezone"],
+                    "properties": {
+                        "precision": { "const": "date" },
+                        "value": { "type": "string", "format": "date" },
+                        "timezone": { "type": "string", "minLength": 1, "maxLength": 128 }
+                    },
+                    "additionalProperties": false
+                },
+                {
+                    "type": "object",
+                    "required": ["precision", "value", "timezone"],
+                    "properties": {
+                        "precision": { "const": "datetime" },
+                        "value": { "type": "string", "format": "date-time" },
+                        "timezone": { "type": "string", "minLength": 1, "maxLength": 128 }
+                    },
+                    "additionalProperties": false
+                }
+            ]
+        },
+        "criterion": {
+            "type": "object",
+            "required": ["id", "description", "status"],
+            "properties": {
+                "id": { "$ref": "#/$defs/entryId" },
+                "description": { "type": "string", "minLength": 1, "maxLength": 2000 },
+                "status": { "type": "string", "enum": ["pending", "met", "not_met", "waived"] },
+                "verification": { "type": "object" }
+            },
+            "additionalProperties": false
+        },
+        "outcome": {
+            "type": "object",
+            "properties": {
+                "statement": { "$ref": "#/$defs/statement" },
+                "status": { "type": "string", "enum": ["proposed", "accepted", "achieved", "abandoned"] },
+                "target": { "$ref": "#/$defs/temporalTarget" },
+                "successCriteria": { "type": "array", "maxItems": 50, "items": { "$ref": "#/$defs/criterion" } },
+                "outcomeRecordId": { "type": "string", "minLength": 1 },
+                "abandonedReason": { "type": "string", "minLength": 1, "maxLength": 2000 }
+            },
+            "additionalProperties": false
+        },
+        "risk": {
+            "type": "object",
+            "required": ["id", "description", "status"],
+            "properties": {
+                "id": { "$ref": "#/$defs/entryId" },
+                "description": { "type": "string", "minLength": 1, "maxLength": 2000 },
+                "impact": { "type": "string", "enum": ["low", "medium", "high", "critical"] },
+                "status": { "type": "string", "enum": ["open", "mitigated", "accepted", "closed"] },
+                "owner": { "type": "string", "minLength": 1 },
+                "mitigation": { "type": "string", "minLength": 1, "maxLength": 2000 }
+            },
+            "additionalProperties": false
+        },
+        "appearance": {
+            "type": "object",
+            "properties": {
+                "glyph": {
+                    "oneOf": [
+                        { "type": "object", "required": ["type", "value"], "properties": { "type": { "const": "emoji" }, "value": { "type": "string", "minLength": 1, "maxLength": 16 } }, "additionalProperties": false },
+                        { "type": "object", "required": ["type", "name"], "properties": { "type": { "const": "icon" }, "name": { "type": "string", "enum": ["task", "agent", "proposal", "evaluation", "claims", "question", "discussion", "incident"] } }, "additionalProperties": false }
+                    ]
+                }
+            },
+            "additionalProperties": false
+        },
+        "contractBody": {
+            "type": "object",
+            "required": ["version", "revision", "status", "kindRef", "authoredBy", "authoredAt", "workingMode", "recipe"],
+            "properties": {
+                "version": { "const": 2 },
+                "revision": { "type": "string", "minLength": 1 },
+                "status": { "type": "string", "enum": ["draft", "accepted", "superseded"] },
+                "kindRef": { "$ref": "#/$defs/kindRef" },
+                "authoredBy": { "type": "string", "minLength": 1 },
+                "authoredAt": { "type": "string", "format": "date-time" },
+                "workingMode": { "type": "string", "enum": ["solo", "team", "client"] },
+                "recipe": { "type": "string", "enum": ["project", "flow", "proposal", "evaluation", "claims", "research", "discussion", "incident"] },
+                "locale": { "type": "string", "minLength": 2, "maxLength": 32 },
+                "timezone": { "type": "string", "minLength": 1, "maxLength": 128 },
+                "temporalMode": { "type": "string", "enum": ["finite", "ongoing"] },
+                "tags": { "type": "array", "uniqueItems": true, "maxItems": 20, "items": { "type": "string", "minLength": 1, "maxLength": 80 } },
+                "appearance": { "$ref": "#/$defs/appearance" },
+                "intent": { "$ref": "#/$defs/statement" },
+                "outcome": { "$ref": "#/$defs/outcome" },
+                "completion": { "type": "object" },
+                "ownerId": { "type": "string", "minLength": 1 },
+                "scope": { "type": "object" },
+                "constraints": { "type": "array", "maxItems": 50, "items": { "$ref": "#/$defs/statement" } },
+                "assumptions": { "type": "array", "maxItems": 50, "items": { "type": "object" } },
+                "questions": { "type": "array", "maxItems": 50, "items": { "type": "object" } },
+                "risks": { "type": "array", "maxItems": 50, "items": { "$ref": "#/$defs/risk" } },
+                "participants": { "type": "array", "maxItems": 100, "items": { "type": "object" } },
+                "roles": { "type": "array", "maxItems": 50, "items": { "type": "object" } },
+                "agents": { "type": "array", "maxItems": 20, "items": { "type": "object" } },
+                "decision": { "type": "object" },
+                "plan": { "type": "object" },
+                "attachments": { "type": "array", "maxItems": 100, "items": { "type": "object" } }
+            },
+            "additionalProperties": true
+        },
+        "contractRef": {
+            "type": "object",
+            "required": ["revision", "bodyHash", "bodyRef"],
+            "properties": {
+                "revision": { "type": "string", "minLength": 1 },
+                "bodyHash": { "$ref": "#/$defs/hash" },
+                "bodyRef": { "type": "object" },
+                "body": { "$ref": "#/$defs/contractBody" }
+            },
+            "additionalProperties": true
+        },
+        "effectiveContractRef": {
+            "allOf": [
+                { "$ref": "#/$defs/contractRef" },
+                {
+                    "type": "object",
+                    "required": ["acceptedBy", "acceptedAt"],
+                    "properties": {
+                        "acceptedBy": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "minLength": 1 } },
+                        "acceptedAt": { "type": "string", "format": "date-time" }
+                    }
+                }
+            ]
+        },
+        "contractHeads": {
+            "type": "object",
+            "properties": { "proposed": { "$ref": "#/$defs/contractRef" }, "effective": { "$ref": "#/$defs/effectiveContractRef" } },
+            "additionalProperties": false
+        },
+        "projection": {
+            "type": "object",
+            "required": ["revision", "title", "status", "kindRef", "attachmentCount", "operationCount"],
+            "properties": {
+                "revision": { "type": "string", "minLength": 1 },
+                "title": { "type": "string", "minLength": 1, "maxLength": 280 },
+                "status": { "type": "string", "enum": ["draft", "active", "waiting", "blocked", "resolved", "archived", "redirected"] },
+                "kindRef": { "$ref": "#/$defs/kindRef" },
+                "appearance": { "$ref": "#/$defs/appearance" },
+                "attachmentCount": { "type": "integer", "minimum": 0 },
+                "operationCount": { "type": "integer", "minimum": 0 }
+            },
+            "additionalProperties": true
+        },
+        "recurrence": {
+            "oneOf": [
+                { "type": "object", "required": ["frequency", "time", "timezone"], "properties": { "frequency": { "const": "daily" }, "time": { "type": "string", "pattern": "^(?:[01]\\d|2[0-3]):[0-5]\\d$" }, "timezone": { "type": "string", "minLength": 1 } }, "additionalProperties": false },
+                { "type": "object", "required": ["frequency", "days", "time", "timezone"], "properties": { "frequency": { "const": "weekly" }, "days": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "enum": ["monday", "tuesday", "wednesday", "thursday", "friday", "saturday", "sunday"] } }, "time": { "type": "string", "pattern": "^(?:[01]\\d|2[0-3]):[0-5]\\d$" }, "timezone": { "type": "string", "minLength": 1 } }, "additionalProperties": false }
+            ]
+        },
+        "automation": {
+            "type": "object",
+            "required": ["provider", "scheduleId", "actionId", "recurrence", "status"],
+            "properties": {
+                "provider": { "const": "temporal" },
+                "scheduleId": { "type": "string", "minLength": 1 },
+                "actionId": { "type": "string", "minLength": 1 },
+                "recurrence": { "$ref": "#/$defs/recurrence" },
+                "status": { "type": "string", "enum": ["pending", "active", "paused", "failed"] },
+                "nextRunAt": { "type": "string", "format": "date-time" }
+            },
+            "additionalProperties": false
+        },
+        "bindings": {
+            "type": "object",
+            "properties": {
+                "governanceProposal": { "type": "object" },
+                "claims": { "type": "object" },
+                "automations": { "type": "array", "maxItems": 20, "items": { "$ref": "#/$defs/automation" } },
+                "context": { "type": "array", "maxItems": 100, "items": { "type": "object" } }
+            },
+            "additionalProperties": false
+        }
+    }
+}

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

@@ -6,7 +6,7 @@
     "required": ["provider", "resource", "fileId", "version", "cid", "contentHash", "path", "name", "mimeType", "size"],
     "properties": {
         "provider": { "const": "ixo.vfs" },
-        "resource": { "type": "string", "pattern": "^ixo:filesystem/.+" },
+        "resource": { "type": "string", "pattern": "^ixo:filesystem(?:/.+)?$" },
         "fileId": { "type": "string", "minLength": 1 },
         "version": { "type": "integer", "minimum": 1 },
         "cid": { "type": "string", "minLength": 1 },

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

@@ -11,7 +11,7 @@
         "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"] },
+        "kind": { "type": "string", "enum": ["discussion", "question", "decision", "proposal", "task", "incident", "flow", "agent_task", "evaluation", "claims"] },
         "domain": {
             "type": "object",
             "required": ["id"],

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

@@ -5,15 +5,26 @@
     "type": "object",
     "required": ["version", "operationId", "topicId", "type", "previousRevision", "actor", "createdAt", "payload"],
     "properties": {
-        "version": { "const": 1 },
+        "version": { "enum": [1, 2] },
         "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", "attach-files", "detach-files", "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", "propose-contract", "update-contract", "accept-contract", "supersede-contract", "bind-automation", "update-automation", "pause-automation", "remove-automation", "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
+    "additionalProperties": true,
+    "allOf": [
+        {
+            "if": {
+                "properties": {
+                    "type": { "enum": ["propose-contract", "update-contract", "accept-contract", "supersede-contract", "bind-automation", "update-automation", "pause-automation", "remove-automation"] }
+                },
+                "required": ["type"]
+            },
+            "then": { "properties": { "version": { "const": 2 } } }
+        }
+    ]
 }

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

@@ -5,8 +5,53 @@
     "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"] } } } },
+        "version": { "enum": [1, 2] },
+        "topics": {
+            "type": "object",
+            "additionalProperties": {
+                "type": "object",
+                "required": ["notificationMode", "pinned"],
+                "properties": {
+                    "notificationMode": { "type": "string", "enum": ["follow", "default", "mute"] },
+                    "pinned": { "type": "boolean" },
+                    "markedUnreadFrom": { "type": ["string", "null"] },
+                    "companion": {
+                        "type": "object",
+                        "required": ["oracleDid", "sessionId"],
+                        "properties": {
+                            "oracleDid": { "type": "string", "minLength": 1 },
+                            "sessionId": { "type": "string", "minLength": 1 },
+                            "lastContextRevision": { "type": "string", "minLength": 1 }
+                        },
+                        "additionalProperties": false
+                    },
+                    "reminder": {
+                        "oneOf": [
+                            {
+                                "type": "object",
+                                "required": ["mode", "at", "timezone"],
+                                "properties": {
+                                    "mode": { "const": "at" },
+                                    "at": { "type": "string", "format": "date-time" },
+                                    "timezone": { "type": "string", "minLength": 1 }
+                                },
+                                "additionalProperties": false
+                            },
+                            {
+                                "type": "object",
+                                "required": ["mode", "minutes"],
+                                "properties": {
+                                    "mode": { "const": "before_due" },
+                                    "minutes": { "type": "integer", "minimum": 0 }
+                                },
+                                "additionalProperties": false
+                            }
+                        ]
+                    }
+                },
+                "additionalProperties": false
+            }
+        },
         "autoFollow": { "type": "string", "enum": ["none", "started", "started_or_participated"] }
     },
     "additionalProperties": false

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

@@ -5,10 +5,10 @@
     "type": "object",
     "required": ["version", "id", "title", "status", "createdBy", "createdAt"],
     "properties": {
-        "version": { "const": 1 },
+        "version": { "enum": [1, 2] },
         "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"] },
+        "kind": { "type": "string", "enum": ["discussion", "question", "decision", "proposal", "task", "incident", "flow", "agent_task", "evaluation", "claims"] },
         "status": { "type": "string", "enum": ["draft", "active", "waiting", "blocked", "resolved", "archived", "redirected"] },
         "createdBy": { "type": "string", "minLength": 1 },
         "createdAt": { "type": "string", "format": "date-time" },
@@ -44,5 +44,11 @@
             "additionalProperties": false
         }
     },
-    "additionalProperties": true
+    "additionalProperties": true,
+    "allOf": [
+        {
+            "if": { "properties": { "version": { "const": 2 } }, "required": ["version"] },
+            "then": { "properties": { "kind": true }, "required": ["kind"] }
+        }
+    ]
 }