Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
27.4 KB
Raw Blame
/**
 * Upload sessions (Wave B, spec 6.2): begin_page_upload, upload_page_part,
 * get_page_upload, commit_page_upload and abort_page_upload write a page
 * larger than one request in parts. Every op is write scope and treats
 * `ctx.remote !== false` as untrusted, with put_page's posture: begin routes
 * the source through the write grant and the slug through both slug fences,
 * the session is bound to its creating principal, source incarnation and page
 * (any mismatch answers `upload_not_found`, exactly as an unknown id does),
 * staged bytes count against per-principal and per-brain quotas, and commit
 * submits an ordinary put_page by reference (persistence/page-upload.ts), so
 * admission, sanitizing and the revision check run as for content sent
 * inline. Never import from '../operations.ts' here (cycle).
 */
import { randomUUID } from 'node:crypto';
import type { Operation, OperationContext } from './contract.ts';
import { OperationError, opError } from './contract.ts';
import { enforceClientSlugFence, enforceSubagentSlugFence, sourceScopeOpts, validatePageSlug } from './context.ts';
import { initializeLocalPersistence, pageMutationSource, requestPrincipalForContext, submitPageMutation } from '../persistence/page-mutations.ts';
import { CONTENT_ORIGIN_PARAM, PAGE_MUTATION_PARAMS, WRITE_WAIT_PARAM } from '../persistence/params.ts';
import { parseWriteRequestId } from '../persistence/preconditions.ts';
import { isWriteRequestId } from '../persistence/types.ts';
import { getWriteRequest } from '../persistence/journal.ts';
import { submissionAuthority } from '../persistence/authority.ts';
import { pageNotVisibleError } from '../persistence/page-visibility.ts';
import { assertLargePageAdmission } from '../persistence/large-page-guard.ts';
import { sha256 } from '../persistence/digest.ts';
import { isTerminal, type Principal, type WriteRequest } from '../persistence/model.ts';
import { PAGE_MAX_BYTES } from '../page-size-policy.ts';
import { contentSizeHold } from '../markdown.ts';
import { readPageBodyPolicy } from '../page-body/limits.ts';
import { contentRefusalError, loadImportSanityConfig } from '../import-screen.ts';
import { DEFAULT_WRITE_GATE_CONFIG, writeGateApplies } from '../write-gate.ts';
import { admitPageAppend } from '../persistence/page-append.ts';
import {
  abortUpload, appendPart, expireIfLapsed, partBytes, partMaxFrameBytes, partSha256, readUpload, readUploadByRequest, reserveUpload,
  isStagingBodyRef, sealUpload, stagedSha256, transitionUploads, uploadExpired, uploadNotFound, uploadPartFrameBytes, uploadPartLimit, type StagingBodyRef, type UploadMode, type UploadRow,
} from '../persistence/page-upload.ts';

const MODES: readonly UploadMode[] = ['create', 'replace', 'append'];
const SHA256_HEX = /^[0-9a-f]{64}$/i;
const PUT_PAGE_FLAGS = ['allow_shrink', 'allow_empty', 'drop_timeline', 'content_origin'] as const;

async function callerPrincipal(ctx: OperationContext): Promise<Principal> {
  await initializeLocalPersistence(ctx);
  return requestPrincipalForContext(ctx);
}

/**
 * The binding every call after begin re-checks: the creating principal; for a remote caller, its write source (inside
 * its read scope); the source still active at the incarnation the session began under; and, until the session is
 * committed, the page it began against (for create: still no page at the slug).
 */
