@k2b/cloud 0.45.0 → 0.46.0

package/src/ai/chat/message-utils.ts

@@ -327,6 +327,7 @@ export const displayToolName = (name: string, locale: string) => {
 
 const BUILT_IN_TOOL_ICONS = new Map<string, string>([
   ["card", "ti ti-layout-cards"],
+  ["map", "ti ti-map-search"],
   ["cloud_card", "ti ti-layout-cards"],
   ["chart", "ti ti-chart-bar"],
   ["survey", "ti ti-forms"],

package/src/ai/chat/tool-names.ts

@@ -10,6 +10,7 @@ const toolNames = i18n.define({
     en: {
       calculate: "Calculate",
       card: "Card",
+      map: "Places and maps",
       chart: "Chart",
       survey: "Survey",
       text_editor: "Text editor",
@@ -86,6 +87,7 @@ const toolNames = i18n.define({
     de: {
       calculate: "Rechnen",
       card: "Karte",
+      map: "Orte und Karten",
       chart: "Diagramm",
       survey: "Umfrage",
       text_editor: "Texteditor",

package/src/ai/chat/turn-layout.ts

@@ -70,11 +70,12 @@ const resultTarget = (block: ToolBlock): string | null => {
 };
 
 const isResult = (block: ToolBlock, phase: AiTurnPhase, codePresentations: boolean): boolean => {
+  if (block.name === "map" && block.result && typeof block.result === "object" && "map" in block.result) return true;
   if (isFailedTool(block) || block.status === "rejected" || block.status === "awaiting_approval") return false;
   // A running delivery reserves its place once its arguments arrived: a new version of an earlier result must find the
   // earlier place before it takes one of its own.
   const delivered = block.status === "completed" || (live(phase) && block.status === "running" && block.args !== undefined);
-  if (block.name === "present" || isCardToolName(block.name) || isChartToolName(block.name)) return delivered;
+  if (block.name === "map" || block.name === "present" || isCardToolName(block.name) || isChartToolName(block.name)) return delivered;
   if (block.name === "code_present") return codePresentations && delivered;
   return hasCapabilityTable(block);
 };

package/src/ai/chat/turn-view.tsx

@@ -23,6 +23,7 @@ import { CompactionBlockView, CompactToolRow, SurveyToolView, TextEditorToolView
 import { CapabilityTablePreview } from "./capability-table";
 import { CloudChartBlock } from "./chart-block";
 import { PresentToolBlock } from "./file-tools";
+import { AiMapToolBlock } from "./map-widget";
 import { useAiChatActions } from "./message-actions";
 import { aiToolIcon, displayToolName, isCardToolName, isChartToolName, isRecord, isSurveyToolName } from "./message-utils";
 import { aiChatMessages } from "./messages";
@@ -438,6 +439,9 @@ function AiTurnResultView(props: { result: Accessor<AiTurnResult | undefined>; r
     <Show when={block()}>
       {(current) => (
         <Switch>
+          <Match when={current().name === "map"}>
+            <AiMapToolBlock block={current()} />
+          </Match>
           <Match when={current().name === "present"}>
             <PresentToolBlock block={current()} />
           </Match>
@@ -653,7 +657,18 @@ export function AiTurnView(props: { segment: Accessor<AiTurnSegment>; disclosure
   const chatActions = useAiChatActions();
   const layout = () => props.segment().layout;
   const results = createMemo(() => new Map(layout().results.map((result) => [result.id, result])));
-  const resultIds = createMemo(() => [...results().keys()]);
+  const isMapFollowup = (id: string) => {
+    const block = results().get(id)?.block;
+    return (
+      block?.name === "map" &&
+      typeof block.result === "object" &&
+      block.result !== null &&
+      "anchor" in block.result &&
+      block.result.anchor === false
+    );
+  };
+  const resultIds = createMemo(() => [...results().keys()].filter((id) => !isMapFollowup(id)));
+  const mapFollowupIds = createMemo(() => [...results().keys()].filter(isMapFollowup));
   const actions = createMemo(() => new Map(layout().actions.map((action) => [action.id, action])));
   const actionIds = createMemo(() => [...actions().keys()]);
   const live = () => isLive(props.segment().phase);
@@ -709,6 +724,7 @@ export function AiTurnView(props: { segment: Accessor<AiTurnSegment>; disclosure
             earlier={() => props.segment().earlier}
           />
         </Show>
+        <For each={mapFollowupIds()}>{(id) => <AiTurnResultView result={() => results().get(id)} receipt={() => false} />}</For>
         <Show when={props.segment().scheduledTask?.stop ? undefined : props.segment().scheduledTask?.reason}>
           {(reason) => (
             <Chat.Activity

package/src/ai/default-tools.ts

@@ -56,6 +56,7 @@ import {
   CloudAiLocalWriteInputSchema,
   CloudAiLocalWriteOutputSchema,
 } from "./local-tool-contracts";
+import { createCloudAiMapTool } from "./map-tool";
 import { createCloudAiMarkdownToPdfTool } from "./markdown-pdf-tool";
 import { createAiTodoTool } from "./todo-tool";
 import { defineAiTool } from "./tools";
@@ -303,6 +304,7 @@ export const CLOUD_AI_DEFERRED_BUILTIN_TOOL_NAMES = new Set<string>([
   "markdown_to_pdf",
   "html_to_pdf",
   "present",
+  "map",
   "read_cloud_resource",
 ]);
 
@@ -314,6 +316,7 @@ export const createConfiguredDefaultCloudAiTools = async (config?: {
 }) => {
   const tools: AiRuntimeTool[] = [
     ...createDefaultCloudAiTools(),
+    createCloudAiMapTool(),
     ...createCodeSourceTools(),
     createCloudAiListFilesTool(),
     createCloudAiReadFileTool(),

package/src/ai/executor.ts

@@ -547,7 +547,7 @@ const createEventMapper = (
       args: "args" in patch ? patch.args : existing?.args,
       status: patch.status ?? existing?.status ?? "running",
       at: patch.at ?? existing?.at,
-      result: "result" in patch ? patch.result : existing?.result,
+      result: patch.isError && existing?.result !== undefined ? existing.result : "result" in patch ? patch.result : existing?.result,
       isError: "isError" in patch ? patch.isError : existing?.isError,
       approval: approval && !allowRememberedApprovals ? { ...approval, allowAlways: false, allowChat: false } : approval,
       review: patch.review ?? existing?.review,
@@ -1080,6 +1080,11 @@ export class AiTurnExecutor {
     const dynamicToolRuntimeContext = {
       turnId,
       reportToolProgress: (callId: string, message: string) => pipeline.reportToolProgress(callId, message),
+      reportToolResult: (callId: string, result: unknown) => pipeline.reportToolResult(callId, result),
+      maxToolResultChars: resolveAiToolResultMaxChars({
+        contextWindow: resolved.provider.contextWindow,
+        configuredMaxChars: settings.maxToolResultChars,
+      }),
       reportWebsiteReceipts: (callId: string, receipts: AiWebsiteReceipt[]) => pipeline.reportWebsiteReceipts(callId, receipts),
       localToolsEnabled: activeTools.some((tool) => tool.def.name === "local_upload"),
       attachedFilePaths: new Set(config.files?.attached.map((file) => file.path) ?? []),
@@ -2501,6 +2506,13 @@ class StreamPipeline {
     await this.maybeSnapshot();
   }
 
+  async reportToolResult(callId: string, result: unknown): Promise<void> {
+    const block = this.blocks.find((block) => block.kind === "tool" && block.callId === callId);
+    if (!block || block.kind !== "tool" || block.status !== "running") return;
+    await this.emitOp(this.mapper.setTool(callId, { result }));
+    await this.maybeSnapshot();
+  }
+
   async reportToolProgress(callId: string, progress: string): Promise<void> {
     const block = this.blocks.find((block) => block.kind === "tool" && block.callId === callId);
     if (!block || block.kind !== "tool" || block.progress === progress) return;

package/src/ai/map-contracts.ts

@@ -0,0 +1,209 @@
+import { z } from "zod";
+import {
+  GeoAddressSchema,
+  GeoAvailabilityDataSchema,
+  GeoCategorySchema,
+  GeoCostsSchema,
+  GeoPlaceSchema,
+  GeoPlaceSearchInputSchema,
+  GeoPointSchema,
+} from "../contracts/geo";
+import {
+  GeoRouteChangesSchema,
+  GeoRouteOptionsSchema,
+  GeoRoutePlanSchema,
+  GeoRouteSchema,
+  GeoRouteUpdateDataSchema,
+} from "../contracts/geo-route";
+
+/** Provider website text is optional and is not guaranteed to be a valid URL. */
+export const aiMapWebsite = (value: string | undefined): string | undefined => {
+  try {
+    const url = new URL(value ?? "");
+    return url.protocol === "https:" || url.protocol === "http:" ? value : undefined;
+  } catch {
+    return undefined;
+  }
+};
+
+const label = z.string().trim().min(1).max(160);
+const web = z.object({ placeId: z.string().max(2048), description: z.string().max(600), url: z.url().max(2000) }).strict();
+// A map may accumulate two full Places result pages. Subsequent searches replace the secondary group.
+export const AiMapSchema = z
+  .object({
+    id: z.uuid(),
+    conversationId: z.string(),
+    revision: z.number().int().positive(),
+    title: label,
+    selectionId: z.string().optional(),
+    timeZone: z.string().optional(),
+    kind: z.enum(["places", "route"]),
+    pending: z.boolean().optional(),
+    pendingTurnId: z.uuid().optional(),
+    retryUsesMarks: z.boolean().optional(),
+    originCallId: z.string().optional(),
+    anchorSeq: z.number().int().positive().optional(),
+    viewedAt: z.iso.datetime().optional(),
+    lastSearch: z
+      .object({
+        categories: z.array(GeoCategorySchema),
+        name: GeoPlaceSearchInputSchema.shape.name,
+        near: z.string().optional(),
+        placeId: z.string().optional(),
+        radiusMeters: z.number().optional(),
+        title: label,
+        along: z.object({ fromKm: z.number(), toKm: z.number(), bufferMeters: z.number().optional() }).optional(),
+      })
+      .optional(),
+    searchAddress: z.object({ text: z.string(), address: GeoAddressSchema }).strict().optional(),
+    availability: GeoAvailabilityDataSchema,
+    groups: z.array(z.object({ title: label, places: z.array(GeoPlaceSchema).max(20) }).strict()).max(2),
+    web: z.array(web).max(40),
+    route: GeoRouteSchema.optional(),
+    plan: GeoRoutePlanSchema.optional(),
+    preview: z.object({ result: GeoRouteUpdateDataSchema, changes: GeoRouteChangesSchema, title: label }).strict().optional(),
+    undo: z.object({ route: GeoRouteSchema, title: label }).strict().optional(),
+    receipt: z.object({ title: label, at: z.iso.datetime() }).strict().optional(),
+    candidates: z.array(GeoAddressSchema).max(5).optional(),
+    ambiguousStopId: z.string().optional(),
+    picker: z.array(GeoPlaceSchema).max(5).optional(),
+    retryInsertStopId: z.uuid().optional(),
+    issue: z
+      .object({
+        code: z.string(),
+        scope: z.enum(["person", "cloud"]).optional(),
+        resetsAt: z.string().optional(),
+        retryAfterSeconds: z.number().optional(),
+        costs: GeoCostsSchema.optional(),
+        requiredCredits: z.number().nonnegative().optional(),
+        availableCredits: z.number().optional(),
+        turnId: z.uuid().optional(),
+        requiresCostConfirmation: z.literal(true).optional(),
+        shortfallCredits: z.number().nonnegative().optional(),
+      })
+      .strict()
+      .optional(),
+  })
+  .strict();
+export type AiMap = z.infer<typeof AiMapSchema>;
+
+const search = z
+  .object({
+    categories: z.array(GeoCategorySchema).min(1).max(5),
+    name: GeoPlaceSearchInputSchema.shape.name,
+    near: z.string().min(1).max(300).optional(),
+    placeId: z.string().max(2048).optional(),
+    radiusMeters: z.number().min(1).max(50000).optional(),
+    along: z
+      .object({ fromKm: z.number().nonnegative(), toKm: z.number().positive(), bufferMeters: z.number().min(100).max(5000).optional() })
+      .strict()
+      .optional(),
+    title: label,
+  })
+  .strict();
+// Model-facing inputs cannot inject points, polylines, or a provider result. These are resolved on the server.
+const stop = z
+  .object({
+    id: z.string().min(1).max(40),
+    address: z.string().min(1).max(300).optional(),
+    placeId: z.string().max(2048).optional(),
+    label: label.optional(),
+  })
+  .strict()
+  .refine((value) => Boolean(value.address) !== Boolean(value.placeId), "Supply exactly one address or verified place ID");
+export const AiMapCommandSchema = z.discriminatedUnion("type", [
+  z.object({ type: z.literal("places"), search, web: z.array(web).max(20).optional() }).strict(),
+  z
+    .object({
+      type: z.literal("route"),
+      stops: z
+        .array(stop)
+        .min(2)
+        .max(26)
+        .refine((stops) => new Set(stops.map((s) => s.id)).size === stops.length, "Stop IDs must be unique"),
+      options: GeoRouteOptionsSchema.optional(),
+      title: label,
+    })
+    .strict(),
+  z.object({ type: z.literal("search"), search, insert: z.boolean().optional(), web: z.array(web).max(20).optional() }).strict(),
+  z.object({ type: z.literal("describe"), web: z.array(web).max(40) }).strict(),
+  z
+    .object({
+      type: z.literal("preview"),
+      change: z.discriminatedUnion("type", [
+        z.object({ type: z.literal("insert"), placeId: z.string().max(2048), afterStopId: z.string().optional() }).strict(),
+        z.object({ type: z.literal("move"), stopId: z.string(), toIndex: z.number().int().min(0).max(25) }).strict(),
+        z.object({ type: z.literal("optimize") }).strict(),
+        z
+          .object({
+            type: z.literal("options"),
+            options: GeoRouteOptionsSchema,
+            leg: z.object({ fromStopId: z.string(), toStopId: z.string() }).strict().optional(),
+          })
+          .strict(),
+      ]),
+    })
+    .strict(),
+  z.object({ type: z.literal("choose"), index: z.number().int().min(0).max(4) }).strict(),
+  z.object({ type: z.literal("accept") }).strict(),
+  z.object({ type: z.literal("discard") }).strict(),
+  z.object({ type: z.literal("undo") }).strict(),
+  z.object({ type: z.literal("retry") }).strict(),
+]);
+export const AiMapBrowserCommandSchema = z.union([
+  AiMapCommandSchema,
+  z.object({ type: z.literal("location"), destinationId: z.string(), point: GeoPointSchema }).strict(),
+  z
+    .object({ type: z.literal("repair"), stopId: z.string(), address: z.string().trim().min(1).max(300), point: GeoPointSchema.optional() })
+    .strict(),
+]);
+export type AiMapCommand = z.infer<typeof AiMapBrowserCommandSchema>;
+export const AiMapToolInputSchema = z
+  .object({ mapId: z.uuid().optional(), revision: z.number().int().positive().optional(), command: AiMapCommandSchema })
+  .strict();
+export const AiMapReferenceSchema = AiMapSchema.pick({
+  id: true,
+  conversationId: true,
+  revision: true,
+  title: true,
+  kind: true,
+  pending: true,
+  anchorSeq: true,
+}).extend({ reference: z.literal(true) });
+export const AiMapToolResultSchema = z
+  .object({ map: z.union([AiMapSchema, AiMapReferenceSchema]), anchor: z.boolean(), summary: z.unknown().optional() })
+  .strict();
+/** Geometry belongs to the durable map, never to the model context or streaming result budget. */
+export const aiMapToolResult = (map: AiMap, anchor: boolean): z.infer<typeof AiMapToolResultSchema> => ({
+  anchor,
+  map: {
+    reference: true,
+    id: map.id,
+    conversationId: map.conversationId,
+    revision: map.revision,
+    title: map.title,
+    kind: map.kind,
+    pending: map.pending,
+    anchorSeq: map.anchorSeq,
+  },
+  summary: {
+    mapId: map.id,
+    revision: map.revision,
+    places: map.groups.map((g) => ({
+      title: g.title.slice(0, 64),
+      places: g.places.map((p, i) => ({
+        id: map.groups.indexOf(g) === 0 ? String(i + 1) : String.fromCharCode(65 + i),
+        name: p.name.slice(0, 48),
+      })),
+    })),
+    candidates: map.candidates?.map((p, index) => ({ index, address: p.formatted.slice(0, 96) })),
+    picker: map.picker?.map((p, i) => ({ id: `pick-${i + 1}`, name: p.name.slice(0, 48), atMeters: p.atMeters })),
+    stops: map.route?.stops.map((s) => ({ id: s.id, label: s.label?.slice(0, 48) })),
+    distanceMeters: map.route?.distanceMeters,
+    durationSeconds: map.route?.durationSeconds,
+    preview: map.preview ? { title: map.preview.title, delta: map.preview.result.delta } : undefined,
+    issue: map.issue,
+  },
+});
+export type AiMapToolResult = z.infer<typeof AiMapToolResultSchema>;
+export const AiMapActionSchema = z.object({ revision: z.number().int().positive(), command: AiMapBrowserCommandSchema }).strict();

package/src/ai/map-execution.ts

@@ -0,0 +1,14 @@
+import type { AiMapCommand } from "./map-contracts";
+import { type AiMapContext, applyAiMap } from "./map-service";
+import { type AiMapStored, aiMaps } from "./map-store";
+
+/** Lock and check the revision before provider work; a concurrent or stale click cannot spend against this map. */
+export async function executeStoredAiMap(
+  conversationId: string,
+  ownerUserId: string,
+  before: AiMapStored,
+  command: AiMapCommand,
+  context: AiMapContext,
+) {
+  return aiMaps.mutate(conversationId, ownerUserId, before.map.revision, before.map.id, (current) => applyAiMap(current, command, context));
+}

package/src/ai/map-notebook-save.ts

@@ -0,0 +1,276 @@
+import { z } from "zod";
+import { type CapabilityClientError, type CapabilityHttpOptions, invokeCapabilityWithDataSchema } from "../capabilities/client";
+import { CAPABILITY_MAX_REQUEST_BYTES } from "../contracts/capabilities";
+import { cloudResourceHref } from "../contracts/resource-href";
+
+const hashSchema = z.string().regex(/^sha256:[a-f0-9]{64}$/);
+const shortId = z.string().regex(/^[A-Za-z0-9]{6}$/);
+const offset = z.number().int().nonnegative();
+const pendingSchema = z
+  .object({
+    kind: z.enum(["create", "append"]),
+    key: z.string().min(1).max(200),
+    end: offset,
+    beforeHash: hashSchema,
+    afterHash: hashSchema,
+  })
+  .strict();
+
+/** Persist under the signed-in user and source key; retain saved checkpoints to prevent duplicates. */
+export const MapNotebookSaveCheckpointSchema = z
+  .object({
+    version: z.literal(1),
+    sourceKey: z.string().min(1).max(256),
+    notebookId: shortId,
+    contentHash: hashSchema,
+    total: offset,
+    completed: offset,
+    attempt: offset,
+    noteId: shortId.optional(),
+    pending: pendingSchema.optional(),
+  })
+  .strict();
+export type MapNotebookSaveCheckpoint = z.infer<typeof MapNotebookSaveCheckpointSchema>;
+export type MapNotebookSaveResult = {
+  status: "saved" | "cancelled" | "conflict" | "unknown" | "error";
+  checkpoint?: MapNotebookSaveCheckpoint;
+  notebookHref: string;
+  noteId?: string;
+  noteHref?: string;
+  /** Stable helper code or the original capability error code; caller supplies localized UI text. */
+  code?: string;
+  message?: string;
+};
+export type MapNotebookSaveOptions = {
+  /** Exact server export, with its existing first # title. Refetch the same export on resume. */
+  content: string;
+  notebookId: string;
+  /** Map ID + revision (and conversation if needed), stable across explicit resumes. */
+  sourceKey: string;
+  checkpoint?: MapNotebookSaveCheckpoint;
+  /** Must durably persist before resolving. Called before EVERY mutation and after every receipt. */
+  onCheckpoint: (checkpoint: MapNotebookSaveCheckpoint) => void | Promise<void>;
+  signal?: AbortSignal;
+  /** Normal public capability transport; also supplies a fake HTTP seam for tests. */
+  client?: CapabilityHttpOptions;
+};
+
+const encoder = new TextEncoder();
+const hash = async (content: string): Promise<string> => {
+  const digest = await crypto.subtle.digest("SHA-256", encoder.encode(content));
+  return `sha256:${Array.from(new Uint8Array(digest), (byte) => byte.toString(16).padStart(2, "0")).join("")}`;
+};
+const fits = (input: unknown): boolean => encoder.encode(JSON.stringify({ input })).byteLength <= CAPABILITY_MAX_REQUEST_BYTES;
+// Offsets and public character caps use UTF-16. Keep a supplementary character in one request.
+const boundary = (content: string, end: number): number =>
+  end > 0 && end < content.length && /[\uD800-\uDBFF]/.test(content[end - 1]!) && /[\uDC00-\uDFFF]/.test(content[end]!) ? end - 1 : end;
+
+const createEnd = (content: string, notebookId: string): number => {
+  let low = 0;
+  let high = Math.min(content.length, 200_000);
+  while (low < high) {
+    const mid = Math.ceil((low + high) / 2);
+    if (fits({ notebookId, content: content.slice(0, mid) })) low = mid;
+    else high = mid - 1;
+  }
+  return boundary(content, low);
+};
+type Append = { kind: "append"; content: string; separator: "none" };
+const appendBatch = (content: string, start: number, noteId: string, ifContentHash: string) => {
+  const operations: Append[] = [];
+  let end = start;
+  while (end < content.length && operations.length < 20) {
+    const next = boundary(content, Math.min(end + 10_000, content.length));
+    const operation: Append = { kind: "append", content: content.slice(end, next), separator: "none" };
+    if (!fits({ noteId, ifContentHash, blockLimit: 0, operations: [...operations, operation] })) break;
+    operations.push(operation);
+    end = next;
+  }
+  return { end, input: { noteId, ifContentHash, blockLimit: 0, operations } };
+};
+// The platform treats a valid owning-app 4xx as no effect. Unknown/claim errors are exceptions.
+const definitelyRejected = (error: CapabilityClientError): boolean =>
+  error.status >= 400 &&
+  error.status < 500 &&
+  ![
+    "IDEMPOTENCY_IN_PROGRESS",
+    "IDEMPOTENCY_UNCERTAIN",
+    "IDEMPOTENCY_CONFLICT",
+    "ACTION_OUTCOME_UNKNOWN",
+    "REQUEST_CANCELLED",
+    "DEADLINE_EXCEEDED",
+    "INVALID_APP_RESPONSE",
+    "RESPONSE_TOO_LARGE",
+  ].includes(error.code);
+
+const noteSchema = z.object({ id: shortId, notebookId: shortId });
+const readSchema = noteSchema.extend({ contentHash: hashSchema });
+const editSchema = z.object({ beforeHash: hashSchema, afterHash: hashSchema });
+
+/**
+ * One bounded save, with no automatic retries. The app invokes this again for explicit resume.
+ * Unknown creates are never repeated, even after the platform's 24-hour claim retention.
+ * note.edit forbids idempotency headers; full-content hashes detect changed prefixes. An uncertain append at the old hash stays unknown.
+ * This helper uses ordinary capabilities and never approves an Action on the caller's behalf.
+ */
+export async function saveMapNotebook(options: MapNotebookSaveOptions): Promise<MapNotebookSaveResult> {
+  const { content, notebookId, sourceKey, signal, client } = options;
+  const notebookHref = cloudResourceHref({ type: "notebooks.notebook", id: notebookId });
+  let checkpoint: MapNotebookSaveCheckpoint | undefined;
+  const result = (status: MapNotebookSaveResult["status"], code?: string, message?: string): MapNotebookSaveResult => ({
+    status,
+    checkpoint,
+    notebookHref,
+    code,
+    message,
+    ...(checkpoint?.noteId
+      ? { noteId: checkpoint.noteId, noteHref: cloudResourceHref({ type: "notebooks.note", id: checkpoint.noteId }) }
+      : {}),
+  });
+  const persist = async (next: MapNotebookSaveCheckpoint) => {
+    checkpoint = next;
+    // Never hand mutable internal state to the storage/UI callback.
+    await options.onCheckpoint(structuredClone(next));
+  };
+  const read = (id: string) =>
+    invokeCapabilityWithDataSchema(
+      {
+        kind: "query",
+        appId: "notebooks",
+        capabilityId: "note.read",
+        input: { id, contentLimit: 1 },
+        signal,
+      },
+      readSchema,
+      client,
+    );
+  try {
+    shortId.parse(notebookId);
+    z.string().min(1).max(256).parse(sourceKey);
+    // The exporter supplies a title; otherwise note.create may prepend one and change the prefix.
+    const titleEnd = content.indexOf("\n");
+    if (!/^# [^\r\n\s][^\r\n]*/.test(content)) return result("error", "invalid_title");
+    const contentHash = await hash(content);
+    if (options.checkpoint) {
+      checkpoint = MapNotebookSaveCheckpointSchema.parse(options.checkpoint);
+      if (
+        checkpoint.sourceKey !== sourceKey ||
+        checkpoint.notebookId !== notebookId ||
+        checkpoint.contentHash !== contentHash ||
+        checkpoint.total !== content.length ||
+        checkpoint.completed > content.length ||
+        (!checkpoint.noteId && checkpoint.completed !== 0)
+      )
+        return result("conflict", "source_changed");
+      const pending = checkpoint.pending;
+      if (
+        pending &&
+        (pending.end <= checkpoint.completed ||
+          pending.end > content.length ||
+          pending.beforeHash !== (await hash(content.slice(0, checkpoint.completed))) ||
+          pending.afterHash !== (await hash(content.slice(0, pending.end))) ||
+          (pending.kind === "create") === Boolean(checkpoint.noteId))
+      )
+        return result("conflict", "invalid_checkpoint");
+    } else {
+      checkpoint = { version: 1, sourceKey, notebookId, contentHash, total: content.length, completed: 0, attempt: 0 };
+    }
+    if (signal?.aborted) return result("cancelled", "cancelled");
+    if (checkpoint.pending?.kind === "create") return result("unknown", "create_outcome_unknown");
+    if (checkpoint.noteId) {
+      const current = await read(checkpoint.noteId);
+      if (!current.ok) return result(signal?.aborted ? "cancelled" : "unknown", current.error.code, current.error.message);
+      if (current.data.data.id !== checkpoint.noteId || current.data.data.notebookId !== notebookId)
+        return result("conflict", "note_moved");
+      const currentHash = current.data.data.contentHash;
+      if (checkpoint.pending && currentHash === checkpoint.pending.afterHash) {
+        await persist({ ...checkpoint, completed: checkpoint.pending.end, pending: undefined });
+      } else if (currentHash === (await hash(content.slice(0, checkpoint.completed)))) {
+        // The service checks the hash before publication, without compare-and-swap.
+        // The original request could still publish later: the old hash is NOT proof of no effect.
+        if (checkpoint.pending) return result("unknown", "append_outcome_unknown");
+      } else return result("conflict", "content_changed");
+    }
+    // Every iteration consumes a nonempty prefix: no retries, no work independent of source size.
+    while (checkpoint.completed < content.length) {
+      if (signal?.aborted) return result("cancelled", "cancelled");
+      const beforeHash = await hash(content.slice(0, checkpoint.completed));
+      const batch = checkpoint.noteId ? appendBatch(content, checkpoint.completed, checkpoint.noteId, beforeHash) : undefined;
+      const end = batch?.end ?? createEnd(content, notebookId);
+      if (end <= checkpoint.completed || (!checkpoint.noteId && end < (titleEnd < 0 ? content.length : titleEnd + 1))) {
+        return result("error", "request_too_large");
+      }
+      const afterHash = await hash(content.slice(0, end));
+      // Source digest scopes creates across reloads; offset + attempt identifies each batch.
+      const key = `map-note:${await hash(`${sourceKey}:${notebookId}:${contentHash}`)}:${checkpoint.completed}:${checkpoint.attempt}`;
+      const pending = { kind: checkpoint.noteId ? ("append" as const) : ("create" as const), key, end, beforeHash, afterHash };
+      try {
+        await persist({ ...checkpoint, pending, attempt: checkpoint.attempt + 1 });
+      } catch (cause) {
+        // This attempt is known unsent, even if storage wrote and then threw.
+        // Keep its incremented identity; a caller can persist this safe checkpoint and resume.
+        checkpoint = { ...checkpoint, pending: undefined };
+        return result("error", "checkpoint_failed", cause instanceof Error ? cause.message : String(cause));
+      }
+      if (signal?.aborted) {
+        // Nothing was dispatched; the next explicit resume can safely use a new attempt.
+        await persist({ ...checkpoint, pending: undefined });
+        return result("cancelled", "cancelled");
+      }
+      if (!batch) {
+        const created = await invokeCapabilityWithDataSchema(
+          {
+            kind: "action",
+            appId: "notebooks",
+            capabilityId: "note.create",
+            input: { notebookId, content: content.slice(0, end) },
+            idempotencyKey: key,
+            signal,
+          },
+          noteSchema,
+          client,
+        );
+        if (!created.ok) {
+          if (definitelyRejected(created.error)) {
+            await persist({ ...checkpoint, pending: undefined });
+            return result("error", created.error.code, created.error.message);
+          }
+          return result(signal?.aborted ? "cancelled" : "unknown", created.error.code, created.error.message);
+        }
+        // Persist the known ID before querying or performing another mutation.
+        await persist({ ...checkpoint, noteId: created.data.data.id, completed: end, pending: undefined });
+        if (created.data.data.notebookId !== notebookId) return result("conflict", "note_moved");
+        const current = await read(created.data.data.id);
+        if (!current.ok) return result(signal?.aborted ? "cancelled" : "unknown", current.error.code, current.error.message);
+        if (current.data.data.contentHash !== afterHash || current.data.data.notebookId !== notebookId)
+          return result("conflict", "content_changed");
+      } else {
+        const edited = await invokeCapabilityWithDataSchema(
+          {
+            kind: "action",
+            appId: "notebooks",
+            capabilityId: "note.edit",
+            input: batch.input,
+            signal,
+          },
+          editSchema,
+          client,
+        );
+        if (!edited.ok) {
+          if (definitelyRejected(edited.error)) {
+            await persist({ ...checkpoint, pending: undefined });
+            return result(edited.error.status === 409 ? "conflict" : "error", edited.error.code, edited.error.message);
+          }
+          return result(signal?.aborted ? "cancelled" : "unknown", edited.error.code, edited.error.message);
+        }
+        if (edited.data.data.beforeHash !== beforeHash || edited.data.data.afterHash !== afterHash)
+          return result("conflict", "unexpected_receipt");
+        await persist({ ...checkpoint, completed: end, pending: undefined });
+      }
+    }
+    return result("saved");
+  } catch (cause) {
+    // Includes persistence failures. Never proceed to a dependent mutation after a failed callback.
+    return result(signal?.aborted ? "cancelled" : "error", "save_failed", cause instanceof Error ? cause.message : String(cause));
+  }
+}