@ixo/topic-protocol 0.1.0

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

@@ -0,0 +1,569 @@
+export declare const SCHEMA_REGISTRY: Readonly<{
+    "action-receipt": {
+        $schema: string;
+        $id: string;
+        title: string;
+        type: string;
+        required: string[];
+        properties: {
+            receiptId: {
+                type: string;
+                minLength: number;
+            };
+            topicId: {
+                type: string;
+                pattern: string;
+            };
+            action: {
+                type: string;
+                minLength: number;
+            };
+            actor: {
+                type: string;
+                minLength: number;
+            };
+            status: {
+                type: string;
+                enum: string[];
+            };
+            idempotencyKey: {
+                type: string;
+                minLength: number;
+            };
+            createdAt: {
+                type: string;
+                format: string;
+            };
+            capability: {
+                type: string;
+            };
+        };
+        additionalProperties: boolean;
+    };
+    "agent-run": {
+        $schema: string;
+        $id: string;
+        title: string;
+        type: string;
+        required: string[];
+        properties: {
+            runId: {
+                type: string;
+                minLength: number;
+            };
+            topicId: {
+                type: string;
+                pattern: string;
+            };
+            agentId: {
+                type: string;
+                minLength: number;
+            };
+            capsuleRevision: {
+                type: string;
+                minLength: number;
+            };
+            status: {
+                type: string;
+                enum: string[];
+            };
+            startedAt: {
+                type: string;
+                format: string;
+            };
+            finishedAt: {
+                type: string;
+                format: string;
+            };
+            outputs: {
+                type: string;
+                items: {
+                    type: string;
+                };
+            };
+        };
+        additionalProperties: boolean;
+    };
+    "external-session-binding": {
+        $schema: string;
+        $id: string;
+        title: string;
+        type: string;
+        required: string[];
+        properties: {
+            bindingId: {
+                type: string;
+                minLength: number;
+            };
+            topicId: {
+                type: string;
+                pattern: string;
+            };
+            provider: {
+                type: string;
+                minLength: number;
+            };
+            sessionReference: {
+                type: string;
+                minLength: number;
+            };
+            actor: {
+                type: string;
+                minLength: number;
+            };
+            createdAt: {
+                type: string;
+                format: string;
+            };
+            policy: {
+                type: string;
+                required: string[];
+                properties: {
+                    privateByDefault: {
+                        type: string;
+                    };
+                };
+                additionalProperties: boolean;
+            };
+        };
+        additionalProperties: boolean;
+    };
+    "room-policy": {
+        $schema: string;
+        $id: string;
+        title: string;
+        type: string;
+        required: string[];
+        properties: {
+            version: {
+                const: number;
+            };
+            mode: {
+                type: string;
+                enum: string[];
+            };
+            generalEnabled: {
+                type: string;
+            };
+            allowTopicsInDirectRooms: {
+                type: string;
+            };
+            authorisedRoles: {
+                type: string;
+                items: {
+                    type: string;
+                };
+            };
+        };
+        additionalProperties: boolean;
+    };
+    "topic-capsule": {
+        $schema: string;
+        $id: string;
+        title: string;
+        type: string;
+        required: string[];
+        properties: {
+            topicId: {
+                type: string;
+                pattern: string;
+            };
+            anchor: {
+                type: string;
+                required: string[];
+                properties: {
+                    roomId: {
+                        type: string;
+                    };
+                    rootEventId: {
+                        type: string;
+                        pattern: string;
+                    };
+                };
+            };
+            stateRevision: {
+                type: string;
+                minLength: number;
+            };
+            participants: {
+                type: string;
+                items: {
+                    type: string;
+                };
+            };
+            linkedContext: {
+                type: string;
+                items: {
+                    type: string;
+                };
+            };
+            acceptedMemory: {
+                type: string;
+                items: {
+                    type: string;
+                };
+            };
+            relevantEvents: {
+                type: string;
+                items: {
+                    type: string;
+                };
+            };
+            capabilities: {
+                type: string;
+                items: {
+                    type: string;
+                };
+            };
+            runtimePolicy: {
+                type: string;
+            };
+        };
+        additionalProperties: boolean;
+    };
+    "topic-index-entry": {
+        $schema: string;
+        $id: string;
+        title: string;
+        type: string;
+        required: string[];
+        properties: {
+            topicId: {
+                type: string;
+                pattern: string;
+            };
+            roomId: {
+                type: string;
+                minLength: number;
+            };
+            rootEventId: {
+                type: string;
+                pattern: string;
+            };
+            status: {
+                type: string;
+            };
+            latestActivityAt: {
+                type: string;
+                format: string;
+            };
+            notificationMode: {
+                type: string;
+                enum: string[];
+            };
+            completeness: {
+                type: string;
+                enum: string[];
+            };
+        };
+        additionalProperties: boolean;
+    };
+    "topic-message": {
+        $schema: string;
+        $id: string;
+        title: string;
+        type: string;
+        required: string[];
+        properties: {
+            topicId: {
+                type: string;
+                pattern: string;
+            };
+            roomId: {
+                type: string;
+                minLength: number;
+            };
+            rootEventId: {
+                type: string;
+                pattern: string;
+            };
+            eventId: {
+                type: string;
+                pattern: string;
+            };
+            sender: {
+                type: string;
+                minLength: number;
+            };
+            body: {
+                type: string;
+            };
+            createdAt: {
+                type: string;
+                format: string;
+            };
+            inReplyTo: {
+                type: string;
+                pattern: string;
+            };
+        };
+        additionalProperties: boolean;
+    };
+    "topic-operation": {
+        $schema: string;
+        $id: string;
+        title: string;
+        type: string;
+        required: string[];
+        properties: {
+            version: {
+                const: number;
+            };
+            operationId: {
+                type: string;
+                minLength: number;
+            };
+            topicId: {
+                type: string;
+                pattern: string;
+            };
+            type: {
+                type: string;
+                enum: string[];
+            };
+            previousRevision: {
+                type: string;
+                minLength: number;
+            };
+            actor: {
+                type: string;
+                minLength: number;
+            };
+            createdAt: {
+                type: string;
+                format: string;
+            };
+            payload: {
+                type: string;
+            };
+            capability: {
+                type: string;
+            };
+        };
+        additionalProperties: boolean;
+    };
+    "topic-preferences": {
+        $schema: string;
+        $id: string;
+        title: string;
+        type: string;
+        required: string[];
+        properties: {
+            version: {
+                const: number;
+            };
+            topics: {
+                type: string;
+                additionalProperties: {
+                    type: string;
+                    required: string[];
+                    properties: {
+                        notificationMode: {
+                            type: string;
+                            enum: string[];
+                        };
+                        pinned: {
+                            type: string;
+                        };
+                        markedUnreadFrom: {
+                            type: string[];
+                        };
+                    };
+                };
+            };
+            autoFollow: {
+                type: string;
+                enum: string[];
+            };
+        };
+        additionalProperties: boolean;
+    };
+    "topic-record": {
+        $schema: string;
+        $id: string;
+        title: string;
+        type: string;
+        required: string[];
+        properties: {
+            recordId: {
+                type: string;
+                minLength: number;
+            };
+            topicId: {
+                type: string;
+                pattern: string;
+            };
+            kind: {
+                type: string;
+                enum: string[];
+            };
+            createdBy: {
+                type: string;
+                minLength: number;
+            };
+            createdAt: {
+                type: string;
+                format: string;
+            };
+            sourceEventIds: {
+                type: string;
+                items: {
+                    type: string;
+                    pattern: string;
+                };
+            };
+            content: {
+                type: string;
+            };
+            accepted: {
+                type: string;
+            };
+        };
+        additionalProperties: boolean;
+    };
+    "topic-relation": {
+        $schema: string;
+        $id: string;
+        title: string;
+        type: string;
+        required: string[];
+        properties: {
+            relationId: {
+                type: string;
+                minLength: number;
+            };
+            fromTopicId: {
+                type: string;
+                pattern: string;
+            };
+            type: {
+                type: string;
+                enum: string[];
+            };
+            toTopicId: {
+                type: string;
+                pattern: string;
+            };
+            createdBy: {
+                type: string;
+                minLength: number;
+            };
+            createdAt: {
+                type: string;
+                format: string;
+            };
+        };
+        additionalProperties: boolean;
+    };
+    "topic-root": {
+        $schema: string;
+        $id: string;
+        title: string;
+        type: string;
+        required: string[];
+        properties: {
+            version: {
+                const: number;
+            };
+            id: {
+                type: string;
+                pattern: string;
+            };
+            title: {
+                type: string;
+                minLength: number;
+                maxLength: number;
+            };
+            kind: {
+                type: string;
+                enum: string[];
+            };
+            status: {
+                type: string;
+                enum: string[];
+            };
+            createdBy: {
+                type: string;
+                minLength: number;
+            };
+            createdAt: {
+                type: string;
+                format: string;
+            };
+            context: {
+                type: string;
+                items: {
+                    type: string;
+                    required: string[];
+                    properties: {
+                        type: {
+                            type: string;
+                        };
+                        id: {
+                            type: string;
+                        };
+                    };
+                };
+            };
+        };
+        additionalProperties: boolean;
+    };
+    "topic-state": {
+        $schema: string;
+        $id: string;
+        title: string;
+        type: string;
+        required: string[];
+        properties: {
+            topicId: {
+                type: string;
+                pattern: string;
+            };
+            revision: {
+                type: string;
+                minLength: number;
+            };
+            status: {
+                type: string;
+                enum: string[];
+            };
+            purpose: {
+                type: string;
+            };
+            acceptedFacts: {
+                type: string;
+                items: {
+                    type: string;
+                };
+            };
+            decisions: {
+                type: string;
+                items: {
+                    type: string;
+                };
+            };
+            unresolvedQuestions: {
+                type: string;
+                items: {
+                    type: string;
+                };
+            };
+            basedOnEvents: {
+                type: string;
+                items: {
+                    type: string;
+                    pattern: string;
+                };
+            };
+            conflicts: {
+                type: string;
+                items: {
+                    type: string;
+                };
+            };
+        };
+        additionalProperties: boolean;
+    };
+}>;
+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-relation" | "topic-root" | "topic-state")[];

