@axiom-lattice/protocols 4.1.1 → 4.1.2

package/src/TrustedRunContextProtocol.ts

@@ -0,0 +1,119 @@
+import { snapshotExactRecord } from "./ExactDataSnapshot";
+
+/** Queue execution behavior available to privileged host dispatchers. */
+export type QueuedExecutionMode = "followup";
+
+/** Trusted Project Room identity persisted with a privileged queue message. */
+export interface ProjectRoomTrustedRunContext {
+  tenantId: string;
+  workspaceId: string;
+  projectId: string;
+  roomId: string;
+  sourceRoomMessageId: string;
+  membershipId: string;
+  assistantId: string;
+  inputMessageId: string;
+  role: "coordinator" | "specialist";
+  title: string;
+  responsibility?: string;
+}
+
+/** Trusted Project Task identity persisted with a privileged queue message. */
+export interface ProjectTaskTrustedRunContext {
+  tenantId: string;
+  workspaceId: string;
+  projectId: string;
+  roomId: string;
+  membershipId: string;
+  assistantId: string;
+  taskId: string;
+  threadId: string;
+  inputMessageId: string;
+}
+
+/** Host-authenticated metadata that cannot be supplied through public Agent APIs. */
+export interface TrustedRunContext {
+  projectRoom?: ProjectRoomTrustedRunContext;
+  projectTask?: ProjectTaskTrustedRunContext;
+}
+
+/**
+ * Strictly validates and clones host-authenticated queue context read from durable storage.
+ *
+ * @param value - Untrusted decoded database value.
+ * @returns A validated defensive clone of the trusted run context.
+ * @throws Error when the stored value does not exactly match the trusted context contract.
+ */
+export function parseTrustedRunContext(value: unknown): TrustedRunContext {
+  const contextValues = snapshotExactRecord(value, [], ["projectRoom", "projectTask"]);
+  if (!contextValues || Object.keys(contextValues).length !== 1) {
+    throw new Error("Invalid trusted agent run context");
+  }
+  if (Object.prototype.hasOwnProperty.call(contextValues, "projectTask")) {
+    const requiredKeys = [
+      "tenantId", "workspaceId", "projectId", "roomId", "membershipId",
+      "assistantId", "taskId", "threadId", "inputMessageId",
+    ] as const;
+    const projectTaskValues = snapshotExactRecord(contextValues.projectTask, requiredKeys);
+    if (!projectTaskValues
+      || requiredKeys.some((key) => typeof projectTaskValues[key] !== "string" || projectTaskValues[key].length === 0)) {
+      throw new Error("Invalid trusted agent run context");
+    }
+    return {
+      projectTask: {
+        tenantId: projectTaskValues.tenantId as string,
+        workspaceId: projectTaskValues.workspaceId as string,
+        projectId: projectTaskValues.projectId as string,
+        roomId: projectTaskValues.roomId as string,
+        membershipId: projectTaskValues.membershipId as string,
+        assistantId: projectTaskValues.assistantId as string,
+        taskId: projectTaskValues.taskId as string,
+        threadId: projectTaskValues.threadId as string,
+        inputMessageId: projectTaskValues.inputMessageId as string,
+      },
+    };
+  }
+  const projectRoomValue = contextValues?.projectRoom;
+  const requiredKeys = [
+    "tenantId", "workspaceId", "projectId", "roomId", "sourceRoomMessageId", "membershipId",
+    "assistantId", "inputMessageId", "role", "title",
+  ] as const;
+  const projectRoomValues = snapshotExactRecord(projectRoomValue, requiredKeys, ["responsibility"]);
+  const hasResponsibility = projectRoomValues !== undefined
+    && Object.prototype.hasOwnProperty.call(projectRoomValues, "responsibility");
+  if (!projectRoomValues
+    || requiredKeys.some((key) => typeof projectRoomValues[key] !== "string" || projectRoomValues[key].length === 0)
+    || (hasResponsibility && projectRoomValues.responsibility !== undefined
+      && (typeof projectRoomValues.responsibility !== "string" || projectRoomValues.responsibility.length === 0))
+    || (projectRoomValues.role !== "coordinator" && projectRoomValues.role !== "specialist")) {
+    throw new Error("Invalid trusted agent run context");
+  }
+  const parsedProjectRoom: ProjectRoomTrustedRunContext = {
+    tenantId: projectRoomValues.tenantId as string,
+    workspaceId: projectRoomValues.workspaceId as string,
+    projectId: projectRoomValues.projectId as string,
+    roomId: projectRoomValues.roomId as string,
+    sourceRoomMessageId: projectRoomValues.sourceRoomMessageId as string,
+    membershipId: projectRoomValues.membershipId as string,
+    assistantId: projectRoomValues.assistantId as string,
+    inputMessageId: projectRoomValues.inputMessageId as string,
+    role: projectRoomValues.role,
+    title: projectRoomValues.title as string,
+  };
+  if (hasResponsibility && typeof projectRoomValues.responsibility === "string") {
+    parsedProjectRoom.responsibility = projectRoomValues.responsibility;
+  }
+  return { projectRoom: parsedProjectRoom };
+}
+
+/**
+ * Strictly validates a queued execution mode read from durable storage.
+ *
+ * @param value - Untrusted database value.
+ * @returns The validated execution mode.
+ * @throws Error when the stored value is not supported.
+ */
+export function parseQueuedExecutionMode(value: unknown): QueuedExecutionMode {
+  if (value !== "followup") throw new Error("Invalid queued execution mode");
+  return value;
+}

