@beyondwork/docx-react-component 1.0.67 → 1.0.70

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

@@ -0,0 +1,331 @@
+/**
+ * @endStateApi v3 — `runtime.collab` family.
+ *
+ * getSessionInfo (live-with-adapter) / getPresence (live-with-adapter) /
+ * getPosture (live-with-adapter).
+ *
+ * Shape note: "Runtime API + Collab" is the layer-07 name per the refactor
+ * master plan. `RuntimeApiHandle` now exposes `collabSession` as an
+ * optional accessor — hosts that wire Yjs/Awareness supply it, and the
+ * getPresence + getPosture functions delegate to
+ * `CollabSession.getPresenceSnapshot` / `.getCollabPosture` directly.
+ * Headless callers that don't wire collab get a deterministic mock
+ * fallback, so the family remains safe to call on any handle.
+ */
+
+import type { Awareness } from "y-protocols/awareness";
+import type { RuntimeApiHandle } from "../_runtime-handle.ts";
+import type { ApiV3FnMetadata, MockPayload } from "../_layer-metadata.ts";
+import { mockPayload } from "../_mocks.ts";
+import type { MetadataIntegrity } from "../../public-types.ts";
+import {
+  getRemoteCursorStates as getRemoteCursorStatesImpl,
+  type RemoteCursorState,
+} from "../../../runtime/collab/remote-cursor-awareness.ts";
+
+// Re-export so L11 consumers (remote-cursor-plugin) don't peek into
+// `src/runtime/collab/**` for the state type.
+export type { RemoteCursorState };
+
+/**
+ * L11-facing named re-export of the remote-cursor-awareness helper
+ * (coord-11 §4.4 · §4.8 collab-family migration). `remote-cursor-plugin.ts`
+ * — a pure PM plugin with no runtime handle in scope — uses this form
+ * so it doesn't reach into `src/runtime/collab/**` directly. Identity
+ * re-export of the same impl the factory binds; mirrors the pattern
+ * `chart.ts` established for the pure chart helpers.
+ */
+export { getRemoteCursorStatesImpl as getRemoteCursorStates };
+
+/* ================================================================== */
+/*  getSessionInfo — live-with-adapter                                */
+/* ================================================================== */
+
+export interface CollabSessionInfo {
+  readonly documentId: string;
+  readonly docId: string;
+  readonly sessionVersion: string;
+  readonly schemaVersion: string;
+  readonly hasWorkflowOverlay: boolean;
+  readonly hasSharedWorkflowState: boolean;
+}
+
+export const getSessionInfoMetadata: ApiV3FnMetadata = {
+  name: "runtime.collab.getSessionInfo",
+  status: "live-with-adapter",
+  sourceLayer: "package-session",
+  liveEvidence: {
+    runnerTest: "test/api/v3/behavioral-coverage.test.ts",
+    commit: "layer-07-closure-pass",
+  },
+  uxIntent: { uiVisible: false, expectsUxResponse: "none" },
+  agentMetadata: {
+    readOrMutate: "read",
+    boundedScope: "session",
+    auditCategory: "collab-session-info",
+  },
+  stateClass: "B-session",
+  persistsTo: "none",
+  broadcastsVia: "awareness",
+  rwdReference:
+    "§Runtime API § runtime.collab.getSessionInfo. Adapter reads handle.getSessionState() + handle.getWorkflowOverlay() and projects a session-scoped CollabSessionInfo. Promotes to `live` when RuntimeApiHandle exposes a direct `collabSession` accessor.",
+};
+
+/* ================================================================== */
+/*  getPresence — mock (collab facet not yet on handle)               */
+/* ================================================================== */
+
+export interface CollabPresenceSnapshot {
+  readonly peers: readonly unknown[];
+  readonly transportStatus: "online" | "syncing" | "offline";
+  readonly queuedLocalEvents: number;
+  readonly __mock?: true;
+}
+
+export const getPresenceMetadata: ApiV3FnMetadata = {
+  name: "runtime.collab.getPresence",
+  status: "live-with-adapter",
+  sourceLayer: "workflow-review",
+  liveEvidence: {
+    runnerTest: "test/api/v3/behavioral-coverage.test.ts",
+    commit: "layer-07-closure-pass-graduation",
+  },
+  mockShape: {
+    deterministic: true,
+    seededFrom: "fixed",
+    shapeDescription:
+      "Empty presence snapshot — peers:[], transportStatus:'offline', queuedLocalEvents:0. Emitted only when the handle carries no `collabSession` (headless drivers, pre-wire tests). Hosts that supply `collabSession` get the live PresenceSnapshot projected into the v3 shape.",
+    carriesMockFlag: true,
+  },
+  uxIntent: { uiVisible: false, expectsUxResponse: "none" },
+  agentMetadata: {
+    readOrMutate: "read",
+    boundedScope: "session",
+    auditCategory: "collab-presence",
+  },
+  stateClass: "B-session",
+  persistsTo: "none",
+  broadcastsVia: "awareness",
+  rwdReference:
+    "§Runtime API § runtime.collab.getPresence. Adapter delegates to handle.collabSession.getPresenceSnapshot() when the handle carries one; falls back to deterministic mock when absent. Promotes to `live` when collabSession is no longer optional (hosts default-attach).",
+};
+
+/* ================================================================== */
+/*  getPosture — mock (collab facet not yet on handle)                */
+/* ================================================================== */
+
+export interface CollabPostureSnapshot {
+  readonly role: "author" | "reviewer" | "observer" | "unattached";
+  readonly peerCount: number;
+  readonly transportStatus: "online" | "syncing" | "offline";
+  readonly __mock?: true;
+}
+
+export const getPostureMetadata: ApiV3FnMetadata = {
+  name: "runtime.collab.getPosture",
+  status: "live-with-adapter",
+  sourceLayer: "workflow-review",
+  liveEvidence: {
+    runnerTest: "test/api/v3/behavioral-coverage.test.ts",
+    commit: "layer-07-closure-pass-graduation",
+  },
+  mockShape: {
+    deterministic: true,
+    seededFrom: "fixed",
+    shapeDescription:
+      "Default posture — role:'unattached', peerCount:0, transportStatus:'offline'. Emitted only when the handle carries no `collabSession`. Hosts that supply `collabSession` get the live CollabPosture projected into the v3 shape.",
+    carriesMockFlag: true,
+  },
+  uxIntent: { uiVisible: false, expectsUxResponse: "none" },
+  agentMetadata: {
+    readOrMutate: "read",
+    boundedScope: "session",
+    auditCategory: "collab-posture",
+  },
+  stateClass: "B-session",
+  persistsTo: "none",
+  broadcastsVia: "awareness",
+  rwdReference:
+    "§Runtime API § runtime.collab.getPosture. Adapter delegates to handle.collabSession.getCollabPosture() when the handle carries one; falls back to deterministic mock when absent. Promotes to `live` when collabSession is no longer optional (hosts default-attach).",
+};
+
+/* ================================================================== */
+/*  getMetadataIntegrity — live-with-adapter (collab expansion)       */
+/* ================================================================== */
+
+/**
+ * Snapshot shape — wraps the `MetadataIntegrity` union
+ * (`"unsigned" | "verified" | "tampered"`) in an object so the mock
+ * fallback can carry `__mock: true`. Agents reading the tamper gate
+ * branch on `snapshot.integrity`.
+ */
+export interface CollabMetadataIntegritySnapshot {
+  readonly integrity: MetadataIntegrity;
+  readonly __mock?: true;
+}
+
+export const getMetadataIntegrityMetadata: ApiV3FnMetadata = {
+  name: "runtime.collab.getMetadataIntegrity",
+  status: "live-with-adapter",
+  sourceLayer: "workflow-review",
+  liveEvidence: {
+    runnerTest: "test/api/v3/behavioral-coverage.test.ts",
+    commit: "refactor-07-collab-expansion-tamper-read-2026-04-23",
+  },
+  mockShape: {
+    deterministic: true,
+    seededFrom: "fixed",
+    shapeDescription:
+      "Default integrity 'unsigned' — emitted only when the handle carries no `collabSession` (headless drivers, pre-wire tests). Hosts that supply `collabSession` get the live MetadataIntegrity from the tamper-gate.",
+    carriesMockFlag: true,
+  },
+  uxIntent: { uiVisible: false, expectsUxResponse: "none" },
+  agentMetadata: {
+    readOrMutate: "read",
+    boundedScope: "session",
+    auditCategory: "collab-tamper-read",
+  },
+  stateClass: "B-session",
+  persistsTo: "none",
+  broadcastsVia: "awareness",
+  rwdReference:
+    "§Runtime API § runtime.collab.getMetadataIntegrity. Adapter delegates to handle.collabSession.getMetadataIntegrity() when the handle carries one; falls back to a deterministic 'unsigned' snapshot otherwise. Backs coord-07 §2.1 collab expansion: agent-facing tamper-state read without reaching into `src/runtime/workflow/tamper-gate.ts`. Promotes to `live` when collabSession is no longer optional.",
+};
+
+/* ================================================================== */
+/*  getRemoteCursorStates — live (collab expansion remainder)         */
+/* ================================================================== */
+
+export interface GetRemoteCursorStatesInput {
+  readonly awareness: Awareness;
+  readonly localClientId: number;
+}
+
+export const getRemoteCursorStatesMetadata: ApiV3FnMetadata = {
+  name: "runtime.collab.getRemoteCursorStates",
+  status: "live",
+  sourceLayer: "workflow-review",
+  liveEvidence: {
+    runnerTest: "test/api/v3/behavioral-coverage.test.ts",
+    commit: "refactor-07-collab-remote-cursor-2026-04-23",
+  },
+  uxIntent: { uiVisible: false, expectsUxResponse: "none" },
+  agentMetadata: {
+    readOrMutate: "read",
+    boundedScope: "session",
+    auditCategory: "collab-remote-cursor-read",
+  },
+  stateClass: "B-session",
+  persistsTo: "none",
+  broadcastsVia: "awareness",
+  rwdReference:
+    "§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.",
+};
+
+/* ================================================================== */
+/*  family factory                                                    */
+/* ================================================================== */
+
+export function createCollabFamily(runtime: RuntimeApiHandle) {
+  return {
+    getSessionInfo(): CollabSessionInfo {
+      // @endStateApi — live-with-adapter. Composes handle.getSessionState()
+      // + handle.getWorkflowOverlay() into a session-scoped projection.
+      // No __mock flag — every field is sourced from real runtime state.
+      const state = runtime.getSessionState();
+      const overlay = runtime.getWorkflowOverlay();
+      return {
+        documentId: state.documentId,
+        docId: state.docId ?? state.documentId,
+        sessionVersion: state.sessionVersion ?? "editor-session-state/1",
+        schemaVersion: String(state.schemaVersion ?? "cds/1.0.0"),
+        hasWorkflowOverlay: overlay !== null && overlay !== undefined,
+        hasSharedWorkflowState: Boolean(
+          overlay && typeof overlay === "object" && "sharedWorkflowState" in overlay,
+        ),
+      };
+    },
+
+    getPresence(): CollabPresenceSnapshot & Partial<MockPayload> {
+      // @endStateApi — live-with-adapter. When the host wires
+      // handle.collabSession, delegates to getPresenceSnapshot() and
+      // projects into the v3 shape. Otherwise returns the mock fallback
+      // so headless drivers stay safe.
+      const session = runtime.collabSession;
+      if (session) {
+        const live = session.getPresenceSnapshot();
+        return {
+          peers: live.peers as readonly unknown[],
+          transportStatus: live.transportStatus as "online" | "syncing" | "offline",
+          queuedLocalEvents: live.queuedLocalEvents,
+        };
+      }
+      return mockPayload(
+        "handle.collabSession not wired; hosts attach it via createCollabSession({ydoc,awareness,...}) and pass through to createApiV3",
+        "CollabPresenceSnapshot",
+        {
+          peers: [] as readonly unknown[],
+          transportStatus: "offline" as const,
+          queuedLocalEvents: 0,
+        },
+      );
+    },
+
+    getPosture(): CollabPostureSnapshot & Partial<MockPayload> {
+      // @endStateApi — live-with-adapter. Same delegation pattern as
+      // getPresence — live via handle.collabSession.getCollabPosture()
+      // or mock fallback.
+      const session = runtime.collabSession;
+      if (session) {
+        const live = session.getCollabPosture();
+        // CollabPosture.transport is "none" | "attached"; v3 surface
+        // reshapes to the consumer-friendly "online/syncing/offline"
+        // triad. `attached` → `online` at this layer; hosts wanting
+        // syncing granularity pass a transportStatus override.
+        const transportStatus: "online" | "syncing" | "offline" =
+          live.transport === "attached" ? "online" : "offline";
+        return {
+          role: live.role as "author" | "reviewer" | "observer" | "unattached",
+          peerCount: live.peers,
+          transportStatus,
+        };
+      }
+      return mockPayload(
+        "handle.collabSession not wired; hosts attach it via createCollabSession({ydoc,awareness,...}) and pass through to createApiV3",
+        "CollabPostureSnapshot",
+        {
+          role: "unattached" as const,
+          peerCount: 0,
+          transportStatus: "offline" as const,
+        },
+      );
+    },
+
+    getRemoteCursorStates(input: GetRemoteCursorStatesInput): RemoteCursorState[] {
+      // @endStateApi — live. Pure delegation; `awareness` is the host-
+      // owned Yjs Awareness instance. Returns [] when no remote peer has
+      // published a cursor state. Color is sanitized to a safe-hex
+      // allowlist or hashed fallback by the underlying helper — callers
+      // can interpolate the value into inline style without re-validating.
+      return getRemoteCursorStatesImpl(input.awareness, input.localClientId);
+    },
+
+    getMetadataIntegrity(): CollabMetadataIntegritySnapshot & Partial<MockPayload> {
+      // @endStateApi — live-with-adapter. Coord-07 §2.1 collab expansion
+      // — exposes the tamper-gate state for agents without reaching into
+      // `src/runtime/workflow/tamper-gate.ts`. Live via
+      // handle.collabSession.getMetadataIntegrity() or "unsigned"
+      // mock fallback (the same default the fresh tamper-gate reports
+      // before any signed payload attaches).
+      const session = runtime.collabSession;
+      if (session) {
+        return { integrity: session.getMetadataIntegrity() };
+      }
+      return mockPayload(
+        "handle.collabSession not wired; hosts attach it via createCollabSession({ydoc,awareness,...}) and pass through to createApiV3",
+        "CollabMetadataIntegritySnapshot",
+        { integrity: "unsigned" as MetadataIntegrity },
+      );
+    },
+  };
+}

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

