Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* Upload sessions (Wave B, spec 6.2): the session rows, parts, reservations and
* the preparation of a committed upload. A session is a `page_body_stagings`
* row of kind `upload` whose raw parts are `page_body_staging_parts`; its
* declared bytes are reserved in `persistence_counters` (limits.ts
* `stagedCounterKeys`) from begin until the session commits (in the
* publication transaction of its write), aborts or expires (on its next use, at
* the caller's next begin, or in the segment sweep). Begin recounts the live
* sessions under the counter row locks, so a session a cascade removed never
* keeps its capacity.
*
* A commit admits an ordinary put_page (or, for mode append, an append_page)
* whose intent carries `body_ref: {kind: 'staging', staging_id, sha256, bytes}`
* instead of the text; `withStagedUpload` binds the preparation to the sealed
* session and commits it in the write's publication. A put_page body within the
* single-string ceiling (PAGE_MAX_BYTES) is read back and prepared as if the
* content had been sent, so every put_page rule (remote sanitizing, trust, the
* timeline omission and shrink guards, the revision check under the page lock)
* applies; a larger one streams through upload-streamed.ts.
*/
import { createHash } from 'node:crypto';
import type { BrainEngine } from '../engine.ts';
import type { OperationContext } from '../ops/contract.ts';
import { opError, type OperationError } from '../ops/contract.ts';
import { encodedFrameBytes } from '../egress-budget.ts';
import { bodyStagingGoneError, LIVE_STAGING_STATES } from '../engine-sql/page-body.ts';
import { ENSURE_COUNTERS_SQL, LOCK_COUNTERS_SQL } from './journal.ts';
import { BRAIN_STAGED_KEY, RELEASE_STAGED_CTE, readUploadLimits, stagedCounterKeys, stagedQuotaExhausted } from './limits.ts';
import type { Principal, SqlEngine, WriteRequest } from './model.ts';
import { timelineSectionOf } from './timeline-omission.ts';
import { PAGE_MAX_BYTES } from '../page-size-policy.ts';
export type UploadMode = 'create' | 'replace' | 'append';
export type UploadState = 'open' | 'sealed' | 'prepared' | 'committed' | 'aborted' | 'expired';
/** Largest part frame on any connection: the stdio and local cap, so the journal and IPC stay small. */
export const UPLOAD_PART_FRAME_CAP_BYTES = 4 * 1024 ** 2;
/** Bytes of a part frame kept for the JSON-RPC envelope around the arguments. */
export const UPLOAD_FRAME_RESERVE_BYTES = 4096;
/** The legacy HTTP transport's default inbound cap (GBRAIN_HTTP_MAX_BODY_BYTES), assumed for an HTTP caller whose cap is unknown. */
export const LEGACY_HTTP_BODY_BYTES = 1024 ** 2;
/**
* The largest `upload_page_part` frame this connection accepts: its inbound cap (`ctx.inboundFrameBytes`, set by
* each transport) capped at UPLOAD_PART_FRAME_CAP_BYTES, minus the envelope reserve. A trusted local caller and
* stdio get the cap; an HTTP caller without a recorded cap gets the legacy HTTP default.
*/
export function partMaxFrameBytes(ctx: Pick<OperationContext, 'remote' | 'transport' | 'inboundFrameBytes'>): number {
const inbound = ctx.inboundFrameBytes ?? (ctx.remote !== false && ctx.transport !== 'stdio' ? LEGACY_HTTP_BODY_BYTES : UPLOAD_PART_FRAME_CAP_BYTES);
return Math.min(inbound, UPLOAD_PART_FRAME_CAP_BYTES) - UPLOAD_FRAME_RESERVE_BYTES;
}
/**
* The most parts one session takes: 64 plus one per 64 KiB of its declared bytes (one per eighth of the part limit on a
* connection whose limit is under 512 KiB), so a client cutting parts near part_max_frame_bytes, even of fully escaped
* text, never reaches it while a session of tiny parts cannot grow its part rows without bound.
*/
export function uploadPartLimit(declaredBytes: number, partFrameBytes: number): number {
return 64 + Math.ceil(declaredBytes / Math.min(64 * 1024, Math.floor(partFrameBytes / 8)));
}
/** The encoded size of one `upload_page_part` call's arguments, the measure clients cut parts by (egress-budget.ts). */
export function uploadPartFrameBytes(args: { upload_id: string; part: number; text: string; part_sha256: string }): number {
return encodedFrameBytes({ upload_id: args.upload_id, part: args.part, text: args.text, part_sha256: args.part_sha256 });
}
const LONE_SURROGATE = /[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/;
/** A part's raw UTF-8 bytes. A part that starts or ends inside a code point, or holds an unpaired surrogate, is refused. */
export function partBytes(text: unknown): Buffer {
if (typeof text !== 'string' || text.length === 0) {
throw opError('invalid_params', 'text must be a non-empty string.', 'Send the next slice of the page as text; every part holds at least one character.');
}
const first = text.charCodeAt(0), last = text.charCodeAt(text.length - 1);
if ((last >= 0xd800 && last <= 0xdbff) || (first >= 0xdc00 && first <= 0xdfff)) {
throw opError('part_splits_code_point', 'This part starts or ends inside a code point (half of a surrogate pair), so it was not stored.',
'Cut parts between code points: move the cut before the high surrogate so both halves of the pair travel in the same part, then send the part again.');
}
if (LONE_SURROGATE.test(text)) {
throw opError('invalid_params', 'text is not valid UTF-8: it holds an unpaired surrogate.', 'Send the page as valid Unicode text; an unpaired surrogate has no UTF-8 encoding.');
}
return Buffer.from(text, 'utf8');
}
/** The answer for an unknown upload id and for a session this caller may not use: identical, so it is no existence oracle. */
export function uploadNotFound(): OperationError {
return opError('upload_not_found', 'No open upload session matches this upload_id for this connection.',
'Begin a new upload with begin_page_upload (a new request_id), then send its parts from part 0.');
}
export function uploadExpired(row: Pick<UploadRow, 'slug' | 'source_id' | 'mode'>): OperationError {
return opError('upload_expired', 'This upload session expired before it was committed, so its parts were discarded and nothing was written.',
'Begin the upload again with begin_page_upload and a new request_id, then send every part from part 0.',
{ fix: { mcp: { tool: 'begin_page_upload', arguments: { slug: row.slug, source_id: row.source_id, mode: row.mode } }, consent: [], actor: 'agent', requires_exclusive: false,
why: 'An expired session never resumes; a new session takes the same page from its first part.',
inputs: [{ name: 'total_bytes', how: 'the UTF-8 byte length of the complete page' }, { name: 'sha256', how: 'the hex SHA-256 of those bytes' },
{ name: 'request_id', how: 'a new UUID' }] } });
}
export interface UploadRow {
id: string; principal_kind: string; principal_id: string; client_request_id: string; source_id: string; source_incarnation: string;
slug: string; page_id: number | null; mode: UploadMode; base_revision: string | null; base_generation: number | null;
declared_bytes: number; declared_sha256: string; received_bytes: number; next_part: number; reserved_bytes: number;
state: UploadState; commit_request_id: string | null; idle_expires_at: string; hard_expires_at: string;
/** Past a deadline and held by no unfinished write: the session expires on its next use. */
lapsed: boolean;
current_incarnation: string | null; source_archived: boolean | null; current_page_id: number | null;
}
const LIVE = `'{${LIVE_STAGING_STATES.join(',')}}'::text[]`;
/** The session `s` is named by an unfinished write (its staged body is a GC root until that write ends). */
const REQUEST_HELD_SQL = `EXISTS (SELECT 1 FROM persistence_requests r WHERE r.state IN ('queued','deferred','running','recovering')
AND r.intent->'body_ref'->>'staging_id' = s.id::text)`;
/**
* The session `s` expires: an open session past either deadline, a sealed (committing) one only past its hard deadline,
* which sealing extends by one idle period; never one an unfinished write names. A commit in progress is never expired.
*/
const LAPSED_SQL = `(s.state = ANY(${LIVE}) AND (s.hard_expires_at <= now() OR s.state = 'open' AND s.idle_expires_at <= now()) AND NOT ${REQUEST_HELD_SQL})`;
const iso = (value: unknown) => new Date(value as string | Date).toISOString();
const toRow = (raw: Record<string, unknown>): UploadRow => ({
...(raw as unknown as UploadRow),
page_id: raw.page_id == null ? null : Number(raw.page_id),
base_generation: raw.base_generation == null ? null : Number(raw.base_generation),
declared_bytes: Number(raw.declared_bytes), received_bytes: Number(raw.received_bytes), next_part: Number(raw.next_part),
reserved_bytes: Number(raw.reserved_bytes), current_page_id: raw.current_page_id == null ? null : Number(raw.current_page_id),
idle_expires_at: iso(raw.idle_expires_at), hard_expires_at: iso(raw.hard_expires_at), lapsed: raw.lapsed === true,
});
const UPLOAD_SELECT = `SELECT s.id::text AS id, s.principal_kind, s.principal_id, s.client_request_id::text AS client_request_id, s.source_id,
s.source_incarnation::text AS source_incarnation, s.slug, s.page_id, s.mode, s.base_revision::text AS base_revision, s.base_generation,
s.declared_bytes, encode(s.declared_sha256, 'hex') AS declared_sha256, s.received_bytes, s.next_part, s.reserved_bytes, s.state,
s.commit_request_id::text AS commit_request_id, s.idle_expires_at, s.hard_expires_at, ${LAPSED_SQL} AS lapsed,
src.incarnation::text AS current_incarnation, src.archived AS source_archived, p.id AS current_page_id
FROM page_body_stagings s LEFT JOIN sources src ON src.id = s.source_id LEFT JOIN pages p ON p.source_id = s.source_id AND p.slug = s.slug`;
/** The upload session `id` with its source's current incarnation and the page now at its slug; FOR UPDATE of the session with `lock`. */
export async function readUpload(exec: SqlEngine, id: string, opts: { lock?: boolean } = {}): Promise<UploadRow | null> {
const [raw] = await exec.executeRaw<Record<string, unknown>>(`${UPLOAD_SELECT} WHERE s.id = $1::uuid AND s.kind = 'upload'${opts.lock ? ' FOR UPDATE OF s' : ''}`, [id]);
return raw ? toRow(raw) : null;
}
export async function readUploadByRequest(exec: SqlEngine, principal: Principal, clientRequestId: string): Promise<UploadRow | null> {
const [raw] = await exec.executeRaw<Record<string, unknown>>(`${UPLOAD_SELECT}
WHERE s.principal_kind = $1 AND s.principal_id = $2 AND s.client_request_id = $3::uuid AND s.kind = 'upload'`, [principal.kind, principal.id, clientRequestId]);
return raw ? toRow(raw) : null;
}
/**
* Moves the live upload sessions `where` selects (over alias `s`, binding `params`) to `state`, deletes their parts and
* releases their reservations in the same statement; returns how many moved. A commit records its request.
*/
export async function transitionUploads(exec: SqlEngine, state: 'aborted' | 'expired' | 'committed', where: string, params: unknown[],
opts: { commitRequestId?: string } = {}): Promise<number> {
const commit = opts.commitRequestId !== undefined ? `, commit_request_id = $${params.length + 1}::uuid` : '';
const [row] = await exec.executeRaw<{ n: number }>(`WITH gone AS (UPDATE page_body_stagings s SET state = '${state}', updated_at = now()${commit}
WHERE s.kind = 'upload' AND s.state = ANY(${LIVE}) AND ${where} RETURNING s.id, s.kind, s.principal_kind, s.principal_id, s.reserved_bytes),
${RELEASE_STAGED_CTE}
SELECT count(*)::int AS n FROM gone`, opts.commitRequestId !== undefined ? [...params, opts.commitRequestId] : params);
return Number(row?.n ?? 0);
}
/**
* Expires the session if it lapsed (releasing its reservation); true only when it was already expired or this call
* expired it. False on a row that moved on meanwhile (a commit sealed it): the caller re-reads it and follows its state.
*/
export async function expireIfLapsed(exec: SqlEngine, row: UploadRow): Promise<boolean> {
if (row.state === 'expired') return true;
if (!row.lapsed) return false;
return await transitionUploads(exec, 'expired', `s.id = $1::uuid AND ${LAPSED_SQL}`, [row.id]) > 0;
}
/**
* Aborts the live session unless a commit holds it: no commit was submitted, or the submitted one ended without
* committing. True when it moved (its parts deleted and its bytes released).
*/
export async function abortUpload(exec: SqlEngine, id: string): Promise<boolean> {
return await transitionUploads(exec, 'aborted', `s.id = $1::uuid AND NOT ${REQUEST_HELD_SQL} AND (s.commit_request_id IS NULL
OR EXISTS (SELECT 1 FROM persistence_requests r WHERE r.id = s.commit_request_id AND r.state IN ('conflict','failed','cancelled')))`, [id]) > 0;
}
export interface UploadReservation {
id: string; principal: Principal; clientRequestId: string; sourceId: string; sourceIncarnation: string; slug: string;
pageId: number | null; mode: UploadMode; baseRevision: string | null; totalBytes: number; sha256: string;
}
/**
* Begin: in one transaction, lock the caller's and the brain's staged counters (key order), expire the caller's lapsed
* sessions, recount every live session (the brain sum leaves out other principals' lapsed sessions, which the sweep
* expires and which nothing revives: a lapsed session takes no part and cannot be sealed), refuse past a cap (`write_quota_exhausted`), insert the session and store the
* counts with its reservation.
*/
export async function reserveUpload(engine: BrainEngine, input: UploadReservation): Promise<void> {
const limits = await readUploadLimits(engine);
const keys = stagedCounterKeys(input.principal);
const all = [keys.staged, keys.uploads, BRAIN_STAGED_KEY].sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
const owner = [input.principal.kind, input.principal.id];
await engine.transaction(async tx => {
await tx.executeRaw(ENSURE_COUNTERS_SQL, [all]);
await tx.executeRaw(LOCK_COUNTERS_SQL, [all]);
await transitionUploads(tx, 'expired', `s.principal_kind = $1 AND s.principal_id = $2 AND ${LAPSED_SQL}`, owner);
const [usage] = await tx.executeRaw<{ staged: unknown; brain: unknown; uploads: unknown }>(`SELECT
COALESCE(SUM(s.reserved_bytes) FILTER (WHERE s.principal_kind = $1 AND s.principal_id = $2), 0)::text AS staged,
COALESCE(SUM(s.reserved_bytes) FILTER (WHERE NOT ${LAPSED_SQL}), 0)::text AS brain,
(count(*) FILTER (WHERE s.principal_kind = $1 AND s.principal_id = $2))::text AS uploads
FROM page_body_stagings s WHERE s.kind = 'upload' AND s.state = ANY(${LIVE})`, owner);
const staged = Number(usage?.staged ?? 0), brain = Number(usage?.brain ?? 0), uploads = Number(usage?.uploads ?? 0);
if (uploads + 1 > limits.principalUploads) throw stagedQuotaExhausted('open upload sessions for this connection', 'principalUploads', uploads, limits.principalUploads, 1, 'open_uploads');
if (staged + input.totalBytes > limits.principalStagedBytes) throw stagedQuotaExhausted('staged upload bytes for this connection', 'principalStagedBytes', staged, limits.principalStagedBytes, input.totalBytes, 'staged_bytes');
if (brain + input.totalBytes > limits.brainStagedBytes) throw stagedQuotaExhausted('staged upload bytes for this brain', 'brainStagedBytes', null, limits.brainStagedBytes, input.totalBytes, 'staged_bytes');
await tx.executeRaw(`INSERT INTO page_body_stagings (id, kind, principal_kind, principal_id, client_request_id, source_id, source_incarnation, slug,
page_id, mode, base_revision, base_generation, declared_bytes, declared_sha256, reserved_bytes, idle_expires_at, hard_expires_at)
VALUES ($1::uuid, 'upload', $2, $3, $4::uuid, $5, $6::uuid, $7, $8::int, $9, $10::uuid, (SELECT body_generation FROM pages WHERE id = $8::int),
$11::bigint, decode($12, 'hex'), $11::bigint,
now() + LEAST($13::bigint, $14::bigint) * interval '1 second', now() + $14::bigint * interval '1 second')`,
[input.id, input.principal.kind, input.principal.id, input.clientRequestId, input.sourceId, input.sourceIncarnation, input.slug, input.pageId,
input.mode, input.baseRevision, input.totalBytes, input.sha256, limits.uploadIdleSeconds, limits.uploadMaxSeconds]);
await tx.executeRaw(`UPDATE persistence_counters SET
intent_bytes = CASE key WHEN $1 THEN $4::bigint WHEN $2 THEN $5::bigint ELSE intent_bytes END,
outstanding_count = CASE key WHEN $3 THEN $6::bigint ELSE outstanding_count END
WHERE key IN ($1, $2, $3)`, [keys.staged, BRAIN_STAGED_KEY, keys.uploads, staged + input.totalBytes, brain + input.totalBytes, uploads + 1]);
});
}
export async function partSha256(exec: SqlEngine, stagingId: string, part: number): Promise<string | null> {
const [row] = await exec.executeRaw<{ sha: string }>(`SELECT encode(sha256, 'hex') AS sha FROM page_body_staging_parts WHERE staging_id = $1::uuid AND part_no = $2`, [stagingId, part]);
return row?.sha ?? null;
}
/** Stores part `next_part` of the locked session and advances it, restarting its idle deadline (never past the hard one). */
export async function appendPart(exec: SqlEngine, row: UploadRow, bytes: Buffer, sha256: string): Promise<{ received_bytes: number; next_part: number }> {
const limits = await readUploadLimits(exec);
await exec.executeRaw(`INSERT INTO page_body_staging_parts (staging_id, part_no, byte_start, byte_len, sha256, body)
VALUES ($1::uuid, $2, $3::bigint, $4, decode($5, 'hex'), $6::bytea)`, [row.id, row.next_part, row.received_bytes, bytes.byteLength, sha256, bytes]);
const [next] = await exec.executeRaw<{ received_bytes: unknown; next_part: unknown }>(`UPDATE page_body_stagings
SET received_bytes = received_bytes + $2::bigint, next_part = next_part + 1, updated_at = now(),
idle_expires_at = LEAST(hard_expires_at, now() + $3::bigint * interval '1 second')
WHERE id = $1::uuid RETURNING received_bytes, next_part`, [row.id, bytes.byteLength, limits.uploadIdleSeconds]);
return { received_bytes: Number(next!.received_bytes), next_part: Number(next!.next_part) };
}
/** Hex SHA-256 of the session's stored parts in order, read one part at a time; null when the parts are not contiguous. */
export async function stagedSha256(exec: SqlEngine, row: Pick<UploadRow, 'id' | 'next_part' | 'received_bytes'>): Promise<string | null> {
const hash = createHash('sha256');
let at = 0;
for (let part = 0; part < row.next_part; part++) {
const [stored] = await exec.executeRaw<{ byte_start: unknown; body: Uint8Array }>(`SELECT byte_start, body FROM page_body_staging_parts
WHERE staging_id = $1::uuid AND part_no = $2`, [row.id, part]);
if (!stored || Number(stored.byte_start) !== at) return null;
hash.update(stored.body);
at += stored.body.byteLength;
}
return at === row.received_bytes ? hash.digest('hex') : null;
}
/**
* Seals the open session for its commit: no more parts, and no expiry until its hard deadline, which moves to at least
* one idle period from now so the commit can journal. True when this call sealed it; false when it was no longer open.
*/
export async function sealUpload(exec: SqlEngine, id: string): Promise<boolean> {
const limits = await readUploadLimits(exec);
const sealed = await exec.executeRaw<{ id: string }>(`UPDATE page_body_stagings s SET state = 'sealed', updated_at = now(),
hard_expires_at = GREATEST(s.hard_expires_at, now() + $2::bigint * interval '1 second')
WHERE s.id = $1::uuid AND s.state = 'open' AND NOT ${LAPSED_SQL} RETURNING s.id::text AS id`, [id, limits.uploadIdleSeconds]);
return sealed.length > 0;
}
/** A journal body reference to a sealed upload session (spec 3.2). */
export interface StagingBodyRef { kind: 'staging'; staging_id: string; sha256: string; bytes: number }
export function isStagingBodyRef(value: unknown): value is StagingBodyRef {
const ref = value as Partial<StagingBodyRef> | null | undefined;
return !!ref && typeof ref === 'object' && ref.kind === 'staging' && typeof ref.staging_id === 'string' && typeof ref.sha256 === 'string' && Number.isSafeInteger(ref.bytes);
}
/** @internal Work counters of the staged-body readers: whole-body strings built, streamed preparations, largest part held. */
export const stagedUploadWork = { wholeTexts: 0, streamed: 0, largestPart: 0 };
/** The staged parts of a body reference in order, one part at a time; null at a gap. */
export async function* stagedUploadParts(engine: SqlEngine, ref: StagingBodyRef): AsyncIterable<Uint8Array | null> {
for (let part = 0, at = 0; at < ref.bytes; part++) {
const [stored] = await engine.executeRaw<{ byte_start: unknown; body: Uint8Array }>(
'SELECT byte_start, body FROM page_body_staging_parts WHERE staging_id = $1::uuid AND part_no = $2', [ref.staging_id, part]);
if (!stored || Number(stored.byte_start) !== at) { yield null; return; }
stagedUploadWork.largestPart = Math.max(stagedUploadWork.largestPart, stored.body.byteLength);
at += stored.body.byteLength;
yield stored.body;
}
}
/** The staged page text a body reference names, verified against its byte count and sha256; null when it no longer matches. */
export async function stagedUploadText(engine: SqlEngine, ref: StagingBodyRef): Promise<string | null> {
stagedUploadWork.wholeTexts++;
const buffers: Buffer[] = [];
for await (const part of stagedUploadParts(engine, ref)) {
if (!part) return null;
buffers.push(Buffer.from(part.buffer, part.byteOffset, part.byteLength));
}
const body = Buffer.concat(buffers);
if (body.byteLength !== ref.bytes || createHash('sha256').update(body).digest('hex') !== ref.sha256) return null;
return new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(body);
}
interface Publishable { apply(tx: BrainEngine, preimage?: never): Promise<Record<string, unknown>> }
/**
* A write whose intent names a sealed upload session (put_page, or append_page with mode append): the session must
* still be the sealed upload of the request's principal, source and slug, matching the reference. `prepare` builds the
* write; its publication re-checks the session under a row lock, and the same transaction marks it committed and
* releases its reservation.
*/
export async function withStagedUpload<T extends Publishable>(engine: BrainEngine, row: WriteRequest, prepare: (ref: StagingBodyRef) => Promise<T>): Promise<T> {
const ref = (row.intent as Record<string, unknown>).body_ref as StagingBodyRef;
const [staging] = await engine.executeRaw<{ state: string; principal_kind: string; principal_id: string; source_id: string; slug: string; declared_bytes: unknown; sha: string }>(
`SELECT state, principal_kind, principal_id, source_id, slug, declared_bytes, encode(declared_sha256, 'hex') AS sha FROM page_body_stagings
WHERE id = $1::uuid AND kind = 'upload'`, [ref.staging_id]);
if (!staging || staging.principal_kind !== row.principal_kind || staging.principal_id !== row.principal_id || staging.source_id !== row.source_id
|| staging.slug !== row.slug || Number(staging.declared_bytes) !== ref.bytes || staging.sha !== ref.sha256) throw bodyStagingGoneError(row.slug, ref.staging_id, null);
if (staging.state !== 'sealed') throw bodyStagingGoneError(row.slug, ref.staging_id, staging.state);
const prepared = await prepare(ref);
const apply = prepared.apply.bind(prepared);
prepared.apply = async (tx, preimage) => {
const [held] = await tx.executeRaw<{ state: string }>('SELECT state FROM page_body_stagings WHERE id = $1::uuid FOR UPDATE', [ref.staging_id]);
if (held?.state !== 'sealed') throw bodyStagingGoneError(row.slug, ref.staging_id, held?.state ?? null);
const outcome = await apply(tx, preimage);
await transitionUploads(tx, 'committed', 's.id = $1::uuid', [ref.staging_id], { commitRequestId: row.id });
return outcome;
};
return prepared;
}
/** `prepare` under withStagedUpload when the request's intent names an upload session (an append upload), else as is. */
export async function withStagedBodyIf<T extends Publishable>(engine: BrainEngine, row: WriteRequest, prepare: () => Promise<T>): Promise<T> {
return isStagingBodyRef(row.intent?.body_ref) ? withStagedUpload(engine, row, prepare) : prepare();
}
/**
* Preparation of a put_page whose intent names a sealed upload session. A body within the single-string ceiling
* (PAGE_MAX_BYTES) is read back and `prepare` gets the request with it as its content (and the timeline section put_page
* admission records for content), so every put_page rule applies; a larger body streams from its parts through the
* segmented import (upload-streamed.ts) and is never held as one string.
*/
export async function prepareStagedUpload<T extends Publishable>(engine: BrainEngine, row: WriteRequest, prepare: (row: WriteRequest) => Promise<T>): Promise<T> {
return withStagedUpload(engine, row, async ref => {
if (ref.bytes > PAGE_MAX_BYTES) return (await import('./upload-streamed.ts')).prepareStreamedUpload(engine, row, ref) as unknown as Promise<T>;
const content = await stagedUploadText(engine, ref);
if (content === null) throw bodyStagingGoneError(row.slug, ref.staging_id, null);
const { body_ref: _ref, ...rest } = row.intent as Record<string, unknown>;
return prepare({ ...row, intent: { ...rest, content,
...(rest.kind === undefined && rest.timeline_section === undefined ? { timeline_section: timelineSectionOf(content, row.slug) } : {}) } });
});
}