@echovisionlab/geul-event 0.1.0

package/src/interactive-mutation.test.ts

@@ -0,0 +1,287 @@
+import { create } from "@bufbuild/protobuf";
+import {
+  AIDocumentCreateTranslationOperationSchema,
+  AIDocumentDeleteTranslationOperationSchema,
+  AIDocumentDeleteBlockOperationSchema,
+  AIDocumentDomain,
+  AIDocumentLocaleSchema,
+  AIDocumentOperationSchema,
+  AIDocumentReferenceSchema,
+} from "@echovisionlab/geul-proto/secure/ai_pb.ts";
+import {
+  InteractiveAIDocumentMutationOrigin,
+  RelayInteractiveAIDocumentMutationRequestSchema,
+} from "@echovisionlab/geul-proto/intra/collaboration_pb.ts";
+import { describe, expect, it } from "vitest";
+import { assertRelayInteractiveAIDocumentMutationRequest } from "./interactive-mutation.ts";
+
+function validEvent() {
+  return create(RelayInteractiveAIDocumentMutationRequestSchema, {
+    mutationId: "mutation-1",
+    origin:
+      InteractiveAIDocumentMutationOrigin.INTERACTIVE_AI_DOCUMENT_MUTATION_ORIGIN_MCP,
+    document: create(AIDocumentReferenceSchema, {
+      domain: AIDocumentDomain.AI_DOCUMENT_DOMAIN_POST,
+      reference: "post-1",
+    }),
+    locale: create(AIDocumentLocaleSchema, { code: "ko" }),
+    expectedDocumentRevision: "revision-before",
+    acceptedDocumentRevision: "revision-after",
+    operations: [
+      create(AIDocumentOperationSchema, {
+        operation: {
+          case: "deleteBlock",
+          value: create(AIDocumentDeleteBlockOperationSchema, {
+            blockHandle: "block-1",
+          }),
+        },
+      }),
+    ],
+    actorMemberId: "member-1",
+  });
+}
+
+describe("interactive AI document mutation relay", () => {
+  it.each([
+    InteractiveAIDocumentMutationOrigin.INTERACTIVE_AI_DOCUMENT_MUTATION_ORIGIN_IN_EDITOR_AI,
+    InteractiveAIDocumentMutationOrigin.INTERACTIVE_AI_DOCUMENT_MUTATION_ORIGIN_MCP,
+  ])("accepts active interactive origin %s", (origin) => {
+    const event = validEvent();
+    event.origin = origin;
+    expect(() =>
+      assertRelayInteractiveAIDocumentMutationRequest(event),
+    ).not.toThrow();
+  });
+
+  it.each([
+    {
+      name: "blank mutation id",
+      mutate: (event: ReturnType<typeof validEvent>) => {
+        event.mutationId = "  ";
+      },
+      error: "id",
+    },
+    {
+      name: "unspecified origin",
+      mutate: (event: ReturnType<typeof validEvent>) => {
+        event.origin =
+          InteractiveAIDocumentMutationOrigin.INTERACTIVE_AI_DOCUMENT_MUTATION_ORIGIN_UNSPECIFIED;
+      },
+      error: "origin",
+    },
+    {
+      name: "missing document",
+      mutate: (event: ReturnType<typeof validEvent>) => {
+        event.document = undefined;
+      },
+      error: "document",
+    },
+    {
+      name: "unknown origin",
+      mutate: (event: ReturnType<typeof validEvent>) => {
+        // @ts-expect-error Simulate an unknown numeric enum decoded from the wire.
+        event.origin = 99;
+      },
+      error: "origin",
+    },
+    {
+      name: "unspecified domain",
+      mutate: (event: ReturnType<typeof validEvent>) => {
+        if (event.document === undefined) {
+          throw new Error("test fixture document is required");
+        }
+        event.document.domain = AIDocumentDomain.AI_DOCUMENT_DOMAIN_UNSPECIFIED;
+      },
+      error: "domain",
+    },
+    {
+      name: "unknown domain",
+      mutate: (event: ReturnType<typeof validEvent>) => {
+        if (event.document === undefined) {
+          throw new Error("test fixture document is required");
+        }
+        // @ts-expect-error Simulate an unknown numeric enum decoded from the wire.
+        event.document.domain = 99;
+      },
+      error: "domain",
+    },
+    {
+      name: "blank reference",
+      mutate: (event: ReturnType<typeof validEvent>) => {
+        if (event.document === undefined) {
+          throw new Error("test fixture document is required");
+        }
+        event.document.reference = "  ";
+      },
+      error: "reference",
+    },
+    {
+      name: "missing locale",
+      mutate: (event: ReturnType<typeof validEvent>) => {
+        event.locale = undefined;
+      },
+      error: "locale",
+    },
+    {
+      name: "blank locale",
+      mutate: (event: ReturnType<typeof validEvent>) => {
+        if (event.locale === undefined) {
+          throw new Error("test fixture locale is required");
+        }
+        event.locale.code = "  ";
+      },
+      error: "locale",
+    },
+    {
+      name: "blank expected document revision",
+      mutate: (event: ReturnType<typeof validEvent>) => {
+        event.expectedDocumentRevision = "  ";
+      },
+      error: "expected document revision",
+    },
+    {
+      name: "blank accepted document revision",
+      mutate: (event: ReturnType<typeof validEvent>) => {
+        event.acceptedDocumentRevision = "  ";
+      },
+      error: "accepted document revision",
+    },
+    {
+      name: "blank expected target revision",
+      mutate: (event: ReturnType<typeof validEvent>) => {
+        event.expectedTargetRevision = "  ";
+      },
+      error: "expected target revision",
+    },
+    {
+      name: "blank accepted target revision",
+      mutate: (event: ReturnType<typeof validEvent>) => {
+        event.acceptedTargetRevision = "  ";
+      },
+      error: "accepted target revision",
+    },
+    {
+      name: "target revision disappears outside delete",
+      mutate: (event: ReturnType<typeof validEvent>) => {
+        event.expectedTargetRevision = "target-before";
+        event.acceptedDocumentRevision = event.expectedDocumentRevision;
+      },
+      error: "cannot disappear",
+    },
+    {
+      name: "source mutation preserves document revision",
+      mutate: (event: ReturnType<typeof validEvent>) => {
+        event.acceptedDocumentRevision = event.expectedDocumentRevision;
+      },
+      error: "must advance",
+    },
+    {
+      name: "missing operations",
+      mutate: (event: ReturnType<typeof validEvent>) => {
+        event.operations = [];
+      },
+      error: "operations",
+    },
+    {
+      name: "missing operation arm",
+      mutate: (event: ReturnType<typeof validEvent>) => {
+        event.operations = [create(AIDocumentOperationSchema)];
+      },
+      error: "operation 0",
+    },
+    {
+      name: "mixed locale lifecycle operation",
+      mutate: (event: ReturnType<typeof validEvent>) => {
+        event.operations.push(
+          create(AIDocumentOperationSchema, {
+            operation: {
+              case: "createTranslation",
+              value: create(AIDocumentCreateTranslationOperationSchema),
+            },
+          }),
+        );
+      },
+      error: "must be exclusive",
+    },
+    {
+      name: "blank actor member id",
+      mutate: (event: ReturnType<typeof validEvent>) => {
+        event.actorMemberId = "  ";
+      },
+      error: "actor member id",
+    },
+  ])("rejects $name", ({ mutate, error }) => {
+    const event = validEvent();
+    mutate(event);
+    expect(() =>
+      assertRelayInteractiveAIDocumentMutationRequest(event),
+    ).toThrow(error);
+  });
+
+  it("accepts existing-target and missing-target value transitions", () => {
+    const existing = validEvent();
+    existing.acceptedDocumentRevision = existing.expectedDocumentRevision;
+    existing.expectedTargetRevision = "target-before";
+    existing.acceptedTargetRevision = "target-after";
+    expect(() =>
+      assertRelayInteractiveAIDocumentMutationRequest(existing),
+    ).not.toThrow();
+
+    const firstWrite = validEvent();
+    firstWrite.acceptedDocumentRevision = firstWrite.expectedDocumentRevision;
+    firstWrite.acceptedTargetRevision = "target-created";
+    expect(() =>
+      assertRelayInteractiveAIDocumentMutationRequest(firstWrite),
+    ).not.toThrow();
+  });
+
+  it("accepts a source mutation with an advanced document revision", () => {
+    const event = validEvent();
+    expect(() =>
+      assertRelayInteractiveAIDocumentMutationRequest(event),
+    ).not.toThrow();
+  });
+
+  it("accepts explicit target create and delete transitions", () => {
+    const createTarget = validEvent();
+    createTarget.acceptedDocumentRevision =
+      createTarget.expectedDocumentRevision;
+    createTarget.acceptedTargetRevision = "target-created";
+    createTarget.operations = [
+      create(AIDocumentOperationSchema, {
+        operation: {
+          case: "createTranslation",
+          value: create(AIDocumentCreateTranslationOperationSchema),
+        },
+      }),
+    ];
+    expect(() =>
+      assertRelayInteractiveAIDocumentMutationRequest(createTarget),
+    ).not.toThrow();
+
+    const deleteTarget = validEvent();
+    deleteTarget.acceptedDocumentRevision =
+      deleteTarget.expectedDocumentRevision;
+    deleteTarget.expectedTargetRevision = "target-before";
+    deleteTarget.operations = [
+      create(AIDocumentOperationSchema, {
+        operation: {
+          case: "deleteTranslation",
+          value: create(AIDocumentDeleteTranslationOperationSchema),
+        },
+      }),
+    ];
+    expect(() =>
+      assertRelayInteractiveAIDocumentMutationRequest(deleteTarget),
+    ).not.toThrow();
+  });
+
+  it("rejects target changes that replace the shared document token", () => {
+    const event = validEvent();
+    event.expectedTargetRevision = "target-before";
+    event.acceptedTargetRevision = "target-after";
+    expect(() =>
+      assertRelayInteractiveAIDocumentMutationRequest(event),
+    ).toThrow("preserve the document revision");
+  });
+});