function callerMayUse(ctx: OperationContext, principal: Principal, row: UploadRow, opts: { ownerOnly?: boolean } = {}): boolean {
  if (row.principal_kind !== principal.kind || row.principal_id !== principal.id) return false;
  if (ctx.remote !== false) {
    const scope = sourceScopeOpts(ctx);
    const readable = scope.sourceIds ?? (scope.sourceId !== undefined ? [scope.sourceId] : null);
    if (row.source_id !== (ctx.auth?.sourceId ?? ctx.sourceId ?? 'default') || (readable && !readable.includes(row.source_id))) return false;
  }
  try {
    enforceClientSlugFence(ctx, row.slug, 'begin_page_upload');
    enforceSubagentSlugFence(ctx, row.slug, 'begin_page_upload');
  } catch { return false; }
  if (opts.ownerOnly) return true;
  if (row.source_archived !== false || row.current_incarnation !== row.source_incarnation) return false;
  const uncommitted = row.commit_request_id === null && ['open', 'sealed', 'prepared'].includes(row.state);
  if (uncommitted && (row.mode === 'create' ? row.current_page_id !== null : row.current_page_id !== row.page_id)) return false;
  return true;
}

async function boundUpload(ctx: OperationContext, principal: Principal, uploadId: unknown, opts: { exec?: OperationContext['engine']; lock?: boolean; ownerOnly?: boolean } = {}): Promise<UploadRow> {
  if (!isWriteRequestId(uploadId)) throw uploadNotFound();
  const row = await readUpload(opts.exec ?? ctx.engine, uploadId.toLowerCase(), { lock: opts.lock });
  if (!row || !callerMayUse(ctx, principal, row, { ownerOnly: opts.ownerOnly })) throw uploadNotFound();
  return row;
}

/**
 * A lapsed session expires here (`upload_expired`); when another call moved it on first (a commit sealed it), the row
 * is read again and the caller follows its real state instead of reporting an expiry that did not happen.
 */
async function settleLapse(ctx: OperationContext, principal: Principal, row: UploadRow, opts: { ownerOnly?: boolean } = {}): Promise<UploadRow> {
  if (await expireIfLapsed(ctx.engine, row)) throw uploadExpired(row);
  if (!row.lapsed) return row;
  const current = await boundUpload(ctx, principal, row.id, opts);
  if (current.state === 'expired') throw uploadExpired(current);
  return current;
}

/** @internal Forced-race seam of the commit test: runs after commit sealed the session and hashed its parts. */
export const uploadCommitProbe: { afterHash?: (uploadId: string) => Promise<void> } = {};

function sessionStatus(ctx: OperationContext, row: UploadRow) {
  return { upload_id: row.id, state: row.state, next_part: row.next_part, received_bytes: row.received_bytes, total_bytes: row.declared_bytes,
    part_max_frame_bytes: partMaxFrameBytes(ctx), expires: row.idle_expires_at < row.hard_expires_at ? row.idle_expires_at : row.hard_expires_at,
    idle_expires_at: row.idle_expires_at, hard_expires_at: row.hard_expires_at };
}

const statusFix = (uploadId: string) => ({ mcp: { tool: 'get_page_upload', arguments: { upload_id: uploadId } }, consent: [], actor: 'agent' as const, requires_exclusive: false,
  why: 'Returns the part to send next and the bytes received so far.' });
const pageFix = (slug: string, sourceId: string) => ({ argv: ['gbrain', 'get', '--source', sourceId, '--', slug],
  mcp: { tool: 'get_page', arguments: { slug, source_id: sourceId, body: 'none' } }, consent: [], actor: 'agent' as const, requires_exclusive: false,
  why: "Returns the page's current revision and size without its body." });

function revisionChanged(slug: string, sourceId: string): OperationError {
  return opError('revision_changed', `Page ${slug} changed since this upload began, so the upload was not committed and nothing was written.`,
    "Read the page's current revision with get_page body: 'none', then begin a new upload with mode replace and that expected_revision.",
    { fix: pageFix(slug, sourceId) });
}

function invalidParam(message: string, suggestion: string): OperationError {
  return opError('invalid_params', message, suggestion);
}

/**
 * A body over the single-string ceiling: create and replace go up to the brain's page ceiling (pages.max_bytes, the
 * engine ceiling by default) through the segmented streamed preparation; an append stays within the ceiling (lane 3a
 * reads appended text whole). A remote writer is refused at once where the write gate applies to an agent-written page,
 * since the gate scans a whole body and commit would refuse the same way.
 */