package/dist/src/contracts/schemas.js

@@ -0,0 +1,30 @@
+import actionReceipt from "../../schemas/action-receipt.schema.json" with { type: "json" };
+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 topicIndexEntry from "../../schemas/topic-index-entry.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" };
+import topicRecord from "../../schemas/topic-record.schema.json" with { type: "json" };
+import topicRelation from "../../schemas/topic-relation.schema.json" with { type: "json" };
+import topicRoot from "../../schemas/topic-root.schema.json" with { type: "json" };
+import topicState from "../../schemas/topic-state.schema.json" with { type: "json" };
+export const SCHEMA_REGISTRY = Object.freeze({
+    "action-receipt": actionReceipt,
+    "agent-run": agentRun,
+    "external-session-binding": externalSessionBinding,
+    "room-policy": roomPolicy,
+    "topic-capsule": topicCapsule,
+    "topic-index-entry": topicIndexEntry,
+    "topic-message": topicMessage,
+    "topic-operation": topicOperation,
+    "topic-preferences": topicPreferences,
+    "topic-record": topicRecord,
+    "topic-relation": topicRelation,
+    "topic-root": topicRoot,
+    "topic-state": topicState,
+});
+export const CONTRACT_NAMES = Object.freeze(Object.keys(SCHEMA_REGISTRY).sort());
+//# sourceMappingURL=schemas.js.map

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

