@ixo/topic-protocol 0.1.0

package/dist/src/index.d.ts

@@ -0,0 +1,11 @@
+export { CONTRACT_NAMES, type ContractName, } from "./contracts/schemas.js";
+export { assertContract, validateContract, type ContractValidationError, type ContractValidationResult, } from "./contracts/validator.js";
+export { TopicProtocolError, type TopicProtocolErrorCode, } from "./errors.js";
+export { projectTopic } from "./projector/project.js";
+export { selectCanonicalTopicAnchor } from "./matrix/anchors.js";
+export { assertMatrixAnchor, assertMatrixRoomId, assertServerEventId, assertTopicMessageContent, buildTopicMessageContent, buildTopicOperationContent, buildTopicRootContent, createTopicId, } from "./matrix/content.js";
+export { isTopicInfrastructureEvent, parseTopicRootEvent, projectMatrixTopic, } from "./matrix/events.js";
+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 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 TopicOperation, type TopicOperationType, type TopicProjection, type TopicProjectionConflict, type TopicRelationType, type TopicRoot, type TopicStatus, } from "./projector/types.js";

package/dist/src/index.js

@@ -0,0 +1,12 @@
+export { CONTRACT_NAMES, } from "./contracts/schemas.js";
+export { assertContract, validateContract, } from "./contracts/validator.js";
+export { TopicProtocolError, } from "./errors.js";
+export { projectTopic } from "./projector/project.js";
+export { selectCanonicalTopicAnchor } from "./matrix/anchors.js";
+export { assertMatrixAnchor, assertMatrixRoomId, assertServerEventId, assertTopicMessageContent, buildTopicMessageContent, buildTopicOperationContent, buildTopicRootContent, createTopicId, } from "./matrix/content.js";
+export { isTopicInfrastructureEvent, parseTopicRootEvent, projectMatrixTopic, } from "./matrix/events.js";
+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";
+//# sourceMappingURL=index.js.map

package/dist/src/index.js.map

@@ -0,0 +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,GACd,MAAM,qBAAqB,CAAC;AAC7B,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,GAiB3B,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,WAAW,EACX,cAAc,GAgBf,MAAM,sBAAsB,CAAC"}

package/dist/src/matrix/anchors.d.ts

@@ -0,0 +1,2 @@
+import type { CanonicalTopicAnchor, TopicMatrixEvent } from "./types.js";
+export declare function selectCanonicalTopicAnchor(events: readonly TopicMatrixEvent[], topicId: string): CanonicalTopicAnchor;

package/dist/src/matrix/anchors.js

@@ -0,0 +1,55 @@
+import { TopicProtocolError } from "../errors.js";
+import { compareText } from "../shared/compare.js";
+import { parseTopicRootEvent } from "./events.js";
+function anchorKey(root) {
+    return `${root.anchor.roomId}\u0000${root.anchor.rootEventId}`;
+}
+function previousKey(root) {
+    return root.replaces === undefined
+        ? undefined
+        : `${root.replaces.roomId}\u0000${root.replaces.rootEventId}`;
+}
+function compareRoots(left, right) {
+    return compareText(left.anchor.rootEventId, right.anchor.rootEventId)
+        || compareText(left.anchor.roomId, right.anchor.roomId);
+}
+function conflictFor(previous, contenders) {
+    const [canonical, ...competing] = contenders;
+    if (canonical === undefined || competing.length === 0)
+        return undefined;
+    return {
+        previous: previous.anchor,
+        canonical: canonical.anchor,
+        competing: competing.map(({ anchor }) => anchor),
+    };
+}
+export function selectCanonicalTopicAnchor(events, topicId) {
+    const roots = events
+        .map(parseTopicRootEvent)
+        .filter((root) => root?.root.id === topicId);
+    const initial = roots.filter((root) => root.replaces === undefined).sort(compareRoots);
+    if (initial.length === 0) {
+        throw new TopicProtocolError("TOPIC_ROOT_NOT_FOUND", "No initial Topic root was found", { topicId });
+    }
+    if (initial.length > 1) {
+        throw new TopicProtocolError("ANCHOR_CONFLICT", "Multiple initial Topic roots were found", { topicId });
+    }
+    let current = initial[0];
+    const conflicts = [];
+    const visited = new Set([anchorKey(current)]);
+    let contenders = roots.filter((root) => previousKey(root) === anchorKey(current)).sort(compareRoots);
+    while (contenders.length > 0) {
+        const conflict = conflictFor(current, contenders);
+        if (conflict !== undefined)
+            conflicts.push(conflict);
+        const next = contenders[0];
+        if (visited.has(anchorKey(next))) {
+            throw new TopicProtocolError("ANCHOR_CYCLE", "Topic anchor replacement contains a cycle", { topicId });
+        }
+        current = next;
+        visited.add(anchorKey(current));
+        contenders = roots.filter((root) => previousKey(root) === anchorKey(current)).sort(compareRoots);
+    }
+    return { anchor: current.anchor, root: current.root, conflicts };
+}
+//# sourceMappingURL=anchors.js.map