@@ -0,0 +1,236 @@
+/**
+ * @endStateApi v3 — `runtime.content` family.
+ *
+ * search (live-with-adapter) / getLocation (live-with-adapter) /
+ * replaceText (live-with-adapter) / insertFragment (live-with-adapter).
+ *
+ * 2026-04-23 — insertFragment graduated off the last v3 mock. Routes
+ * through the L08 compiler-service facade (same path as replaceText +
+ * ai.applyReplacementScope) carrying `proposedContent.kind === "structured"`.
+ * v3 is now 100% non-mock.
+ */
+
+import type { RuntimeApiHandle } from "../_runtime-handle.ts";
+import type { ApiV3FnMetadata } from "../_layer-metadata.ts";
+import type { CanonicalDocumentFragment } from "../../public-types.ts";
+import { emitUxResponse } from "../_ux-response.ts";
+import { createScopeCompilerService } from "../../../runtime/scopes/index.ts";
+
+/* ================================================================== */
+/*  search                                                            */
+/* ================================================================== */
+
+export interface SearchInput {
+  readonly query: string;
+  readonly caseSensitive?: boolean;
+  readonly limit?: number;
+}
+
+export const searchMetadata: ApiV3FnMetadata = {
+  name: "runtime.content.search",
+  status: "live-with-adapter",
+  sourceLayer: "canonical",
+  liveEvidence: {
+    runnerTest: "test/api/v3/live-parity.test.ts",
+    commit: "phase-p-prime",
+  },
+  uxIntent: { uiVisible: false, expectsUxResponse: "none" },
+  agentMetadata: { readOrMutate: "read", boundedScope: "document", auditCategory: "search" },
+  stateClass: "A-canonical",
+  persistsTo: "canonical",
+  rwdReference: "§Runtime API § runtime.content.search",
+};
+
+/* ================================================================== */
+/*  getLocation                                                       */
+/* ================================================================== */
+
+export interface GetLocationInput {
+  readonly scopeId?: string;
+  readonly blockId?: string;
+}
+
+export const getLocationMetadata: ApiV3FnMetadata = {
+  name: "runtime.content.getLocation",
+  status: "live-with-adapter",
+  sourceLayer: "canonical",
+  liveEvidence: {
+    runnerTest: "test/api/v3/live-parity.test.ts",
+    commit: "layer-07-closure-pass",
+  },
+  uxIntent: { uiVisible: false, expectsUxResponse: "none" },
+  agentMetadata: { readOrMutate: "read", boundedScope: "scope", auditCategory: "location" },
+  stateClass: "A-canonical",
+  persistsTo: "canonical",
+  rwdReference:
+    "§Runtime API § runtime.content.getLocation. Adapter: scopeId path composes handle.getScope(scopeId) + handle.getLocationForAnchor(scope.anchor) — typed L07 seam, no debug-facet dependency. blockId path is NOT supported today — no shipped blockId → anchor resolver exists.",
+};
+
+/* ================================================================== */
+/*  replaceText                                                       */
+/* ================================================================== */
+
+export interface ReplaceTextInput {
+  readonly scopeId: string;
+  readonly replacement: string;
+}
+
+export interface ReplaceTextResult {
+  readonly applied: boolean;
+  readonly reason?: string;
+}
+
+export const replaceTextMetadata: ApiV3FnMetadata = {
+  name: "runtime.content.replaceText",
+  status: "live-with-adapter",
+  sourceLayer: "semantic-scope-compiler",
+  liveEvidence: {
+    runnerTest: "test/runtime/scopes/replacement-text-only.test.ts",
+    commit: "refactor-08-slice-5",
+  },
+  uxIntent: { uiVisible: true, expectsUxResponse: "inline-change", expectedDelta: "text inside target scope changes" },
+  agentMetadata: { readOrMutate: "mutate", boundedScope: "scope", auditCategory: "text-replacement" },
+  stateClass: "A-canonical",
+  persistsTo: "canonical",
+  broadcastsVia: "crdt",
+  rwdReference:
+    "§Runtime API § runtime.content.replaceText. Adapter: resolves scopeId, re-validates, compiles per-kind plan, dispatches via DocumentRuntime.applyScopeReplacement, emits one ScopeActionAudit. No AI action policy here — this is the host/UI path (actorId defaults to 'user').",
+};
+
+/* ================================================================== */
+/*  insertFragment                                                    */
+/* ================================================================== */
+
+/**
+ * Scope-scoped structured-fragment insert. `scopeId` names the
+ * compiled scope whose range will be replaced with `fragment`; this
+ * matches the `replaceText` contract but takes a structured
+ * `CanonicalDocumentFragment` payload instead of flat text. Under the
+ * L08 compiler pipeline the "insert" resolves to a `fragment-replace`
+ * step dispatched through the runtime's existing `insertFragment`
+ * command — see coord-08 §8 (paragraph-kind shipped 2026-04-22).
+ */
+export interface InsertFragmentInput {
+  readonly scopeId: string;
+  readonly fragment: CanonicalDocumentFragment;
+}
+
+export interface InsertFragmentResult {
+  readonly applied: boolean;
+  readonly reason?: string;
+}
+
+export const insertFragmentMetadata: ApiV3FnMetadata = {
+  name: "runtime.content.insertFragment",
+  status: "live-with-adapter",
+  sourceLayer: "semantic-scope-compiler",
+  liveEvidence: {
+    runnerTest: "test/api/v3/live-parity.test.ts",
+    commit: "refactor-07-insert-fragment-graduation-2026-04-23",
+  },
+  uxIntent: {
+    uiVisible: true,
+    expectsUxResponse: "surface-refresh",
+    expectedDelta: "selected scope is replaced with the supplied structured fragment",
+  },
+  agentMetadata: { readOrMutate: "mutate", boundedScope: "scope", auditCategory: "fragment-insert" },
+  stateClass: "A-canonical",
+  persistsTo: "canonical",
+  broadcastsVia: "crdt",
+  rwdReference:
+    "§Runtime API § runtime.content.insertFragment. Graduation (2026-04-23): routes through createScopeCompilerService(runtime).applyReplacement({targetScopeId, operation:'replace', proposedContent:{kind:'structured', structured: fragment}}) — same L08 pipeline replaceText uses. Emits one ScopeActionAudit via the compiler's lifecycle. Promotes to `live` when an insert-after-anchor primitive exists that matches a distinct agent semantic (this call is replace-with-fragment-shaped today).",
+};
+
+/* ================================================================== */
+/*  family factory                                                    */
+/* ================================================================== */
+
+export function createContentFamily(runtime: RuntimeApiHandle) {
+  const compiler = createScopeCompilerService(runtime);
+  return {
+    search(input: SearchInput) {
+      // @endStateApi — live-with-adapter. Reshape of EditorAnchorProjection[]
+      // + optional limit slicing. v3 spells its boolean `caseSensitive`;
+      // runtime SearchOptions spells the same field `matchCase` — the prior
+      // cast was passing `{caseSensitive}` which the runtime silently ignored.
+      const hits = runtime.findAllText(input.query, { matchCase: input.caseSensitive });
+      const limited = typeof input.limit === "number" ? hits.slice(0, input.limit) : hits;
+      return limited;
+    },
+
+    getLocation(input: GetLocationInput) {
+      // @endStateApi — live-with-adapter. scopeId path composes
+      // handle.getScope(scopeId) + handle.getLocationForAnchor(scope.anchor).
+      // This replaced the earlier `runtime.debug.getSnapshot({scopeFilter})`
+      // composition (debug channel was an escape hatch around a missing L07
+      // seam; the typed scope+anchor path is the real L07 read). blockId
+      // input is NOT supported — no shipped blockId → anchor resolver —
+      // returns null.
+      if (input.scopeId) {
+        const scope = runtime.getScope(input.scopeId);
+        if (!scope) return null;
+        return runtime.getLocationForAnchor(scope.anchor) ?? null;
+      }
+      return null;
+    },
+
+    replaceText(input: ReplaceTextInput): ReplaceTextResult {
+      // @endStateApi — live-with-adapter (Slice 5). Routes through the
+      // Layer-08 compiler-service facade. Same pipeline as
+      // ai.applyReplacementScope; the host/UI path omits actionId (not
+      // an agent action) and tags origin:"ui" + actorId:"user".
+      const result = compiler.applyReplacement({
+        targetScopeId: input.scopeId,
+        operation: "replace",
+        proposedText: input.replacement,
+        actorId: "user",
+        origin: "ui",
+        emittedAtUtc: new Date(0).toISOString(),
+      });
+
+      emitUxResponse(runtime, {
+        apiFn: replaceTextMetadata.name,
+        intent: replaceTextMetadata.uxIntent.expectedDelta ?? "",
+        mockOrLive: "live",
+        uiVisible: true,
+        expectedDelta: replaceTextMetadata.uxIntent.expectedDelta,
+      });
+
+      return {
+        applied: result.applied,
+        ...(result.reason ? { reason: result.reason } : {}),
+      };
+    },
+
+    insertFragment(input: InsertFragmentInput): InsertFragmentResult {
+      // @endStateApi — live-with-adapter. Coord-07 §1.1 closed 2026-04-23
+      // after L08 §8 shipped the structured-fragment compile path
+      // (paragraph-kind). Delegates to the same compiler-service facade
+      // replaceText uses, flagging `proposedContent.kind = "structured"`
+      // so compileReplacement emits `fragment-replace` instead of
+      // `text-replace`. One ScopeActionAudit emits on the scope channel
+      // via the compiler's lifecycle.
+      const result = compiler.applyReplacement({
+        targetScopeId: input.scopeId,
+        operation: "replace",
+        proposedContent: { kind: "structured", structured: input.fragment },
+        actorId: "user",
+        origin: "ui",
+        emittedAtUtc: new Date(0).toISOString(),
+      });
+
+      emitUxResponse(runtime, {
+        apiFn: insertFragmentMetadata.name,
+        intent: insertFragmentMetadata.uxIntent.expectedDelta ?? "",
+        mockOrLive: "live",
+        uiVisible: true,
+        expectedDelta: insertFragmentMetadata.uxIntent.expectedDelta,
+      });
+
+      return {
+        applied: result.applied,
+        ...(result.reason ? { reason: result.reason } : {}),
+      };
+    },
+  };
+}