async function assertLargeUploadAdmissible(ctx: OperationContext, mode: UploadMode, total: number): Promise<void> {
  const ceiling = mode === 'append' ? PAGE_MAX_BYTES : Math.max(PAGE_MAX_BYTES, (await readPageBodyPolicy(ctx.engine)).maxBytes);
  if (total > ceiling) {
    throw opError('request_too_large', contentSizeHold(total, ceiling)!.message, mode === 'append'
      ? `Nothing was staged. An append upload carries at most ${PAGE_MAX_BYTES} bytes; append the text in several uploads.`
      : `Nothing was staged. Pages up to ${ceiling} bytes are stored and searchable on this brain; split the content into smaller pages.`);
  }
  if (ctx.remote !== false && mode !== 'append' && writeGateApplies('agent_written', (await loadImportSanityConfig(ctx.engine)).writeGate ?? DEFAULT_WRITE_GATE_CONFIG)) {
    throw contentRefusalError({ code: 'file_too_large', message: `Page too large (${total} bytes) for this writer: the write gate scans an agent-written page whole, and a page over ${PAGE_MAX_BYTES} bytes is never held whole.` },
      `Nothing was staged. Split the content into pages of at most ${PAGE_MAX_BYTES} bytes; whether agent-written pages may skip the write gate (write_gate.agent_mode) is the brain host operator's decision.`,
      { legacy_error: 'request_too_large' });
  }
}