package/dist/src/matrix/anchors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"anchors.js","sourceRoot":"","sources":["../../../src/matrix/anchors.ts"],"names":[],"mappings":"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"}

package/dist/src/matrix/content.d.ts

@@ -0,0 +1,11 @@
+import type { MatrixAnchor, TopicOperation, TopicRoot } from "../projector/types.js";
+import { MATRIX_ROOM_MESSAGE, TOPIC_OPERATION_EVENT_TYPE, type MatrixEventContent, type TopicRootContentOptions } from "./types.js";
+export declare function createTopicId(): string;
+export declare function assertServerEventId(eventId: string): void;
+export declare function assertMatrixRoomId(roomId: string): void;
+export declare function assertMatrixAnchor(anchor: MatrixAnchor): void;
+export declare function assertTopicMessageContent(message: MatrixEventContent): void;
+export declare function buildTopicRootContent(root: TopicRoot, options?: TopicRootContentOptions): MatrixEventContent;
+export declare function buildTopicMessageContent(anchor: MatrixAnchor, message: MatrixEventContent): MatrixEventContent;
+export declare function buildTopicOperationContent(anchor: MatrixAnchor, operation: TopicOperation): MatrixEventContent;
+export { MATRIX_ROOM_MESSAGE, TOPIC_OPERATION_EVENT_TYPE };

package/dist/src/matrix/content.js

@@ -0,0 +1,64 @@
+import { v7 as uuidv7 } from "uuid";
+import { assertContract } from "../contracts/validator.js";
+import { TopicProtocolError } from "../errors.js";
+import { MATRIX_ROOM_MESSAGE, TOPIC_ANCHOR_KEY, TOPIC_METADATA_KEY, TOPIC_OPERATION_EVENT_TYPE, } from "./types.js";
+export function createTopicId() {
+    return `ixo:topic:${uuidv7()}`;
+}
+export function assertServerEventId(eventId) {
+    if (eventId.startsWith("$") && eventId.length > 1)
+        return;
+    throw new TopicProtocolError("INVALID_SERVER_EVENT_ID", "Topic anchors require a server-assigned Matrix event ID", { eventId });
+}
+export function assertMatrixRoomId(roomId) {
+    if (roomId.startsWith("!") && roomId.length > 1)
+        return;
+    throw new TopicProtocolError("INVALID_ANCHOR", "Topic anchors require a Matrix room ID", { roomId });
+}
+export function assertMatrixAnchor(anchor) {
+    assertMatrixRoomId(anchor.roomId);
+    assertServerEventId(anchor.rootEventId);
+}
+export function assertTopicMessageContent(message) {
+    if (typeof message.msgtype === "string" && typeof message.body === "string")
+        return;
+    throw new TopicProtocolError("INVALID_MATRIX_EVENT", "Topic messages require Matrix msgtype and body fields");
+}
+export function buildTopicRootContent(root, options = {}) {
+    assertContract("topic-root", root);
+    if (options.replaces !== undefined)
+        assertMatrixAnchor(options.replaces);
+    return {
+        msgtype: "m.notice",
+        body: `Topic: ${root.title}`,
+        [TOPIC_METADATA_KEY]: root,
+        ...(options.replaces === undefined
+            ? {}
+            : { [TOPIC_ANCHOR_KEY]: { replaces: options.replaces } }),
+    };
+}
+export function buildTopicMessageContent(anchor, message) {
+    assertMatrixAnchor(anchor);
+    assertTopicMessageContent(message);
+    return {
+        ...message,
+        "m.relates_to": {
+            rel_type: "m.thread",
+            event_id: anchor.rootEventId,
+            is_falling_back: true,
+        },
+    };
+}
+export function buildTopicOperationContent(anchor, operation) {
+    assertMatrixAnchor(anchor);
+    assertContract("topic-operation", operation);
+    return {
+        operation,
+        "m.relates_to": {
+            rel_type: "m.reference",
+            event_id: anchor.rootEventId,
+        },
+    };
+}
+export { MATRIX_ROOM_MESSAGE, TOPIC_OPERATION_EVENT_TYPE };
+//# sourceMappingURL=content.js.map