@@ -0,0 +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,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;AAErF,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,gBAAgB,EAAE,aAAa;IAC/B,YAAY,EAAE,SAAS;IACvB,aAAa,EAAE,UAAU;CAC1B,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/contracts/validator.d.ts

@@ -0,0 +1,14 @@
+import { type ContractName } from "./schemas.js";
+export interface ContractValidationError {
+    readonly instancePath: string;
+    readonly keyword: string;
+    readonly message: string;
+}
+export type ContractValidationResult = {
+    readonly ok: true;
+} | {
+    readonly ok: false;
+    readonly errors: readonly ContractValidationError[];
+};
+export declare function validateContract(name: ContractName, value: unknown): ContractValidationResult;
+export declare function assertContract(name: ContractName, value: unknown): void;

package/dist/src/contracts/validator.js

@@ -0,0 +1,43 @@
+import { Ajv2020, } from "ajv/dist/2020.js";
+import * as formatsModule from "ajv-formats";
+import { TopicProtocolError } from "../errors.js";
+import { SCHEMA_REGISTRY, } from "./schemas.js";
+const ajv = new Ajv2020({ allErrors: true, strict: true });
+const validators = new Map();
+const addFormats = formatsModule.default;
+addFormats(ajv);
+function isContractName(value) {
+    return Object.hasOwn(SCHEMA_REGISTRY, value);
+}
+function validatorFor(name) {
+    const existing = validators.get(name);
+    if (existing !== undefined)
+        return existing;
+    const validator = ajv.compile(SCHEMA_REGISTRY[name]);
+    validators.set(name, validator);
+    return validator;
+}
+function normaliseError(error) {
+    const path = error.instancePath.length === 0 ? "/" : error.instancePath;
+    return {
+        instancePath: path,
+        keyword: error.keyword,
+        message: `${path} ${error.message ?? "is invalid"}`,
+    };
+}
+export function validateContract(name, value) {
+    if (!isContractName(name)) {
+        throw new TopicProtocolError("UNKNOWN_CONTRACT", `Unknown Topic Protocol contract: ${String(name)}`, { name });
+    }
+    const validator = validatorFor(name);
+    if (validator(value))
+        return { ok: true };
+    return { ok: false, errors: (validator.errors ?? []).map(normaliseError) };
+}
+export function assertContract(name, value) {
+    const result = validateContract(name, value);
+    if (result.ok)
+        return;
+    throw new TopicProtocolError("CONTRACT_VALIDATION_FAILED", `${name} failed contract validation`, { contract: name, errors: result.errors });
+}
+//# sourceMappingURL=validator.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"validator.js","sourceRoot":"","sources":["../../../src/contracts/validator.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,OAAO,GAGR,MAAM,kBAAkB,CAAC;AAC1B,OAAO,KAAK,aAAa,MAAM,aAAa,CAAC;AAG7C,OAAO,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAClD,OAAO,EACL,eAAe,GAEhB,MAAM,cAAc,CAAC;AAYtB,MAAM,GAAG,GAAG,IAAI,OAAO,CAAC,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC;AAC3D,MAAM,UAAU,GAAG,IAAI,GAAG,EAAkC,CAAC;AAC7D,MAAM,UAAU,GAAG,aAAa,CAAC,OAAmC,CAAC;AACrE,UAAU,CAAC,GAAG,CAAC,CAAC;AAEhB,SAAS,cAAc,CAAC,KAAa;IACnC,OAAO,MAAM,CAAC,MAAM,CAAC,eAAe,EAAE,KAAK,CAAC,CAAC;AAC/C,CAAC;AAED,SAAS,YAAY,CAAC,IAAkB;IACtC,MAAM,QAAQ,GAAG,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IACtC,IAAI,QAAQ,KAAK,SAAS;QAAE,OAAO,QAAQ,CAAC;IAC5C,MAAM,SAAS,GAAG,GAAG,CAAC,OAAO,CAAC,eAAe,CAAC,IAAI,CAAC,CAAC,CAAC;IACrD,UAAU,CAAC,GAAG,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC;IAChC,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,SAAS,cAAc,CAAC,KAAkB;IACxC,MAAM,IAAI,GAAG,KAAK,CAAC,YAAY,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,KAAK,CAAC,YAAY,CAAC;IACxE,OAAO;QACL,YAAY,EAAE,IAAI;QAClB,OAAO,EAAE,KAAK,CAAC,OAAO;QACtB,OAAO,EAAE,GAAG,IAAI,IAAI,KAAK,CAAC,OAAO,IAAI,YAAY,EAAE;KACpD,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,gBAAgB,CAC9B,IAAkB,EAClB,KAAc;IAEd,IAAI,CAAC,cAAc,CAAC,IAAI,CAAC,EAAE,CAAC;QAC1B,MAAM,IAAI,kBAAkB,CAC1B,kBAAkB,EAClB,oCAAoC,MAAM,CAAC,IAAI,CAAC,EAAE,EAClD,EAAE,IAAI,EAAE,CACT,CAAC;IACJ,CAAC;IACD,MAAM,SAAS,GAAG,YAAY,CAAC,IAAI,CAAC,CAAC;IACrC,IAAI,SAAS,CAAC,KAAK,CAAC;QAAE,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC;IAC1C,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC,SAAS,CAAC,MAAM,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,cAAc,CAAC,EAAE,CAAC;AAC7E,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,IAAkB,EAAE,KAAc;IAC/D,MAAM,MAAM,GAAG,gBAAgB,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;IAC7C,IAAI,MAAM,CAAC,EAAE;QAAE,OAAO;IACtB,MAAM,IAAI,kBAAkB,CAC1B,4BAA4B,EAC5B,GAAG,IAAI,6BAA6B,EACpC,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,CAC1C,CAAC;AACJ,CAAC"}

package/dist/src/errors.d.ts

@@ -0,0 +1,6 @@
+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 declare class TopicProtocolError extends Error {
+    readonly code: TopicProtocolErrorCode;
+    readonly details: Readonly<Record<string, unknown>>;
+    constructor(code: TopicProtocolErrorCode, message: string, details?: Readonly<Record<string, unknown>>, options?: ErrorOptions);
+}

package/dist/src/errors.js

@@ -0,0 +1,11 @@
+export class TopicProtocolError extends Error {
+    code;
+    details;
+    constructor(code, message, details = {}, options) {
+        super(message, options);
+        this.name = "TopicProtocolError";
+        this.code = code;
+        this.details = details;
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/src/errors.js.map

@@ -0,0 +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"}