oysterun 1.6.0-beta.4 → 1.6.0-beta.6

package/dev/client/connectivity/completed-message-neighbor-click.mjs

@@ -0,0 +1,78 @@
+// @ts-check
+
+/**
+ * Owns the lifetime of one completed-message navigation request at a time.
+ * Timeline movement is deliberately absent from this API: only click() reads.
+ *
+ * @template TResponse
+ * @param {{ readNeighbors: (request: { roomId: string, anchorEventId?: string, anchorPosition?: "latest" }) => Promise<TResponse>, selectTarget: (response: TResponse, direction: "previous" | "next") => string | undefined }} options
+ */
+export function createCompletedMessageNeighborClickCoordinator(options) {
+  /** @type {string | null} */
+  let scope = null;
+  let generation = 0;
+  /** @type {{ generation: number, scope: string } | null} */
+  let active = null;
+  let disposed = false;
+
+  /** @param {string} nextScope */
+  function setScope(nextScope) {
+    if (scope === nextScope) return;
+    scope = nextScope;
+    generation += 1;
+    active = null;
+  }
+
+  return {
+    setScope,
+    dispose() {
+      disposed = true;
+      generation += 1;
+      active = null;
+    },
+    isLoading() {
+      return active !== null;
+    },
+    /**
+     * @param {{ scope: string, roomId: string, direction: "previous" | "next", anchorEventId?: string, anchorPosition?: "latest" }} request
+     */
+    async click(request) {
+      if (disposed || request.scope !== scope) return { status: "stale" };
+      if (active !== null) return { status: "busy" };
+
+      const transaction = { generation, scope: request.scope };
+      active = transaction;
+      try {
+        const response = await options.readNeighbors({
+          roomId: request.roomId,
+          anchorEventId: request.anchorEventId,
+          anchorPosition: request.anchorPosition,
+        });
+        if (
+          disposed ||
+          active !== transaction ||
+          generation !== transaction.generation ||
+          scope !== transaction.scope
+        ) {
+          return { status: "stale" };
+        }
+        const targetEventId = options.selectTarget(response, request.direction);
+        return targetEventId
+          ? { status: "target", response, targetEventId }
+          : { status: "no_target", response };
+      } catch (error) {
+        if (
+          disposed ||
+          active !== transaction ||
+          generation !== transaction.generation ||
+          scope !== transaction.scope
+        ) {
+          return { status: "stale" };
+        }
+        return { status: "error", error };
+      } finally {
+        if (active === transaction) active = null;
+      }
+    },
+  };
+}

package/dev/client/connectivity/completed-message-neighbor-contract.mjs

