@beyondwork/docx-react-component 1.0.106 → 1.0.108

package/src/api/v3/runtime/collab.ts

@@ -22,6 +22,29 @@ import {
   getRemoteCursorStates as getRemoteCursorStatesImpl,
   type RemoteCursorState,
 } from "../../../runtime/collab/remote-cursor-awareness.ts";
+import {
+  COMMAND_EVENT_SCHEMA_VERSION,
+  BROADCAST_COMMAND_TYPES,
+  LOCAL_ONLY_COMMAND_TYPES,
+} from "../../../runtime/collab/event-types.ts";
+import type {
+  RuntimeTelemetryEvent,
+  TelemetryChannel,
+} from "../../../runtime/debug/types.ts";
+
+const COMMAND_ORIGIN_KINDS = [
+  "local-typing",
+  "local-command",
+  "runtime",
+  "agent",
+  "import",
+  "field-refresh",
+  "unknown",
+] as const;
+
+type CommandOriginKind = (typeof COMMAND_ORIGIN_KINDS)[number];
+
+const COMMAND_ORIGIN_KIND_SET: ReadonlySet<string> = new Set(COMMAND_ORIGIN_KINDS);
 
 // Re-export so L11 consumers (remote-cursor-plugin) don't peek into
 // `src/runtime/collab/**` for the state type.
@@ -222,6 +245,292 @@ export const getRemoteCursorStatesMetadata: ApiV3FnMetadata = {
     "§Runtime API § runtime.collab.getRemoteCursorStates. Direct delegation to getRemoteCursorStates (src/runtime/collab/remote-cursor-awareness.ts). Extracts remote peers' cursor states from a Yjs Awareness instance, filtered by localClientId and sanitized (color allowlisted to safe-hex or hashed fallback). Backs coord-07 §2.1 collab expansion remainder — PM remote-cursor plugin flips from src/runtime/collab/** to this seam.",
 };
 
