@ixo/oracle-runtime-workers 0.4.0 → 0.9.0

package/README.md

@@ -109,7 +109,11 @@ lifetime are in [operations](docs/operations.md).
   for production (0.1.0–0.1.2 could send plaintext into an encrypted room
   after a lazy-member sync delta, and queued session markers behind
   background replays — both fixed in 0.1.3 and re-measured, see
-  [load-tests](docs/load-tests.md#session-creation-is-the-one-funnel)).
+  [load-tests](docs/load-tests.md#session-creation-is-the-one-funnel));
+  0.3.1 brings the streamed media calls the legacy-copy import and the
+  attachments now use (a 50 MB Node-era checkpoint no longer resets the
+  user object's isolate) and the crypto-snapshot flush before every keys
+  upload.
 - Open: the memory engine's recall ranking on accounts with a long history;
   the storage cost of task-holding users at scale (R2 page tier, see
   [architecture](docs/architecture.md#storage-cost-planning)).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ixo/oracle-runtime-workers",
-  "version": "0.4.0",
+  "version": "0.9.0",
   "description": "QiForge oracle runtime for Cloudflare Workers — Durable Object per user (SQLite in WASM over DO storage), Matrix E2EE gateway Durable Object, Hono HTTP/SSE shell.",
   "private": false,
   "publishConfig": {
@@ -33,7 +33,7 @@
     "@composio/core": "0.10.0",
     "@composio/langchain": "0.9.2",
     "@ixo/editor": "6.0.1",
-    "@ixo/matrix-bot-workers-sdk": "0.1.3",
+    "@ixo/matrix-bot-workers-sdk": "0.4.0",
     "@ixo/matrix-crdt": "^1.2.5",
     "@langchain/core": "1.1.48",
     "@langchain/langgraph": "1.3.2",
@@ -52,7 +52,7 @@
     "matrix-js-sdk": "^42.2.0",
     "superjson": "1.13.3",
     "wa-sqlite": "1.0.0",
-    "yjs": "^13.6.27",
+    "yjs": "13.6.32",
     "zod": "^4.4.3",
     "@ixo/ucan": "2.2.0"
   },

package/src/attachments/download.ts

@@ -52,15 +52,20 @@ export function validateUrlTarget(targetUrl: string): void {
  * Durable Object in the user object; tests pass an in-memory fake.
  */
 export interface MatrixMediaSource {
-  /** Raw bytes behind an `mxc://` URI (authenticated media download). */
-  downloadMxc(mxc: string): Promise<Uint8Array>;
+  /**
+   * Raw bytes behind an `mxc://` URI (authenticated media download), the
+   * transfer cut off once it passes `maxBytes`.
+   */
+  downloadMxc(mxc: string, maxBytes?: number): Promise<Uint8Array>;
   /**
    * Bytes of the media event `eventId` in `roomId`, decrypted when the event
-   * carries an encrypted `file`. Null when the event does not exist.
+   * carries an encrypted `file`, the transfer cut off once it passes
+   * `maxBytes`. Null when the event does not exist.
    */
   downloadEvent(
     roomId: string,
     eventId: string,
+    maxBytes?: number,
   ): Promise<{
     bytes: Uint8Array;
     mimetype?: string;
@@ -104,6 +109,33 @@ function concat(chunks: Uint8Array[], total: number): Uint8Array {
   return out;
 }
 
+/**
+ * Collect a stream into bytes with a running size check: the moment the
+ * total passes `maxBytes` the stream is cancelled and an error thrown, so an
+ * oversized file never lands in memory whole.
+ */
+export async function readBytesCapped(
+  stream: ReadableStream<Uint8Array>,
+  maxBytes: number,
+): Promise<Uint8Array> {
+  const reader = stream.getReader();
+  const chunks: Uint8Array[] = [];
+  let total = 0;
+  for (;;) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    total += value.byteLength;
+    if (total > maxBytes) {
+      void reader.cancel();
+      throw new Error(
+        `File exceeds maximum size (${Math.round(maxBytes / 1024 / 1024)} MB) — download aborted`,
+      );
+    }
+    chunks.push(value);
+  }
+  return concat(chunks, total);
+}
+
 /**
  * Download an http(s) URL: every redirect hop is SSRF-validated, the body is
  * streamed with a running size check so an oversized file never lands in
@@ -150,24 +182,9 @@ export async function downloadFromUrl(
         `File too large: server reports ${Math.round(parseInt(contentLength, 10) / 1024 / 1024)} MB (limit: ${Math.round(maxBytes / 1024 / 1024)} MB)`,
       );
     }
-    const reader = response.body?.getReader();
-    if (!reader) throw new Error('Response body is not readable');
-    const chunks: Uint8Array[] = [];
-    let total = 0;
-    for (;;) {
-      const { done, value } = await reader.read();
-      if (done) break;
-      total += value.byteLength;
-      if (total > maxBytes) {
-        void reader.cancel();
-        throw new Error(
-          `File exceeds maximum size (${Math.round(maxBytes / 1024 / 1024)} MB) — download aborted`,
-        );
-      }
-      chunks.push(value);
-    }
+    if (!response.body) throw new Error('Response body is not readable');
     return {
-      data: concat(chunks, total),
+      data: await readBytesCapped(response.body, maxBytes),
       contentType,
       ...(currentUrl !== url ? { finalUrl: currentUrl } : {}),
     };
@@ -206,12 +223,16 @@ export async function loadAttachmentBytes(
       throw new Error(
         `Cannot fetch event ${attachment.eventId}: no Matrix room for this turn`,
       );
-    const media = await source.downloadEvent(roomId, attachment.eventId);
+    const media = await source.downloadEvent(
+      roomId,
+      attachment.eventId,
+      maxBytes,
+    );
     if (!media) throw new Error(`Matrix event ${attachment.eventId} not found`);
     bytes = media.bytes;
     httpType = media.mimetype;
   } else if (attachment.mxcUri!.startsWith('mxc://')) {
-    bytes = await source.downloadMxc(attachment.mxcUri!);
+    bytes = await source.downloadMxc(attachment.mxcUri!, maxBytes);
   } else {
     const result = await downloadFromUrl(attachment.mxcUri!, {
       ...opts,

package/src/attachments/index.ts

@@ -8,6 +8,7 @@ export {
   downloadFromUrl,
   loadAttachmentBytes,
   MAX_FILE_SIZE,
+  readBytesCapped,
   MAX_TOTAL_SIZE,
   validateUrlTarget,
   type DownloadOptions,

package/src/core/env.ts

@@ -21,6 +21,14 @@ import { NOOP_LOGGER } from './utils';
  * other non-string bindings on the Worker `env` object never reach plugins
  * through `ctx.config`.
  */
+/**
+ * Three times the Node runtime's hard-coded `recursionLimit: 200`. A tool-call
+ * round trip costs about 6 steps with the bundled middlewares, so 600 is
+ * roughly 100 chained tool calls — room for long research turns without an
+ * env override.
+ */
+export const TURN_RECURSION_LIMIT_DEFAULT = 600;
+
 export const baseEnvSchema = z.object({
   // --- identity -----------------------------------------------------------
   ORACLE_NAME: z.string().min(1),
@@ -86,6 +94,17 @@ export const baseEnvSchema = z.object({
    * token, at some cost to hard multi-step reasoning.
    */
   MAIN_REASONING_EFFORT: z.enum(['low', 'medium', 'high']).default('medium'),
+  /**
+   * LangGraph `recursionLimit` for one turn — the super-steps (a model call,
+   * a batch of tool calls, a middleware hook) a turn may take before it fails
+   * with `GraphRecursionError`. Default 600 (the Node runtime hard-codes 200);
+   * see `TURN_RECURSION_LIMIT_DEFAULT`.
+   */
+  TURN_RECURSION_LIMIT: z.coerce
+    .number()
+    .int()
+    .min(1)
+    .default(TURN_RECURSION_LIMIT_DEFAULT),
 
   // --- misc ---------------------------------------------------------------
   LOG_LEVEL: z.string().default('info'),

package/src/core/main-agent.ts

@@ -1,5 +1,6 @@
 import {
   createAgent,
+  ToolInvocationError,
   toolRetryMiddleware,
   type StructuredTool,
 } from 'langchain';
@@ -16,12 +17,28 @@ import { buildMetaTools } from './meta-tools';
 import {
   createByoHistorySanitizerMiddleware,
   createCapabilityGateMiddleware,
+  createDanglingToolCallRepairMiddleware,
   createPageContextMiddleware,
   createSafetyGuardrailMiddleware,
   createSummarizationMiddleware,
   createToolRepetitionGuardMiddleware,
   createToolValidationMiddleware,
 } from './middlewares';
+
+/**
+ * The model's arguments failed the tool's schema (LangChain's ToolNode
+ * throws `ToolInvocationError` before the tool runs). Matched by class AND by
+ * name / message shape: a bundle can carry the class twice (ESM and CJS
+ * entry points), and then `instanceof` is false for the very error it names.
+ */
+function isToolInvocationError(error: unknown): boolean {
+  if (error instanceof ToolInvocationError) return true;
+  if (!(error instanceof Error)) return false;
+  return (
+    error.name === 'ToolInvocationError' ||
+    /^Error invoking tool '.+' with kwargs /.test(error.message)
+  );
+}
 import {
   composePrompt,
   formatTimeContext,
@@ -295,13 +312,21 @@ export async function createMainAgent(
   const resolveModel = hooks?.resolveModel ?? ambient.llm.get.bind(ambient.llm);
 
   const middleware = [
-    // Outermost, as on Node: rewrite cross-provider reasoning residue before
-    // the summarizer condenses (a well-formed) history.
+    // Outermost: a turn that died between a tool call and its result (abort,
+    // object reset) must not poison every later model request on the thread.
+    createDanglingToolCallRepairMiddleware({ logger: ambient.logger }),
+    // Then, as on Node: rewrite cross-provider reasoning residue before the
+    // summarizer condenses (a well-formed) history.
     createByoHistorySanitizerMiddleware({ logger: ambient.logger }),
     // Condense long threads before everything tool-related.
     // Without this, thread state — reloaded, re-serialized, and re-uploaded to
     // the owner store on every turn — grows without bound.
-    createSummarizationMiddleware({ model: resolveModel('routing') }),
+    // The summarizer's own model call is internal: it must never stream its
+    // tokens into the user's reply (belt: no streaming here; braces: the SSE
+    // stream drops `lc_source: 'summarization'` events).
+    createSummarizationMiddleware({
+      model: resolveModel('routing', { disableStreaming: true }),
+    }),
     createCapabilityGateMiddleware({
       pluginByToolName,
       visibilityByToolName,
@@ -312,7 +337,34 @@ export async function createMainAgent(
       logger: ambient.logger,
     }),
     createToolRepetitionGuardMiddleware({ logger: ambient.logger }),
-    toolRetryMiddleware({ onFailure: (error) => error.message }),
+    // Retries are for transient failures. A ToolInvocationError is the
+    // model's arguments failing the tool's schema: the same call again gives
+    // the same rejection, so it is not retried — and it is logged, because
+    // the error ToolMessage it becomes is otherwise invisible in the logs
+    // (the tool-validation middleware above never sees it; ToolNode throws
+    // it before the tool runs).
+    toolRetryMiddleware({
+      retryOn: (error) => !isToolInvocationError(error),
+      onFailure: (error) => {
+        const rejected = isToolInvocationError(error);
+        ambient.logger.warn(
+          `[tool-retry] ${rejected ? 'tool call rejected by the tool schema' : 'tool failed after retries'}: ${error.message.split('\n')[0] ?? error.message}`,
+        );
+        if (!rejected) return error.message;
+        // The model (and the Portal's card) get the reason, not the kwargs
+        // dump — `Error invoking tool 'x' with kwargs {…} with error: Error:
+        // Received tool input did not match expected schema` stays in the tail.
+        const toolName = /^Error invoking tool '([^']+)'/.exec(
+          error.message,
+        )?.[1];
+        const reason =
+          error.message
+            .split(' with error: ')
+            .at(-1)
+            ?.replace(/^Error: /, '') ?? error.message;
+        return `Invalid arguments for ${toolName ?? 'the tool'}: ${reason}. Check the tool's parameter schema and call it again with corrected arguments.`;
+      },
+    }),
     // Same host-gated pair as the Node runtime: the page-context block needs a
     // title lookup, the safety guardrail a classification model.
     ...(hooks?.getRoomTitle

package/src/core/middlewares/dangling-tool-calls.ts

@@ -0,0 +1,99 @@
+/**
+ * A turn that dies between the model's tool call and the tool's result — the
+ * user aborted it, or the runtime was reset while the tool ran — leaves the
+ * checkpoint with an assistant message whose `tool_calls` have no
+ * `ToolMessage`. OpenRouter chat completions tolerate that history; the
+ * ChatGPT-subscription lane (Responses API) rejects every later turn on the
+ * session with `400 No tool output found for function call …`. This
+ * middleware answers each unanswered call, for the model request only, with
+ * a tool result that says the call was interrupted. The checkpoint is left as
+ * it is: nothing is rewritten in place, and the model is free to call the
+ * tool again.
+ */
+import {
+  type BaseMessage,
+  isAIMessage,
+  isToolMessage,
+  ToolMessage,
+} from '@langchain/core/messages';
+import { type AgentMiddleware, createMiddleware } from 'langchain';
+import type { Logger } from '../../plugin-api/types';
+import { NOOP_LOGGER } from '../utils';
+
+export interface DanglingToolCallRepairMiddlewareOptions {
+  /** Optional logger; defaults to a no-op. */
+  logger?: Logger;
+}
+
+/** The result handed to the model for a tool call that never returned. */
+export function interruptedToolResult(toolName: string): string {
+  return `The call to ${toolName} was interrupted before it returned a result (the turn was aborted or the runtime restarted while it ran), so nothing from it was recorded. Call it again if its result is still needed.`;
+}
+
+export interface DanglingToolCallRepair {
+  /** The original array when nothing was missing, otherwise a repaired copy. */
+  messages: BaseMessage[];
+  /** How many tool calls were answered. */
+  repaired: number;
+}
+
+/**
+ * Insert a synthetic `ToolMessage` for every `tool_calls` entry of an
+ * assistant message that has no `ToolMessage` among the tool messages that
+ * directly follow it. The synthetic results go right after the real ones,
+ * before the next non-tool message, which is the position every provider's
+ * request converter requires.
+ */
+export function repairDanglingToolCalls(
+  messages: BaseMessage[],
+): DanglingToolCallRepair {
+  const out: BaseMessage[] = [];
+  let repaired = 0;
+  for (let i = 0; i < messages.length; i += 1) {
+    const message = messages[i]!;
+    out.push(message);
+    if (!isAIMessage(message)) continue;
+    const toolCalls = message.tool_calls ?? [];
+    if (toolCalls.length === 0) continue;
+
+    const answered = new Set<string>();
+    let next = i + 1;
+    while (next < messages.length && isToolMessage(messages[next]!)) {
+      const toolMessage = messages[next] as ToolMessage;
+      answered.add(toolMessage.tool_call_id);
+      out.push(toolMessage);
+      next += 1;
+    }
+    for (const call of toolCalls) {
+      if (!call.id || answered.has(call.id)) continue;
+      out.push(
+        new ToolMessage({
+          tool_call_id: call.id,
+          name: call.name,
+          content: interruptedToolResult(call.name),
+          status: 'error',
+        }),
+      );
+      repaired += 1;
+    }
+    i = next - 1;
+  }
+  return { messages: repaired === 0 ? messages : out, repaired };
+}
+
+export const createDanglingToolCallRepairMiddleware = (
+  options?: DanglingToolCallRepairMiddlewareOptions,
+): AgentMiddleware => {
+  const logger = options?.logger ?? NOOP_LOGGER;
+  return createMiddleware({
+    name: 'DanglingToolCallRepairMiddleware',
+    wrapModelCall: async (request, handler) => {
+      const { messages, repaired } = repairDanglingToolCalls(request.messages);
+      if (repaired === 0) return handler(request);
+      logger.warn(
+        `[DanglingToolCallRepair] ${repaired} tool call(s) had no result in the thread history; answered as interrupted for this model call`,
+      );
+      return handler({ ...request, messages });
+    },
+  });
+};

package/src/core/middlewares/index.ts

@@ -11,6 +11,11 @@ export {
 } from './summarization';
 export type { SummarizationMiddlewareOptions } from './summarization';
 export { createByoHistorySanitizerMiddleware } from './byo-history-sanitizer';
+export {
+  createDanglingToolCallRepairMiddleware,
+  repairDanglingToolCalls,
+} from './dangling-tool-calls';
+export type { DanglingToolCallRepairMiddlewareOptions } from './dangling-tool-calls';
 export type { ByoHistorySanitizerMiddlewareOptions } from './byo-history-sanitizer';
 export { createPageContextMiddleware } from './page-context';
 export type { PageContextMiddlewareOptions } from './page-context';

package/src/core/runtime-context.ts

@@ -8,6 +8,7 @@ import type {
   ChatOpenAIFields,
   Logger,
   MatrixEvent,
+  MatrixPostOpts,
   MergedConfig,
   MessageCacheInvalidationPayload,
   ModelRole,
@@ -60,7 +61,11 @@ export interface BlobStoreAdapter {
 
 /** Matrix adapter exposing only scoped operations a plugin should ever need. */
 export interface MatrixAdapter {
-  postToRoom(roomId: string, content: unknown): Promise<string>;
+  postToRoom(
+    roomId: string,
+    content: unknown,
+    opts?: MatrixPostOpts,
+  ): Promise<string>;
   /**
    * Post a timeline event with a caller-chosen event type. `postToRoom` is
    * the `m.room.message` shorthand; this is the general form. Returns the
@@ -70,6 +75,7 @@ export interface MatrixAdapter {
     roomId: string,
     eventType: string,
     content: object,
+    opts?: MatrixPostOpts,
   ): Promise<string>;
   getRoomState(roomId: string): Promise<RoomStateSnapshot>;
   getEventById(roomId: string, eventId: string): Promise<MatrixEvent>;
@@ -165,6 +171,8 @@ export interface AmbientServices {
   /** Host attachment access for the current session, when provided. */
   attachments?: AttachmentViewSurface;
   onTurnEnd?: (dispose: () => void | Promise<void>) => void;
+  /** Host keep-alive for un-awaited work (`ctx.waitUntil` on Workers). */
+  background?: (work: Promise<unknown>) => void;
 }
 
 // ── Scoped emitter ──────────────────────────────────────────────────────────
@@ -401,11 +409,11 @@ export function buildRuntimeContext<TConfig = MergedConfig>(
         ambient.blobStore.isValidBlobId(value),
     },
     matrix: {
-      postToRoom: (roomId, content) =>
-        ambient.matrix.postToRoom(roomId, content),
+      postToRoom: (roomId, content, opts) =>
+        ambient.matrix.postToRoom(roomId, content, opts),
       botCredentials: () => ambient.matrix.botCredentials(),
-      postEvent: (roomId, eventType, content) =>
-        ambient.matrix.postEvent(roomId, eventType, content),
+      postEvent: (roomId, eventType, content, opts) =>
+        ambient.matrix.postEvent(roomId, eventType, content, opts),
       getRoomState: (roomId) => ambient.matrix.getRoomState(roomId),
       getEventById: (roomId, eventId) =>
         ambient.matrix.getEventById(roomId, eventId),
@@ -444,6 +452,7 @@ export function buildRuntimeContext<TConfig = MergedConfig>(
     ...(ambient.frontend ? { frontend: ambient.frontend } : {}),
     ...(ambient.attachments ? { attachments: ambient.attachments } : {}),
     ...(ambient.onTurnEnd ? { onTurnEnd: ambient.onTurnEnd } : {}),
+    ...(ambient.background ? { background: ambient.background } : {}),
     shared: EMPTY_SHARED,
     ...(runConfig.toolCall?.id ? { toolCallId: runConfig.toolCall.id } : {}),
   };

package/src/core/subagent-as-tool.ts

@@ -12,6 +12,7 @@ import {
   type AgentMiddleware,
   type StructuredTool,
 } from 'langchain';
+import { createDanglingToolCallRepairMiddleware } from './middlewares/dangling-tool-calls';
 import { z } from 'zod';
 import type { Logger } from '../plugin-api/types';
 import { NOOP_LOGGER } from './utils';
@@ -220,6 +221,11 @@ export function createSubagentAsTool(
         },
         ...(parentContext ? { context: parentContext } : {}),
         runName: spec.name,
+        // The sub-agent's model calls are the parent's tool work, not the
+        // reply: the SSE stream drops model events carrying this tag so its
+        // tokens never surface as user-visible text (its result reaches the
+        // model as the tool's output).
+        tags: ['internal', `subagent:${spec.name}`],
       },
     );
     return result.messages as BaseMessage[];
@@ -269,7 +275,12 @@ export function createSubagentAsTool(
           model: spec.model,
           tools: innerTools,
           systemPrompt: spec.systemPrompt,
-          middleware: spec.middleware ?? [],
+          // Sub-agent threads are checkpointed too, so an interrupted tool
+          // call in one would poison its later invocations the same way.
+          middleware: [
+            createDanglingToolCallRepairMiddleware(),
+            ...(spec.middleware ?? []),
+          ],
           checkpointer,
         });
 

package/src/do/ambient.ts

@@ -131,10 +131,15 @@ export function createMatrixAdapter(
   gateway: DurableObjectStub<MatrixGatewayObject>,
 ): AmbientServices['matrix'] {
   return {
-    postToRoom: (roomId, content) =>
-      gateway.sendEvent(roomId, 'm.room.message', JSON.stringify(content)),
-    postEvent: (roomId, eventType, content) =>
-      gateway.sendEvent(roomId, eventType, JSON.stringify(content)),
+    postToRoom: (roomId, content, opts) =>
+      gateway.sendEvent(
+        roomId,
+        'm.room.message',
+        JSON.stringify(content),
+        opts ?? {},
+      ),
+    postEvent: (roomId, eventType, content, opts) =>
+      gateway.sendEvent(roomId, eventType, JSON.stringify(content), opts ?? {}),
     botCredentials: () => gateway.botCredentials(),
     getRoomState: async (roomId): Promise<RoomStateSnapshot> => {
       const raw = await gateway.getRoomState(roomId);
@@ -221,6 +226,8 @@ export interface CreateAmbientInput {
   frontend?: import('../plugin-api/types').FrontendCallSurface;
   /** Per-turn cleanup registry (see `RuntimeContext.onTurnEnd`). */
   onTurnEnd?: (dispose: () => void | Promise<void>) => void;
+  /** Keep-alive for un-awaited work (see `RuntimeContext.background`). */
+  background?: (work: Promise<unknown>) => void;
   config: Record<string, unknown>;
   identity: OracleIdentity;
   availablePlugins: ReadonlySet<string>;
@@ -246,6 +253,8 @@ export function createAmbientServices(
     ...(input.tasks ? { tasks: input.tasks } : {}),
     ...(input.preferences ? { preferences: input.preferences } : {}),
     ...(input.frontend ? { frontend: input.frontend } : {}),
+    ...(input.onTurnEnd ? { onTurnEnd: input.onTurnEnd } : {}),
+    ...(input.background ? { background: input.background } : {}),
     config: input.config,
     identity: input.identity,
     availablePlugins: input.availablePlugins,

package/src/do/boot-dirty.ts

@@ -0,0 +1,38 @@
+/**
+ * Whether a freshly opened working copy has writes the system of record has
+ * not seen. The dirty mark is normally set at the end of a turn; a turn that
+ * died in the middle (an object reset, a provider error, the user's stop)
+ * leaves LangGraph's per-step checkpoints committed in SQLite with no mark,
+ * and the upload waits for whatever dirties the object next — possibly
+ * never, and a reload from the system of record would drop those steps. The
+ * VFS records a write generation with the file and the object records the
+ * generation it last uploaded; a mismatch on boot is the missing mark.
+ */
+export interface BootDirtyInput {
+  /** The object's in-memory flag (a warm boot already knows). */
+  dirtyInMemory: boolean;
+  /** The persisted `meta:dirty` flag. */
+  dirtyFlag: unknown;
+  /** The persisted generation of the last successful upload (undefined = never uploaded). */
+  uploadedGen: unknown;
+  /** The working copy's current write generation. */
+  writeGeneration: number;
+}
+
+export type BootDirtyDecision =
+  | 'already-dirty'
+  /** The persisted flag is set: adopt it (the flush alarm is armed already). */
+  | 'flagged'
+  /** Never uploaded: the first completed turn marks and flushes; nothing to reconcile. */
+  | 'never-uploaded'
+  /** Writes after the last upload with no mark: mark dirty now. */
+  | 'behind-upload'
+  | 'clean';
+
+export function decideBootDirty(input: BootDirtyInput): BootDirtyDecision {
+  if (input.dirtyInMemory) return 'already-dirty';
+  if (input.dirtyFlag === true) return 'flagged';
+  if (typeof input.uploadedGen !== 'number') return 'never-uploaded';
+  if (input.uploadedGen !== input.writeGeneration) return 'behind-upload';
+  return 'clean';
+}