@@ -0,0 +1,205 @@
+// @ts-check
+
+export const COMPLETED_MESSAGE_NEIGHBOR_SCHEMA_VERSION =
+  "routec.p206_completed_turn_final_message_neighbors.v1";
+
+/** @typedef {{ event_id: string, routec_stream_seq: number, origin_server_ts: number | null, provider_turn_id: string }} CompletedMessageNeighborEvent */
+/** @typedef {{ anchor_position: "event", event_id: string, routec_stream_seq: number } | { anchor_position: "latest", event_id: null, routec_stream_seq: number | null }} CompletedMessageNeighborAnchor */
+/** @typedef {{ schema_version: typeof COMPLETED_MESSAGE_NEIGHBOR_SCHEMA_VERSION, lookup_source: string, lookup_strategy: string, order_by: "final_candidate_stream_seq", candidate_predicate: "complete_message_notification_candidate", completion_predicate: "complete_message_notification_completion", navigation_index_version: number | null, navigation_index_names: string[], raw_event_scan_limit: null, raw_event_payload_returned: false, message_body_returned: false }} CompletedMessageNeighborProof */
+/** @typedef {{ status: "ok", session_id: string, matrix_room_id: string, anchor: CompletedMessageNeighborAnchor, previous: CompletedMessageNeighborEvent | null, next: CompletedMessageNeighborEvent | null, boundaries: { no_completed_turns: boolean, at_first_completed_message: boolean, at_latest_completed_message: boolean }, proof: CompletedMessageNeighborProof, committed_transcript_truth?: "matrix_room_timeline", routec_completed_message_neighbor_endpoint?: true, completed_message_truth_source?: "complete_message_notification_candidate_and_completion_predicates", raw_event_payload_returned: false, message_body_returned: false }} CompletedMessageNeighborsResponse */
+/** @typedef {{ sessionId?: string, matrixRoomId?: string, anchorEventId?: string | null, anchorPosition?: "latest" | null }} CompletedMessageNeighborExpectedIdentity */
+
+/**
+ * @param {unknown} value
+ * @returns {value is Record<string, unknown>}
+ */
+function isRecord(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+/**
+ * @param {unknown} value
+ * @returns {value is string}
+ */
+function nonEmptyString(value) {
+  return typeof value === "string" && value.trim().length > 0;
+}
+
+/**
+ * @param {unknown} value
+ * @returns {value is number}
+ */
+function isNonnegativeSafeInteger(value) {
+  return Number.isSafeInteger(value) && Number(value) >= 0;
+}
+
+/**
+ * @param {unknown} value
+ * @returns {value is CompletedMessageNeighborEvent}
+ */
+function isNeighbor(value) {
+  return (
+    isRecord(value) &&
+    nonEmptyString(value.event_id) &&
+    isNonnegativeSafeInteger(value.routec_stream_seq) &&
+    (typeof value.origin_server_ts === "number" ||
+      value.origin_server_ts === null) &&
+    nonEmptyString(value.provider_turn_id)
+  );
+}
+
+/**
+ * @param {CompletedMessageNeighborsResponse} value
+ * @param {CompletedMessageNeighborExpectedIdentity} expected
+ */
+function assertRequestIdentity(value, expected) {
+  if (expected.sessionId && value.session_id !== expected.sessionId) {
+    throw new Error("Completed-message neighbor Session identity mismatch.");
+  }
+  if (expected.matrixRoomId && value.matrix_room_id !== expected.matrixRoomId) {
+    throw new Error("Completed-message neighbor room identity mismatch.");
+  }
+  if (expected.anchorEventId) {
+    if (
+      value.anchor.anchor_position !== "event" ||
+      value.anchor.event_id !== expected.anchorEventId
+    ) {
+      throw new Error("Completed-message neighbor anchor identity mismatch.");
+    }
+  } else if (expected.anchorPosition === "latest") {
+    if (
+      value.anchor.anchor_position !== "latest" ||
+      value.anchor.event_id !== null
+    ) {
+      throw new Error("Completed-message neighbor latest anchor mismatch.");
+    }
+  }
+}
+
+/**
+ * @param {unknown} value
+ * @param {CompletedMessageNeighborExpectedIdentity} [expected]
+ * @returns {CompletedMessageNeighborsResponse}
+ */
+export function assertCompletedMessageNeighborsResponse(value, expected = {}) {
+  if (!isRecord(value)) {
+    throw new Error("Completed-message neighbor response must be an object.");
+  }
+  const anchor = value.anchor;
+  const boundaries = value.boundaries;
+  const proof = value.proof;
+  const validAnchor =
+    isRecord(anchor) &&
+    (anchor.anchor_position === "event" ||
+      anchor.anchor_position === "latest") &&
+    (typeof anchor.event_id === "string" || anchor.event_id === null) &&
+    (isNonnegativeSafeInteger(anchor.routec_stream_seq) ||
+      anchor.routec_stream_seq === null) &&
+    (anchor.anchor_position === "event"
+      ? nonEmptyString(anchor.event_id) &&
+        isNonnegativeSafeInteger(anchor.routec_stream_seq)
+      : anchor.event_id === null);
+  const indexNames = isRecord(proof) ? proof.navigation_index_names : null;
+  const indexVersion = isRecord(proof)
+    ? proof.navigation_index_version
+    : undefined;
+  const validIndexDiagnostics =
+    Array.isArray(indexNames) &&
+    indexNames.every(nonEmptyString) &&
+    new Set(indexNames).size === indexNames.length &&
+    (Number.isSafeInteger(indexVersion) || indexVersion === null) &&
+    ((indexVersion === null && indexNames.length === 0) ||
+      (Number.isSafeInteger(indexVersion) && indexNames.length > 0));
+  const validProof =
+    isRecord(proof) &&
+    proof.schema_version === COMPLETED_MESSAGE_NEIGHBOR_SCHEMA_VERSION &&
+    nonEmptyString(proof.lookup_source) &&
+    nonEmptyString(proof.lookup_strategy) &&
+    proof.order_by === "final_candidate_stream_seq" &&
+    proof.candidate_predicate === "complete_message_notification_candidate" &&
+    proof.completion_predicate === "complete_message_notification_completion" &&
+    validIndexDiagnostics &&
+    proof.raw_event_scan_limit === null &&
+    proof.raw_event_payload_returned === false &&
+    proof.message_body_returned === false;
+  if (
+    value.status !== "ok" ||
+    !nonEmptyString(value.session_id) ||
+    !nonEmptyString(value.matrix_room_id) ||
+    !validAnchor ||
+    !(value.previous === null || isNeighbor(value.previous)) ||
+    !(value.next === null || isNeighbor(value.next)) ||
+    !isRecord(boundaries) ||
+    typeof boundaries.no_completed_turns !== "boolean" ||
+    typeof boundaries.at_first_completed_message !== "boolean" ||
+    typeof boundaries.at_latest_completed_message !== "boolean" ||
+    !validProof ||
+    !(
+      value.committed_transcript_truth === undefined ||
+      value.committed_transcript_truth === "matrix_room_timeline"
+    ) ||
+    !(
+      value.routec_completed_message_neighbor_endpoint === undefined ||
+      value.routec_completed_message_neighbor_endpoint === true
+    ) ||
+    !(
+      value.completed_message_truth_source === undefined ||
+      value.completed_message_truth_source ===
+        "complete_message_notification_candidate_and_completion_predicates"
+    ) ||
+    value.raw_event_payload_returned !== false ||
+    value.message_body_returned !== false
+  ) {
+    throw new Error("Completed-message neighbor response failed validation.");
+  }
+  const validated = /** @type {CompletedMessageNeighborsResponse} */ (value);
+  if (
+    validated.boundaries.at_first_completed_message !==
+      (validated.previous === null) ||
+    validated.boundaries.at_latest_completed_message !==
+      (validated.next === null) ||
+    (boundaries.no_completed_turns &&
+      (validated.previous !== null ||
+        validated.next !== null ||
+        !boundaries.at_first_completed_message ||
+        !boundaries.at_latest_completed_message))
+  ) {
+    throw new Error("Completed-message neighbor boundaries are inconsistent.");
+  }
+  if (validated.anchor.anchor_position === "event") {
+    if (
+      (validated.previous &&
+        validated.previous.routec_stream_seq >=
+          validated.anchor.routec_stream_seq) ||
+      (validated.next &&
+        validated.next.routec_stream_seq <= validated.anchor.routec_stream_seq)
+    ) {
+      throw new Error("Completed-message neighbor ordering is inconsistent.");
+    }
+  }
+  assertRequestIdentity(validated, expected);
+  return validated;
+}
+
+/**
+ * @param {Omit<CompletedMessageNeighborsResponse, "status" | "raw_event_payload_returned" | "message_body_returned">} input
+ * @returns {CompletedMessageNeighborsResponse}
+ */
+export function buildCompletedMessageNeighborsResponse(input) {
+  return assertCompletedMessageNeighborsResponse(
+    {
+      status: "ok",
+      ...input,
+      raw_event_payload_returned: false,
+      message_body_returned: false,
+    },
+    {
+      sessionId: input.session_id,
+      matrixRoomId: input.matrix_room_id,
+      anchorEventId:
+        input.anchor.anchor_position === "event" ? input.anchor.event_id : null,
+      anchorPosition:
+        input.anchor.anchor_position === "latest" ? "latest" : null,
+    }
+  );
+}

package/dev/client/connectivity/test-completed-message-neighbor-click.mjs

@@ -0,0 +1,180 @@
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { test } from "node:test";
+
+import { createCompletedMessageNeighborClickCoordinator } from "./completed-message-neighbor-click.mjs";
+
+const response = (previous, next) => ({ previous, next });
+const selectTarget = (value, direction) => value[direction]?.event_id;
+
+function deferred() {
+  let resolve;
+  let reject;
+  const promise = new Promise((yes, no) => {
+    resolve = yes;
+    reject = no;
+  });
+  return { promise, resolve, reject };
+}
+
+test("mount, refresh, anchor and 100 local focus/scroll changes do not read", async () => {
+  let reads = 0;
+  const coordinator = createCompletedMessageNeighborClickCoordinator({
+    readNeighbors: async () => {
+      reads += 1;
+      return response(null, { event_id: "$next" });
+    },
+    selectTarget,
+  });
+  coordinator.setScope("session:room");
+  for (const signal of ["mount", "anchor-change", "session-data-refresh-after-five-seconds"]) {
+    assert.ok(signal);
+    assert.equal(coordinator.isLoading(), false);
+  }
+  for (let index = 0; index < 100; index += 1) {
+    // These represent timeline-local anchor/focus/scroll changes. The
+    // coordinator intentionally exposes no background-read operation.
+    assert.equal(coordinator.isLoading(), false);
+  }
+  assert.equal(reads, 0);
+
+  const result = await coordinator.click({
+    scope: "session:room",
+    roomId: "room",
+    direction: "next",
+    anchorPosition: "latest",
+  });
+  assert.equal(result.status, "target");
+  assert.equal(result.targetEventId, "$next");
+  assert.equal(reads, 1);
+});
+
+test("each direction uses exactly one request and preserves click-time anchor", async () => {
+  const requests = [];
+  const coordinator = createCompletedMessageNeighborClickCoordinator({
+    readNeighbors: async (request) => {
+      requests.push(request);
+      return response({ event_id: "$previous" }, { event_id: "$next" });
+    },
+    selectTarget,
+  });
+  coordinator.setScope("session:room");
+  const previous = await coordinator.click({
+    scope: "session:room",
+    roomId: "room",
+    direction: "previous",
+    anchorEventId: "$visible-anchor",
+  });
+  const next = await coordinator.click({
+    scope: "session:room",
+    roomId: "room",
+    direction: "next",
+    anchorPosition: "latest",
+  });
+  assert.deepEqual(
+    [previous.status, previous.targetEventId, next.status, next.targetEventId],
+    ["target", "$previous", "target", "$next"]
+  );
+  assert.deepEqual(requests, [
+    {
+      roomId: "room",
+      anchorEventId: "$visible-anchor",
+      anchorPosition: undefined,
+    },
+    { roomId: "room", anchorEventId: undefined, anchorPosition: "latest" },
+  ]);
+});
+
+test("double click is rejected while the first transaction owns its response", async () => {
+  const pending = deferred();
+  let reads = 0;
+  const coordinator = createCompletedMessageNeighborClickCoordinator({
+    readNeighbors: () => {
+      reads += 1;
+      return pending.promise;
+    },
+    selectTarget,
+  });
+  coordinator.setScope("session:room");
+  const first = coordinator.click({
+    scope: "session:room",
+    roomId: "room",
+    direction: "next",
+    anchorPosition: "latest",
+  });
+  const second = await coordinator.click({
+    scope: "session:room",
+    roomId: "room",
+    direction: "next",
+    anchorPosition: "latest",
+  });
+  assert.equal(second.status, "busy");
+  assert.equal(reads, 1);
+  pending.resolve(response(null, { event_id: "$fixed" }));
+  assert.equal((await first).targetEventId, "$fixed");
+});
+
+test("no-result and error release the next click", async () => {
+  const replies = [
+    response(null, null),
+    new Error("offline"),
+    response(null, { event_id: "$new" }),
+  ];
+  let reads = 0;
+  const coordinator = createCompletedMessageNeighborClickCoordinator({
+    readNeighbors: async () => {
+      const reply = replies[reads++];
+      if (reply instanceof Error) throw reply;
+      return reply;
+    },
+    selectTarget,
+  });
+  coordinator.setScope("session:room");
+  const click = () =>
+    coordinator.click({
+      scope: "session:room",
+      roomId: "room",
+      direction: "next",
+      anchorPosition: "latest",
+    });
+  assert.equal((await click()).status, "no_target");
+  assert.equal((await click()).status, "error");
+  const recovered = await click();
+  assert.equal(recovered.status, "target");
+  assert.equal(recovered.targetEventId, "$new");
+  assert.equal(reads, 3);
+});
+
+test("scope change rejects a late response and never substitutes a new target", async () => {
+  const pending = deferred();
+  const coordinator = createCompletedMessageNeighborClickCoordinator({
+    readNeighbors: () => pending.promise,
+    selectTarget,
+  });
+  coordinator.setScope("old-session:old-room");
+  const oldClick = coordinator.click({
+    scope: "old-session:old-room",
+    roomId: "old-room",
+    direction: "next",
+    anchorPosition: "latest",
+  });
+  coordinator.setScope("new-session:new-room");
+  pending.resolve(response(null, { event_id: "$old-target" }));
+  assert.equal((await oldClick).status, "stale");
+});
+
+test("RoomTimeline keeps the established focus and cold-load paths", () => {
+  const clientRoot = join(import.meta.dirname, "..");
+  const source = readFileSync(
+    join(clientRoot, "web-chat/src/app/features/room/RoomTimeline.tsx"),
+    "utf8"
+  );
+  assert.match(source, /requestOysterunActiveRoomTimelineFocus\(\{/);
+  assert.match(source, /void handleOpenEvent\(targetEventId\)/);
+  assert.match(source, /loadEventTimeline\(evtId\)/);
+  assert.match(source, /getOysterunHostSessionChatFocusPath\(targetEventId\)/);
+  assert.doesNotMatch(source, /debouncedRequestRouteCHostOwnerNeighbors/);
+  assert.doesNotMatch(source, /routeCHostOwnerNeighborPendingRequestRef/);
+  assert.doesNotMatch(source, /routeCHostOwnerNeighborInvalidationSeq/);
+});