@k2b/cloud 0.44.0 → 0.46.0

package/src/ai/types.ts

@@ -313,6 +313,7 @@ export type AiStoredMessage = {
     toolPresentations?: Record<string, AiToolPresentation>;
     toolReviews?: Record<string, AiStoredActionReview>;
     toolChecks?: Record<string, AiActionCheck>;
+    toolInterimResults?: Record<string, unknown>;
     /** How the person decided an approval; `expired` when the turn ended while it still waited. */
     toolOutcomes?: Record<string, "rejected" | "approved" | "expired">;
     /** Requests a website approval let through, by tool call and then by `AiWebsiteReceipt.index`. */
@@ -1159,6 +1160,8 @@ export type AiToolRuntime<TInput extends z.ZodType = z.ZodType, TOutput extends
           timeZone?: string;
           /** Localized short status; never include payloads or secrets. */
           reportProgress?: (message: string) => Promise<void>;
+          /** A validated result snapshot while a server tool is still running. */
+          reportResult?: (result: z.infer<TOutput>) => Promise<void>;
           /** Asks like `requestApproval`, and lets the person remember the approval of `target`. */
           requestApprovalFor?: (message: string, target: AiApprovalTarget, review?: CapabilityActionCallReview) => Promise<boolean>;
           /** Relays a decision for an effect another platform component consumes and executes. */

package/src/api/accounts-entities.ts

@@ -36,6 +36,7 @@ const QuerySchema = z
     profile: UserProfileSchema.optional(),
     user_ids: z.string().optional(),
     group_ids: z.string().optional(),
+    service_account_ids: z.string().optional(),
     service_account_kinds: z.string().optional(),
     service_account_status: ServiceAccountStatusSchema.optional(),
     exclude_user_ids: z.string().optional(),
@@ -47,7 +48,6 @@ const QuerySchema = z
     parent_group_id: z.uuid().optional(),
     managed_by_user_id: z.uuid().optional(),
     recursive: z.enum(["true", "false"]).optional(),
-    include_personal: z.enum(["true", "false"]).optional(),
   })
   .refine(
     (value) => {
@@ -112,7 +112,7 @@ export const createAccountsEntitiesRoutes = (dependencies: AccountsEntitiesRoute
       tags: ["Accounts"],
       summary: "List visible directory entries",
       description:
-        "List visible users and groups with SQL-backed filtering and pagination. Guest accounts see only themselves and their effective groups; relation filters require a full user account. Standalone and agent accounts with read scope see only explicitly shared directory entries and cannot query relationships. Personal Linux groups (a user's private primary group, flagged with `personalOwner`) are left out unless `include_personal=true`; exact `group_ids` lookups and relation filters always return them.",
+        "List visible users and groups with SQL-backed filtering and pagination. Guest accounts see only themselves and their effective groups; relation filters require a full user account. Standalone and agent accounts with read scope see only explicitly shared directory entries and cannot query relationships. Personal Linux groups are excluded, including exact group IDs and relation filters. Inspect the owning user's Linux identity for diagnostic attributes.",
       ...requiresAuth,
       responses: {
         200: jsonResponse(EntitiesListResponseSchema, "Paginated mixed entity list"),
@@ -153,6 +153,9 @@ export const createAccountsEntitiesRoutes = (dependencies: AccountsEntitiesRoute
       const groupIds = parseUuidList(query.group_ids, "group_ids");
       if (!groupIds.ok) return respond(c, fail(err.badInput(groupIds.message)));
 
+      const serviceAccountIds = parseUuidList(query.service_account_ids, "service_account_ids");
+      if (!serviceAccountIds.ok) return respond(c, fail(err.badInput(serviceAccountIds.message)));
+
       const filters = {
         search: query.search,
         kinds: kinds.value,
@@ -160,6 +163,7 @@ export const createAccountsEntitiesRoutes = (dependencies: AccountsEntitiesRoute
         profile: query.profile,
         userIds: userIds.value,
         groupIds: groupIds.value,
+        serviceAccountIds: serviceAccountIds.value,
         serviceAccountKinds: serviceAccountKinds.value,
         serviceAccountStatus: query.service_account_status,
         excludeUserIds: excludeUserIds.value,
@@ -171,7 +175,6 @@ export const createAccountsEntitiesRoutes = (dependencies: AccountsEntitiesRoute
         parentGroupId: query.parent_group_id,
         managedByUserId: query.managed_by_user_id,
         recursive: query.recursive === "true",
-        includePersonal: query.include_personal === "true",
       };
       if (!user) {
         const result = await (dependencies.searchShares ?? directoryShares.search)({

package/src/api/admin-ai-skills.ts

@@ -94,7 +94,10 @@ export const createAdminAiSkillsRoutes = (authenticate: MiddlewareHandler<AuthCo
     .get("/:skillId/projects", async (c) => {
       const skill = await aiSkills.admin.getByShortId(c.req.param("skillId")!);
       if (!skill) return notFound(c, "Skill");
-      const projects = await aiSkills.admin.linkedProjects(skill.id, c.get("accessSubject") ?? null);
+      const projects = await aiSkills.admin.linkedProjects(skill.id, {
+        actor: c.get("actor"),
+        accessSubject: c.get("accessSubject"),
+      });
       return respond(c, ok({ projects: projects.map((project) => ({ id: project.shortId, name: project.name })) }));
     })
     .get("/:skillId/access", async (c) => {

package/src/api/auth.ts

@@ -162,13 +162,20 @@ export const createAuthRoutes = (notificationSender: AuthNotificationSender) =>
         tags: ["Auth"],
         summary: "Logout",
         description:
-          "Idempotent: clears the session cookie and revokes the current credential if present. No authentication required — logout must always succeed.",
+          "Idempotent: clears the session cookie and revokes the current credential if present. No authentication required. An optional X-Cloud-Logout-User header binds revocation to that user UUID (or none) without writing the shared browser cookie; a changed account returns 409 without revocation.",
+        parameters: [{ in: "header", name: "X-Cloud-Logout-User", required: false, schema: { type: "string" } }],
         responses: {
           200: jsonResponse(MessageResponseSchema, "Session invalidated"),
+          400: jsonResponse(ErrorResponseSchema, "Invalid expected account"),
+          409: jsonResponse(ErrorResponseSchema, "Browser account changed"),
         },
       }),
       async (c) => {
-        await auth.session.delete(c);
+        const expected = c.req.header("x-cloud-logout-user");
+        if (expected !== undefined && expected !== "none" && !z.string().uuid().safeParse(expected).success)
+          return c.json({ message: "Invalid expected account" }, 400);
+        if (!(await auth.session.delete(c, expected === "none" ? null : expected)))
+          return c.json({ message: "Browser account changed; reload before signing out" }, 409);
         log.info("Logout");
         return c.json({ message: "Logged out" });
       },

package/src/api/capabilities.ts

@@ -3,14 +3,14 @@ import { describeRoute } from "hono-openapi";
 import { z } from "zod";
 import { type CatalogSubscription, projectAppEventCatalog, readCatalogSubscriptions } from "../_internal/app-event-catalog";
 import { readBoundedJson } from "../_internal/bounded-json";
-import { resolveCapabilityManifestPresentation } from "../_internal/capabilities";
+import { isPersonVisibleCapabilityQuery, resolveCapabilityManifestPresentation } from "../_internal/capabilities";
 import {
   capabilityActionReceiptIssues,
   capabilityActionReviewIssues,
   capabilityQueryChecksActionOutcome,
 } from "../_internal/capability-reviews";
 import { capabilityTimeoutMs, createCapabilityDeadline, withCapabilityRequestTimeout } from "../_internal/capability-timeout";
-import { getCapability, listApps } from "../_internal/registry";
+import { getApp, getCapability, listApps } from "../_internal/registry";
 import { resolveCommandLink } from "../capabilities/command-link";
 import {
   type CapabilityClaimScope,
@@ -59,12 +59,13 @@ import { AppAccessDeniedError, appAccessDeniedBody } from "../server/middleware/
 import { oauthScopeByOperation } from "../server/middleware/auth";
 import { noTransform } from "../server/middleware/no-transform";
 import { hasOAuthScope } from "../server/oauth-scope";
+import { ratelimit } from "../server/ratelimit";
 import { appAccessAuthority, canUseApp } from "../services/app-access";
 import { discoverableApps } from "../services/app-discovery";
 import { authorityFromParentInvocation, invocationAuthorityFromRequest } from "../services/identity/invocation-authority";
 import { capabilityInvocationOperation } from "../services/identity/invocation-operations";
 import type { CloudInvocationClaims, InvocationAuthority } from "../services/identity/invocation-token";
-import { normalizeInvocationRequestId } from "../services/identity/invocation-token";
+import { normalizeInvocationRequestId, signAppQueryInvocation } from "../services/identity/invocation-token";
 import { issueInvocationToken as signInvocationToken } from "../services/identity/issue-invocation";
 import { withActiveIdentitySigner } from "../services/identity/key-ring";
 import {
@@ -73,6 +74,7 @@ import {
   nestedInvocationLeases,
   nestedSourceDeadline,
 } from "../services/identity/nested-invocation";
+import type { AuthenticatedWorkload } from "../services/identity/workload-auth";
 import { logger } from "../services/logging";
 import { withMandateIssueAuthority } from "../services/mandates";
 import * as settings from "../services/settings";
@@ -80,6 +82,9 @@ import { resolveAppPresentation } from "../shared/app-presentation";
 import { capabilityMessages } from "../shared/capability-messages";
 import { dispatchCapabilityStream, sealCapabilityStream } from "./capability-streams";
 
+// Approved reader-check budget, shared across targets for each calling application.
+export const APP_QUERY_REQUESTS_PER_MINUTE = 1_501;
+const appQueryLimit = ratelimit({ id: "app-queries", limit: APP_QUERY_REQUESTS_PER_MINUTE, windowSecs: 60 });
 const log = logger("capabilities");
 const DEFAULT_CATALOG_LIMIT = 10;
 const MAX_CATALOG_LIMIT = 25;
@@ -114,6 +119,7 @@ const CapabilityCatalogQuerySchema = z
 export type CapabilityRouteDependencies = {
   listApps?: () => Promise<AppRegistryEntry[]>;
   eventSubscriptions?: () => Promise<CatalogSubscription[]>;
+  getApp?: (appId: string) => Promise<AppRegistryEntry | null>;
   getCapability?: (appId: string) => Promise<CapabilityRegistryEntry | null>;
   fetch?: (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
   authenticate?: MiddlewareHandler<AuthContext>;
@@ -122,12 +128,15 @@ export type CapabilityRouteDependencies = {
   withMandateIssueAuthority?: typeof withMandateIssueAuthority;
   queryTimeoutMs?: number;
   actionTimeoutMs?: number;
+  checkAppQueryRate?: (appId: string) => Promise<{ limited: boolean }>;
   reviewTimeoutMs?: number;
   appUrl?: () => Promise<string>;
 };
 
 export type CapabilityDispatchDependencies = Pick<
   CapabilityRouteDependencies,
+  | "checkAppQueryRate"
+  | "getApp"
   | "getCapability"
   | "fetch"
   | "queryTimeoutMs"
@@ -223,7 +232,7 @@ export const loadCapabilityCatalogPage = async (
       appName: presentedEntry.name,
       appIcon: capability.appIcon,
       appDescription: presentedEntry.description,
-      manifest,
+      manifest: { ...manifest, queries: manifest.queries.filter(isPersonVisibleCapabilityQuery) },
       ...(manifest.events ? { events: projectAppEventCatalog(manifest, manifest.events.length ? await loadSubscribers() : []) } : {}),
     };
     const projectedBytes = new TextEncoder().encode(JSON.stringify(projected)).byteLength;
@@ -276,6 +285,8 @@ export type CapabilityDispatchParams = {
   assistantTurn?: { conversationId: string; turnId: string };
   /** Core-only absolute child deadline; cannot be extended by the application. */
   deadline?: number;
+  /** Core-only authenticated workload. Never populated from request JSON. */
+  workload?: AuthenticatedWorkload;
   mandate?: MandatedCapabilityAuthority;
   callingAppId?: string;
   /** Internal observation only: called immediately before attempting the app request. */
@@ -342,6 +353,43 @@ const runCapabilityDispatch = async (
     );
     return error;
   }
+  if ("appOnly" in operation && operation.appOnly !== undefined && !params.workload)
+    return errorResponse("FORBIDDEN", "App authority required for this query", 403);
+  if (params.workload) {
+    if (
+      params.authority ||
+      params.mandate ||
+      params.parentInvocation ||
+      params.review ||
+      params.kind !== "queries" ||
+      !("appOnly" in operation) ||
+      operation.appOnly !== true ||
+      operation.stream
+    )
+      return errorResponse("FORBIDDEN", "App caller is not allowed for this query", 403);
+    try {
+      const caller = await deadline.wait(() => (params.dependencies?.getApp ?? getApp)(params.workload!.appId));
+      if (!caller) return errorResponse("APP_UNAVAILABLE", "Calling app registry entry unavailable", 503);
+      if (!caller.platformPermissions?.includes("resources:readers"))
+        return errorResponse("APP_QUERY_NOT_ADMITTED", "App caller does not declare resources:readers", 403);
+    } catch {
+      deadline.check();
+      return errorResponse("APP_UNAVAILABLE", "App registry unavailable", 503);
+    }
+    try {
+      if (
+        (
+          await deadline.wait(() =>
+            (params.dependencies?.checkAppQueryRate ?? ((appId) => appQueryLimit.check(appId)))(params.workload!.appId),
+          )
+        ).limited
+      )
+        return errorResponse("RATE_LIMITED", "App query rate limit exceeded; retry after one minute", 429);
+    } catch {
+      deadline.check();
+      return errorResponse("APP_UNAVAILABLE", "App query rate limiter unavailable", 503);
+    }
+  }
   if (params.review && (params.kind !== "actions" || !("review" in operation) || operation.review !== true)) {
     const error = errorResponse(
       "CAPABILITY_NOT_FOUND",
@@ -488,6 +536,33 @@ const runCapabilityDispatch = async (
           });
         })()
       : await (async () => {
+          if (params.workload) {
+            const workload = params.workload;
+            return deadline.wait(() =>
+              (params.dependencies?.withActiveSigner ?? withActiveIdentitySigner)(
+                "invocation",
+                async (signer) => {
+                  deadline.check();
+                  const signed = await signAppQueryInvocation({
+                    workload,
+                    targetAppId: params.appId,
+                    capabilityId: params.capabilityId,
+                    schemaHash: operation.schemaHash,
+                    input: input.data,
+                    requestId,
+                    signer,
+                  });
+                  observed.invocationId = signed.claims.jti;
+                  return new Headers({
+                    "content-type": "application/json",
+                    accept: "application/json",
+                    authorization: `Bearer ${signed.token}`,
+                  });
+                },
+                { signal, timeoutMs: deadline.remainingMs() },
+              ),
+            );
+          }
           if (!params.authority) throw new Error("Resolved request authority is required for Cloud invocation issuance");
           const authority = params.authority;
           const signed = await deadline.wait(() =>
@@ -665,12 +740,15 @@ const runCapabilityDispatch = async (
   try {
     params.onUpstreamAttempt?.();
     const fetchResponse = () =>
-      fetchUpstream(`${entry.endpoint}/${params.kind}/${encodeURIComponent(params.capabilityId)}${params.review ? "/review" : ""}`, {
-        method: "POST",
-        headers,
-        body: requestBody,
-        signal,
-      });
+      fetchUpstream(
+        `${entry.endpoint}/${params.workload ? "app-queries" : params.kind}/${encodeURIComponent(params.capabilityId)}${params.review ? "/review" : ""}`,
+        {
+          method: "POST",
+          headers,
+          body: requestBody,
+          signal,
+        },
+      );
     // A read may be released at its deadline; Action effects retain their existing uncertainty handling.
     response = params.kind === "queries" || params.review ? await deadline.wait(fetchResponse) : await fetchResponse();
   } catch (error) {
@@ -895,12 +973,12 @@ export const dispatchCapability = async (params: CapabilityDispatchParams): Prom
         origin: params.origin,
         invocationId: observed.invocationId,
         parentInvocationId: params.parentInvocation?.jti,
-        viaAppId: params.parentInvocation ? params.callingAppId : undefined,
+        viaAppId: params.workload?.appId ?? (params.parentInvocation ? params.callingAppId : undefined),
         appId: params.appId,
         capability: `${params.appId}.${params.capabilityId}`,
         kind: params.kind === "queries" ? "query" : "action",
         destructive: observed.destructive,
-        actorKind: principal?.type ?? null,
+        actorKind: params.workload ? "app" : (principal?.type ?? null),
         actorId: principal?.id ?? null,
         userId: actor?.kind === "user" ? actor.user.id : (actor?.delegatedUser?.id ?? (principal?.type === "user" ? principal.id : null)),
         accessSubject: subject && subject.id !== principal?.id ? subject : null,

package/src/api/mcp.ts

@@ -16,7 +16,7 @@ import { Hono, type MiddlewareHandler } from "hono";
 import { z } from "zod";
 import { type CatalogSubscription, projectAppEventCatalog, readEventCatalogSubscriptions } from "../_internal/app-event-catalog";
 import { readBoundedJson } from "../_internal/bounded-json";
-import { resolveCapabilityManifestPresentation } from "../_internal/capabilities";
+import { isPersonVisibleCapabilityQuery, resolveCapabilityManifestPresentation } from "../_internal/capabilities";
 import { capabilitySentenceText } from "../_internal/capability-sentences";
 import { withCapabilityRequestTimeout } from "../_internal/capability-timeout";
 import {
@@ -311,7 +311,9 @@ const orderedCapabilityEntries = function* (app: CapabilityRegistryEntry): Gener
   for (const operation of [...app.manifest.actions].sort((left, right) => left.localId.localeCompare(right.localId))) {
     yield { app, kind: "actions", operation };
   }
-  for (const operation of [...app.manifest.queries].sort((left, right) => left.localId.localeCompare(right.localId))) {
+  for (const operation of app.manifest.queries
+    .filter(isPersonVisibleCapabilityQuery)
+    .sort((left, right) => left.localId.localeCompare(right.localId))) {
     yield { app, kind: "queries", operation };
   }
 };

package/src/browser/notifications.ts

@@ -13,6 +13,8 @@ export type BrowserNotificationState = {
   permission: NotificationPermission;
   enabled: boolean;
   reason?: string;
+  /** On iPhone and iPad outside the Home Screen app: notifications start working once Cloud is added to the Home Screen. */
+  homeScreenRequired?: true;
 };
 
 const isIos = (): boolean =>
@@ -21,7 +23,15 @@ const isIos = (): boolean =>
 const isStandalone = (): boolean =>
   window.matchMedia("(display-mode: standalone)").matches || (navigator as Navigator & { standalone?: boolean }).standalone === true;
 
-const support = (): { supported: boolean; reason?: string } => {
+const support = (): { supported: boolean; reason?: string; homeScreenRequired?: true } => {
+  // Safari on iPhone and iPad offers push only to the Home Screen app, so it lacks the APIs checked below.
+  if (typeof window !== "undefined" && isIos() && !isStandalone()) {
+    return {
+      supported: false,
+      reason: "On iPhone and iPad, add Cloud to your Home Screen before enabling browser notifications.",
+      homeScreenRequired: true,
+    };
+  }
   if (
     typeof window === "undefined" ||
     !window.isSecureContext ||
@@ -31,12 +41,6 @@ const support = (): { supported: boolean; reason?: string } => {
   ) {
     return { supported: false, reason: "Browser notifications are not supported in this browser." };
   }
-  if (isIos() && !isStandalone()) {
-    return {
-      supported: false,
-      reason: "On iPhone and iPad, add Cloud to your Home Screen before enabling browser notifications.",
-    };
-  }
   return { supported: true };
 };
 
@@ -101,7 +105,13 @@ const pushSubscriptionError = (cause: unknown): Error => {
 const currentState = async (registration?: ServiceWorkerRegistration): Promise<BrowserNotificationState> => {
   const capability = support();
   if (!capability.supported) {
-    return { supported: false, permission: "denied", enabled: false, reason: capability.reason };
+    return {
+      supported: false,
+      permission: "denied",
+      enabled: false,
+      reason: capability.reason,
+      ...(capability.homeScreenRequired ? { homeScreenRequired: true } : {}),
+    };
   }
   return withNotificationTimeout(
     (async () => {
@@ -131,6 +141,13 @@ export const browserNotificationClient = {
     return (await response.json()).state;
   },
 
+  /** End do not disturb now, for every app. Quiet hours keep their schedule. Returns the quiet state afterwards. */
+  endDoNotDisturb: async (): Promise<NotificationQuietState> => {
+    const response = await apiClient.me.notifications.quiet.$patch({ json: { doNotDisturbUntil: null } });
+    if (!response.ok) throw await responseError(response, "Failed to end do not disturb.");
+    return (await response.json()).state;
+  },
+
   /** Close this application's group on this device without opting into notifications. */
   closeGroup: async (appId: string, group: string): Promise<void> => {
     const tag = notificationGroupTag(appId, group);

package/src/browser/session.ts

@@ -0,0 +1,39 @@
+import { apiClient } from "../clients/core";
+
+/** Fence and remove application-owned entries in the authenticated user's browser namespace. */
+const clearUserStorage = (userId: string): void => {
+  const prefix = `cloud:user:${userId}:`;
+  localStorage.setItem(`cloud:user-epoch:${userId}`, crypto.randomUUID());
+  if (typeof window !== "undefined") window.dispatchEvent(new CustomEvent("cloud:user-storage-invalidated", { detail: { userId } }));
+  const keys = Array.from({ length: localStorage.length }, (_, index) => localStorage.key(index));
+  for (const key of keys) if (key?.startsWith(prefix)) localStorage.removeItem(key);
+};
+
+/** Revoke this browser's credential even if local storage cleanup fails. The caller keeps a visible retry until both succeed. */
+export const signOutBrowserSession = async (userId: string | undefined, errorMessage: string): Promise<void> => {
+  await import("./notifications").then(({ browserNotificationClient }) => browserNotificationClient.disable()).catch(() => undefined);
+  let cleanupFailed = false;
+  try {
+    if (userId) {
+      clearUserStorage(userId);
+      const { logoutSharedTextOffline } = await import("./shared-text-offline");
+      await logoutSharedTextOffline(userId);
+    }
+  } catch {
+    cleanupFailed = true;
+  }
+  const response = await apiClient.auth.logout.$post({}, { headers: { "x-cloud-logout-user": userId ?? "none" } });
+  // Close the interval between the first local fence and credential revocation:
+  // a tab that authenticated during it must not retain or recreate device data.
+  if (response.ok && userId) {
+    try {
+      clearUserStorage(userId);
+      const { logoutSharedTextOffline } = await import("./shared-text-offline");
+      await logoutSharedTextOffline(userId);
+      cleanupFailed = false;
+    } catch {
+      cleanupFailed = true;
+    }
+  }
+  if (!response.ok || cleanupFailed) throw new Error(errorMessage);
+};

package/src/browser/shared-text-history-validation.ts

@@ -0,0 +1,151 @@
+import * as T from "@k2b/ui/text-editor/model";
+import * as Y from "yjs";
+
+type NativeFrame = Y.UndoManager["undoStack"][number];
+type Span = { from: number; to: number };
+type Piece = Span & { original: number | null };
+
+export class SharedTextNativeHistoryError extends Error {
+  readonly code = "shared_text_history_target";
+  constructor(readonly reason: "dependency" | "unavailable") {
+    super("The input history target is unavailable");
+  }
+}
+
+const intersect = (set: NativeFrame["insertions"], item: Y.Item): Span[] =>
+  (set.clients.get(item.id.client) ?? []).flatMap((run) => {
+    const from = Math.max(run.clock, item.id.clock) - item.id.clock;
+    const to = Math.min(run.clock + run.len, item.id.clock + item.length) - item.id.clock;
+    return from < to ? [{ from, to }] : [];
+  });
+const subtract = (wanted: Span[], excluded: Span[]): Span[] =>
+  wanted.flatMap((span) => {
+    const result: Span[] = [];
+    let from = span.from;
+    for (const cut of excluded) {
+      if (cut.to <= from || cut.from >= span.to) continue;
+      if (cut.from > from) result.push({ from, to: cut.from });
+      from = Math.max(from, cut.to);
+    }
+    if (from < span.to) result.push({ from, to: span.to });
+    return result;
+  });
+
+type Region = Span & { key: string | undefined };
+const regions = (source: string, original: (position: number) => number | null): Region[] =>
+  T.findTables(source).flatMap((table) =>
+    table.lines.flatMap((line, row) =>
+      line.cells.map((_cell, column) => {
+        const left = line.leadingPipe ? line.pipes[column]! + 1 : column === 0 ? line.from : line.pipes[column - 1]! + 1;
+        const right = (line.leadingPipe ? line.pipes[column + 1] : line.pipes[column]) ?? line.to;
+        const separator = table.lines[1]!.cells[column];
+        const hyphen = separator ? original(separator.from + separator.text.indexOf("-")) : null;
+        const header = original(table.lines[0]!.to);
+        const rowIdentity = row < 2 ? row : original(line.from - 1);
+        // Extra physical cells have no separator hyphen. Their surviving left
+        // delimiter distinguishes them even when columns are inserted/removed.
+        // An unknown identity is never evidence that two targets are the same.
+        const columnIdentity = separator ? hyphen : original(left - 1);
+        return {
+          from: left,
+          to: right,
+          key:
+            header === null || rowIdentity === null || columnIdentity === null
+              ? undefined
+              : `${header}:${rowIdentity}:${separator ? "column" : "extra"}:${columnIdentity}`,
+        };
+      }),
+    ),
+  );
+const locate = (regions: Region[], position: number, end: number) => {
+  let low = 0,
+    high = regions.length;
+  while (low < high) {
+    const middle = (low + high) >>> 1;
+    if (regions[middle]!.to <= position) low = middle + 1;
+    else high = middle;
+  }
+  const region = regions[low];
+  return region && region.from <= position ? { key: region.key, to: region.to } : { key: null, to: region?.from ?? end };
+};
+
+/** Project root plain-text native effects without a second manager or live mutation.
+ * Identity sets and linked Item/content fields are exported Yjs contracts. Native
+ * restoration occupies the original deleted item's gap; redone items already
+ * have their effect and are not copied again. Unknown content refuses safely.
+ */
+export const validateNativeHistory = (
+  text: Y.Text,
+  frame: NativeFrame,
+  liveInsertions: NativeFrame["insertions"],
+  baseline: Uint8Array | null,
+) => {
+  const known = baseline ? Y.decodeStateVector(baseline) : new Map<number, number>();
+  const chunks: string[] = [];
+  const pieces: Piece[] = [];
+  const protectedSpans: { before: number; after: number; length: number }[] = [];
+  let before = 0,
+    after = 0;
+  const append = (value: string, original: number | null) => {
+    if (!value.length) return;
+    chunks.push(value);
+    pieces.push({ from: after, to: after + value.length, original });
+    after += value.length;
+  };
+  for (const item of Y.getTypeChildren(text)) {
+    // Adopted frames lack correspondence captured by this controller. Native
+    // Undo follows pre-existing redone chains for insertions; projecting only
+    // the original IDs would omit their live effects. Leave such frames intact.
+    if (baseline === null && item.redone !== null && intersect(frame.insertions, item).length)
+      throw new SharedTextNativeHistoryError("unavailable");
+    if (item.deleted) {
+      const restore = subtract(intersect(frame.deletions, item), intersect(frame.insertions, item));
+      if (!restore.length || item.redone !== null) continue;
+      const content = item.content;
+      if (!(content instanceof Y.ContentString)) throw new SharedTextNativeHistoryError("unavailable");
+      for (const span of restore) append(content.str.slice(span.from, span.to), null);
+      continue;
+    }
+    if (!item.countable) continue;
+    const content = item.content;
+    if (!(content instanceof Y.ContentString)) throw new SharedTextNativeHistoryError("unavailable");
+    const keep = subtract([{ from: 0, to: item.length }], intersect(liveInsertions, item));
+    for (const span of keep) {
+      const newer = Math.max(span.from, (known.get(item.id.client) ?? 0) - item.id.clock);
+      if (newer < span.to) protectedSpans.push({ before: before + newer, after: after + newer - span.from, length: span.to - newer });
+      append(content.str.slice(span.from, span.to), before + span.from);
+    }
+    before += item.length;
+  }
+  const source = text.toString();
+  const candidate = chunks.join("");
+  if (before !== source.length) throw new SharedTextNativeHistoryError("unavailable");
+  const original = (position: number) => {
+    let low = 0,
+      high = pieces.length;
+    while (low < high) {
+      const middle = (low + high) >>> 1;
+      if (pieces[middle]!.to <= position) low = middle + 1;
+      else high = middle;
+    }
+    const piece = pieces[low];
+    return piece?.original != null ? piece.original + position - piece.from : null;
+  };
+  const beforeRegions = regions(source, (position) => position);
+  const afterRegions = regions(candidate, original);
+  for (const span of protectedSpans) {
+    let offset = 0;
+    while (offset < span.length) {
+      const oldAt = span.before + offset,
+        newAt = span.after + offset;
+      const oldTarget = locate(beforeRegions, oldAt, source.length);
+      const newTarget = locate(afterRegions, newAt, candidate.length);
+      if (oldTarget.key === undefined || newTarget.key === undefined || oldTarget.key !== newTarget.key)
+        throw new SharedTextNativeHistoryError("dependency");
+      const length = Math.min(span.length - offset, oldTarget.to - oldAt, newTarget.to - newAt);
+      if (length <= 0) throw new SharedTextNativeHistoryError("unavailable");
+      offset += length;
+    }
+  }
+  return candidate;
+};