+/* ================================================================== */
+/*  getEventDiscipline — PE2 Slice 2 origin/channel read              */
+/* ================================================================== */
+
+export interface CollabEventDiscipline {
+  readonly commandEventSchemaVersion: typeof COMMAND_EVENT_SCHEMA_VERSION;
+  readonly commandEventChannel: "runtime-command-event";
+  readonly awarenessChannel: "awareness";
+  readonly commandOriginKinds: typeof COMMAND_ORIGIN_KINDS;
+  readonly commandOriginSources: readonly [
+    "keyboard",
+    "toolbar",
+    "context_menu",
+    "comment_panel",
+    "review_panel",
+    "api",
+    "runtime",
+    "agent",
+    "import",
+    "field_refresh",
+    "unspecified",
+  ];
+  readonly originCoverage: readonly CollabOriginCoverage[];
+  readonly broadcastCommandTypes: readonly string[];
+  readonly localOnlyCommandTypes: readonly string[];
+  readonly remoteReplay: {
+    readonly appliesThroughRuntime: true;
+    readonly validatesBaseDocFingerprint: true;
+    readonly rejectsSchemaMismatch: true;
+    readonly coalescesByDefault: true;
+  };
+  readonly awarenessInputs: readonly [
+    "presence",
+    "remote-cursor",
+    "remote-selection",
+    "hover",
+    "typing-indicator",
+    "viewing-scope",
+  ];
+}
+
+export interface CollabOriginCoverage {
+  readonly class:
+    | "local-typing"
+    | "local-command"
+    | "remote-runtime-command-event"
+    | "remote-awareness"
+    | "agent"
+    | "import"
+    | "field-refresh";
+  readonly channel: "runtime-command-event" | "awareness";
+  readonly canonicalMutation: boolean;
+  readonly commandOriginKinds?: readonly CollabEventDiscipline["commandOriginKinds"][number][];
+  readonly commandOriginSources?: readonly CollabEventDiscipline["commandOriginSources"][number][];
+  readonly awarenessInputs?: readonly CollabEventDiscipline["awarenessInputs"][number][];
+}
+
+export interface CollabRemoteReplayState {
+  readonly attached: boolean;
+  readonly readOnly: boolean;
+  readonly baseDocFingerprint: string | null;
+  readonly appliedEventCount: number;
+  readonly remoteActivitySignal: {
+    readonly aborted: boolean;
+  };
+  readonly guardrails: {
+    readonly appliesThroughRuntime: true;
+    readonly validatesBaseDocFingerprint: true;
+    readonly rejectsSchemaMismatch: true;
+    readonly suppressesOutboundWhenReadOnly: true;
+    readonly suppressesInboundWhenReadOnly: true;
+    readonly coalescesByDefault: true;
+  };
+  readonly __mock?: true;
+}
+
+export interface CollabEventTelemetryChannelSummary {
+  readonly channel: Extract<TelemetryChannel, "api" | "command" | "collab">;
+  readonly enabled: boolean;
+  readonly bufferedEventCount: number;
+  readonly persistedInSessionRing: true;
+  readonly subscriptionCapable: true;
+}
+
+export interface CollabEventTelemetry {
+  readonly channels: readonly CollabEventTelemetryChannelSummary[];
+  readonly counters: {
+    readonly commandEventCount: number;
+    readonly collabEventCount: number;
+    readonly uxResponseEventCount: number;
+    readonly remoteReplayEventCount: number;
+    readonly schemaMismatchEventCount: number;
+    readonly totalAuditableEventCount: number;
+  };
+  readonly originKindCounts: Readonly<Partial<Record<CommandOriginKind, number>>>;
+  readonly lastEventTypes: readonly string[];
+  readonly retention: {
+    readonly kind: "session-ring-buffer";
+    readonly tailReadLimit: 256;
+    readonly cost: "caller-paid-snapshot";
+  };
+}
+
+export const getEventDisciplineMetadata: ApiV3FnMetadata = {
+  name: "runtime.collab.getEventDiscipline",
+  status: "live",
+  sourceLayer: "workflow-review",
+  liveEvidence: {
+    runnerTest: "test/api/v3/behavioral-coverage.test.ts",
+    commit: "refactor-07-pe2-origin-discipline",
+  },
+  uxIntent: { uiVisible: false, expectsUxResponse: "none" },
+  agentMetadata: {
+    readOrMutate: "read",
+    boundedScope: "session",
+    auditCategory: "collab-origin-discipline",
+  },
+  stateClass: "B-session",
+  persistsTo: "none",
+  broadcastsVia: "awareness",
+  rwdReference:
+    "§Runtime API § runtime.collab.getEventDiscipline. PE2 Slice-2 origin/channel read: exposes the distinction between runtime command-event replay and Awareness/session inputs. Command events carry normalized origin.kind/source on the shared command log; Awareness inputs remain session-only and must not mutate canonical document state.",
+};
+
+export const getRemoteReplayStateMetadata: ApiV3FnMetadata = {
+  name: "runtime.collab.getRemoteReplayState",
+  status: "live-with-adapter",
+  sourceLayer: "workflow-review",
+  liveEvidence: {
+    runnerTest: "test/api/v3/behavioral-coverage.test.ts",
+    commit: "refactor-07-pe2-remote-replay-state",
+  },
+  mockShape: {
+    deterministic: true,
+    seededFrom: "fixed",
+    shapeDescription:
+      "Detached remote replay snapshot — attached:false, readOnly:false, baseDocFingerprint:null, appliedEventCount:0, remoteActivitySignal.aborted:false. Emitted only when the handle carries no `collabSync`; hosts that pass RuntimeCollabSyncHandle get live replay guard state.",
+    carriesMockFlag: true,
+  },
+  uxIntent: { uiVisible: false, expectsUxResponse: "none" },
+  agentMetadata: {
+    readOrMutate: "read",
+    boundedScope: "session",
+    auditCategory: "collab-remote-replay-state",
+  },
+  stateClass: "B-session",
+  persistsTo: "none",
+  broadcastsVia: "awareness",
+  rwdReference:
+    "§Runtime API § runtime.collab.getRemoteReplayState. PE2 Slice-2 replay discipline read: projects the host-wired RuntimeCollabSyncHandle into plain values — base-doc fingerprint, read-only quarantine, applied-event dedup count, and remote-activity signal state — without exposing Yjs or runtime sync internals. The metadata keeps broadcastsVia:'awareness' because this is B-session posture shared as session awareness state; command-event replay remains the mutation transport and is described by getEventDiscipline.remoteReplay.",
+};
+
+export const getEventTelemetryMetadata: ApiV3FnMetadata = {
+  name: "runtime.collab.getEventTelemetry",
+  status: "live",
+  sourceLayer: "workflow-review",
+  liveEvidence: {
+    runnerTest: "test/api/v3/behavioral-coverage.test.ts",
+    commit: "refactor-07-pe2-event-telemetry-readback",
+  },
+  uxIntent: { uiVisible: false, expectsUxResponse: "none" },
+  agentMetadata: {
+    readOrMutate: "read",
+    boundedScope: "session",
+    auditCategory: "collab-event-telemetry",
+    contextPromptShape:
+      "Session telemetry counters for command/collab/api event channels, including origin-kind and replay/schema-mismatch counts.",
+  },
+  stateClass: "B-session",
+  persistsTo: "none",
+  broadcastsVia: "awareness",
+  rwdReference:
+    "§Runtime API § runtime.collab.getEventTelemetry. PE2 Slice-2 event/audit readback over the session TelemetryBus ring buffers. This is a caller-paid snapshot over command/collab/api tails, not a hot-path subscription primitive. Exposes persisted per-channel tail counts and origin-kind counters for command/collab/api events; `lastEventTypes` returns the 10 most recent auditable event types ordered by TelemetryBus seq across the three channels. Callers that need live updates subscribe to the same TelemetryBus channels through the runtime debug facet rather than inferring from Yjs internals.",
+};
+
+function eventOriginKind(event: RuntimeTelemetryEvent): CommandOriginKind | null {
+  const payload = event.payload;
+  if (!payload || typeof payload !== "object") return null;
+  const origin = (payload as { readonly origin?: unknown }).origin;
+  if (!origin || typeof origin !== "object") return null;
+  const kind = (origin as { readonly kind?: unknown }).kind;
+  return typeof kind === "string" && COMMAND_ORIGIN_KIND_SET.has(kind)
+    ? kind as CommandOriginKind
+    : null;
+}
+
+function countByOriginKind(
+  eventSets: readonly (readonly RuntimeTelemetryEvent[])[],
+): Partial<Record<CommandOriginKind, number>> {
+  const counts: Partial<Record<CommandOriginKind, number>> = {};
+  for (const events of eventSets) {
+    for (const event of events) {
+      const kind = eventOriginKind(event);
+      if (!kind) continue;
+      counts[kind] = (counts[kind] ?? 0) + 1;
+    }
+  }
+  return counts;
+}
+
+function countMatchingEvents(
+  eventSets: readonly (readonly RuntimeTelemetryEvent[])[],
+  predicate: (event: RuntimeTelemetryEvent) => boolean,
+): number {
+  let count = 0;
+  for (const events of eventSets) {
+    for (const event of events) {
+      if (predicate(event)) count += 1;
+    }
+  }
+  return count;
+}
+
+function eventSeq(event: RuntimeTelemetryEvent): number {
+  return typeof event.seq === "number" ? event.seq : 0;
+}
+
+function collectLastEventTypes(
+  eventSets: readonly (readonly RuntimeTelemetryEvent[])[],
+): readonly string[] {
+  const recent: RuntimeTelemetryEvent[] = [];
+  for (const events of eventSets) {
+    for (const event of events) {
+      const insertAt = recent.findIndex((existing) => eventSeq(event) < eventSeq(existing));
+      if (insertAt === -1) recent.push(event);
+      else recent.splice(insertAt, 0, event);
+      if (recent.length > 10) recent.shift();
+    }
+  }
+  return recent.map((event) => event.type);
+}
+
+function summarizeEventTelemetry(runtime: RuntimeApiHandle): CollabEventTelemetry {
+  const bus = runtime.debug.bus;
+  const commandEvents = bus.tail("command", 256);
+  const collabEvents = bus.tail("collab", 256);
+  const apiEvents = bus.tail("api", 256);
+  const auditableEventSets = [commandEvents, collabEvents, apiEvents] as const;
+  const channels = bus.getChannels();
+  const channelSummaries: CollabEventTelemetryChannelSummary[] = [
+    {
+      channel: "command",
+      enabled: channels.command,
+      bufferedEventCount: commandEvents.length,
+      persistedInSessionRing: true,
+      subscriptionCapable: true,
+    },
+    {
+      channel: "collab",
+      enabled: channels.collab,
+      bufferedEventCount: collabEvents.length,
+      persistedInSessionRing: true,
+      subscriptionCapable: true,
+    },
+    {
+      channel: "api",
+      enabled: channels.api,
+      bufferedEventCount: apiEvents.length,
+      persistedInSessionRing: true,
+      subscriptionCapable: true,
+    },
+  ];
+
+  return {
+    channels: channelSummaries,
+    counters: {
+      commandEventCount: commandEvents.length,
+      collabEventCount: collabEvents.length,
+      uxResponseEventCount: apiEvents.filter((event) => event.type.startsWith("ux.response.")).length,
+      remoteReplayEventCount: collabEvents.filter((event) => event.type.includes("remote-replay")).length,
+      schemaMismatchEventCount: countMatchingEvents(
+        auditableEventSets,
+        (event) => event.type.includes("schema_mismatch"),
+      ),
+      totalAuditableEventCount: commandEvents.length + collabEvents.length + apiEvents.length,
+    },
+    originKindCounts: countByOriginKind(auditableEventSets),
+    lastEventTypes: collectLastEventTypes(auditableEventSets),
+    retention: {
+      kind: "session-ring-buffer",
+      tailReadLimit: 256,
+      cost: "caller-paid-snapshot",
+    },
+  };
+}
+
 /* ================================================================== */
 /*  family factory                                                    */
 /* ================================================================== */