const begin_page_upload: Operation = {
  name: 'begin_page_upload',
  idempotent: true,
  outputRedaction: 'no_stored_text',
  description: 'Start writing a page too large for one request: then upload_page_part from part 0 and commit_page_upload. Same request_id resumes this upload.',
  params: {
    slug: { type: 'string', required: true, description: 'Page slug.' },
    source_id: PAGE_MUTATION_PARAMS.source_id,
    mode: { type: 'string', required: true, enum: [...MODES], description: 'create a new page, replace it (expected_revision required) or append to it.' },
    total_bytes: { type: 'number', required: true, description: 'UTF-8 bytes of the complete content.' },
    sha256: { type: 'string', required: true, description: 'Hex SHA-256 of those bytes.' },
    expected_revision: { type: 'string', description: 'Revision read; required for replace.' },
    request_id: { type: 'string', required: true, description: 'Reuse only to resume this upload.' },
  },
  mutating: true,
  scope: 'write',
  area: 'pages',
  handler: async (ctx, p) => {
    const sourceId = pageMutationSource(ctx, p, 'begin_page_upload');
    const mode = p.mode as UploadMode;
    if (!MODES.includes(mode)) throw invalidParam('mode must be create, replace or append.', 'Pass mode create for a new page, replace with expected_revision for an existing one, or append.');
    const slug = typeof p.slug === 'string' ? p.slug.toLowerCase() : '';
    validatePageSlug(slug);
    enforceClientSlugFence(ctx, slug, 'begin_page_upload');
    enforceSubagentSlugFence(ctx, slug, 'begin_page_upload');
    const total = p.total_bytes;
    if (typeof total !== 'number' || !Number.isSafeInteger(total) || total < 1) {
      throw invalidParam('total_bytes must be a positive whole number of bytes.', 'Pass the UTF-8 byte length of the complete content.');
    }
    if (total > PAGE_MAX_BYTES) await assertLargeUploadAdmissible(ctx, mode, total);
    if (typeof p.sha256 !== 'string' || !SHA256_HEX.test(p.sha256)) throw invalidParam('sha256 must be 64 hex characters.', 'Pass the hex SHA-256 of the complete content\'s UTF-8 bytes.');
    if (p.request_id === undefined) throw invalidParam('request_id is required.', 'Pass a new UUID; send the same request_id again only to resume this upload.');
    const clientRequestId = parseWriteRequestId(p.request_id)!;
    const expected = p.expected_revision;
    if (expected !== undefined && !isWriteRequestId(expected)) throw invalidParam('expected_revision must be the UUID returned by a page read.', 'Read the page and pass its revision unchanged.');
    if (mode === 'replace' && expected === undefined) {
      throw invalidParam('mode replace requires expected_revision.', "Read the page with get_page body: 'none' and pass its revision as expected_revision.");
    }
    if (mode === 'create' && expected !== undefined) throw invalidParam('mode create takes no expected_revision.', 'Use mode replace to write over an existing page.');
    if (ctx.dryRun) return { dry_run: true, action: 'begin_page_upload', slug, mode };
    const want = { sourceId, slug, mode, totalBytes: total, sha256: p.sha256.toLowerCase(), baseRevision: (expected as string | undefined)?.toLowerCase() ?? null };
    const principal = await callerPrincipal(ctx);
    const resumed = async (row: UploadRow) => {
      if (row.source_id !== want.sourceId || row.slug !== want.slug || row.mode !== want.mode || row.declared_bytes !== want.totalBytes
        || row.declared_sha256 !== want.sha256 || row.base_revision !== want.baseRevision) {
        throw opError('idempotency_conflict', 'This request_id already began a different upload.', 'Begin this upload with a new request_id; reuse a request_id only to resume the same upload.');
      }
      if (!callerMayUse(ctx, principal, row)) throw uploadNotFound();
      return sessionStatus(ctx, await settleLapse(ctx, principal, row));
    };
    const prior = await readUploadByRequest(ctx.engine, principal, clientRequestId);
    if (prior) return resumed(prior);
    const [source] = await ctx.engine.executeRaw<{ incarnation: string; archived: boolean }>('SELECT incarnation::text AS incarnation, archived FROM sources WHERE id=$1', [sourceId]);
    if (!source || source.archived) {
      throw opError('source_changed', 'The write source is not active.', `Source ${sourceId} is archived or not registered, so nothing was staged. Write to an active source (sources_list shows them).`);
    }
    // put_page's grant and visibility checks first: a page this caller may not see answers as put_page does, before any read of it.
    await submissionAuthority(ctx, mode === 'append' ? 'append_page' : 'put_page', sourceId, source.incarnation, slug);
    const snapshot = await ctx.engine.readPageSnapshot(slug, { sourceId, includeDeleted: true });
    if (mode === 'create' && snapshot) {
      throw opError('revision_required', `Page ${slug} already exists, so an upload with mode create cannot write it; nothing was staged.`,
        "Read the page with get_page body: 'none', then begin with mode replace and its revision as expected_revision.", { fix: pageFix(slug, sourceId) });
    }
    if (mode !== 'create' && (!snapshot || snapshot.page.deleted_at)) {
      if (ctx.remote !== false) throw pageNotVisibleError();
      throw opError('page_not_found', `Page not found: ${slug}`, `An upload with mode ${mode} writes an existing page; begin with mode create to make it.`);
    }
    if (mode !== 'create' && want.baseRevision !== null && snapshot!.revision !== want.baseRevision) throw revisionChanged(slug, sourceId);
    const id = randomUUID();
    try {
      await reserveUpload(ctx.engine, { id, principal, clientRequestId, sourceId, sourceIncarnation: source.incarnation, slug,
        pageId: snapshot ? Number(snapshot.page.id) : null, mode, baseRevision: want.baseRevision, totalBytes: total, sha256: want.sha256 });
    } catch (error) {
      const raced = await readUploadByRequest(ctx.engine, principal, clientRequestId);
      if (raced) return resumed(raced);
      throw error;
    }
    return sessionStatus(ctx, (await readUpload(ctx.engine, id))!);
  },
};