package/src/interactive-mutation.ts

@@ -0,0 +1,136 @@
+import { AIDocumentDomain } from "@echovisionlab/geul-proto/secure/ai_pb.ts";
+import {
+  InteractiveAIDocumentMutationOrigin,
+  type RelayInteractiveAIDocumentMutationRequest,
+} from "@echovisionlab/geul-proto/intra/collaboration_pb.ts";
+
+const activeDocumentDomains = new Set<number>(
+  Object.values(AIDocumentDomain).filter(
+    (value): value is number =>
+      typeof value === "number" &&
+      value !== AIDocumentDomain.AI_DOCUMENT_DOMAIN_UNSPECIFIED,
+  ),
+);
+
+function requireNonBlank(value: string, name: string): void {
+  if (value.trim() === "") {
+    throw new Error(`interactive AI document mutation ${name} is required`);
+  }
+}
+
+// Transport-independent validation shared by the post-commit API publisher and
+// the Collab relay receiver. It creates no retry, history, or persistence.
+export function assertRelayInteractiveAIDocumentMutationRequest(
+  event: RelayInteractiveAIDocumentMutationRequest,
+): void {
+  requireNonBlank(event.mutationId, "id");
+
+  switch (event.origin) {
+    case InteractiveAIDocumentMutationOrigin.INTERACTIVE_AI_DOCUMENT_MUTATION_ORIGIN_IN_EDITOR_AI:
+    case InteractiveAIDocumentMutationOrigin.INTERACTIVE_AI_DOCUMENT_MUTATION_ORIGIN_MCP:
+      break;
+    case InteractiveAIDocumentMutationOrigin.INTERACTIVE_AI_DOCUMENT_MUTATION_ORIGIN_UNSPECIFIED:
+    default:
+      throw new Error(
+        `unsupported interactive AI document mutation origin: ${event.origin}`,
+      );
+  }
+
+  if (event.document === undefined) {
+    throw new Error("interactive AI document mutation document is required");
+  }
+  if (!activeDocumentDomains.has(event.document.domain)) {
+    throw new Error(
+      `unsupported interactive AI document mutation domain: ${event.document.domain}`,
+    );
+  }
+  requireNonBlank(event.document.reference, "reference");
+
+  if (event.locale === undefined) {
+    throw new Error("interactive AI document mutation locale is required");
+  }
+  requireNonBlank(event.locale.code, "locale");
+  requireNonBlank(event.expectedDocumentRevision, "expected document revision");
+  requireNonBlank(event.acceptedDocumentRevision, "accepted document revision");
+
+  if (event.operations.length === 0) {
+    throw new Error("interactive AI document mutation operations are required");
+  }
+  event.operations.forEach((operation, index) => {
+    if (operation.operation.case === undefined) {
+      throw new Error(
+        `interactive AI document mutation operation ${index} is required`,
+      );
+    }
+  });
+  if (
+    event.operations.length !== 1 &&
+    event.operations.some(
+      (operation) =>
+        operation.operation.case === "createTranslation" ||
+        operation.operation.case === "deleteTranslation",
+    )
+  ) {
+    throw new Error(
+      "interactive AI document mutation locale lifecycle operation must be exclusive",
+    );
+  }
+
+  if (event.expectedTargetRevision !== undefined) {
+    requireNonBlank(event.expectedTargetRevision, "expected target revision");
+  }
+  if (event.acceptedTargetRevision !== undefined) {
+    requireNonBlank(event.acceptedTargetRevision, "accepted target revision");
+  }
+  const isTargetMutation =
+    event.expectedTargetRevision !== undefined ||
+    event.acceptedTargetRevision !== undefined;
+  if (isTargetMutation) {
+    if (event.acceptedDocumentRevision !== event.expectedDocumentRevision) {
+      throw new Error(
+        "interactive AI document target mutation must preserve the document revision",
+      );
+    }
+  } else {
+    if (
+      event.expectedTargetRevision === undefined &&
+      event.acceptedTargetRevision === undefined &&
+      event.acceptedDocumentRevision === event.expectedDocumentRevision
+    ) {
+      throw new Error(
+        "interactive AI document source mutation must advance the document revision",
+      );
+    }
+  }
+
+  const onlyOperation =
+    event.operations.length === 1 ? event.operations[0] : undefined;
+  if (onlyOperation?.operation.case === "createTranslation") {
+    if (
+      event.expectedTargetRevision !== undefined ||
+      event.acceptedTargetRevision === undefined
+    ) {
+      throw new Error(
+        "interactive AI document mutation create translation revisions are invalid",
+      );
+    }
+  } else if (onlyOperation?.operation.case === "deleteTranslation") {
+    if (
+      event.expectedTargetRevision === undefined ||
+      event.acceptedTargetRevision !== undefined
+    ) {
+      throw new Error(
+        "interactive AI document mutation delete translation revisions are invalid",
+      );
+    }
+  } else if (
+    event.expectedTargetRevision !== undefined &&
+    event.acceptedTargetRevision === undefined
+  ) {
+    throw new Error(
+      "interactive AI document mutation target revision cannot disappear",
+    );
+  }
+
+  requireNonBlank(event.actorMemberId, "actor member id");
+}