package/src/__tests__/BindingProtocol.test.ts

@@ -0,0 +1,36 @@
+import type { BindingMutablePatch, BindingRegistry, CreateBindingInput } from "../BindingProtocol";
+
+describe("BindingProtocol mutation contract", () => {
+  it("accepts mutable fields and rejects identity fields at compile time", () => {
+    const mutable: BindingMutablePatch = {
+      agentId: "agent-2", threadId: "thread-2", workspaceId: "workspace-2",
+      projectId: "project-2", threadMode: "fixed", senderDisplayName: "Sender",
+      senderMetadata: { source: "test" }, enabled: false,
+    };
+    expect(mutable.enabled).toBe(false);
+
+    // @ts-expect-error channel is immutable after binding creation
+    const invalid: BindingMutablePatch = { channel: "room" };
+    expect(invalid).toBeDefined();
+  });
+
+  it("requires tenant scope for mutation methods", () => {
+    const update: BindingRegistry["update"] = async (...args) => {
+      expect(args).toHaveLength(3);
+      throw new Error("not invoked");
+    };
+    const remove: BindingRegistry["delete"] = async (...args) => {
+      expect(args).toHaveLength(2);
+    };
+    expect(update).toBeDefined();
+    expect(remove).toBeDefined();
+  });
+
+  it("allows trusted callers to choose the initial enabled state", () => {
+    const input: CreateBindingInput = {
+      channel: "room", channelInstallationId: "room-internal:tenant-a", tenantId: "tenant-a",
+      senderId: "room:room-1:membership-1", agentId: "agent-1", enabled: false,
+    };
+    expect(input.enabled).toBe(false);
+  });
+});

package/src/__tests__/ExactDataSnapshot.test.ts