package/dist/src/matrix/content.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"content.js","sourceRoot":"","sources":["../../../src/matrix/content.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,EAAE,IAAI,MAAM,EAAE,MAAM,MAAM,CAAC;AAEpC,OAAO,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAC3D,OAAO,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAElD,OAAO,EACL,mBAAmB,EACnB,gBAAgB,EAChB,kBAAkB,EAClB,0BAA0B,GAG3B,MAAM,YAAY,CAAC;AAEpB,MAAM,UAAU,aAAa;IAC3B,OAAO,aAAa,MAAM,EAAE,EAAE,CAAC;AACjC,CAAC;AAED,MAAM,UAAU,mBAAmB,CAAC,OAAe;IACjD,IAAI,OAAO,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO;IAC1D,MAAM,IAAI,kBAAkB,CAC1B,yBAAyB,EACzB,yDAAyD,EACzD,EAAE,OAAO,EAAE,CACZ,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,kBAAkB,CAAC,MAAc;IAC/C,IAAI,MAAM,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO;IACxD,MAAM,IAAI,kBAAkB,CAAC,gBAAgB,EAAE,wCAAwC,EAAE,EAAE,MAAM,EAAE,CAAC,CAAC;AACvG,CAAC;AAED,MAAM,UAAU,kBAAkB,CAAC,MAAoB;IACrD,kBAAkB,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IAClC,mBAAmB,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC;AAC1C,CAAC;AAED,MAAM,UAAU,yBAAyB,CAAC,OAA2B;IACnE,IAAI,OAAO,OAAO,CAAC,OAAO,KAAK,QAAQ,IAAI,OAAO,OAAO,CAAC,IAAI,KAAK,QAAQ;QAAE,OAAO;IACpF,MAAM,IAAI,kBAAkB,CAC1B,sBAAsB,EACtB,uDAAuD,CACxD,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,qBAAqB,CACnC,IAAe,EACf,UAAmC,EAAE;IAErC,cAAc,CAAC,YAAY,EAAE,IAAI,CAAC,CAAC;IACnC,IAAI,OAAO,CAAC,QAAQ,KAAK,SAAS;QAAE,kBAAkB,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;IACzE,OAAO;QACL,OAAO,EAAE,UAAU;QACnB,IAAI,EAAE,UAAU,IAAI,CAAC,KAAK,EAAE;QAC5B,CAAC,kBAAkB,CAAC,EAAE,IAAI;QAC1B,GAAG,CAAC,OAAO,CAAC,QAAQ,KAAK,SAAS;YAChC,CAAC,CAAC,EAAE;YACJ,CAAC,CAAC,EAAE,CAAC,gBAAgB,CAAC,EAAE,EAAE,QAAQ,EAAE,OAAO,CAAC,QAAQ,EAAE,EAAE,CAAC;KAC5D,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,wBAAwB,CACtC,MAAoB,EACpB,OAA2B;IAE3B,kBAAkB,CAAC,MAAM,CAAC,CAAC;IAC3B,yBAAyB,CAAC,OAAO,CAAC,CAAC;IACnC,OAAO;QACL,GAAG,OAAO;QACV,cAAc,EAAE;YACd,QAAQ,EAAE,UAAU;YACpB,QAAQ,EAAE,MAAM,CAAC,WAAW;YAC5B,eAAe,EAAE,IAAI;SACtB;KACF,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,0BAA0B,CACxC,MAAoB,EACpB,SAAyB;IAEzB,kBAAkB,CAAC,MAAM,CAAC,CAAC;IAC3B,cAAc,CAAC,iBAAiB,EAAE,SAAS,CAAC,CAAC;IAC7C,OAAO;QACL,SAAS;QACT,cAAc,EAAE;YACd,QAAQ,EAAE,aAAa;YACvB,QAAQ,EAAE,MAAM,CAAC,WAAW;SAC7B;KACF,CAAC;AACJ,CAAC;AAED,OAAO,EAAE,mBAAmB,EAAE,0BAA0B,EAAE,CAAC"}

package/dist/src/matrix/events.d.ts

@@ -0,0 +1,4 @@
+import { type MatrixTopicProjection, type MatrixTopicProjectionInput, type ParsedTopicRoot, type TopicMatrixEvent } from "./types.js";
+export declare function parseTopicRootEvent(event: TopicMatrixEvent): ParsedTopicRoot | null;
+export declare function isTopicInfrastructureEvent(event: TopicMatrixEvent): boolean;
+export declare function projectMatrixTopic(input: MatrixTopicProjectionInput): MatrixTopicProjection;

package/dist/src/matrix/events.js