@@ -310,6 +619,159 @@ export function createCollabFamily(runtime: RuntimeApiHandle) {
       return getRemoteCursorStatesImpl(input.awareness, input.localClientId);
     },
 
+    getEventDiscipline(): CollabEventDiscipline {
+      // @endStateApi — live. Static protocol read for PE2 origin
+      // discipline: command events are replayed through runtime; awareness
+      // inputs are session overlays only. Kept here so agents and debug
+      // consumers do not infer transport policy from Yjs internals.
+      return {
+        commandEventSchemaVersion: COMMAND_EVENT_SCHEMA_VERSION,
+        commandEventChannel: "runtime-command-event",
+        awarenessChannel: "awareness",
+        commandOriginKinds: COMMAND_ORIGIN_KINDS,
+        commandOriginSources: [
+          "keyboard",
+          "toolbar",
+          "context_menu",
+          "comment_panel",
+          "review_panel",
+          "api",
+          "runtime",
+          "agent",
+          "import",
+          "field_refresh",
+          "unspecified",
+        ],
+        originCoverage: [
+          {
+            class: "local-typing",
+            channel: "runtime-command-event",
+            canonicalMutation: true,
+            commandOriginKinds: ["local-typing"],
+            commandOriginSources: ["keyboard"],
+          },
+          {
+            class: "local-command",
+            channel: "runtime-command-event",
+            canonicalMutation: true,
+            commandOriginKinds: ["local-command"],
+            commandOriginSources: [
+              "toolbar",
+              "context_menu",
+              "comment_panel",
+              "review_panel",
+              "api",
+            ],
+          },
+          {
+            class: "remote-runtime-command-event",
+            channel: "runtime-command-event",
+            canonicalMutation: true,
+            commandOriginKinds: ["runtime"],
+            commandOriginSources: ["runtime"],
+          },
+          {
+            class: "remote-awareness",
+            channel: "awareness",
+            canonicalMutation: false,
+            awarenessInputs: [
+              "presence",
+              "remote-cursor",
+              "remote-selection",
+              "hover",
+              "typing-indicator",
+              "viewing-scope",
+            ],
+          },
+          {
+            class: "agent",
+            channel: "runtime-command-event",
+            canonicalMutation: true,
+            commandOriginKinds: ["agent"],
+            commandOriginSources: ["agent"],
+          },
+          {
+            class: "import",
+            channel: "runtime-command-event",
+            canonicalMutation: true,
+            commandOriginKinds: ["import"],
+            commandOriginSources: ["import"],
+          },
+          {
+            class: "field-refresh",
+            channel: "runtime-command-event",
+            canonicalMutation: true,
+            commandOriginKinds: ["field-refresh"],
+            commandOriginSources: ["field_refresh"],
+          },
+        ],
+        broadcastCommandTypes: [...BROADCAST_COMMAND_TYPES].sort(),
+        localOnlyCommandTypes: [...LOCAL_ONLY_COMMAND_TYPES].sort(),
+        remoteReplay: {
+          appliesThroughRuntime: true,
+          validatesBaseDocFingerprint: true,
+          rejectsSchemaMismatch: true,
+          coalescesByDefault: true,
+        },
+        awarenessInputs: [
+          "presence",
+          "remote-cursor",
+          "remote-selection",
+          "hover",
+          "typing-indicator",
+          "viewing-scope",
+        ],
+      };
+    },
+
+    getRemoteReplayState(): CollabRemoteReplayState & Partial<MockPayload> {
+      // @endStateApi — live-with-adapter. Dynamic counterpart to
+      // getEventDiscipline(): exposes the current command-event replay
+      // guard posture as plain values while keeping the Yjs sync handle
+      // behind the RuntimeApiHandle.
+      const sync = runtime.collabSync;
+      const guardrails = {
+        appliesThroughRuntime: true,
+        validatesBaseDocFingerprint: true,
+        rejectsSchemaMismatch: true,
+        suppressesOutboundWhenReadOnly: true,
+        suppressesInboundWhenReadOnly: true,
+        coalescesByDefault: true,
+      } as const;
+      if (sync) {
+        return {
+          attached: true,
+          readOnly: sync.isReadOnly(),
+          baseDocFingerprint: sync.getBaseDocFingerprint(),
+          appliedEventCount: sync.getAppliedEventCount(),
+          remoteActivitySignal: {
+            aborted: sync.getRemoteActivitySignal().aborted,
+          },
+          guardrails,
+        };
+      }
+      return mockPayload(
+        "handle.collabSync not wired; hosts pass RuntimeCollabSyncHandle from createRuntimeCollabSync(...) to expose live replay guard state",
+        "CollabRemoteReplayState",
+        {
+          attached: false,
+          readOnly: false,
+          baseDocFingerprint: null,
+          appliedEventCount: 0,
+          remoteActivitySignal: { aborted: false },
+          guardrails,
+        },
+      );
+    },
+
+    getEventTelemetry(): CollabEventTelemetry {
+      // @endStateApi — live. Reads the session TelemetryBus tails as the
+      // durable-enough PE2 event/audit counter store for command/collab/api
+      // channels. Does not allocate or subscribe unless telemetry has already
+      // been enabled by the host/debug surface.
+      return summarizeEventTelemetry(runtime);
+    },
+
     getMetadataIntegrity(): CollabMetadataIntegritySnapshot & Partial<MockPayload> {
       // @endStateApi — live-with-adapter. Coord-07 §2.1 collab expansion
       // — exposes the tamper-gate state for agents without reaching into