@@ -0,0 +1,105 @@
+import { runInNewContext } from "node:vm";
+import { snapshotExactArray, snapshotExactRecord } from "../ExactDataSnapshot";
+
+describe("exact data snapshots", () => {
+  it("canonicalizes cross-realm and hostile-prototype records without reading their prototype", () => {
+    const crossRealm = runInNewContext("({ id: 'one', value: 2 })");
+    let inheritedReads = 0;
+    const prototype = Object.create(null);
+    Object.defineProperty(prototype, "constructor", {
+      get: () => { inheritedReads += 1; throw new Error("must not run"); },
+    });
+    Object.defineProperty(prototype, "inherited", {
+      get: () => { inheritedReads += 1; throw new Error("must not run"); },
+    });
+    const hostilePrototype = Object.assign(Object.create(prototype), { id: "two", value: 3 });
+
+    expect(snapshotExactRecord(crossRealm, ["id", "value"])).toEqual({ id: "one", value: 2 });
+    expect(snapshotExactRecord(hostilePrototype, ["id", "value"])).toEqual({ id: "two", value: 3 });
+    expect(inheritedReads).toBe(0);
+  });
+
+  it.each([
+    ["accessor", Object.defineProperty({ id: "one" }, "value", { enumerable: true, get: () => 2 })],
+    ["extra", { id: "one", value: 2, extra: true }],
+    ["non-enumerable", Object.defineProperty({ id: "one" }, "value", { enumerable: false, value: 2 })],
+    ["symbol", Object.assign({ id: "one", value: 2 }, { [Symbol("extra")]: true })],
+  ])("rejects an own %s record property", (_name, value) => {
+    expect(snapshotExactRecord(value, ["id", "value"])).toBeUndefined();
+  });
+
+  it("canonicalizes cross-realm arrays and rejects non-dense or accessor-bearing arrays", () => {
+    expect(snapshotExactArray(runInNewContext("['one', 'two']"))).toEqual(["one", "two"]);
+    const accessor = ["one"];
+    Object.defineProperty(accessor, "0", { enumerable: true, get: () => "one" });
+    expect(snapshotExactArray(accessor)).toBeUndefined();
+    expect(snapshotExactArray(Object.assign(["one"], { extra: true }))).toBeUndefined();
+    expect(snapshotExactArray(new Array(1))).toBeUndefined();
+  });
+
+  it("rejects record accessors without reading polluted descriptor prototypes", () => {
+    const originalValue = Object.getOwnPropertyDescriptor(Object.prototype, "value");
+    const originalEnumerable = Object.getOwnPropertyDescriptor(Object.prototype, "enumerable");
+    let inheritedReads = 0;
+    const accessor = Object.defineProperty({ id: "one" }, "value", {
+      enumerable: true,
+      get: () => 2,
+    });
+    try {
+      Object.defineProperty(Object.prototype, "value", {
+        configurable: true,
+        get: () => {
+          inheritedReads += 1;
+          return "forged";
+        },
+      });
+      Object.defineProperty(Object.prototype, "enumerable", Object.assign(Object.create(null), {
+        configurable: true,
+        get: () => {
+          inheritedReads += 1;
+          return true;
+        },
+      }));
+
+      expect(snapshotExactRecord(accessor, ["id", "value"])).toBeUndefined();
+      expect(inheritedReads).toBe(0);
+    } finally {
+      if (originalValue) Object.defineProperty(Object.prototype, "value", originalValue);
+      else delete (Object.prototype as { value?: unknown }).value;
+      if (originalEnumerable) Object.defineProperty(Object.prototype, "enumerable", originalEnumerable);
+      else delete (Object.prototype as { enumerable?: unknown }).enumerable;
+    }
+  });
+
+  it("rejects array accessors without reading polluted descriptor prototypes", () => {
+    const originalValue = Object.getOwnPropertyDescriptor(Object.prototype, "value");
+    const originalEnumerable = Object.getOwnPropertyDescriptor(Object.prototype, "enumerable");
+    let inheritedReads = 0;
+    const accessor = ["one"];
+    Object.defineProperty(accessor, "0", { enumerable: true, get: () => "one" });
+    try {
+      Object.defineProperty(Object.prototype, "value", {
+        configurable: true,
+        get: () => {
+          inheritedReads += 1;
+          return "forged";
+        },
+      });
+      Object.defineProperty(Object.prototype, "enumerable", Object.assign(Object.create(null), {
+        configurable: true,
+        get: () => {
+          inheritedReads += 1;
+          return true;
+        },
+      }));
+
+      expect(snapshotExactArray(accessor)).toBeUndefined();
+      expect(inheritedReads).toBe(0);
+    } finally {
+      if (originalValue) Object.defineProperty(Object.prototype, "value", originalValue);
+      else delete (Object.prototype as { value?: unknown }).value;
+      if (originalEnumerable) Object.defineProperty(Object.prototype, "enumerable", originalEnumerable);
+      else delete (Object.prototype as { enumerable?: unknown }).enumerable;
+    }
+  });
+});