const upload_page_part: Operation = {
  name: 'upload_page_part',
  idempotent: true,
  outputRedaction: 'no_stored_text',
  description: 'Send the next part of an upload: part equals next_part, the whole call within part_max_frame_bytes, cut between code points.',
  params: {
    upload_id: { type: 'string', required: true, description: 'From begin_page_upload.' },
    part: { type: 'number', required: true, description: 'Part number: next_part, from 0.' },
    text: { type: 'string', required: true, description: 'The next slice of the content.' },
    part_sha256: { type: 'string', required: true, description: "Hex SHA-256 of this part's UTF-8 bytes." },
  },
  mutating: true,
  scope: 'write',
  area: 'pages',
  handler: async (ctx, p) => {
    const part = p.part;
    if (typeof part !== 'number' || !Number.isSafeInteger(part) || part < 0) throw invalidParam('part must be a whole number from 0.', 'Send next_part from begin_page_upload or get_page_upload.');
    if (typeof p.part_sha256 !== 'string' || !SHA256_HEX.test(p.part_sha256)) throw invalidParam('part_sha256 must be 64 hex characters.', "Pass the hex SHA-256 of this part's UTF-8 bytes.");
    const partSha = p.part_sha256.toLowerCase();
    const cap = partMaxFrameBytes(ctx);
    const frame = uploadPartFrameBytes({ upload_id: String(p.upload_id), part, text: typeof p.text === 'string' ? p.text : '', part_sha256: partSha });
    if (frame > cap) {
      throw opError('part_too_large', `This part's frame is ${frame} bytes, over this connection's ${cap}-byte part limit (part_max_frame_bytes), so it was not stored.`,
        `Cut the part so the whole call's encoded JSON stays within ${cap} bytes (escaped quotes, backslashes and control characters count at their escaped size), then send it again as part ${part}.`,
        { detail: JSON.stringify({ frame_bytes: frame, part_max_frame_bytes: cap }) });
    }
    const bytes = partBytes(p.text);
    if (sha256(bytes) !== partSha) throw invalidParam('part_sha256 does not match the SHA-256 of this part\'s UTF-8 bytes.', 'Hash exactly the UTF-8 bytes of text and send the part again.');
    if (ctx.dryRun) return { dry_run: true, action: 'upload_page_part', upload_id: p.upload_id, part };
    const principal = await callerPrincipal(ctx);
    const outcome = await ctx.engine.transaction(async (tx): Promise<{ expired: UploadRow } | { state: { received_bytes: number; next_part: number } }> => {
      const row = await boundUpload(ctx, principal, p.upload_id, { exec: tx, lock: true });
      if (row.state === 'expired' || row.lapsed) return { expired: row };
      if (part < row.next_part) {
        if (await partSha256(tx, row.id, part) === partSha) return { state: { received_bytes: row.received_bytes, next_part: row.next_part } };
        throw opError('idempotency_conflict', `Part ${part} of this upload was already received with different bytes.`,
          `Resume at part ${row.next_part}; to change content already sent, abort this upload and begin a new one.`, { fix: statusFix(row.id) });
      }
      if (row.state !== 'open') {
        throw opError('invalid_params', `This upload is ${row.state}, so it takes no more parts.`, 'Commit it with commit_page_upload, or begin a new upload.', { fix: statusFix(row.id) });
      }
      if (part !== row.next_part) {
        throw opError('invalid_params', `Parts are sent in order: this upload expects part ${row.next_part}, not ${part}.`, `Send part ${row.next_part} next.`, { fix: statusFix(row.id) });
      }
      const limit = uploadPartLimit(row.declared_bytes, cap);
      if (part >= limit && row.received_bytes + bytes.byteLength < row.declared_bytes) {
        throw opError('upload_too_many_parts', `This upload takes at most ${limit} parts for its ${row.declared_bytes} bytes, and part ${part} does not complete it, so it was not stored.`,
          `Send the remaining ${row.declared_bytes - row.received_bytes} bytes in part ${part}, cut near part_max_frame_bytes (${cap}); or abort this upload and begin again with larger parts.`, { fix: statusFix(row.id) });
      }
      if (row.received_bytes + bytes.byteLength > row.declared_bytes) {
        throw invalidParam(`This part would make the upload ${row.received_bytes + bytes.byteLength} bytes, over its declared total_bytes (${row.declared_bytes}).`,
          'Send only the remaining bytes of the content, or abort and begin again with the right total_bytes.');
      }
      return { state: await appendPart(tx, row, bytes, partSha) };
    });
    if ('expired' in outcome) {
      const current = await settleLapse(ctx, principal, outcome.expired);
      throw opError('invalid_params', `This upload is ${current.state}, so it takes no more parts.`, 'Commit it with commit_page_upload, or begin a new upload.', { fix: statusFix(current.id) });
    }
    return outcome.state;
  },
};