@@ -0,0 +1,94 @@
+import { validateContract } from "../contracts/validator.js";
+import { TopicProtocolError } from "../errors.js";
+import { projectTopic } from "../projector/project.js";
+import { MATRIX_ROOM_MESSAGE, TOPIC_ANCHOR_KEY, TOPIC_METADATA_KEY, TOPIC_OPERATION_EVENT_TYPE, } from "./types.js";
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function parseAnchor(value) {
+    if (!isRecord(value) || !isRecord(value.replaces))
+        return undefined;
+    const roomId = value.replaces.roomId;
+    const rootEventId = value.replaces.rootEventId;
+    if (typeof roomId !== "string" || !roomId.startsWith("!"))
+        return undefined;
+    if (typeof rootEventId !== "string" || !rootEventId.startsWith("$"))
+        return undefined;
+    return { roomId, rootEventId };
+}
+function hasServerAnchor(event) {
+    return event.roomId.startsWith("!") && event.roomId.length > 1
+        && event.eventId.startsWith("$") && event.eventId.length > 1;
+}
+export function parseTopicRootEvent(event) {
+    if (event.type !== MATRIX_ROOM_MESSAGE || event.redacted === true)
+        return null;
+    if (!hasServerAnchor(event))
+        return null;
+    if (event.content["m.relates_to"] !== undefined)
+        return null;
+    const root = event.content[TOPIC_METADATA_KEY];
+    if (!validateContract("topic-root", root).ok)
+        return null;
+    const anchorMetadata = event.content[TOPIC_ANCHOR_KEY];
+    const replaces = parseAnchor(anchorMetadata);
+    if (anchorMetadata !== undefined && replaces === undefined)
+        return null;
+    const parsed = {
+        event,
+        root: root,
+        anchor: { roomId: event.roomId, rootEventId: event.eventId },
+    };
+    return replaces === undefined ? parsed : { ...parsed, replaces };
+}
+export function isTopicInfrastructureEvent(event) {
+    if (event.type === TOPIC_OPERATION_EVENT_TYPE)
+        return true;
+    return parseTopicRootEvent(event) !== null;
+}
+function rejected(eventId, reason) {
+    return { rejection: { eventId, reason } };
+}
+function relationRoot(content) {
+    const relation = content["m.relates_to"];
+    if (!isRecord(relation) || relation.rel_type !== "m.reference")
+        return undefined;
+    return typeof relation.event_id === "string" ? relation.event_id : undefined;
+}
+function parseOperationEvent(event, rootEventId, authenticateActor) {
+    if (event.redacted === true)
+        return rejected(event.eventId, "redacted");
+    if (event.type !== TOPIC_OPERATION_EVENT_TYPE)
+        return rejected(event.eventId, "invalid-content");
+    const relation = relationRoot(event.content);
+    if (relation === undefined)
+        return rejected(event.eventId, "invalid-relation");
+    if (relation !== rootEventId)
+        return rejected(event.eventId, "wrong-root");
+    const operation = event.content.operation;
+    if (!validateContract("topic-operation", operation).ok)
+        return rejected(event.eventId, "invalid-content");
+    const typed = operation;
+    if (typed.operationId !== event.eventId)
+        return rejected(event.eventId, "invalid-content");
+    if (!authenticateActor(typed, event))
+        return rejected(event.eventId, "actor-mismatch");
+    return { operation: typed };
+}
+export function projectMatrixTopic(input) {
+    const parsedRoot = parseTopicRootEvent(input.rootEvent);
+    if (parsedRoot === null) {
+        throw new TopicProtocolError("INVALID_MATRIX_EVENT", "Topic projection requires a valid relation-free root event");
+    }
+    const parsed = input.operationEvents.map((event) => parseOperationEvent(event, input.rootEvent.eventId, input.authenticateActor));
+    const operations = parsed.flatMap(({ operation }) => operation === undefined ? [] : [operation]);
+    const rejectedEvents = parsed.flatMap(({ rejection }) => rejection === undefined ? [] : [rejection]);
+    const projection = projectTopic({
+        root: parsedRoot.root,
+        anchor: parsedRoot.anchor,
+        operations,
+        authorize: input.authorize,
+    });
+    return { projection, rejectedEvents };
+}
+//# sourceMappingURL=events.js.map

package/dist/src/matrix/events.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.js","sourceRoot":"","sources":["../../../src/matrix/events.ts"],"names":[],"mappings":"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"}

package/dist/src/matrix/pending.d.ts