package/src/__tests__/ProjectRoomProtocol.test.ts

@@ -0,0 +1,48 @@
+import type {
+  ProjectBotMembership,
+  ProjectRoomMessage,
+  ProjectRoomMessageCursor,
+} from "../ProjectRoomProtocol";
+
+describe("Project Room protocol types", () => {
+  it("models bot membership, system messages, and message cursors", () => {
+    const bot: ProjectBotMembership = {
+      id: "bm-1",
+      tenantId: "t-1",
+      workspaceId: "w-1",
+      projectId: "p-1",
+      roomId: "r-1",
+      assistantId: "a-1",
+      role: "coordinator",
+      title: "Lead",
+      mentionName: "lead",
+      status: "paused",
+      roomThreadId: "th-1",
+      joinedAt: new Date(0),
+      updatedAt: new Date(0),
+    };
+    const message: ProjectRoomMessage = {
+      id: "m-1",
+      tenantId: "t-1",
+      workspaceId: "w-1",
+      projectId: "p-1",
+      roomId: "r-1",
+      author: { type: "system" },
+      content: { type: "text", text: "Room ready" },
+      mentions: [],
+      source: "system",
+      idempotencyKey: "room-ready:p-1",
+      createdAt: new Date(0),
+    };
+    const cursor: ProjectRoomMessageCursor = {
+      createdAt: message.createdAt,
+      id: message.id,
+    };
+
+    expect([bot.status, message.source, cursor.id]).toEqual([
+      "paused",
+      "system",
+      "m-1",
+    ]);
+  });
+});

package/src/__tests__/ProjectRoomRealtimeProtocol.test.ts