const get_page_upload: Operation = {
  name: 'get_page_upload',
  idempotent: true,
  outputRedaction: 'no_stored_text',
  description: 'An upload\'s state and next_part, to resume after a lost reply.',
  params: { upload_id: { type: 'string', required: true, description: 'From begin_page_upload.' } },
  mutating: false,
  scope: 'write',
  area: 'pages',
  handler: async (ctx, p) => {
    const principal = await callerPrincipal(ctx);
    return sessionStatus(ctx, await settleLapse(ctx, principal, await boundUpload(ctx, principal, p.upload_id)));
  },
};

const abort_page_upload: Operation = {
  name: 'abort_page_upload',
  idempotent: true,
  outputRedaction: 'no_stored_text',
  description: 'Discard an uncommitted upload session: its staged parts are deleted and its quota is freed.',
  params: { upload_id: { type: 'string', required: true, description: 'From begin_page_upload.' } },
  mutating: true,
  scope: 'write',
  area: 'pages',
  handler: async (ctx, p) => {
    if (ctx.dryRun) return { dry_run: true, action: 'abort_page_upload', upload_id: p.upload_id };
    // The creating principal in its source may always abort, even after the page, slug or source incarnation moved on.
    const principal = await callerPrincipal(ctx);
    const row = await settleLapse(ctx, principal, await boundUpload(ctx, principal, p.upload_id, { ownerOnly: true }), { ownerOnly: true });
    if (row.state === 'aborted') return { upload_id: row.id, state: 'aborted' };
    if (row.state !== 'committed' && await abortUpload(ctx.engine, row.id)) return { upload_id: row.id, state: 'aborted' };
    const [request] = row.commit_request_id ? await ctx.engine.executeRaw<Pick<WriteRequest, 'state'>>('SELECT state FROM persistence_requests WHERE id = $1::uuid', [row.commit_request_id]) : [];
    if (row.state !== 'committed' && request && !isTerminal(request)) {
      throw opError('write_pending', 'A commit of this upload is still being written, so it cannot be aborted now.',
        'Call commit_page_upload again with this upload_id to wait for its result; abort it only if that commit ends without writing.', { fix: statusFix(row.id) });
    }
    throw opError('invalid_params', 'This upload was already committed, so it cannot be aborted.', 'Read the write with commit_page_upload (it returns the receipt again).', { fix: statusFix(row.id) });
  },
};