@@ -0,0 +1,22 @@
+import type { PendingTopicCreation, PendingTopicStore } from "./types.js";
+type Awaitable<T> = T | Promise<T>;
+export interface TopicKeyValueStore {
+    getItem(key: string): Awaitable<string | null>;
+    setItem(key: string, value: string): Awaitable<void>;
+    removeItem(key: string): Awaitable<void>;
+}
+export declare class MemoryPendingTopicStore implements PendingTopicStore {
+    #private;
+    get(roomId: string, topicId: string): Promise<PendingTopicCreation | null>;
+    save(pending: PendingTopicCreation): Promise<void>;
+    remove(roomId: string, topicId: string): Promise<void>;
+}
+export declare class JsonPendingTopicStore implements PendingTopicStore {
+    private readonly storage;
+    constructor(storage: TopicKeyValueStore);
+    get(roomId: string, topicId: string): Promise<PendingTopicCreation | null>;
+    save(pending: PendingTopicCreation): Promise<void>;
+    remove(roomId: string, topicId: string): Promise<void>;
+    private read;
+}
+export {};

package/dist/src/matrix/pending.js

@@ -0,0 +1,83 @@
+import { TopicProtocolError } from "../errors.js";
+const STORAGE_KEY = "ixo.topic.pending.v1";
+function pendingKey(roomId, topicId) {
+    return `${roomId}\u0000${topicId}`;
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isPending(value) {
+    if (!isRecord(value))
+        return false;
+    return typeof value.roomId === "string"
+        && value.roomId.startsWith("!")
+        && typeof value.topicId === "string"
+        && value.topicId.startsWith("ixo:topic:")
+        && (value.rootEventId === null
+            || (typeof value.rootEventId === "string" && value.rootEventId.startsWith("$")))
+        && typeof value.createdAt === "string";
+}
+function parsePendingValues(value) {
+    if (!isRecord(value))
+        return null;
+    const parsed = {};
+    for (const [key, pending] of Object.entries(value)) {
+        if (!isPending(pending))
+            return null;
+        parsed[key] = pending;
+    }
+    return parsed;
+}
+export class MemoryPendingTopicStore {
+    #pending = new Map();
+    get(roomId, topicId) {
+        return Promise.resolve(this.#pending.get(pendingKey(roomId, topicId)) ?? null);
+    }
+    save(pending) {
+        this.#pending.set(pendingKey(pending.roomId, pending.topicId), pending);
+        return Promise.resolve();
+    }
+    remove(roomId, topicId) {
+        this.#pending.delete(pendingKey(roomId, topicId));
+        return Promise.resolve();
+    }
+}
+export class JsonPendingTopicStore {
+    storage;
+    constructor(storage) {
+        this.storage = storage;
+    }
+    async get(roomId, topicId) {
+        const values = await this.read();
+        return values[pendingKey(roomId, topicId)] ?? null;
+    }
+    async save(pending) {
+        const values = await this.read();
+        values[pendingKey(pending.roomId, pending.topicId)] = pending;
+        await this.storage.setItem(STORAGE_KEY, JSON.stringify(values));
+    }
+    async remove(roomId, topicId) {
+        const values = await this.read();
+        delete values[pendingKey(roomId, topicId)];
+        if (Object.keys(values).length === 0)
+            await this.storage.removeItem(STORAGE_KEY);
+        else
+            await this.storage.setItem(STORAGE_KEY, JSON.stringify(values));
+    }
+    async read() {
+        const raw = await this.storage.getItem(STORAGE_KEY);
+        if (raw === null)
+            return {};
+        try {
+            const value = JSON.parse(raw);
+            const parsed = parsePendingValues(value);
+            if (parsed !== null)
+                return parsed;
+        }
+        catch (cause) {
+            throw new TopicProtocolError("STORAGE_FAILED", "Pending Topic storage is corrupt", {}, { cause });
+        }
+        throw new TopicProtocolError("STORAGE_FAILED", "Pending Topic storage must contain an object");
+    }
+}
+//# sourceMappingURL=pending.js.map

package/dist/src/matrix/pending.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pending.js","sourceRoot":"","sources":["../../../src/matrix/pending.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAMlD,MAAM,WAAW,GAAG,sBAAsB,CAAC;AAS3C,SAAS,UAAU,CAAC,MAAc,EAAE,OAAe;IACjD,OAAO,GAAG,MAAM,SAAS,OAAO,EAAE,CAAC;AACrC,CAAC;AAED,SAAS,QAAQ,CAAC,KAAc;IAC9B,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;AAC9E,CAAC;AAED,SAAS,SAAS,CAAC,KAAc;IAC/B,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IACnC,OAAO,OAAO,KAAK,CAAC,MAAM,KAAK,QAAQ;WAClC,KAAK,CAAC,MAAM,CAAC,UAAU,CAAC,GAAG,CAAC;WAC5B,OAAO,KAAK,CAAC,OAAO,KAAK,QAAQ;WACjC,KAAK,CAAC,OAAO,CAAC,UAAU,CAAC,YAAY,CAAC;WACtC,CAAC,KAAK,CAAC,WAAW,KAAK,IAAI;eACzB,CAAC,OAAO,KAAK,CAAC,WAAW,KAAK,QAAQ,IAAI,KAAK,CAAC,WAAW,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC;WAC/E,OAAO,KAAK,CAAC,SAAS,KAAK,QAAQ,CAAC;AAC3C,CAAC;AAED,SAAS,kBAAkB,CAAC,KAAc;IACxC,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IAClC,MAAM,MAAM,GAAyC,EAAE,CAAC;IACxD,KAAK,MAAM,CAAC,GAAG,EAAE,OAAO,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACnD,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC;YAAE,OAAO,IAAI,CAAC;QACrC,MAAM,CAAC,GAAG,CAAC,GAAG,OAAO,CAAC;IACxB,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,MAAM,OAAO,uBAAuB;IACzB,QAAQ,GAAG,IAAI,GAAG,EAAgC,CAAC;IAE5D,GAAG,CAAC,MAAc,EAAE,OAAe;QACjC,OAAO,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,UAAU,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC;IACjF,CAAC;IAED,IAAI,CAAC,OAA6B;QAChC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,UAAU,CAAC,OAAO,CAAC,MAAM,EAAE,OAAO,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC,CAAC;QACxE,OAAO,OAAO,CAAC,OAAO,EAAE,CAAC;IAC3B,CAAC;IAED,MAAM,CAAC,MAAc,EAAE,OAAe;QACpC,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,UAAU,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;QAClD,OAAO,OAAO,CAAC,OAAO,EAAE,CAAC;IAC3B,CAAC;CACF;AAED,MAAM,OAAO,qBAAqB;IACH;IAA7B,YAA6B,OAA2B;QAA3B,YAAO,GAAP,OAAO,CAAoB;IAAG,CAAC;IAE5D,KAAK,CAAC,GAAG,CAAC,MAAc,EAAE,OAAe;QACvC,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,IAAI,EAAE,CAAC;QACjC,OAAO,MAAM,CAAC,UAAU,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,IAAI,IAAI,CAAC;IACrD,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,OAA6B;QACtC,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,IAAI,EAAE,CAAC;QACjC,MAAM,CAAC,UAAU,CAAC,OAAO,CAAC,MAAM,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC,GAAG,OAAO,CAAC;QAC9D,MAAM,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,WAAW,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC;IAClE,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,MAAc,EAAE,OAAe;QAC1C,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,IAAI,EAAE,CAAC;QACjC,OAAO,MAAM,CAAC,UAAU,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;QAC3C,IAAI,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,MAAM,KAAK,CAAC;YAAE,MAAM,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,WAAW,CAAC,CAAC;;YAC5E,MAAM,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,WAAW,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC;IACvE,CAAC;IAEO,KAAK,CAAC,IAAI;QAChB,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC;QACpD,IAAI,GAAG,KAAK,IAAI;YAAE,OAAO,EAAE,CAAC;QAC5B,IAAI,CAAC;YACH,MAAM,KAAK,GAAY,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;YACvC,MAAM,MAAM,GAAG,kBAAkB,CAAC,KAAK,CAAC,CAAC;YACzC,IAAI,MAAM,KAAK,IAAI;gBAAE,OAAO,MAAM,CAAC;QACrC,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,IAAI,kBAAkB,CAAC,gBAAgB,EAAE,kCAAkC,EAAE,EAAE,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC;QACpG,CAAC;QACD,MAAM,IAAI,kBAAkB,CAAC,gBAAgB,EAAE,8CAA8C,CAAC,CAAC;IACjG,CAAC;CACF"}

package/dist/src/matrix/runtime.d.ts

@@ -0,0 +1,18 @@
+import { type PendingTopicStore, type TopicCreationInput, type TopicCreationResult, type TopicMatrixTransport } from "./types.js";
+export interface TopicRuntimeOptions {
+    readonly transport: TopicMatrixTransport;
+    readonly pendingStore: PendingTopicStore;
+}
+export declare class TopicRuntime {
+    #private;
+    constructor(options: TopicRuntimeOptions);
+    createTopic(input: TopicCreationInput): Promise<TopicCreationResult>;
+    discardPending(roomId: string, topicId: string): Promise<void>;
+    private create;
+    private resolveAnchor;
+    private recoverUnknownAnchor;
+    private createRoot;
+    private getPending;
+    private savePending;
+    private removePending;
+}

package/dist/src/matrix/runtime.js

@@ -0,0 +1,121 @@
+import { TopicProtocolError } from "../errors.js";
+import { assertMatrixRoomId, assertServerEventId, assertTopicMessageContent, buildTopicMessageContent, buildTopicRootContent, } from "./content.js";
+import { parseTopicRootEvent } from "./events.js";
+import { MATRIX_ROOM_MESSAGE, } from "./types.js";
+export class TopicRuntime {
+    #inflight = new Map();
+    #transport;
+    #store;
+    constructor(options) {
+        this.#transport = options.transport;
+        this.#store = options.pendingStore;
+    }
+    createTopic(input) {
+        const key = `${input.roomId}\u0000${input.root.id}`;
+        const existing = this.#inflight.get(key);
+        if (existing !== undefined)
+            return existing;
+        const creation = this.create(input);
+        this.#inflight.set(key, creation);
+        void creation.then(() => this.#inflight.delete(key), () => this.#inflight.delete(key));
+        return creation;
+    }
+    async discardPending(roomId, topicId) {
+        await this.removePending(roomId, topicId);
+    }
+    async create(input) {
+        assertMatrixRoomId(input.roomId);
+        buildTopicRootContent(input.root);
+        assertTopicMessageContent(input.firstMessage);
+        const anchor = await this.resolveAnchor(input);
+        const messageRequest = {
+            roomId: input.roomId,
+            type: MATRIX_ROOM_MESSAGE,
+            content: buildTopicMessageContent(anchor, input.firstMessage),
+        };
+        let firstMessageEventId;
+        try {
+            ({ eventId: firstMessageEventId } = await this.#transport.sendEvent(messageRequest));
+            assertServerEventId(firstMessageEventId);
+        }
+        catch (cause) {
+            throw new TopicProtocolError("FIRST_MESSAGE_FAILED", "Topic root exists but the first message failed; creation can be resumed", { anchor, topicId: input.root.id }, { cause });
+        }
+        await this.removePending(input.roomId, input.root.id);
+        return { root: input.root, anchor, firstMessageEventId };
+    }
+    async resolveAnchor(input) {
+        const pending = await this.getPending(input.roomId, input.root.id);
+        if (pending !== null && pending.rootEventId !== null) {
+            assertServerEventId(pending.rootEventId);
+            return { roomId: input.roomId, rootEventId: pending.rootEventId };
+        }
+        if (pending !== null)
+            return this.recoverUnknownAnchor(input, pending);
+        return this.createRoot(input);
+    }
+    async recoverUnknownAnchor(input, pending) {
+        let discovered = null;
+        try {
+            discovered = await this.#transport.findTopicRoot?.(input.roomId, input.root.id) ?? null;
+        }
+        catch (cause) {
+            throw new TopicProtocolError("ROOT_DISCOVERY_FAILED", "Pending Topic root discovery failed", { pending }, { cause });
+        }
+        const parsed = discovered === null ? null : parseTopicRootEvent(discovered);
+        if (parsed === null || parsed.root.id !== input.root.id) {
+            throw new TopicProtocolError("PENDING_ROOT_UNRESOLVED", "A prior root send may have succeeded; refusing to create a duplicate", { pending });
+        }
+        await this.savePending({ ...pending, rootEventId: parsed.anchor.rootEventId });
+        return parsed.anchor;
+    }
+    async createRoot(input) {
+        const pending = {
+            roomId: input.roomId,
+            topicId: input.root.id,
+            rootEventId: null,
+            createdAt: input.root.createdAt,
+        };
+        await this.savePending(pending);
+        try {
+            const response = await this.#transport.sendEvent({
+                roomId: input.roomId,
+                type: MATRIX_ROOM_MESSAGE,
+                content: buildTopicRootContent(input.root),
+            });
+            assertServerEventId(response.eventId);
+            await this.savePending({ ...pending, rootEventId: response.eventId });
+            return { roomId: input.roomId, rootEventId: response.eventId };
+        }
+        catch (cause) {
+            if (cause instanceof TopicProtocolError)
+                throw cause;
+            throw new TopicProtocolError("ROOT_CREATION_FAILED", "Topic root creation failed", { topicId: input.root.id }, { cause });
+        }
+    }
+    async getPending(roomId, topicId) {
+        try {
+            return await this.#store.get(roomId, topicId);
+        }
+        catch (cause) {
+            throw new TopicProtocolError("STORAGE_FAILED", "Could not read pending Topic creation", { roomId, topicId }, { cause });
+        }
+    }
+    async savePending(pending) {
+        try {
+            await this.#store.save(pending);
+        }
+        catch (cause) {
+            throw new TopicProtocolError("STORAGE_FAILED", "Could not persist pending Topic creation", { pending }, { cause });
+        }
+    }
+    async removePending(roomId, topicId) {
+        try {
+            await this.#store.remove(roomId, topicId);
+        }
+        catch (cause) {
+            throw new TopicProtocolError("STORAGE_FAILED", "Could not clear pending Topic creation", { roomId, topicId }, { cause });
+        }
+    }
+}
+//# sourceMappingURL=runtime.js.map

package/dist/src/matrix/runtime.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.js","sourceRoot":"","sources":["../../../src/matrix/runtime.ts"],"names":[],"mappings":"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"}

package/dist/src/matrix/types.d.ts

@@ -0,0 +1,84 @@
+import type { MatrixAnchor, TopicKind, TopicOperation, TopicProjection, TopicRoot } from "../projector/types.js";
+export declare const MATRIX_ROOM_MESSAGE = "m.room.message";
+export declare const TOPIC_METADATA_KEY = "ixo.topic";
+export declare const TOPIC_ANCHOR_KEY = "ixo.topic.anchor";
+export declare const TOPIC_OPERATION_EVENT_TYPE = "ixo.topic.operation";
+export type MatrixEventContent = Readonly<Record<string, unknown>>;
+export interface TopicMatrixEvent {
+    readonly eventId: string;
+    readonly roomId: string;
+    readonly type: string;
+    readonly sender: string;
+    readonly timestamp: number;
+    readonly content: MatrixEventContent;
+    readonly redacted?: boolean;
+}
+export interface MatrixSendRequest {
+    readonly roomId: string;
+    readonly type: string;
+    readonly content: MatrixEventContent;
+}
+export interface TopicMatrixTransport {
+    sendEvent(request: MatrixSendRequest): Promise<{
+        readonly eventId: string;
+    }>;
+    findTopicRoot?(roomId: string, topicId: string): Promise<TopicMatrixEvent | null>;
+}
+export interface PendingTopicCreation {
+    readonly roomId: string;
+    readonly topicId: string;
+    readonly rootEventId: string | null;
+    readonly createdAt: string;
+}
+export interface PendingTopicStore {
+    get(roomId: string, topicId: string): Promise<PendingTopicCreation | null>;
+    save(pending: PendingTopicCreation): Promise<void>;
+    remove(roomId: string, topicId: string): Promise<void>;
+}
+export interface TopicCreationInput {
+    readonly roomId: string;
+    readonly root: TopicRoot;
+    readonly firstMessage: MatrixEventContent;
+}
+export interface TopicCreationResult {
+    readonly root: TopicRoot;
+    readonly anchor: MatrixAnchor;
+    readonly firstMessageEventId: string;
+}
+export interface TopicRootContentOptions {
+    readonly replaces?: MatrixAnchor;
+}
+export interface ParsedTopicRoot {
+    readonly event: TopicMatrixEvent;
+    readonly root: TopicRoot;
+    readonly anchor: MatrixAnchor;
+    readonly replaces?: MatrixAnchor;
+}
+export type RejectedTopicEventReason = "actor-mismatch" | "invalid-content" | "invalid-relation" | "redacted" | "wrong-root";
+export interface RejectedTopicEvent {
+    readonly eventId: string;
+    readonly reason: RejectedTopicEventReason;
+}
+export interface MatrixTopicProjection {
+    readonly projection: TopicProjection;
+    readonly rejectedEvents: readonly RejectedTopicEvent[];
+}
+export interface MatrixTopicProjectionInput {
+    readonly rootEvent: TopicMatrixEvent;
+    readonly operationEvents: readonly TopicMatrixEvent[];
+    readonly authenticateActor: (operation: TopicOperation, event: TopicMatrixEvent) => boolean;
+    readonly authorize: (operation: TopicOperation) => boolean;
+}
+export interface TopicAnchorConflict {
+    readonly previous: MatrixAnchor;
+    readonly canonical: MatrixAnchor;
+    readonly competing: readonly MatrixAnchor[];
+}
+export interface CanonicalTopicAnchor {
+    readonly anchor: MatrixAnchor;
+    readonly root: TopicRoot;
+    readonly conflicts: readonly TopicAnchorConflict[];
+}
+export interface TopicIdFactoryOptions {
+    readonly kind?: TopicKind;
+}