package/src/pgmq.test.ts

@@ -0,0 +1,80 @@
+import { describe, expect, it } from "vitest";
+import {
+  createPgmqEnvelope,
+  pgmqEnvelopePayload,
+  PGMQ_ENVELOPE_SCHEMA_VERSION,
+  PgmqClient,
+  type PgmqExecutor,
+} from "./pgmq.ts";
+
+describe("PGMQ transport contract", () => {
+  it("preserves protobuf bytes without ProtoJSON conversion", () => {
+    const payload = Uint8Array.from([0, 255, 1, 128, 127]);
+    const envelope = createPgmqEnvelope({
+      messageId: "command-1",
+      messageType: "api.manage.v1.Command",
+      payload,
+      createdAt: new Date("2026-08-14T00:00:00.000Z"),
+    });
+    expect(envelope.schema_version).toBe(PGMQ_ENVELOPE_SCHEMA_VERSION);
+    expect(pgmqEnvelopePayload(envelope)).toEqual(payload);
+  });
+
+  it("uses caller-owned executors for atomic enqueue", async () => {
+    const calls: Array<{ text: string; values?: readonly unknown[] }> = [];
+    const transaction: PgmqExecutor = {
+      query: (async (text: string, values?: readonly unknown[]) => {
+        calls.push({ text, values });
+        return { rows: [{ msg_id: "42" }] };
+      }) as PgmqExecutor["query"],
+    };
+    const envelope = createPgmqEnvelope({
+      messageId: "command-1",
+      messageType: "type",
+      payload: new Uint8Array(),
+    });
+    await expect(
+      new PgmqClient().enqueue(transaction, "work.queue", envelope),
+    ).resolves.toBe(42n);
+    expect(calls).toHaveLength(1);
+    expect(calls[0]?.values?.[0]).toBe("work.queue");
+  });
+
+  it("returns malformed rows with transport identity so consumers can archive them", async () => {
+    const executor: PgmqExecutor = {
+      query: (async () => ({
+        rows: [
+          {
+            msg_id: "41",
+            read_ct: 1,
+            enqueued_at: new Date("2026-08-14T00:00:00.000Z"),
+            vt: new Date("2026-08-14T00:00:30.000Z"),
+            message: { schema_version: 999 },
+            headers: {},
+          },
+          {
+            msg_id: "42",
+            read_ct: 1,
+            enqueued_at: new Date("2026-08-14T00:00:00.000Z"),
+            vt: new Date("2026-08-14T00:00:30.000Z"),
+            message: createPgmqEnvelope({
+              messageId: "command-2",
+              messageType: "type",
+              payload: new Uint8Array(),
+            }),
+            headers: {},
+          },
+        ],
+      })) as PgmqExecutor["query"],
+    };
+
+    const messages = await new PgmqClient().read(executor, "work.queue", {
+      visibilityTimeoutSeconds: 30,
+      batch: 2,
+    });
+    expect(messages).toHaveLength(2);
+    expect(messages[0]).toMatchObject({ transportId: 41n });
+    expect(messages[0]?.contractError).toContain("message_id");
+    expect(messages[1]?.envelope?.message_id).toBe("command-2");
+  });
+});