const commit_page_upload: Operation = {
  name: 'commit_page_upload',
  idempotent: true,
  outputRedaction: 'no_stored_text',
  description: 'Write an upload\'s page once every part is sent; returns put_page\'s receipt. Repeat after a lost reply.',
  params: {
    upload_id: { type: 'string', required: true, description: 'From begin_page_upload.' },
    allow_empty: { type: 'boolean', description: 'Allow emptying the page.' },
    allow_shrink: { type: 'boolean', description: 'Allow content under half a >256 KB page.', fullSurfaceOnly: true },
    drop_timeline: { type: 'boolean', description: 'No Timeline in content: delete its entries.' },
    content_origin: CONTENT_ORIGIN_PARAM,
    wait_ms: WRITE_WAIT_PARAM,
  },
  mutating: true,
  scope: 'write',
  area: 'pages',
  handler: async (ctx, p) => {
    if (ctx.dryRun) return { dry_run: true, action: 'commit_page_upload', upload_id: p.upload_id };
    const principal = await callerPrincipal(ctx);
    let row = await boundUpload(ctx, principal, p.upload_id);
    const isSubmitted = (r: UploadRow) => r.state === 'committed' || r.commit_request_id !== null;
    if (!isSubmitted(row)) row = await settleLapse(ctx, principal, row);
    // Sealing is the commit's claim: an atomic open -> sealed that takes the session out of idle expiry. A call that
    // loses it (another commit sealed first, or the session ended) reads the session again and follows its real state.
    if (!isSubmitted(row) && row.state === 'open') {
      if (row.received_bytes !== row.declared_bytes) {
        throw opError('invalid_params', `This upload has ${row.received_bytes} of its ${row.declared_bytes} bytes, so it cannot be committed yet.`,
          `Send part ${row.next_part} and the rest, then commit.`, { fix: statusFix(row.id) });
      }
      if (!await sealUpload(ctx.engine, row.id)) row = await settleLapse(ctx, principal, await boundUpload(ctx, principal, row.id));
      else {
        const hashed = await stagedSha256(ctx.engine, row);
        await uploadCommitProbe.afterHash?.(row.id);
        if (hashed !== row.declared_sha256) {
          await abortUpload(ctx.engine, row.id);
          throw opError('invalid_params', 'The uploaded bytes do not match the sha256 declared at begin, so the upload was discarded and nothing was written.',
            'Begin again with the SHA-256 of exactly the content you send.');
        }
        row = { ...row, state: 'sealed' };
      }
    }
    const submitted = isSubmitted(row);
    if (!submitted) {
      if (row.state === 'expired') throw uploadExpired(row);
      if (row.state === 'aborted') throw uploadNotFound();
      if (row.state === 'open') throw opError('write_pending', 'Another call is committing this upload.', 'Call commit_page_upload again with this upload_id.', { fix: statusFix(row.id) });
    }
    const bodyRef: StagingBodyRef = { kind: 'staging', staging_id: row.id, sha256: row.declared_sha256, bytes: row.declared_bytes };
    if (row.mode === 'append') {
      try {
        return await admitPageAppend(ctx, { slug: row.slug, source_id: row.source_id, request_id: row.client_request_id, body_ref: bodyRef,
          ...(row.base_revision ? { expected_revision: row.base_revision } : {}), ...(p.wait_ms !== undefined ? { wait_ms: p.wait_ms } : {}) }, { stagedBody: true });
      } finally {
        await settleCommit(ctx, principal, row).catch(() => undefined);
      }
    }
    const params: Record<string, unknown> = { slug: row.slug, source_id: row.source_id, request_id: row.client_request_id, body_ref: bodyRef,
      ...(row.mode === 'replace' ? { expected_revision: row.base_revision } : {}),
      ...Object.fromEntries(PUT_PAGE_FLAGS.filter(key => p[key] !== undefined).map(key => [key, p[key]])),
      ...(p.wait_ms !== undefined ? { wait_ms: p.wait_ms } : {}) };
    if (!submitted && row.mode === 'replace') {
      const current = await ctx.engine.readPageSnapshot(row.slug, { sourceId: row.source_id, includeDeleted: true });
      if (current?.revision !== row.base_revision) {
        await abortUpload(ctx.engine, row.id);
        throw revisionChanged(row.slug, row.source_id);
      }
      if (ctx.remote !== false) await assertLargePageAdmission(ctx.engine, row.slug, row.source_id, params);
    }
    try {
      return await submitPageMutation(ctx, { operation: 'put_page', params, stagedBody: true });
    } catch (error) {
      if (row.mode === 'replace' && error instanceof OperationError && error.code === 'revision_conflict') throw revisionChanged(row.slug, row.source_id);
      throw error;
    } finally {
      await settleCommit(ctx, principal, row).catch(() => undefined);
    }
  },
};

/** Records the session's commit request, and ends the session when that write ended without committing (releasing its bytes). */
async function settleCommit(ctx: OperationContext, principal: Principal, row: UploadRow): Promise<void> {
  const request = await getWriteRequest(ctx.engine, principal, row.client_request_id);
  const ref = (request?.intent as Record<string, unknown> | undefined)?.body_ref;
  if (!request || !isStagingBodyRef(ref) || ref.staging_id !== row.id) return;
  await ctx.engine.executeRaw('UPDATE page_body_stagings SET commit_request_id = COALESCE(commit_request_id, $2::uuid) WHERE id = $1::uuid', [row.id, request.id]);
  if (isTerminal(request) && request.state !== 'committed') await transitionUploads(ctx.engine, 'aborted', 's.id = $1::uuid', [row.id]);
}

export const pageUploadOperations: Operation[] = [begin_page_upload, upload_page_part, get_page_upload, commit_page_upload, abort_page_upload];