@@ -0,0 +1,185 @@
+import type {
+  ProjectRoomBrokerCapacityError,
+  ProjectRoomBusinessEvent,
+  ProjectRoomBusinessEventDraft,
+  ProjectRoomControlEvent,
+  ProjectRoomEventScope,
+  ProjectRoomEventSubscription,
+  ProjectRoomRealtimeActor,
+} from "../ProjectRoomRealtimeProtocol";
+import { runInNewContext } from "node:vm";
+import {
+  isProjectRoomEventId,
+  parseProjectRoomEventId,
+  ProjectRoomCursorError,
+  toProjectRoomPublicBotMembership,
+  toProjectRoomPublicMembership,
+  toProjectRoomPublicMessage,
+} from "../ProjectRoomRealtimeProtocol";
+
+const message: ProjectRoomBusinessEvent = {
+  id: "550e8400-e29b-41d4-a716-446655440000:1",
+  type: "message.created",
+  occurredAt: "2026-09-03T00:00:00.000Z",
+  data: {
+    message: {
+      id: "message-1",
+      roomId: "room-1",
+      author: { type: "bot", membershipId: "bot-1" },
+      content: { type: "text", text: "Complete" },
+      mentions: [],
+      source: "agent",
+      createdAt: "2026-09-03T00:00:00.000Z",
+    },
+  },
+};
+
+const draft: ProjectRoomBusinessEventDraft = {
+  type: "task.changed",
+  occurredAt: "2026-09-03T00:00:01.000Z",
+  data: {
+    taskId: "task-1",
+    status: "completed",
+    ownerMembershipId: "bot-1",
+    updatedAt: "2026-09-03T00:00:01.000Z",
+  },
+};
+
+const control: ProjectRoomControlEvent = {
+  type: "resync",
+  data: { reason: "SERVER_RESTART" },
+};
+const scope: ProjectRoomEventScope = { tenantId: "tenant-1", roomId: "room-1", projectId: "project-1" };
+const actor: ProjectRoomRealtimeActor = {
+  tenantId: "tenant-1",
+  userId: "user-1",
+  projectId: "project-1",
+  tokenExpiresAt: 1_788_393_600_000,
+};
+const subscription: ProjectRoomEventSubscription = {
+  replay: [message],
+  headEventId: message.id,
+  unsubscribe: () => undefined,
+};
+
+// @ts-expect-error unsupported business event types are not public protocol values
+const dispatchEvent: ProjectRoomBusinessEventDraft = { type: "dispatch.changed", data: {} };
+// @ts-expect-error control events never carry replay IDs
+const identifiedControl: ProjectRoomControlEvent = { ...control, id: "epoch:1" };
+const internalMessage: ProjectRoomBusinessEvent = {
+  ...message,
+  data: {
+    // @ts-expect-error internal assistant identity is not public message data
+    message: { ...message.data.message, assistantId: "assistant-1" },
+  },
+};
+// @ts-expect-error event IDs are canonical strings, not numbers
+const numericEventId: ProjectRoomBusinessEvent = { ...message, id: 1 };
+
+describe("Project Room realtime protocol", () => {
+  it("defines the exact public business, control, broker, and actor surfaces", () => {
+    expect([message.type, draft.type, control.type]).toEqual([
+      "message.created",
+      "task.changed",
+      "resync",
+    ]);
+    expect(JSON.stringify(message)).not.toContain("assistantId");
+    expect(JSON.stringify(message)).not.toContain("sourceId");
+    expect(scope).toEqual({ tenantId: "tenant-1", roomId: "room-1", projectId: "project-1" });
+    expect(actor).toEqual({
+      tenantId: "tenant-1",
+      userId: "user-1",
+      projectId: "project-1",
+      tokenExpiresAt: 1_788_393_600_000,
+    });
+    expect(subscription.headEventId).toBe(message.id);
+    expect(dispatchEvent).toBeDefined();
+    expect(identifiedControl).toBeDefined();
+    expect(internalMessage).toBeDefined();
+    expect(numericEventId).toBeDefined();
+  });
+
+  it("maps descriptor-safe internal records to public DTOs", () => {
+    const internalMessage = {
+      id: "message-1", tenantId: "tenant-1", workspaceId: "workspace-1", projectId: "project-1",
+      roomId: "room-1", author: { type: "bot", membershipId: "bot-1", assistantId: "assistant-1" },
+      content: { type: "text", text: "Complete" }, mentions: [], source: "agent", sourceId: "reply-1",
+      idempotencyKey: "idem-1", createdAt: new Date("2026-09-03T00:00:00.000Z"),
+    };
+    const internalMembership = {
+      id: "membership-1", tenantId: "tenant-1", projectId: "project-1", userId: "user-1",
+      role: "viewer", status: "active", joinedAt: new Date("2026-09-03T00:00:00.000Z"),
+      updatedAt: new Date("2026-09-03T00:00:01.000Z"),
+    };
+    const internalBot = {
+      id: "bot-1", tenantId: "tenant-1", workspaceId: "workspace-1", projectId: "project-1", roomId: "room-1",
+      assistantId: "assistant-1", role: "specialist", title: "Worker", responsibility: "Build",
+      mentionName: "worker", status: "active", roomThreadId: "thread-1",
+      joinedAt: new Date("2026-09-03T00:00:00.000Z"), updatedAt: new Date("2026-09-03T00:00:01.000Z"),
+    };
+    expect(toProjectRoomPublicMessage(internalMessage)).toEqual(message.data.message);
+    expect(toProjectRoomPublicMembership(internalMembership)).toEqual({
+      id: "membership-1", userId: "user-1", role: "viewer", status: "active",
+      joinedAt: "2026-09-03T00:00:00.000Z", updatedAt: "2026-09-03T00:00:01.000Z",
+    });
+    expect(toProjectRoomPublicBotMembership(internalBot)).toEqual({
+      id: "bot-1", role: "specialist", title: "Worker", responsibility: "Build", mentionName: "worker",
+      status: "active", joinedAt: "2026-09-03T00:00:00.000Z", updatedAt: "2026-09-03T00:00:01.000Z",
+    });
+    expect(JSON.stringify(toProjectRoomPublicMessage(internalMessage))).not.toMatch(
+      /tenantId|workspaceId|projectId|assistantId|thread|idempotency|sourceId/,
+    );
+  });
+
+  it("rejects malformed, accessor-backed, and extra internal records", () => {
+    expect(toProjectRoomPublicMessage({})).toBeUndefined();
+    expect(toProjectRoomPublicMembership({ id: "membership-1", extra: true })).toBeUndefined();
+    expect(toProjectRoomPublicBotMembership({})).toBeUndefined();
+    const accessor = { get id() { return "message-1"; } };
+    expect(toProjectRoomPublicMessage(accessor)).toBeUndefined();
+  });
+
+  it("reconstructs strict mention DTOs and rejects sensitive mention fields", () => {
+    const value = {
+      id: "message-1", tenantId: "tenant-1", workspaceId: "workspace-1", projectId: "project-1", roomId: "room-1",
+      author: { type: "human", userId: "user-1" }, content: { type: "text", text: "hello" }, source: "user", createdAt: new Date("2026-09-03T00:00:00.000Z"),
+      mentions: [{ type: "team" }, { type: "bot", membershipId: "bot-1" }],
+    };
+    const result = toProjectRoomPublicMessage(value);
+    expect(result?.mentions).toEqual([{ type: "team" }, { type: "bot", membershipId: "bot-1" }]);
+    expect(result?.mentions[0]).not.toBe(value.mentions[0]);
+    expect(toProjectRoomPublicMessage({ ...value, mentions: [{ type: "team", tenantId: "secret" }] })).toBeUndefined();
+    let reads = 0;
+    const accessor = Object.defineProperty({ type: "team" }, "type", { enumerable: true, get: () => { reads += 1; return "team"; } });
+    expect(toProjectRoomPublicMessage({ ...value, mentions: [accessor] })).toBeUndefined();
+    expect(reads).toBe(0);
+  });
+
+  it("parses only canonical safe-integer event IDs", () => {
+    expect(parseProjectRoomEventId(message.id)).toEqual({
+      epoch: "550e8400-e29b-41d4-a716-446655440000",
+      sequence: 1,
+    });
+    expect(isProjectRoomEventId(message.id)).toBe(true);
+    expect(isProjectRoomEventId("epoch:1")).toBe(false);
+    expect(isProjectRoomEventId("550E8400-E29B-41D4-A716-446655440000:1")).toBe(false);
+    expect(isProjectRoomEventId(`${message.id}x`)).toBe(false);
+    expect(isProjectRoomEventId(`${message.id.split(":")[0]}:1.0`)).toBe(false);
+    expect(isProjectRoomEventId(`${message.id.split(":")[0]}:${Number.MAX_SAFE_INTEGER + 1}`)).toBe(false);
+    expect(parseProjectRoomEventId("not-an-event-id")).toBeUndefined();
+    expect(isProjectRoomEventId(runInNewContext(`"${message.id}"`))).toBe(true);
+    expect(isProjectRoomEventId(runInNewContext(`new String("${message.id}")`))).toBe(false);
+  });
+
+  it("exposes typed cursor and capacity errors", () => {
+    const cursorError = new ProjectRoomCursorError("CURSOR_EXPIRED");
+    const capacityError: ProjectRoomBrokerCapacityError = {
+      name: "ProjectRoomBrokerCapacityError",
+      message: "sequence exhausted",
+      code: "PROJECT_ROOM_EVENT_SEQUENCE_EXHAUSTED",
+    };
+    expect(cursorError).toBeInstanceOf(Error);
+    expect(cursorError.code).toBe("CURSOR_EXPIRED");
+    expect(capacityError.code).toBe("PROJECT_ROOM_EVENT_SEQUENCE_EXHAUSTED");
+  });
+});