superbee 0.3.0-pre.6 → 0.4.0-pre.1

package/dist/superbee.mjs

@@ -44,7 +44,7 @@ var __toESM = (mod, isNodeMode, target2) => (target2 = mod != null ? __create(__
 var define_SUPERBEE_BUILD_IDENTITY_default;
 var init_define_SUPERBEE_BUILD_IDENTITY = __esm({
   "<define:__SUPERBEE_BUILD_IDENTITY__>"() {
-    define_SUPERBEE_BUILD_IDENTITY_default = { schema: "superbee.build-identity.v1", package: { name: "superbee", version: "0.3.0-pre.6" }, source: { commit: "3c313f3bfc9c052c6d4354111df5c293f8cde272", dirty: false }, artifact: { channel: "npm-package" }, compatibility_contracts: { skill: 1, hook: 1, mcp: 1 } };
+    define_SUPERBEE_BUILD_IDENTITY_default = { schema: "superbee.build-identity.v1", package: { name: "superbee", version: "0.4.0-pre.1" }, source: { commit: "2b1084b2af86558ac242ab74c14fa5b4f9f2dbb4", dirty: false }, artifact: { channel: "npm-package" }, compatibility_contracts: { skill: 1, hook: 1, mcp: 1 } };
   }
 });
 
@@ -9416,6 +9416,9 @@ var init_mutation = __esm({
 });
 
 // ../core/src/kinds.ts
+function isConventionId(id) {
+  return id.startsWith(CONVENTIONS_PREFIX);
+}
 function buildKindRegistry(docs, initialWarnings = [], options = {}) {
   const accepted = /* @__PURE__ */ new Map();
   const warnings = [...initialWarnings];
@@ -20551,6 +20554,18 @@ var init_reference = __esm({
 import { createHash as createHash5, randomUUID as randomUUID3 } from "node:crypto";
 import { lstat as lstat2, readdir as readdir2, rm, stat as stat2, unlink as unlink2 } from "node:fs/promises";
 import { join as join7 } from "node:path";
+function withDefinitionWrites(binding, stated) {
+  const { definition_writes: _previous, ...rest } = binding;
+  return stated === null ? rest : { ...rest, definition_writes: stated };
+}
+async function recordDefinitionWrites(home2, binding, stated) {
+  const current = await readBinding(home2, binding.checkout_id);
+  if (current === null) return binding;
+  if ((current.definition_writes ?? null) === stated) return current;
+  const next = withDefinitionWrites(current, stated);
+  await writeBinding(home2, next);
+  return next;
+}
 function sameFolder(a, b) {
   return a.dev === b.dev && a.ino === b.ino && (!a.birth || !b.birth || a.birth === b.birth);
 }
@@ -20618,7 +20633,9 @@ async function writeBinding(home2, binding) {
 }
 async function readBinding(home2, checkoutId) {
   const value = await readJson(home2, join7(checkoutDir(home2, checkoutId), "binding.json"));
-  return isBinding(value) && value.checkout_id === checkoutId ? value : null;
+  if (!isBinding(value) || value.checkout_id !== checkoutId) return null;
+  const stated = value.definition_writes;
+  return stated === void 0 || stated === "allowed" || stated === "refused" ? value : { ...value, definition_writes: "refused" };
 }
 async function indexCheckoutPath(home2, binding) {
   await writeUserStateFileAtomic0600(
@@ -24032,12 +24049,19 @@ function idleBounded(body, deadlineMs, abort) {
     })
   );
 }
+function requestHeaders(credentials, extra, type) {
+  const headers = new Headers(extra);
+  for (const [name, value] of Object.entries(credentials)) headers.set(name, value);
+  headers.set("Content-Type", type);
+  headers.set("Accept", "application/json");
+  return headers;
+}
 function createFetchCarrier(options) {
   const fetcher = options.fetch ?? fetch;
   const deadlineMs = options.deadlineMs ?? 15e3;
   const bindingHeader = options.bindingHeader ?? "X-Superbee-Checkout";
   const base = new URL(options.baseUrl);
-  async function send(path53, input, signal, extra, deadline) {
+  async function send(path53, body, signal, extra, deadline) {
     if (!path53.startsWith("/")) throw new TypeError(`hosted route '${path53}' must be absolute`);
     let credentials;
     try {
@@ -24050,14 +24074,29 @@ function createFetchCarrier(options) {
       return await fetcher(new URL(path53, base), {
         method: "POST",
         redirect: "error",
-        headers: { ...credentials, ...extra, "Content-Type": "application/json", Accept: "application/json" },
-        body: JSON.stringify(input),
+        headers: requestHeaders(credentials, extra, body.type),
+        body: body.content,
         signal: AbortSignal.any([signal, deadline])
       });
     } catch (cause) {
       throw new HostedCarrierError("unavailable", { cause });
     }
   }
+  const jsonBody = (input) => ({ type: "application/json", content: JSON.stringify(input) });
+  const owned = /* @__PURE__ */ new Set(["x-superbee-write-request", bindingHeader.toLowerCase(), RECREATE_HEADER.toLowerCase(), VIA_HEADER.toLowerCase(), ACCEPT_DELETES_HEADER.toLowerCase()]);
+  async function answer2(path53, body, signal, extra, maximum) {
+    if (!Number.isSafeInteger(maximum) || maximum <= 0) throw new HostedCarrierError("denied");
+    const deadline = AbortSignal.timeout(deadlineMs);
+    const response = await send(path53, body, signal, extra, deadline);
+    let read;
+    try {
+      read = await readBounded(response, maximum);
+    } catch (error51) {
+      if (response.ok) throw error51 instanceof HostedCarrierError ? error51 : new HostedCarrierError("unavailable", { cause: error51 });
+      read = void 0;
+    }
+    return { status: response.status, headers: response.headers, body: read };
+  }
   return {
     async json(path53, input, signal, request2) {
       if (request2.writeRequest !== void 0 && !WRITE_REQUEST.test(request2.writeRequest)) throw new HostedCarrierError("denied");
@@ -24071,23 +24110,26 @@ function createFetchCarrier(options) {
       if (request2.recreate !== void 0) extra[RECREATE_HEADER] = request2.recreate;
       if (request2.via !== void 0) extra[VIA_HEADER] = request2.via;
       if (request2.acceptDeletes !== void 0) extra[ACCEPT_DELETES_HEADER] = String(request2.acceptDeletes);
-      const deadline = AbortSignal.timeout(deadlineMs);
-      const response = await send(path53, input, signal, extra, deadline);
-      let body;
-      try {
-        body = await readBounded(response, request2.maximum);
-      } catch (error51) {
-        if (response.ok) throw error51 instanceof HostedCarrierError ? error51 : new HostedCarrierError("unavailable", { cause: error51 });
-        body = void 0;
+      return answer2(path53, jsonBody(input), signal, extra, request2.maximum);
+    },
+    async bytes(path53, body, signal, request2) {
+      if (!(body instanceof Uint8Array)) throw new HostedCarrierError("denied");
+      if (request2.writeRequest !== void 0 && !WRITE_REQUEST.test(request2.writeRequest)) throw new HostedCarrierError("denied");
+      const extra = {};
+      for (const [name, value] of Object.entries(request2.headers ?? {})) {
+        const lower = name.toLowerCase();
+        if (!ROUTE_HEADER.test(lower) || owned.has(lower) || lower in extra || typeof value !== "string" || !ROUTE_HEADER_VALUE.test(value)) throw new HostedCarrierError("denied");
+        extra[lower] = value;
       }
-      return { status: response.status, headers: response.headers, body };
+      if (request2.writeRequest !== void 0) extra["X-Superbee-Write-Request"] = request2.writeRequest;
+      return answer2(path53, { type: "application/octet-stream", content: body }, signal, extra, request2.maximum);
     },
     async stream(path53, input, signal) {
       const idle = new AbortController();
       const firstByte = setTimeout(() => idle.abort(), deadlineMs);
       let response;
       try {
-        response = await send(path53, input, signal, {}, idle.signal);
+        response = await send(path53, jsonBody(input), signal, {}, idle.signal);
       } finally {
         clearTimeout(firstByte);
       }
@@ -24099,7 +24141,7 @@ function createFetchCarrier(options) {
     }
   };
 }
-var ACCEPT_DELETES_HEADER, MAXIMUM_ACCEPTED_DELETIONS, RECREATE_HEADER, VIA_HEADER, HostedAnswerTooLarge, HostedCarrierError, WRITE_REQUEST, BINDING;
+var ACCEPT_DELETES_HEADER, MAXIMUM_ACCEPTED_DELETIONS, RECREATE_HEADER, VIA_HEADER, HostedAnswerTooLarge, HostedCarrierError, WRITE_REQUEST, BINDING, ROUTE_HEADER, ROUTE_HEADER_VALUE;
 var init_carrier = __esm({
   "../core/src/hosted-transport/carrier.ts"() {
     "use strict";
@@ -24127,10 +24169,43 @@ var init_carrier = __esm({
     };
     WRITE_REQUEST = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
     BINDING = /^sha256:[a-f0-9]{64}$/;
+    ROUTE_HEADER = /^x-superbee-[a-z0-9]+(?:-[a-z0-9]+)*$/;
+    ROUTE_HEADER_VALUE = /^[\x20-\x7e]{0,1024}$/;
   }
 });
 
 // ../core/src/hosted-transport/answer-rows.ts
+function definitionFindingsText(details) {
+  const findings = isRecord7(details) && Array.isArray(details.findings) ? details.findings : [];
+  const clauses = [];
+  for (const finding of findings) {
+    if (!isRecord7(finding)) continue;
+    const rule = findingText(finding.rule);
+    if (!rule) continue;
+    const type = findingText(finding.type);
+    const conventionId = findingText(finding.conventionId);
+    const field = findingText(finding.field);
+    const detail = findingText(finding.detail);
+    const where = [type ? `Kind '${type}'` : conventionId ? `'${conventionId}'` : "", field ? `field '${field}'` : ""].filter(Boolean).join(" ");
+    const instances = isRecord7(finding.instances) ? finding.instances : void 0;
+    const total = instances && Number.isSafeInteger(instances.count) && instances.count > 0 ? instances.count : 0;
+    const ids = instances && Array.isArray(instances.ids) ? instances.ids.map(findingText).filter((id) => id !== void 0) : [];
+    const shown2 = ids.slice(0, FINDING_IDS_SHOWN);
+    const documents = total > 0 ? `: ${total} document${total === 1 ? "" : "s"}${shown2.length > 0 ? `, ${shown2.join(", ")}${total > shown2.length ? ", ..." : ""}` : ""}` : "";
+    clauses.push(`${rule}${where ? ` on ${where}` : ""}${detail ? ` (${detail})` : ""}${documents}`);
+  }
+  const more = isRecord7(details) && details.truncated === true;
+  let text4 = "";
+  for (const [index2, clause] of clauses.entries()) {
+    const next = text4 === "" ? clause : `${text4}; ${clause}`;
+    const rest = clauses.length - index2;
+    if (new TextEncoder().encode(next).byteLength > DEFINITION_FINDINGS_TEXT_BYTES - 32) {
+      return text4 === "" ? `${clause.slice(0, 512)}...${rest > 1 ? `; and ${rest - 1} more` : ""}` : `${text4}; and ${rest} more`;
+    }
+    text4 = next;
+  }
+  return more && text4 !== "" ? `${text4}; and more` : text4;
+}
 function parseWriteResult(raw, expected) {
   const refuse = () => new HostedAnswerError("the write result envelope is not one the client admits");
   if (!isRecord7(raw) || !onlyKeys(raw, ["ok", "operationId", "data", "error"]) || typeof raw.operationId !== "string" || !expected.operationIds.includes(raw.operationId)) throw refuse();
@@ -24144,7 +24219,8 @@ function parseWriteResult(raw, expected) {
   }
   if (raw.ok !== false) throw refuse();
   const error51 = raw.error;
-  if (raw.data !== void 0 || !isRecord7(error51) || !onlyKeys(error51, ERROR_KEYS) || !WRITE_ERROR_CODES.includes(error51.code) || typeof error51.message !== "string" || error51.retryable !== false || error51.writeState !== "not_applied" && error51.writeState !== "unknown" || error51.currentVersion !== void 0 && !isContentVersion(error51.currentVersion) || error51.code === "write_outcome_unknown" && error51.writeState !== "unknown" || (error51.code === "request_capacity" ? error51.scope !== "principal" && error51.scope !== "bundle" || error51.writeState !== "not_applied" || error51.resetAt !== void 0 && (typeof error51.resetAt !== "string" || !Number.isFinite(Date.parse(error51.resetAt))) : error51.scope !== void 0 || error51.resetAt !== void 0) || (error51.code === "deletions_held" ? operationId !== DELETE_OPERATION_ID || error51.writeState !== "not_applied" || !count2(error51.deletions) || !count2(error51.baseline) : error51.deletions !== void 0 || error51.baseline !== void 0)) throw refuse();
+  if (raw.data !== void 0 || !isRecord7(error51) || !onlyKeys(error51, ERROR_KEYS) || !WRITE_ERROR_CODES.includes(error51.code) || typeof error51.message !== "string" || error51.retryable !== false || error51.writeState !== "not_applied" && error51.writeState !== "unknown" || error51.currentVersion !== void 0 && !isContentVersion(error51.currentVersion) || error51.code === "write_outcome_unknown" && error51.writeState !== "unknown" || (error51.code === "request_capacity" ? error51.scope !== "principal" && error51.scope !== "bundle" || error51.writeState !== "not_applied" || error51.resetAt !== void 0 && (typeof error51.resetAt !== "string" || !Number.isFinite(Date.parse(error51.resetAt))) : error51.scope !== void 0 || error51.resetAt !== void 0) || (error51.code === "deletions_held" ? operationId !== DELETE_OPERATION_ID || error51.writeState !== "not_applied" || !count2(error51.deletions) || !count2(error51.baseline) : error51.deletions !== void 0 || error51.baseline !== void 0) || // A model-change refusal says nothing was applied; its findings ride on it alone.
+  error51.code === "definition_incompatible" && error51.writeState !== "not_applied" || error51.definitionDetails !== void 0 && error51.code !== "definition_incompatible") throw refuse();
   return { ok: false, operationId, error: { ...error51 } };
 }
 function updateRow(answer2) {
@@ -24234,13 +24310,14 @@ function decodeOutcomeAnswer(value, expected) {
       throw malformed4();
   }
 }
-var CAPACITY_REFUSAL_CODES, DELETIONS_HELD_REFUSAL_CODE, UPDATE_ANSWER_ROWS, OUTCOME_ANSWER_ROWS, READ_ANSWER_ROWS, WRITE_ERROR_CODES, DELETE_OPERATION_ID, HostedAnswerError, isRecord7, onlyKeys, DATA_KEYS, DELETE_DATA_KEYS, ERROR_KEYS, count2, BEFORE_DISPATCH, rowsByAnswer, HostedOutcomeError, OUTCOME_CONTENT_BYTES;
+var CAPACITY_REFUSAL_CODES, DELETIONS_HELD_REFUSAL_CODE, UPDATE_ANSWER_ROWS, OUTCOME_ANSWER_ROWS, READ_ANSWER_ROWS, WRITE_ERROR_CODES, DELETE_OPERATION_ID, FINDING_IDS_SHOWN, DEFINITION_FINDINGS_TEXT_BYTES, findingText, HostedAnswerError, isRecord7, onlyKeys, DATA_KEYS, DELETE_DATA_KEYS, ERROR_KEYS, count2, BEFORE_DISPATCH, rowsByAnswer, HostedOutcomeError, OUTCOME_CONTENT_BYTES;
 var init_answer_rows = __esm({
   "../core/src/hosted-transport/answer-rows.ts"() {
     "use strict";
     init_define_SUPERBEE_BUILD_IDENTITY();
     init_define_SUPERBEE_UPDATE_POLICY();
     init_version_transport();
+    init_host_text();
     CAPACITY_REFUSAL_CODES = Object.freeze({ principal: "REQUEST_CAPACITY_PRINCIPAL", bundle: "REQUEST_CAPACITY_BUNDLE" });
     DELETIONS_HELD_REFUSAL_CODE = "DELETIONS_HELD";
     UPDATE_ANSWER_ROWS = Object.freeze([
@@ -24261,6 +24338,8 @@ var init_answer_rows = __esm({
       // The remaining not_applied codes of the write schema: definitive once recorded, like the transient ones.
       { answer: "200 result_too_large", recorded: "settled-only", outcome: "refused" },
       { answer: "200 field_action_refused", recorded: "settled-only", outcome: "refused" },
+      // A model change the host's compatibility check refused (designs/hosted-model-evolution.md 4.6).
+      { answer: "200 definition_incompatible", recorded: "settled-only", outcome: "refused" },
       { answer: "200 document_exists", recorded: "settled-only", outcome: "refused" },
       { answer: "200 candidate_unavailable", recorded: "settled-only", outcome: "refused" },
       { answer: "200 candidate_recovery_unavailable", recorded: "settled-only", outcome: "refused" },
@@ -24337,9 +24416,17 @@ var init_answer_rows = __esm({
       "document_id_not_canonical",
       "document_id_collision",
       "request_capacity",
-      "deletions_held"
+      "deletions_held",
+      "definition_incompatible"
     ]);
     DELETE_OPERATION_ID = "documents.delete.v1";
+    FINDING_IDS_SHOWN = 5;
+    DEFINITION_FINDINGS_TEXT_BYTES = 2048;
+    findingText = (value) => {
+      if (typeof value !== "string" || value.length > 256) return void 0;
+      const text4 = stripHostText(value, 256);
+      return text4.length > 0 ? text4 : void 0;
+    };
     HostedAnswerError = class extends Error {
       name = "HostedAnswerError";
     };
@@ -24347,7 +24434,7 @@ var init_answer_rows = __esm({
     onlyKeys = (value, allowed) => Object.keys(value).every((key) => allowed.includes(key));
     DATA_KEYS = ["bundleId", "documentId", "version", "changed", "scope"];
     DELETE_DATA_KEYS = [...DATA_KEYS, "deletedVersion", "deleted"];
-    ERROR_KEYS = ["code", "message", "retryable", "writeState", "currentVersion", "diagnostics", "fieldActionDetails", "candidate", "retentionUnavailable", "scope", "resetAt", "deletions", "baseline"];
+    ERROR_KEYS = ["code", "message", "retryable", "writeState", "currentVersion", "diagnostics", "fieldActionDetails", "definitionDetails", "candidate", "retentionUnavailable", "scope", "resetAt", "deletions", "baseline"];
     count2 = (value) => Number.isSafeInteger(value) && value >= 1;
     BEFORE_DISPATCH = /* @__PURE__ */ new Map([
       [429, { code: "request_capacity", lenient: true }],
@@ -24594,7 +24681,8 @@ function decodeHostedCapabilities(value) {
     bound: Object.freeze({ documents: bound.documents, bytes: bound.bytes }),
     paged,
     root,
-    operationsRetentionMs: retention ?? DEFAULT_OPERATIONS_RETENTION_MS
+    operationsRetentionMs: retention ?? DEFAULT_OPERATIONS_RETENTION_MS,
+    definitionWrites: body.definitionWrites === void 0 ? null : body.definitionWrites === "allowed" ? "allowed" : "refused"
   });
 }
 function boundedLines(body, maximum) {
@@ -25034,7 +25122,9 @@ function createWholeDocumentTransport(options) {
     if (error51.code === "version_conflict" && intent.base === null) return servedHead(intent, "conflict", error51.currentVersion);
     if (error51.code === "version_conflict") return error51.currentVersion === void 0 ? servedHead(intent) : { kind: "conflict", actual: error51.currentVersion };
     const row3 = UPDATE_ANSWER_ROWS.find((candidate) => candidate.answer === `200 ${error51.code}`) ?? updateRow("200 other");
-    return row3.code ? denial(row3.code, error51.message) : { kind: "refused", code: error51.code, message: error51.message };
+    if (row3.code) return denial(row3.code, error51.message);
+    const findings = error51.code === "definition_incompatible" ? definitionFindingsText(error51.definitionDetails) : "";
+    return { kind: "refused", code: error51.code, message: findings ? `${error51.message} Findings: ${findings}.` : error51.message };
   }
   function prepare(intent) {
     const request2 = wholeDocumentRequest(bundleId, intent, options.okfVersion);
@@ -30277,9 +30367,17 @@ function qualifyingCarrier(carrier, prefix, slug) {
     if (bundleId.includes("/")) throw new TypeError("a qualified reference sent through a qualifying client");
     return { ...input, bundleId: hostedBundleReferenceText({ slug, bundleId }) };
   };
+  const bytes = carrier.bytes?.bind(carrier);
   return {
     json: async (route, input, signal, options) => carrier.json(route, qualify(route, input), signal, options),
-    stream: async (route, input, signal) => carrier.stream(route, qualify(route, input), signal)
+    stream: async (route, input, signal) => carrier.stream(route, qualify(route, input), signal),
+    // A raw body names no bundle in a body; only unscoped routes carry one.
+    ...bytes ? {
+      bytes: async (route, body, signal, options) => {
+        if (scoped(route)) throw new TypeError(`a raw body sent to the bundle-scoped route ${route} through a qualifying client`);
+        return bytes(route, body, signal, options);
+      }
+    } : {}
   };
 }
 function createHostedSyncClient(options) {
@@ -30480,7 +30578,15 @@ var init_client = __esm({
     BUNDLES_BYTES = 256 * 1024;
     AGENT_AUDIENCE_PATH = /^\/agents\/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\/mcp$/;
     BUNDLE_LIST_CAP = 100;
-    UNSCOPED_ROUTES = Object.freeze(["whoami", "bundles", "bundle-create"]);
+    UNSCOPED_ROUTES = Object.freeze([
+      "whoami",
+      "bundles",
+      "bundle-create",
+      "bundle-create-begin",
+      "bundle-create-stage",
+      "bundle-create-blob",
+      "bundle-create-commit"
+    ]);
   }
 });
 
@@ -30488,12 +30594,31 @@ var init_client = __esm({
 import { createHash as createHash10 } from "node:crypto";
 import { promises as fs11 } from "node:fs";
 import path29 from "node:path";
-function heldPathReason(rel) {
+function underFolded(rel, folder) {
+  const folded = foldedPath(rel);
+  return folded === folder || folded.startsWith(`${folder}/`);
+}
+function heldPathReason(rel, options = {}) {
   if (isReservedFile(rel)) return "reserved_file";
   if (!rel.endsWith(".md")) return "not_a_document";
-  if (HELD_PREFIXES.some((prefix) => rel.startsWith(prefix))) return "convention_folder";
+  if (HELD_FOLDERS.some((folder) => underFolded(rel, folder))) return "convention_folder";
+  if (underFolded(rel, "conventions") && !(options.definitionWrites === "allowed" && isConventionId(rel))) return "convention_folder";
   return null;
 }
+function heldTypeReason(rel, type, definitionWrites) {
+  if (type === "View") return `'${conceptIdFromPath(rel)}' is a View registration, which the host installs; it does not sync`;
+  if (type === CONVENTION_TYPE && !(definitionWrites === "allowed" && isConventionId(rel))) return `'${conceptIdFromPath(rel)}' is a Kind convention outside conventions/; the host reads Kinds only from conventions/`;
+  if (definitionWrites === "allowed" && isConventionId(rel) && type !== CONVENTION_TYPE) return `'${conceptIdFromPath(rel)}' is under conventions/ but is not a Convention; only Kind conventions sync there`;
+  return null;
+}
+function heldPathMessage(rel, definitionWrites = null, sender = "sync") {
+  if (underFolded(rel, "views-registry")) return `${rel} is under views-registry/, which holds the bundle's View registrations; they are installed on the host and do not sync`;
+  if (underFolded(rel, "conventions") && definitionWrites === "refused") return `${rel} is under conventions/, which holds the bundle's model: ${DEFINITIONS_REFUSED.why}; ${DEFINITIONS_REFUSED.instead}`;
+  if (underFolded(rel, "conventions") && definitionWrites === "allowed") {
+    return sender === "app" ? `${rel} is under conventions/, which holds the bundle's model; change it with the kind and recipe commands` : `${rel} is not under conventions/ as spelled; the bundle's Kinds sync only from the folder named exactly conventions/`;
+  }
+  return `${rel} is under ${rel.split("/")[0]}/, which holds conventions edited in the Superbee app`;
+}
 async function readDeletionWindow(store) {
   const raw = await store.readMeta(DELETION_WINDOW_KEY);
   const hold = raw?.hold && Array.isArray(raw.hold.ids) && typeof raw.hold.token === "string" ? { ids: raw.hold.ids.filter((id) => typeof id === "string"), token: raw.hold.token } : null;
@@ -30700,7 +30825,10 @@ function foldedPath(id) {
 function held(id, rel, reason, message) {
   return { id, path: rel, reason, message };
 }
-function unsendable(id, rel, bytes, stored, context) {
+function unsendable(id, rel, bytes, stored, context, fence) {
+  if (fence && heldPathReason(rel, { definitionWrites: fence.definitionWrites }) === "convention_folder") {
+    return held(id, rel, "convention_folder", heldPathMessage(rel, fence.definitionWrites, fence.sender));
+  }
   if (bytes.byteLength > WHOLE_DOCUMENT_BOUNDS.payloadBytes) {
     return held(id, rel, "too_large", `'${id}' is over the ${WHOLE_DOCUMENT_BOUNDS.payloadBytes / 1024} KiB a sync write carries`);
   }
@@ -30721,6 +30849,8 @@ function unsendable(id, rel, bytes, stored, context) {
   if (Buffer.byteLength(JSON.stringify(frontmatter)) > FRONTMATTER_JSON_BYTES || Object.keys(frontmatter).length > FRONTMATTER_KEY_LIMIT) {
     return held(id, rel, "too_large", `'${id}' has more frontmatter than the host accepts (${FRONTMATTER_JSON_BYTES / 1024} KiB, ${FRONTMATTER_KEY_LIMIT} fields)`);
   }
+  const typed = fence ? heldTypeReason(rel, frontmatter.type, fence.definitionWrites) : null;
+  if (typed !== null) return held(id, rel, "not_sendable", typed);
   const storedType = stored?.frontmatter.type;
   if (typeof storedType === "string" && storedType !== frontmatter.type) {
     return held(id, rel, "type_change", `'${id}' changes type from '${storedType}' to '${String(frontmatter.type)}', which sync cannot send`);
@@ -30783,11 +30913,7 @@ async function scanCheckout(context) {
         continue;
       }
     }
-    if (heldPathReason(rel) === "convention_folder") {
-      report.held.push(held(id, rel, "convention_folder", `${rel} is under ${rel.split("/")[0]}/, which holds conventions edited in the Superbee app`));
-      continue;
-    }
-    const refusal = unsendable(id, rel, bytes, stored.document?.doc ?? null, context);
+    const refusal = unsendable(id, rel, bytes, stored.document?.doc ?? null, context, { definitionWrites: context.definitionWrites ?? null });
     if (refusal) {
       report.held.push(refusal);
       continue;
@@ -30824,6 +30950,14 @@ async function scanCheckout(context) {
       delete projection.files[id];
       continue;
     }
+    const definitionWrites = context.definitionWrites ?? null;
+    const refusedPath = heldPathReason(rel, { definitionWrites }) === "convention_folder";
+    const refusedType = refusedPath ? null : heldTypeReason(rel, stored.document.doc.frontmatter.type, definitionWrites);
+    if (refusedPath || refusedType !== null) {
+      delete projection.files[id];
+      report.held.push(held(id, rel, refusedPath ? "convention_folder" : "not_sendable", `${refusedPath ? heldPathMessage(rel, definitionWrites) : refusedType}; the host's version is placed back in the folder`));
+      continue;
+    }
     if (stored.intents.some((row3) => row3.state === "conflict")) {
       report.held.push(held(id, rel, "deleted_locally", `${rel} was deleted while '${id}' has a conflict to resolve; resolve it first`));
       continue;
@@ -31114,7 +31248,7 @@ async function recoverPlacements(folder, projection) {
   }
   delete projection.discarded;
 }
-var PROJECTION_FILE, PROJECTION_SCHEMA, PROJECTION_BYTES, FRONTMATTER_JSON_BYTES, HELD_PREFIXES, MIN_HELD_DELETIONS, DELETION_WINDOW_MS, DELETION_WINDOW_KEY, UTF8;
+var PROJECTION_FILE, PROJECTION_SCHEMA, PROJECTION_BYTES, FRONTMATTER_JSON_BYTES, HELD_FOLDERS, DEFINITIONS_REFUSED, MIN_HELD_DELETIONS, DELETION_WINDOW_MS, DELETION_WINDOW_KEY, UTF8;
 var init_sync_scan = __esm({
   "../cli/src/hosted/sync-scan.ts"() {
     "use strict";
@@ -31132,7 +31266,11 @@ var init_sync_scan = __esm({
     PROJECTION_SCHEMA = 2;
     PROJECTION_BYTES = 8 * 1024 * 1024;
     FRONTMATTER_JSON_BYTES = 16 * 1024;
-    HELD_PREFIXES = ["conventions/", "views/"];
+    HELD_FOLDERS = ["views", "views-registry"];
+    DEFINITIONS_REFUSED = Object.freeze({
+      why: "you don't have permission to change this bundle's model",
+      instead: "ask whoever manages access to it"
+    });
     MIN_HELD_DELETIONS = 3;
     DELETION_WINDOW_MS = 24 * 60 * 60 * 1e3;
     DELETION_WINDOW_KEY = "cli-deletion-window";
@@ -31196,6 +31334,13 @@ function hostedCheckoutRefusal(row3, words, binding, extra = {}) {
       help: "choose another folder for a local bundle"
     });
   }
+  if (row3.definitions && binding.definition_writes === "refused") {
+    const { why, instead } = DEFINITIONS_REFUSED;
+    return new CliError("FORBIDDEN", `'${words}' refused: ${why} (bundle ${binding.bundle_id} on ${binding.origin}); ${instead}`, {
+      details: { ...details, reason: "definitions_refused" },
+      help: instead
+    });
+  }
   if (row3.instead) {
     return new CliError("FORBIDDEN", `'${words}' cannot sync from a hosted checkout (${row3.why}): ${row3.instead}`, { details, help: row3.instead });
   }
@@ -31211,9 +31356,23 @@ async function assertAllowedInHostedCheckout(command, args, context = {}) {
   if (skip) return;
   const binding = await checkoutFor(command, dir, context.home ?? homedir12(), context.cwd ?? process.cwd());
   if (!binding) return;
+  if (row3.definitions && binding.definition_writes === "allowed") return;
   const sub = row3.words.length > 1 ? args.find((token) => !token.startsWith("-")) : void 0;
   throw hostedCheckoutRefusal(row3, sub ? `${command} ${sub}` : command, binding);
 }
+async function assertKindOnlyRecipe(words, dir, recipe2, context = {}) {
+  const artifacts = [...recipe2.docs.map((doc2) => doc2.id), ...recipe2.pages.flatMap((page) => [page.registry.id, page.entry]), ...recipe2.references.map((reference) => reference.doc.id)];
+  const outside = artifacts.filter((id) => !isConventionId(id));
+  if (outside.length === 0) return;
+  const binding = await checkoutFor("recipe", dir, context.home ?? homedir12(), context.cwd ?? process.cwd());
+  if (!binding) return;
+  throw hostedCheckoutRefusal(
+    { words: words.split(" "), reason: "not_syncable", why: `recipe '${recipe2.id}' installs ${outside.length} artifact(s) outside conventions/, such as Views and References, and a checkout sends Kind conventions only`, instead: KINDS_INSTEAD },
+    words,
+    binding,
+    { recipe: recipe2.id, artifacts: outside.slice(0, 20).join(", "), artifacts_total: String(outside.length) }
+  );
+}
 function hostedHeldWriteRefusal(binding, held2) {
   const instead = HELD_INSTEAD[held2.reason];
   return hostedCheckoutRefusal(
@@ -31286,6 +31445,7 @@ var init_refusals = __esm({
     "use strict";
     init_define_SUPERBEE_BUILD_IDENTITY();
     init_define_SUPERBEE_UPDATE_POLICY();
+    init_src();
     init_bundle2();
     init_errors4();
     init_command_text();
@@ -31297,20 +31457,20 @@ var init_refusals = __esm({
     KINDS_INSTEAD = "to design Kinds, work in a local or Git bundle and publish it";
     HOSTED_CHECKOUT_REFUSALS = Object.freeze([
       { words: ["doc", "verify"], reason: "not_syncable", why: "verification is a managed field the host records" },
-      { words: ["kind", "*"], reason: "not_syncable", why: "a hosted bundle's Kinds cannot be changed from a checkout", instead: KINDS_INSTEAD },
-      { words: ["recipe", "add"], reason: "not_syncable", why: "recipes change a hosted bundle's Kinds, which cannot be changed from a checkout", instead: KINDS_INSTEAD },
-      { words: ["recipe", "evolve"], reason: "not_syncable", why: "recipes change a hosted bundle's Kinds, which cannot be changed from a checkout", instead: KINDS_INSTEAD },
+      { words: ["kind", "*"], reason: "not_syncable", why: "a hosted bundle's Kinds cannot be changed from a checkout", instead: KINDS_INSTEAD, definitions: true },
+      { words: ["recipe", "add"], reason: "not_syncable", why: "recipes change a hosted bundle's Kinds, which cannot be changed from a checkout", instead: KINDS_INSTEAD, definitions: true },
+      { words: ["recipe", "evolve"], reason: "not_syncable", why: "recipes change a hosted bundle's Kinds, which cannot be changed from a checkout", instead: KINDS_INSTEAD, definitions: true },
       { words: ["artifact", "*"], reason: "not_syncable", why: "artifacts carry blobs, which do not sync" },
       {
         words: ["promote"],
         reason: "not_syncable",
-        why: "a key that is not a .md document is stored as a blob, and blobs, reserved files and conventions do not sync",
+        why: "a key that is not a .md document is stored as a blob; blobs, reserved files and View files do not sync, and conventions change only through the kind and recipe commands",
         when: (args) => heldKey(docKey(args) ?? "")
       },
       {
         words: ["delete"],
         reason: "not_syncable",
-        why: "a key that is not a .md document is a blob, and blobs, reserved files and conventions do not sync (delete a document with doc delete)",
+        why: "a key that is not a .md document is a blob; blobs, reserved files and View files do not sync, and conventions change only through the kind and recipe commands (delete a document with doc delete)",
         when: (args) => {
           const key = docKey(args);
           return key !== void 0 && heldKey(key);
@@ -31324,7 +31484,7 @@ var init_refusals = __esm({
         when: (args) => !args.some((token) => token === "--check" || token.startsWith("--check="))
       },
       { words: ["serve"], reason: "not_syncable", why: "the served bundle accepts writes and deletes that do not sync" },
-      { words: ["ui"], reason: "not_syncable", why: "the local app writes Views and conventions, which do not sync" },
+      { words: ["ui"], reason: "not_syncable", why: "the local app writes Views, which do not sync, and conventions outside the kind and recipe commands" },
       { words: ["init"], reason: "checkout_target", why: "the folder is a hosted checkout, not a local bundle" }
     ].map((row3) => Object.freeze({ ...row3, words: Object.freeze([...row3.words]) })));
     HELD_INSTEAD = {
@@ -34519,6 +34679,7 @@ function refusalRow(id, row3, accessWithdrawn = false) {
   if (SIGN_IN_CODES.has(code3) && accessWithdrawn) return { id, state: "refused", reason: "access_withdrawn", version: null, message: ACCESS_WITHDRAWN_MESSAGE };
   if (SIGN_IN_CODES.has(code3)) return { id, state: "paused", reason: "sign_in", version: null, message: "The hosted session ended before this change was sent; sign in and run sync again." };
   if (BUSY_REFUSAL_CODES.has(code3)) return { id, state: "paused", reason: "busy", version: null, message: "The host was busy and did not apply this change; run sync again." };
+  if (code3 === "definition_incompatible") return { id, state: "refused", reason: code3, version: null, message: `The host refused this model change (${code3}): ${message} Fix the documents it names (the sync that sends them sends this change again), or edit the Kind and run sync again.` };
   return { id, state: "refused", reason: code3, version: null, message: `The host refused this document (${code3}): ${message} Edit the file and run sync again.` };
 }
 function waitingRow(id, pausedBy, notSent) {
@@ -34858,13 +35019,14 @@ async function withSession(binding, deps, resumeCommand, body, options = {}) {
       } catch (error51) {
         throw await readFailure(error51, { binding, target: target2, client }, resumeCommand, await unsent());
       }
+      const bound = await recordDefinitionWrites(deps.auth.home, binding, capabilities.definitionWrites);
       projection = await readProjection(deps.auth.home, binding.checkout_id, store);
       await recoverPlacements(binding.path, projection);
       const record5 = projection;
       const persist = () => writeProjection(deps.auth.home, binding.checkout_id, record5);
       await persist();
       return await body({
-        binding,
+        binding: bound,
         target: target2,
         reader,
         capabilities,
@@ -34889,18 +35051,23 @@ async function withSession(binding, deps, resumeCommand, body, options = {}) {
     throw lockFailure(error51, binding.path);
   });
 }
-function createsFirst(store, blocked) {
+function createsFirst(store, blocked, models) {
   return new Proxy(store, {
     get(inner, prop) {
       if (prop === "listIntents") {
         return async (state) => {
-          const rows = await inner.listIntents(state);
+          const rows = (await inner.listIntents(state)).filter(
+            (row3) => !(state === "pending" && (row3.base === null && row3.kind !== DOCUMENT_DELETE_KIND && blocked.has(row3.target) || !models && isConventionId(row3.target)))
+          );
           if (state !== "pending") return rows;
           const deleting = (row3) => row3.kind === DOCUMENT_DELETE_KIND;
+          const model = (row3) => isConventionId(row3.target);
           return [
-            ...rows.filter((row3) => row3.base === null && !deleting(row3) && !blocked.has(row3.target)),
-            ...rows.filter((row3) => row3.base !== null && !deleting(row3)),
-            ...rows.filter(deleting)
+            ...rows.filter((row3) => model(row3) && !deleting(row3)),
+            ...rows.filter((row3) => !model(row3) && row3.base === null && !deleting(row3)),
+            ...rows.filter((row3) => !model(row3) && row3.base !== null && !deleting(row3)),
+            ...rows.filter((row3) => !model(row3) && deleting(row3)),
+            ...rows.filter((row3) => model(row3) && deleting(row3))
           ];
         };
       }
@@ -34909,18 +35076,18 @@ function createsFirst(store, blocked) {
     }
   });
 }
-async function requeueBusy(store) {
-  let requeued = 0;
+async function requeueRefused(store, eligible) {
+  const requeued = [];
   const unsettled = await store.listIntents(UNSETTLED_STATES);
   for (const row3 of unsettled) {
-    if (row3.state !== "refused" || !row3.refusal || !BUSY_REFUSAL_CODES.has(row3.refusal.code)) continue;
+    if (row3.state !== "refused" || !row3.refusal || !eligible(row3)) continue;
     if (unsettled.some((other) => other.after === row3.requestId)) continue;
     const current = await store.readWithJournal(row3.target);
     const latest = current.intents.filter((intent) => intent.state !== "acknowledged").at(-1);
     if (latest?.requestId !== row3.requestId) continue;
     const supersede = { requestId: row3.requestId, expectedState: "refused", expectedAttempts: row3.attempts };
     if (row3.kind === DOCUMENT_DELETE_KIND) {
-      if (await supersedeDeletion(store, row3)) requeued += 1;
+      if (await supersedeDeletion(store, row3)) requeued.push(row3.target);
       continue;
     }
     if (!current.document) continue;
@@ -34938,10 +35105,37 @@ async function requeueBusy(store) {
       },
       supersede
     });
-    requeued += 1;
+    requeued.push(row3.target);
   }
   return requeued;
 }
+function intentFrontmatter(row3, okfVersion) {
+  const text4 = row3.kind === DOCUMENT_DELETE_KIND ? row3.baseContent : row3.content;
+  if (!text4) return null;
+  try {
+    return parseMarkdown(text4, row3.target, { okfVersion }).frontmatter;
+  } catch {
+    return null;
+  }
+}
+function recordLanded(landed, row3, okfVersion) {
+  const frontmatter = intentFrontmatter(row3, okfVersion);
+  if (isConventionId(row3.target)) {
+    if (typeof frontmatter?.governs === "string") landed.governed.add(frontmatter.governs);
+    landed.conventionChanged = true;
+  } else if (typeof frontmatter?.type === "string") landed.types.add(frontmatter.type);
+}
+function definitionRetry(row3, landed, okfVersion, models) {
+  const code3 = row3.refusal?.code;
+  if (isConventionId(row3.target)) {
+    if (!models || code3 !== "definition_incompatible") return false;
+    const governs = intentFrontmatter(row3, okfVersion)?.governs;
+    return landed.conventionChanged || typeof governs === "string" && landed.types.has(governs);
+  }
+  if (code3 !== "validation_failed") return false;
+  const type = intentFrontmatter(row3, okfVersion)?.type;
+  return typeof type === "string" && landed.governed.has(type);
+}
 async function caseCollidingCreates(store) {
   const creates = (await store.listIntents("pending")).filter((row3) => row3.base === null);
   if (creates.length === 0) return [];
@@ -34996,13 +35190,23 @@ async function pushChanges(session, deps, acceptDeletes, heldSink = {}) {
       heldSink.value ??= { deletions, baseline };
     }
   });
-  const ordered = createsFirst(store, new Set(collisions.map((row3) => row3.id)));
+  const models = session.capabilities.definitionWrites === "allowed";
+  const withheld = models ? [] : [...new Set((await store.listIntents("pending")).filter((row3) => isConventionId(row3.target)).map((row3) => row3.target))].map((id) => ({
+    id,
+    path: `${id}.md`,
+    reason: "convention_folder",
+    message: heldPathMessage(`${id}.md`, session.capabilities.definitionWrites)
+  }));
+  const ordered = createsFirst(store, new Set(collisions.map((row3) => row3.id)), models);
   let signInRequired = false;
+  const landed = { types: /* @__PURE__ */ new Set(), governed: /* @__PURE__ */ new Set(), conventionChanged: false };
+  const retried = /* @__PURE__ */ new Set();
   for (let pass = 0; pass < PUSH_PASSES; pass += 1) {
     const report = await push2(ordered, transport, { remote: reader, write: { ...deps.write, settlement: WHOLE_DOCUMENT_SETTLEMENT } });
     for (const settled of report.settled) {
       if (settled.state !== "acknowledged") continue;
       const row3 = await store.readIntent(settled.requestId);
+      if (row3) recordLanded(landed, row3, session.okfVersion);
       acknowledged.set(settled.target, row3?.acknowledgedVersion === DELETION_VERSION ? "" : row3?.acknowledgedVersion ?? "");
       if (row3?.kind === DOCUMENT_DELETE_KIND) {
         deleted.add(settled.target);
@@ -35014,10 +35218,19 @@ async function pushChanges(session, deps, acceptDeletes, heldSink = {}) {
       signInRequired = /^(AUTH_REQUIRED|UNAUTHORIZED)\b/.test(control?.reason ?? "") && !denied;
       break;
     }
-    if (pass === PUSH_PASSES - 1 || await requeueBusy(store) === 0) break;
+    if (pass === PUSH_PASSES - 1) break;
+    const model = /* @__PURE__ */ new Set();
+    const requeued = await requeueRefused(store, (row3) => {
+      if (busyRefusal(row3)) return true;
+      if (retried.has(row3.target) || !definitionRetry(row3, landed, session.okfVersion, models)) return false;
+      model.add(row3.target);
+      return true;
+    });
+    if (requeued.length === 0) break;
+    for (const id of requeued) if (model.has(id)) retried.add(id);
     await (deps.sleep ?? ((ms) => new Promise((resolve2) => setTimeout(resolve2, ms))))(50 + Math.floor(Math.random() * 200));
   }
-  return { acknowledged, deleted, deletedIntents, signInRequired, accessWithdrawn: denied, notSent: null, collisions, via };
+  return { acknowledged, deleted, deletedIntents, signInRequired, accessWithdrawn: denied, notSent: null, collisions: [...collisions, ...withheld], via };
 }
 async function forgetPullDigest(store) {
   const marker = await store.readMeta("pull");
@@ -35109,6 +35322,7 @@ async function runSync(binding, values, deps, mode) {
       okfVersion: session.okfVersion,
       local,
       projection,
+      definitionWrites: session.capabilities.definitionWrites,
       ...acceptDeletes !== void 0 ? { acceptDeletes, confirmAccept: confirmAtTerminal(binding, terminal) } : {}
     });
     await session.persist();
@@ -35256,7 +35470,7 @@ async function pullOnly(binding, session, deps, resumeCommand) {
   {
     const { store, local, reader, projection } = session;
     await reclaimInFlight(local);
-    await scanCheckout({ folder: binding.path, bundleId: binding.bundle_id, okfVersion: session.okfVersion, local, projection });
+    await scanCheckout({ folder: binding.path, bundleId: binding.bundle_id, okfVersion: session.okfVersion, local, projection, definitionWrites: session.capabilities.definitionWrites });
     await session.persist();
     let report;
     try {
@@ -35499,7 +35713,7 @@ async function runInspect2(binding, values, deps, mode) {
 }
 async function assertSendable(session, id, file2, bytes, resumeCommand) {
   const stored = await session.store.readWithJournal(id);
-  const held2 = unsendable(id, `${id}.md`, bytes, stored.document?.doc ?? null, { bundleId: session.binding.bundle_id, okfVersion: session.okfVersion });
+  const held2 = unsendable(id, `${id}.md`, bytes, stored.document?.doc ?? null, { bundleId: session.binding.bundle_id, okfVersion: session.okfVersion }, { definitionWrites: session.capabilities.definitionWrites });
   if (held2) throw new CliError("CONFLICT", `${file2} cannot be sent: ${held2.message}`, { details: { reason: held2.reason, id, file: file2 }, help: `edit ${file2}, then re-run: ${resumeCommand}` });
 }
 async function resolveFolder(session, id, choice, conflict, resumeCommand) {
@@ -35691,7 +35905,7 @@ async function hostedSync(argv2, binding, partial2 = {}) {
   if (values["restore-deletes"]) return runRestore(binding, deps, mode);
   return runSync(binding, values, deps, mode);
 }
-var HOSTED_SYNC_USAGE, DEFAULT_ROW_LIMIT, INSPECT_PREVIEW_CHARS2, PUSH_PASSES, GIT_ONLY_FLAGS;
+var HOSTED_SYNC_USAGE, DEFAULT_ROW_LIMIT, INSPECT_PREVIEW_CHARS2, PUSH_PASSES, GIT_ONLY_FLAGS, busyRefusal;
 var init_sync2 = __esm({
   "../cli/src/hosted/sync.ts"() {
     "use strict";
@@ -35783,6 +35997,7 @@ unless SUPERBEE_VIA says otherwise. SUPERBEE_ACTOR does not set it.
     INSPECT_PREVIEW_CHARS2 = 4e3;
     PUSH_PASSES = 3;
     GIT_ONLY_FLAGS = ["establish", "pull-only", "show-incoming", "yes", "body-out", "migrate"];
+    busyRefusal = (row3) => row3.refusal !== void 0 && BUSY_REFUSAL_CODES.has(row3.refusal.code);
   }
 });
 
@@ -84039,6 +84254,7 @@ async function recipeEvolve(argv2, stdout) {
     throw new CliError("USAGE", loaded.error.message, { help: `${cliInvocation()} recipes` });
   }
   const remote = await resolveRemoteFlag(values.remote, values.dir);
+  if (remote === void 0) await assertKindOnlyRecipe("recipe evolve", values.dir, loaded.recipe);
   const bundle = await openBundle(values.dir, remote);
   const target2 = values.dir !== void 0 ? commandFragment` --dir ${commandQuoted(values.dir)}` : remote !== void 0 ? commandFragment` --remote ${commandQuoted(remote)}` : commandLiteral("");
   const planCommand = `${cliInvocation()} recipe evolve ${commandQuoted(ref)}${target2}`;
@@ -84094,6 +84310,7 @@ async function recipeAdd(argv2, stdout) {
     throw new CliError("USAGE", loaded.error.message, { help: `${cliInvocation()} recipes` });
   }
   const remote = await resolveRemoteFlag(values.remote, values.dir);
+  if (remote === void 0) await assertKindOnlyRecipe("recipe add", values.dir, loaded.recipe);
   const bundle = await openBundle(values.dir, remote);
   const result3 = await applyRecipe(bundle, loaded.recipe);
   const registry2 = await loadKinds(bundle);
@@ -84140,6 +84357,7 @@ var init_recipe = __esm({
     init_recipes();
     init_recipe_evolution();
     init_recipe_source();
+    init_refusals();
     init_command_text();
     RECIPE_USAGE = `superbee recipe \u2014 apply a recipe to this bundle
 
@@ -84220,7 +84438,9 @@ async function classifyCheckout(binding, home2, store) {
     okfVersion: await storeOkfVersion(store),
     local: openLocalBundle(binding.checkout_id, { backend: store }),
     projection: await readProjection(home2, binding.checkout_id, store),
-    preview: true
+    preview: true,
+    // What the host said at the last sync: a preview makes no request.
+    definitionWrites: binding.definition_writes ?? null
   });
   for (const id of report.pending) result3.unsent.add(id);
   for (const id of report.conflicted) result3.conflicts.add(id);
@@ -119715,7 +119935,7 @@ function checkoutGuard(binding, home2, folder, options) {
     }
     const rel = pathFromConceptId(id);
     const reason = heldPathReason(rel);
-    if (reason === "convention_folder") refuse({ id, path: rel, reason, message: `${rel} is under ${rel.split("/")[0]}/, which holds conventions edited in the Superbee app` });
+    if (reason === "convention_folder") refuse({ id, path: rel, reason, message: heldPathMessage(rel, binding.definition_writes ?? null, "app") });
     if (reason !== null) refuse({ id, path: rel, reason, message: `${rel} is a reserved OKF file, which sync does not send` });
     return rel;
   };
@@ -119738,7 +119958,7 @@ function checkoutGuard(binding, home2, folder, options) {
           const rel = documentPath(id);
           const bytes = Buffer.from(stringifyDoc(doc2.frontmatter, doc2.body ?? ""), "utf8");
           const stored = await storedDocument(binding, home2, folder, id);
-          const held2 = unsendable(id, rel, bytes, stored.frontmatter ? { frontmatter: stored.frontmatter } : null, { bundleId: binding.bundle_id, okfVersion: stored.okfVersion });
+          const held2 = unsendable(id, rel, bytes, stored.frontmatter ? { frontmatter: stored.frontmatter } : null, { bundleId: binding.bundle_id, okfVersion: stored.okfVersion }, { definitionWrites: null, sender: "app" });
           if (held2) refuse(held2);
           const current = await folder.read(id).then((read) => read, () => null);
           const expected = writeOptions?.expectedVersion;
@@ -119755,7 +119975,7 @@ function checkoutGuard(binding, home2, folder, options) {
         case "deleteBlob": {
           const key = String(args[0]);
           const reason = heldPathReason(key) ?? "not_a_document";
-          const message = reason === "convention_folder" ? `${key} is under ${key.split("/")[0]}/, which holds conventions edited in the Superbee app` : reason === "reserved_file" ? `${key} is a reserved OKF file, which sync does not send` : `${key} is not a .md document; files other than documents do not sync`;
+          const message = reason === "convention_folder" ? heldPathMessage(key, binding.definition_writes ?? null, "app") : reason === "reserved_file" ? `${key} is a reserved OKF file, which sync does not send` : `${key} is not a .md document; files other than documents do not sync`;
           return refuse({ id: key, path: key, reason, message });
         }
         default:
@@ -128609,7 +128829,7 @@ Options:
 
 // ../cli/src/hosted/publish-state.ts
 import { createHash as createHash20 } from "node:crypto";
-import { unlink as unlink10 } from "node:fs/promises";
+import { readdir as readdir6, unlink as unlink10 } from "node:fs/promises";
 import path45 from "node:path";
 function recordDir(home2) {
   return path45.join(userStateDir(home2), "hosted-publish");
@@ -128639,6 +128859,23 @@ async function writePendingCreate(home2, canonical2, pending) {
   await writeUserStateFileAtomic0600(home2, recordDir(home2), recordName2(canonical2, pendingSuffix(pending.bundle_id)), `${JSON.stringify(pending)}
 `);
 }
+async function listPendingCreates(home2) {
+  let names;
+  try {
+    names = await readdir6(recordDir(home2));
+  } catch {
+    return [];
+  }
+  const records = [];
+  for (const name of names.filter((entry) => /^[0-9a-f]{64}-[0-9a-f]{64}\.json$/.test(entry))) {
+    try {
+      const value = JSON.parse(await readUserStateFile(home2, path45.join(recordDir(home2), name), 1024 * 1024));
+      if (typeof value.request_id === "string" && typeof value.bundle_id === "string" && typeof value.host === "string") records.push(value);
+    } catch {
+    }
+  }
+  return records;
+}
 function clearPendingCreate(home2, canonical2, bundleId) {
   return clearRecord(home2, canonical2, pendingSuffix(bundleId));
 }
@@ -128912,7 +129149,7 @@ async function rebindToWorkspace(canonical2, bound, options, deps, mode) {
 }
 async function bindFolderInPlace(input) {
   const { canonical: canonical2, target: target2, bundleId, deps, resume: resume2 } = input;
-  const { identity, reader, listed: isListed, workspace, reference } = input.connection;
+  const { identity, reader, listed: isListed, workspace, reference, definitionWrites } = input.connection;
   const home2 = deps.auth.home;
   const placedFiles = /* @__PURE__ */ new Map();
   return withCheckoutLock(canonical2, async () => {
@@ -128921,7 +129158,7 @@ async function bindFolderInPlace(input) {
     }
     const identityNow = await folderIdentity(canonical2);
     if (!identityNow) throw new CliError("RUNTIME", `${canonical2} disappeared while binding it`, { help: "retry the same command" });
-    const binding = {
+    const binding = withDefinitionWrites({
       schema: 1,
       checkout_id: newCheckoutId(),
       path: canonical2,
@@ -128936,7 +129173,7 @@ async function bindFolderInPlace(input) {
       created_at: new Date(deps.auth.now()).toISOString(),
       state: "hydrating",
       folder_identity: identityNow
-    };
+    }, definitionWrites);
     await writeBinding(home2, binding);
     let store;
     try {
@@ -129061,7 +129298,7 @@ var init_checkout_adopt = __esm({
 
 // ../cli/src/commands/checkout.ts
 import { homedir as homedir37 } from "node:os";
-import { lstat as lstat9, mkdir as mkdir4, readFile as readFile5, readdir as readdir6, realpath as realpath11, rmdir as rmdir3, stat as stat8, unlink as unlink11 } from "node:fs/promises";
+import { lstat as lstat9, mkdir as mkdir4, readFile as readFile5, readdir as readdir7, realpath as realpath11, rmdir as rmdir3, stat as stat8, unlink as unlink11 } from "node:fs/promises";
 import path47 from "node:path";
 import { parseArgs as parseArgs39 } from "node:util";
 function checkoutDeps(partial2) {
@@ -129081,7 +129318,7 @@ async function entryKind(target2) {
     throw error51;
   }
   if (!info.isDirectory()) return "other";
-  return (await readdir6(target2)).length === 0 ? "empty-dir" : "dir";
+  return (await readdir7(target2)).length === 0 ? "empty-dir" : "dir";
 }
 function bindingView(binding) {
   return {
@@ -129321,7 +129558,7 @@ async function checkout(argv2, partial2 = {}) {
     });
   }
   await assertStandaloneFolder(folder);
-  const { identity, reader, listed: listed2, workspace, reference } = await connectHostedBundle(typed, target2, values.workspace, deps, resume2);
+  const { identity, reader, listed: listed2, workspace, reference, definitionWrites } = await connectHostedBundle(typed, target2, values.workspace, deps, resume2);
   const canonical2 = await canonicalFolder(folder);
   let createdFolder = false;
   const placed = /* @__PURE__ */ new Map();
@@ -129348,7 +129585,7 @@ async function checkout(argv2, partial2 = {}) {
     }
     const identityNow = await folderIdentity(canonical2);
     if (!identityNow) throw new CliError("RUNTIME", `${canonical2} disappeared during checkout`, { help: "retry the same command" });
-    const binding = {
+    const binding = withDefinitionWrites({
       schema: 1,
       checkout_id: newCheckoutId(),
       path: canonical2,
@@ -129363,7 +129600,7 @@ async function checkout(argv2, partial2 = {}) {
       created_at: new Date(deps.auth.now()).toISOString(),
       state: "hydrating",
       folder_identity: identityNow
-    };
+    }, definitionWrites);
     await writeBinding(deps.auth.home, binding);
     let store;
     try {
@@ -129485,7 +129722,7 @@ async function connectHostedBundle(typed, target2, workspaceFlag, deps, resume2)
   }
   if (ids.length > Math.min(CHECKOUT_DOCUMENT_LIMIT, capabilities.bound.documents)) throw tooLarge(reference, target2, ids.length);
   assertProjectable(ids, bundleId, target2);
-  return { identity, reader, listed: listed2, workspace: tenantId ?? workspace, reference, client };
+  return { identity, reader, listed: listed2, workspace: tenantId ?? workspace, reference, client, definitionWrites: capabilities.definitionWrites };
 }
 function catalogLabels(bundleId) {
   const base = bundleId.slice(0, 60).replace(/[._-]+$/, "");
@@ -129640,7 +129877,7 @@ Examples:
 // ../cli/src/commands/export.ts
 import { randomBytes as randomBytes9 } from "node:crypto";
 import { homedir as homedir38 } from "node:os";
-import { link as link3, lstat as lstat10, mkdir as mkdir5, open as open4, readdir as readdir7, realpath as realpath12, rename as rename2, rm as rm2, unlink as unlink12 } from "node:fs/promises";
+import { link as link3, lstat as lstat10, mkdir as mkdir5, open as open4, readdir as readdir8, realpath as realpath12, rename as rename2, rm as rm2, unlink as unlink12 } from "node:fs/promises";
 import path48 from "node:path";
 import { parseArgs as parseArgs40 } from "node:util";
 function exportDeps(partial2) {
@@ -129660,7 +129897,7 @@ async function entryKind2(target2) {
     throw error51;
   }
   if (!info.isDirectory()) return "other";
-  return (await readdir7(target2)).length === 0 ? "empty-dir" : "dir";
+  return (await readdir8(target2)).length === 0 ? "empty-dir" : "dir";
 }
 function shown(paths) {
   return [...paths].sort().slice(0, SHOWN);
@@ -129837,7 +130074,7 @@ async function removeAbandonedStaging(target2) {
   let removed = 0;
   let names;
   try {
-    names = await readdir7(path48.dirname(target2));
+    names = await readdir8(path48.dirname(target2));
   } catch {
     return 0;
   }
@@ -130772,20 +131009,20 @@ async function planPublish(folder, options) {
       skipped.push({ path: entry.rel, reason: "not a plain file" });
       continue;
     }
-    const bytes2 = await fs15.readFile(path50.join(folder, entry.rel));
+    const bytes = await fs15.readFile(path50.join(folder, entry.rel));
     if (isReservedFile(entry.rel)) {
-      const text4 = utf83(bytes2);
+      const text4 = utf83(bytes);
       if (text4 === null) {
         blockers.push({ path: entry.rel, reason: "not_utf8", message: `${entry.rel} is a reserved file that is not UTF-8 text` });
         continue;
       }
-      if (bytes2.byteLength > PUBLISH_BOUNDS.reservedBytes) {
+      if (bytes.byteLength > PUBLISH_BOUNDS.reservedBytes) {
         blockers.push({ path: entry.rel, reason: "too_large", message: `${entry.rel} is over the ${PUBLISH_BOUNDS.reservedBytes / 1024} KiB a reserved file may hold` });
         continue;
       }
       const dir = path50.posix.dirname(entry.rel);
       reserved.push({ dir: dir === "." ? "" : dir, name: path50.posix.basename(entry.rel), content: text4 });
-      if (entry.rel !== "index.md") extras[entry.rel] = digest2(bytes2);
+      if (entry.rel !== "index.md") extras[entry.rel] = digest2(bytes);
       continue;
     }
     if (!entry.rel.endsWith(".md")) {
@@ -130795,12 +131032,12 @@ async function planPublish(folder, options) {
         blockers.push({ path: entry.rel, reason: "unsafe_path", message: `${entry.rel} cannot be a file key (${error51.message})` });
         continue;
       }
-      if (bytes2.byteLength > PUBLISH_BOUNDS.blobBytes) {
-        blockers.push({ path: entry.rel, reason: "too_large", message: `${entry.rel} is over the 1 MB a file may hold` });
+      if (bytes.byteLength > STAGED_PUBLISH_BOUNDS.blobBytes) {
+        blockers.push({ path: entry.rel, reason: "too_large", message: `${entry.rel} is over the 16 MiB a file may hold` });
         continue;
       }
-      blobs2.push({ key: entry.rel, contentType: contentTypeOf(entry.rel), base64: bytes2.toString("base64") });
-      extras[entry.rel] = digest2(bytes2);
+      blobs2.push({ key: entry.rel, contentType: contentTypeOf(entry.rel), bytes });
+      extras[entry.rel] = digest2(bytes);
       continue;
     }
     const id = conceptIdFromPath(entry.rel);
@@ -130814,14 +131051,14 @@ async function planPublish(folder, options) {
       blockers.push({ path: entry.rel, reason: "document_id_not_canonical", message: `${entry.rel} is not in its canonical spelling (a segment starts or ends with a space or an invisible format character, holds a format character other than a joiner, or is not NFC); rename it` });
       continue;
     }
-    const refusal = unsendable(id, entry.rel, bytes2, null, { bundleId: "publish", okfVersion });
+    const refusal = unsendable(id, entry.rel, bytes, null, { bundleId: "publish", okfVersion });
     if (refusal) {
       blockers.push({ path: entry.rel, reason: refusal.reason, message: refusal.message });
       continue;
     }
     let request2;
     try {
-      request2 = wholeDocumentRequest("publish", { kind: "document.write", target: id, base: null, content: utf83(bytes2) }, okfVersion);
+      request2 = wholeDocumentRequest("publish", { kind: "document.write", target: id, base: null, content: utf83(bytes) }, okfVersion);
     } catch (error51) {
       if (error51 instanceof WholeDocumentInputError) {
         blockers.push({ path: entry.rel, reason: "not_sendable", message: error51.message });
@@ -130831,7 +131068,7 @@ async function planPublish(folder, options) {
     }
     if (request2.kind === "delete") throw new Error(`'${id}' became a delete request`);
     documents.push({ id, frontmatter: request2.payload.frontmatter, body: request2.payload.body ?? "" });
-    documentFiles.push({ id, rel: entry.rel, text: utf83(bytes2) });
+    documentFiles.push({ id, rel: entry.rel, text: utf83(bytes) });
   }
   if (rootIndex === null) blockers.push({ path: "index.md", reason: "no_root_index", message: "a hosted bundle needs a root index.md" });
   if (edition === "unsupported") {
@@ -130852,9 +131089,7 @@ async function planPublish(folder, options) {
       claimed.set(key, file2);
     }
   }
-  if (documents.length > PUBLISH_BOUNDS.documents) blockers.push({ path: ".", reason: "too_many_documents", message: `${documents.length} documents; a hosted bundle is created with at most ${PUBLISH_BOUNDS.documents}` });
   if (reserved.length > PUBLISH_BOUNDS.reserved) blockers.push({ path: ".", reason: "too_many_reserved", message: `${reserved.length} reserved files; at most ${PUBLISH_BOUNDS.reserved}` });
-  if (blobs2.length > PUBLISH_BOUNDS.blobs) blockers.push({ path: ".", reason: "too_many_files", message: `${blobs2.length} files that are not documents; at most ${PUBLISH_BOUNDS.blobs}` });
   let history = [];
   let historyPlan = { mode: "current-only", versions: 0, skipped: 0, note: "history starts at publish" };
   if (options.history) {
@@ -130873,24 +131108,49 @@ async function planPublish(folder, options) {
         skipped: skippedVersions,
         note: "earlier Git versions are imported as labeled, unverified history (imported:git/<commit>); nothing reads them back yet"
       };
-      if (history.length > PUBLISH_BOUNDS.history || documents.length + reserved.length + blobs2.length + history.length > PUBLISH_BOUNDS.objects) {
-        blockers.push({
-          path: ".",
-          reason: "too_much_history",
-          message: `${history.length} earlier versions: one creation carries at most ${PUBLISH_BOUNDS.history} versions and ${PUBLISH_BOUNDS.objects} objects in all; publish without --with-history`
-        });
-      }
     }
   }
-  if (documents.length + reserved.length + blobs2.length + history.length > PUBLISH_BOUNDS.objects && !blockers.some((b) => b.reason === "too_much_history")) {
-    blockers.push({ path: ".", reason: "too_many_objects", message: `one creation carries at most ${PUBLISH_BOUNDS.objects} documents, reserved files and files in all` });
-  }
-  const plan = { documents, reserved, blobs: blobs2, history, skipped, blockers, historyPlan, extras };
-  const bytes = Buffer.byteLength(JSON.stringify(createBody(plan, { workspace: "w".repeat(64), bundleId: "b".repeat(128), name: "n".repeat(128) })));
-  if (bytes > PUBLISH_BOUNDS.requestBytes) {
-    blockers.push({ path: ".", reason: "request_too_large", message: `the bundle is ${Math.ceil(bytes / 1024)} KiB as one request; the host takes at most ${PUBLISH_BOUNDS.requestBytes / 1024 / 1024} MiB` });
+  const draft = { documents, reserved, blobs: blobs2, history };
+  const sendPath = publishPath(draft);
+  if (sendPath.mode === "staged") blockers.push(...stagedBlockers(draft));
+  return { documents, reserved, blobs: blobs2, history, path: sendPath, skipped, blockers, historyPlan, extras };
+}
+function publishPath(plan) {
+  const bounds = PUBLISH_BOUNDS;
+  const objects = plan.documents.length + plan.reserved.length + plan.blobs.length + plan.history.length;
+  const why = plan.documents.length > bounds.documents ? `${plan.documents.length} documents (one request carries at most ${bounds.documents})` : plan.blobs.length > bounds.blobs ? `${plan.blobs.length} other files (one request carries at most ${bounds.blobs})` : plan.history.length > bounds.history ? `${plan.history.length} earlier versions (one request carries at most ${bounds.history})` : objects > bounds.objects ? `${objects} objects in all (one request carries at most ${bounds.objects})` : plan.blobs.some((blob) => blob.bytes.byteLength > bounds.blobBytes) ? `a file over 1 MB (${plan.blobs.find((blob) => blob.bytes.byteLength > bounds.blobBytes).key})` : null;
+  if (why !== null) return { mode: "staged", why };
+  const base643 = plan.blobs.reduce((sum, blob) => sum + Math.ceil(blob.bytes.byteLength / 3) * 4, 0);
+  const bytes = base643 > bounds.requestBytes ? base643 : Buffer.byteLength(JSON.stringify(createBody(plan, WIDEST_TARGET)));
+  if (bytes > bounds.requestBytes) return { mode: "staged", why: `${Math.ceil(bytes / 1024)} KiB as one request (one request carries at most ${bounds.requestBytes / MiB} MiB)` };
+  return { mode: "one-shot" };
+}
+function stagedBlockers(plan) {
+  const bounds = STAGED_PUBLISH_BOUNDS;
+  const blockers = [];
+  const noHistory = "publish without --with-history, or with fewer earlier versions";
+  if (plan.documents.length > bounds.documents) blockers.push({ path: ".", reason: "too_many_documents", message: `${plan.documents.length} documents; a hosted bundle is created with at most ${bounds.documents}` });
+  if (plan.blobs.length > bounds.blobs) blockers.push({ path: ".", reason: "too_many_files", message: `${plan.blobs.length} files that are not documents; at most ${bounds.blobs}` });
+  if (plan.history.length > bounds.history) blockers.push({ path: ".", reason: "too_much_history", message: `${plan.history.length} earlier versions; a creation carries at most ${bounds.history}: ${noHistory}` });
+  const content3 = stagedContent(plan);
+  const current = distinctBytes([...content3.documents, ...content3.reserved, ...content3.blobs]);
+  if (current > bounds.currentBytes) blockers.push({ path: ".", reason: "too_large", message: `the bundle's current files are ${Math.ceil(current / MiB)} MiB; a creation carries at most ${bounds.currentBytes / MiB} MiB` });
+  const history = distinctBytes(content3.history);
+  if (history > bounds.historyBytes) blockers.push({ path: ".", reason: "too_much_history", message: `the earlier versions are ${Math.ceil(history / MiB)} MiB; a creation carries at most ${bounds.historyBytes / MiB} MiB: ${noHistory}` });
+  const parts = packParts(content3, content3.objects.keys()).length;
+  if (parts > bounds.parts) blockers.push({ path: ".", reason: "too_many_parts", message: `the bundle needs ${parts} parts; a creation holds at most ${bounds.parts}: ${plan.history.length > 0 ? noHistory : "publish fewer files"}` });
+  const manifest = Buffer.byteLength(JSON.stringify(manifestBody(content3, WIDEST_TARGET)));
+  if (manifest > bounds.manifestBytes) {
+    blockers.push({
+      path: ".",
+      reason: "manifest_too_large",
+      message: `the list of everything sent is ${Math.ceil(manifest / 1024)} KiB; the host takes at most ${bounds.manifestBytes / MiB} MiB: ${plan.history.length > 0 ? noHistory : "publish fewer files"}`
+    });
   }
-  return plan;
+  return blockers;
+}
+function distinctBytes(entries) {
+  return [...new Map(entries.map((entry) => [entry.version, entry.bytes])).values()].reduce((sum, bytes) => sum + bytes, 0);
 }
 function createBody(plan, target2) {
   return {
@@ -130899,14 +131159,89 @@ function createBody(plan, target2) {
     name: target2.name,
     documents: plan.documents,
     reserved: plan.reserved,
-    blobs: plan.blobs,
+    blobs: plan.blobs.map((blob) => ({ key: blob.key, contentType: blob.contentType, base64: blob.bytes.toString("base64") })),
     ...plan.history.length > 0 ? { history: plan.history } : {}
   };
 }
 function planDigest(body) {
   return digest2(Buffer.from(JSON.stringify(body), "utf8"));
 }
-var PUBLISH_BOUNDS, CONTENT_TYPES, HOSTED_KIND_WRITE, FORMAT_AT_EDGE, FORMAT_INSIDE;
+function stagedContent(plan) {
+  const wire = (object5) => ({ ...object5, frontmatter: JSON.parse(JSON.stringify(object5.frontmatter)) });
+  const objects = /* @__PURE__ */ new Map();
+  const keep = (version3, object5) => {
+    if (!objects.has(version3)) objects.set(version3, object5);
+  };
+  const stored = (text4) => ({ version: versionOfBytes(text4), bytes: Buffer.byteLength(text4, "utf8") });
+  const conventions = [];
+  const documents = plan.documents.map((sent) => {
+    const doc2 = wire(sent);
+    const text4 = stringifyDoc(doc2.frontmatter, doc2.body);
+    const entry = stored(text4);
+    keep(entry.version, { kind: "documents", value: doc2 });
+    if (matchesFilter({ id: doc2.id, frontmatter: parseMarkdown(text4, doc2.id).frontmatter }, { prefix: CONVENTIONS_PREFIX, type: CONVENTION_TYPE })) conventions.push(doc2);
+    return { id: doc2.id, ...entry };
+  });
+  const reserved = plan.reserved.map((file2) => {
+    const entry = stored(file2.content);
+    keep(entry.version, { kind: "reserved", value: file2 });
+    return { dir: file2.dir, name: file2.name, ...entry };
+  });
+  const ordinals = /* @__PURE__ */ new Map();
+  const history = plan.history.map((sent) => {
+    const row3 = wire(sent);
+    const ordinal = (ordinals.get(row3.documentId) ?? 0) + 1;
+    ordinals.set(row3.documentId, ordinal);
+    const entry = stored(stringifyDoc(row3.frontmatter, row3.body));
+    keep(entry.version, { kind: "history", value: { ...row3, ordinal } });
+    return { documentId: row3.documentId, ordinal, label: row3.label, author: row3.author, authoredAt: row3.authoredAt, ...entry };
+  });
+  const blobBytes = /* @__PURE__ */ new Map();
+  const blobs2 = plan.blobs.map((blob) => {
+    const version3 = blobVersion(blob.bytes);
+    if (!blobBytes.has(version3)) blobBytes.set(version3, { key: blob.key, bytes: blob.bytes });
+    return { key: blob.key, contentType: blob.contentType, version: version3, bytes: blob.bytes.byteLength };
+  });
+  const root = plan.reserved.find((file2) => file2.dir === "" && file2.name === "index.md")?.content ?? "";
+  return { root, conventions, documents, reserved, blobs: blobs2, history, objects, blobBytes };
+}
+function manifestBody(content3, target2) {
+  return {
+    workspace: target2.workspace,
+    bundleId: target2.bundleId,
+    name: target2.name,
+    root: content3.root,
+    conventions: content3.conventions,
+    documents: content3.documents,
+    reserved: content3.reserved,
+    blobs: content3.blobs,
+    history: content3.history
+  };
+}
+function packParts(content3, versions) {
+  const bounds = STAGED_PUBLISH_BOUNDS;
+  const parts = [];
+  let part = null;
+  let size = 0;
+  const envelope = 512;
+  for (const version3 of new Set(versions)) {
+    const object5 = content3.objects.get(version3);
+    if (!object5) continue;
+    const bytes = Buffer.byteLength(JSON.stringify(object5.value)) + 1;
+    if (part === null || part.versions.length >= bounds.partObjects || size + bytes > bounds.partTargetBytes) {
+      part = { documents: [], reserved: [], history: [], versions: [] };
+      parts.push(part);
+      size = envelope;
+    }
+    if (object5.kind === "documents") part.documents.push(object5.value);
+    else if (object5.kind === "reserved") part.reserved.push(object5.value);
+    else part.history.push(object5.value);
+    part.versions.push(version3);
+    size += bytes;
+  }
+  return parts;
+}
+var MiB, PUBLISH_BOUNDS, STAGED_PUBLISH_BOUNDS, CONTENT_TYPES, HOSTED_KIND_WRITE, FORMAT_AT_EDGE, FORMAT_INSIDE, WIDEST_TARGET;
 var init_publish_plan = __esm({
   "../cli/src/hosted/publish-plan.ts"() {
     "use strict";
@@ -130915,9 +131250,11 @@ var init_publish_plan = __esm({
     init_src2();
     init_src();
     init_hosted_transport();
+    init_versioning();
     init_projection();
     init_sync_scan();
     init_src();
+    MiB = 1024 * 1024;
     PUBLISH_BOUNDS = Object.freeze({
       objects: 1500,
       documents: 1e3,
@@ -130926,7 +131263,22 @@ var init_publish_plan = __esm({
       history: 1e3,
       reservedBytes: 64 * 1024,
       blobBytes: 1e6,
-      requestBytes: 3 * 1024 * 1024
+      requestBytes: 3 * MiB
+    });
+    STAGED_PUBLISH_BOUNDS = Object.freeze({
+      documents: 1e4,
+      reserved: 1e3,
+      blobs: 1e3,
+      history: 5e3,
+      blobBytes: 16 * MiB,
+      currentBytes: 64 * MiB,
+      historyBytes: 64 * MiB,
+      manifestBytes: 3 * MiB,
+      /** The host's cap on one part's body; parts are packed to {@link partTargetBytes}. */
+      partBytes: 3 * MiB,
+      partTargetBytes: 1 * MiB,
+      partObjects: 500,
+      parts: 400
     });
     CONTENT_TYPES = {
       ".txt": "text/plain",
@@ -130951,6 +131303,246 @@ var init_publish_plan = __esm({
     HOSTED_KIND_WRITE = Object.freeze({ strict: true, persistActor: true, producer: "process:superbee-hosted" });
     FORMAT_AT_EDGE = new RegExp("^\\p{Cf}|\\p{Cf}$", "u");
     FORMAT_INSIDE = new RegExp("(?![\\u200c\\u200d])\\p{Cf}", "u");
+    WIDEST_TARGET = Object.freeze({ workspace: "w".repeat(64), bundleId: "b".repeat(128), name: "n".repeat(128) });
+  }
+});
+
+// ../cli/src/hosted/publish-staged.ts
+function isFinalBeforeReservation(refusal) {
+  return !refusal.reserved && refusal.route === "bundle-create-begin" && ["bundle_exists", "document_id_collision", "document_id_not_canonical", "validation_failed", "result_too_large"].includes(refusal.code);
+}
+async function runStagedCreate(request2) {
+  const { client, requestId: requestId2, target: target2, content: content3 } = request2;
+  const sleep = request2.sleep ?? ((ms) => new Promise((resolve2) => setTimeout(resolve2, ms)));
+  const progress = request2.progress ?? (() => {
+  });
+  const route = (name) => `${client.prefix}/${name}`;
+  let reserved = false;
+  let planHash = "";
+  let requests = 0;
+  let bytesSent = 0;
+  const objects = content3.objects.size + content3.blobBytes.size;
+  const contentBytes = [...content3.objects.values()].reduce((sum, object5) => sum + Buffer.byteLength(JSON.stringify(object5.value)), 0) + [...content3.blobBytes.values()].reduce((sum, blob) => sum + blob.bytes.byteLength, 0);
+  const maximumRequests = REQUEST_ALLOWANCE + REQUESTS_PER_OBJECT * objects;
+  const maximumBytes = BYTES_ALLOWANCE + BYTES_PER_CONTENT_BYTE * contentBytes;
+  const unknownOutcome = (why) => new CliError("TRANSIENT", `${why}; the bundle may be partly created`, {
+    details: { reason: "write_outcome_unknown", bundle_id: target2.bundleId, workspace: target2.workspace, host: client.target.origin, request_id: requestId2, retryable: true },
+    help: `re-run the same command; it resumes the same creation, sending only what the host is missing: ${request2.resume}`
+  });
+  async function send(name, body, headers) {
+    for (let attempt = 0; ; attempt++) {
+      requests += 1;
+      bytesSent += body instanceof Uint8Array ? body.byteLength : 0;
+      if (requests > maximumRequests || bytesSent > maximumBytes) {
+        throw unknownOutcome(`${client.target.origin} did not finish the creation within ${maximumRequests} requests and ${Math.ceil(maximumBytes / (1024 * 1024))} MiB sent`);
+      }
+      let answer2;
+      try {
+        if (body instanceof Uint8Array) {
+          if (!client.carrier.bytes) throw new CliError("RUNTIME", "this client cannot send a file's raw bytes");
+          answer2 = await client.carrier.bytes(route(name), body, client.signal, { maximum: ANSWER_BYTES, writeRequest: requestId2, ...headers ? { headers } : {} });
+        } else {
+          answer2 = await client.carrier.json(route(name), body, client.signal, { maximum: ANSWER_BYTES, writeRequest: requestId2 });
+        }
+      } catch (error51) {
+        if (error51 instanceof HostedCarrierError && error51.code === "unavailable") throw unknownOutcome(`the answer from ${client.target.origin} to ${name} did not arrive`);
+        throw hostedFailure(error51, client.target, request2.resume);
+      }
+      if (answer2.status !== 503) return answer2;
+      const delay3 = RETRY_DELAYS_MS[attempt];
+      if (delay3 === void 0) throw unknownOutcome(`${client.target.origin} kept answering ${name} 503`);
+      await sleep(delay3);
+    }
+  }
+  function read(name, answer2) {
+    const envelope = answer2.body ?? {};
+    const code3 = typeof envelope.error?.code === "string" ? envelope.error.code : null;
+    const message = typeof envelope.error?.message === "string" ? envelope.error.message : "";
+    if (answer2.status === 200 && envelope.ok === true && typeof envelope.data === "object" && envelope.data !== null) return envelope.data;
+    if (answer2.status === 200 && envelope.ok === false && code3 === "staged_manifest_missing") return "no_manifest";
+    if (answer2.status === 200 && envelope.ok === false && code3 === "request_conflict" && envelope.error?.retryable === true) return "busy";
+    if (answer2.status === 200 && envelope.ok === false && code3 === "validation_failed" && VERSION_MISMATCH.test(message)) {
+      throw new CliError("RUNTIME", `${client.target.origin} stores an object differently from this CLI (client/host contract mismatch)`, {
+        details: { reason: "staged_mismatch", route: name, host_message: message, host: client.target.origin, request_id: requestId2, retryable: false },
+        help: `upgrade Superbee (npm install -g superbee), then re-run the same command, which resumes this creation: ${request2.resume}`
+      });
+    }
+    if (answer2.status === 200 && envelope.ok === false && code3 !== null) throw new StagedRefusal(code3, message, reserved, name);
+    if (answer2.status === 429 && code3 === "bundle_create_limit") throw new StagedRefusal(code3, message, reserved, name);
+    if (answer2.status === 400 && !reserved) throw new StagedRefusal(code3 ?? "invalid_input", message || `the host refused ${name} as malformed`, false, name);
+    throw hostedFailure(new RemoteError(`hosted ${name} answered ${answer2.status}`, code3 ?? "RUNTIME", answer2.status), client.target, request2.resume);
+  }
+  async function status2(name, data) {
+    const missing2 = data.missing;
+    const staged = data.staged;
+    if (data.state !== "staging" && data.state !== "importing" && data.state !== "created" || typeof data.planHash !== "string" || !VERSION.test(data.planHash) || !isStringList(missing2?.versions) || !isStringList(missing2?.blobs) || typeof staged?.versions !== "number" || typeof staged.blobVersions !== "number") {
+      throw hostedFailure(new MalformedAnswer(`not a staged creation's status`, route(name)), client.target, request2.resume);
+    }
+    const answer2 = data;
+    planHash = answer2.planHash;
+    if (answer2.state !== "staging" && !reserved) {
+      reserved = true;
+      await request2.onReserved?.();
+    }
+    return answer2;
+  }
+  const manifest = manifestBody(content3, target2);
+  async function begin() {
+    let data = read("bundle-create-begin", await send("bundle-create-begin", manifest));
+    for (let retry = 0; data === "busy"; retry++) {
+      if (retry >= CONFLICT_RETRIES) {
+        throw new CliError("TRANSIENT", `an earlier commit of this creation may still be running on ${client.target.origin}`, {
+          details: { reason: "commit_running", bundle_id: target2.bundleId, workspace: target2.workspace, host: client.target.origin, request_id: requestId2, retryable: true },
+          help: `re-run the same command in a minute: ${request2.resume}`
+        });
+      }
+      progress({ phase: "wait", seconds: CONFLICT_RETRY_MS / 1e3, reason: "an earlier commit of this creation may still be running" });
+      await sleep(CONFLICT_RETRY_MS);
+      data = read("bundle-create-begin", await send("bundle-create-begin", manifest));
+    }
+    if (data === "no_manifest") throw hostedFailure(new MalformedAnswer("begin answered that no manifest is staged", route("bundle-create-begin")), client.target, request2.resume);
+    const answer2 = await status2("bundle-create-begin", data);
+    progress({ phase: "begin", state: answer2.state, versions: content3.objects.size, staged: answer2.staged.versions, blobs: content3.blobBytes.size, stagedBlobs: answer2.staged.blobVersions });
+    return answer2;
+  }
+  async function fill(from) {
+    const unknown3 = [...from.missing.versions.filter((v2) => !content3.objects.has(v2)), ...from.missing.blobs.filter((v2) => !content3.blobBytes.has(v2))];
+    if (unknown3.length > 0) {
+      throw new CliError("RUNTIME", `${client.target.origin} asks for ${unknown3.length} object(s) this folder does not hold (client/host contract mismatch)`, {
+        details: { reason: "staged_mismatch", versions: unknown3.slice(0, 5), host: client.target.origin, request_id: requestId2, retryable: false },
+        help: "upgrade Superbee (npm install -g superbee), then re-run the same command"
+      });
+    }
+    const blobs2 = from.missing.blobs;
+    let next = 0;
+    let gone = false;
+    const upload = async () => {
+      try {
+        await uploadEach();
+      } catch (error51) {
+        gone = true;
+        throw error51;
+      }
+    };
+    const uploadEach = async () => {
+      for (let at = next++; at < blobs2.length && !gone; at = next++) {
+        const version3 = blobs2[at];
+        const blob = content3.blobBytes.get(version3);
+        const data = read(
+          "bundle-create-blob",
+          await send("bundle-create-blob", blob.bytes, {
+            "X-Superbee-Workspace": target2.workspace,
+            "X-Superbee-Bundle": target2.bundleId,
+            "X-Superbee-Blob-Version": version3,
+            "X-Superbee-Plan-Hash": planHash
+          })
+        );
+        if (data === "no_manifest" || data === "busy") {
+          gone = true;
+          return;
+        }
+        progress({ phase: "blob", blob: at + 1, blobs: blobs2.length, key: blob.key, bytes: blob.bytes.byteLength });
+      }
+    };
+    let failure3 = null;
+    const settled = await Promise.allSettled(Array.from({ length: Math.min(BLOBS_IN_FLIGHT, blobs2.length) }, upload));
+    for (const result3 of settled) if (result3.status === "rejected" && failure3 === null) failure3 = result3.reason;
+    if (failure3 !== null) throw failure3;
+    if (gone) return "no_manifest";
+    const parts = packParts(content3, from.missing.versions);
+    let last = null;
+    for (const [index2, part] of parts.entries()) {
+      const data = read(
+        "bundle-create-stage",
+        await send("bundle-create-stage", { workspace: target2.workspace, bundleId: target2.bundleId, planHash, documents: part.documents, reserved: part.reserved, history: part.history })
+      );
+      if (data === "no_manifest" || data === "busy") return "no_manifest";
+      last = await status2("bundle-create-stage", data);
+      progress({ phase: "stage", part: index2 + 1, parts: parts.length, objects: part.versions.length });
+    }
+    return blobs2.length > 0 ? null : last;
+  }
+  const outstanding = (s) => s.missing.versions.length + s.missing.blobs.length;
+  const missingKey = (s) => `${outstanding(s)}:${s.missing.versions[0] ?? ""}:${s.missing.blobs[0] ?? ""}`;
+  let current = await begin();
+  let lastFilled = null;
+  let stalls = 0;
+  let commits = 0;
+  for (; ; ) {
+    if (current !== null && current.state !== "created" && outstanding(current) > 0) {
+      const key = missingKey(current);
+      stalls = key === lastFilled ? stalls + 1 : 0;
+      if (stalls >= MAXIMUM_STALLS) {
+        throw new CliError("RUNTIME", `${client.target.origin} keeps naming the same objects as missing after they were sent ${MAXIMUM_STALLS} times`, {
+          details: { reason: "staged_stall", missing: { versions: current.missing.versions.slice(0, 5), blobs: current.missing.blobs.slice(0, 5) }, host: client.target.origin, request_id: requestId2, retryable: true },
+          help: `re-run the same command later; it resumes this creation: ${request2.resume}`
+        });
+      }
+      lastFilled = key;
+      const after = await fill(current);
+      if (after === "no_manifest") {
+        current = await begin();
+        continue;
+      }
+      if (after !== null && outstanding(after) > 0) {
+        current = after;
+        continue;
+      }
+    }
+    commits += 1;
+    const answer2 = await send("bundle-create-commit", { workspace: target2.workspace, bundleId: target2.bundleId, planHash });
+    const data = read("bundle-create-commit", answer2);
+    if (data === "no_manifest" || data === "busy") {
+      current = await begin();
+      continue;
+    }
+    if (typeof data.state !== "string") {
+      return data;
+    }
+    current = await status2("bundle-create-commit", data);
+    progress({ phase: "commit", call: commits, state: current.state, ...current.written ? { written: current.written } : {} });
+  }
+}
+var STAGED_CREATE_ROUTES, ANSWER_BYTES, BLOBS_IN_FLIGHT, RETRY_DELAYS_MS, REQUEST_ALLOWANCE, REQUESTS_PER_OBJECT, BYTES_PER_CONTENT_BYTE, BYTES_ALLOWANCE, MAXIMUM_STALLS, CONFLICT_RETRY_MS, CONFLICT_RETRIES, StagedRefusal, VERSION_MISMATCH, VERSION, isStringList;
+var init_publish_staged = __esm({
+  "../cli/src/hosted/publish-staged.ts"() {
+    "use strict";
+    init_define_SUPERBEE_BUILD_IDENTITY();
+    init_define_SUPERBEE_UPDATE_POLICY();
+    init_src();
+    init_hosted_transport();
+    init_errors4();
+    init_client();
+    init_publish_plan();
+    STAGED_CREATE_ROUTES = Object.freeze(["bundle-create-begin", "bundle-create-stage", "bundle-create-blob", "bundle-create-commit"]);
+    ANSWER_BYTES = 256 * 1024;
+    BLOBS_IN_FLIGHT = 2;
+    RETRY_DELAYS_MS = Object.freeze([500, 1e3, 2e3, 4e3]);
+    REQUEST_ALLOWANCE = 2e3;
+    REQUESTS_PER_OBJECT = 4;
+    BYTES_PER_CONTENT_BYTE = 3;
+    BYTES_ALLOWANCE = 64 * 1024 * 1024;
+    MAXIMUM_STALLS = 3;
+    CONFLICT_RETRY_MS = 6e4;
+    CONFLICT_RETRIES = 5;
+    StagedRefusal = class extends Error {
+      code;
+      hostMessage;
+      /** True when the creation was reserved: the request id must be kept to finish it. */
+      reserved;
+      /** The route that answered it. */
+      route;
+      constructor(code3, hostMessage, reserved, route) {
+        super(`${code3}: ${hostMessage}`);
+        this.code = code3;
+        this.hostMessage = hostMessage;
+        this.reserved = reserved;
+        this.route = route;
+      }
+    };
+    VERSION_MISMATCH = /version or size is not the manifest's/i;
+    VERSION = /^sha256:[0-9a-f]{64}$/;
+    isStringList = (value) => Array.isArray(value) && value.every((item) => typeof item === "string");
   }
 });
 
@@ -130963,6 +131555,8 @@ import { parseArgs as parseArgs42 } from "node:util";
 function publishDeps(partial2) {
   return {
     stdout: partial2.stdout ?? ((text4) => void process.stdout.write(text4)),
+    stderr: partial2.stderr ?? ((text4) => void process.stderr.write(text4)),
+    ...partial2.sleep ? { sleep: partial2.sleep } : {},
     auth: partial2.auth ?? defaultHostedAuthDeps(homedir40()),
     cwd: partial2.cwd ?? process.cwd(),
     ...partial2.fetch ? { fetch: partial2.fetch } : {}
@@ -131058,6 +131652,7 @@ function summary(plan) {
     documents: plan.documents.length,
     reserved_files: plan.reserved.length,
     other_files: plan.blobs.length,
+    sent: plan.path.mode === "one-shot" ? "one request" : `staged: ${plan.path.why}; a list of everything, parts of about 1 MiB, each file, then commits until created (resumable)`,
     history: { mode: plan.historyPlan.mode, versions: plan.historyPlan.versions, ...plan.historyPlan.skipped > 0 ? { skipped: plan.historyPlan.skipped } : {}, note: plan.historyPlan.note }
   };
 }
@@ -131069,11 +131664,17 @@ function createRefusal(code3, message, context) {
     case "workspace_not_found":
       return new CliError("NOT_FOUND", `'${context.workspace}' is not one of your workspaces on ${context.target.origin}`, { details, help: `${cliInvocation()} whoami --host ${commandToken(bindingHostArgument(context.target))}` });
     case "bundle_create_unavailable":
-    case "bundle_create_limit":
-      return new CliError("FORBIDDEN", code3 === "bundle_create_limit" ? `your bundle creation limit in ${context.workspace} is used up` : `${context.workspace} does not offer bundle creation to this client`, {
-        details,
-        help: "ask a workspace admin in the Superbee app"
-      });
+    case "bundle_create_limit": {
+      const open5 = code3 === "bundle_create_limit" && /staged creations open/i.test(message);
+      return new CliError(
+        "FORBIDDEN",
+        open5 ? `you have too many unfinished large publishes open in ${context.workspace}` : code3 === "bundle_create_limit" ? `your bundle creation limit in ${context.workspace} is used up` : `${context.workspace} does not offer bundle creation to this client`,
+        {
+          details: open5 && context.openCreations ? { ...details, open: context.openCreations.map((record5) => ({ bundle_id: record5.bundle_id, ...record5.folder ? { folder: record5.folder } : {} })) } : details,
+          help: open5 ? `finish one by re-running its publish${context.openCreations && context.openCreations.length > 0 ? ` (unfinished from here: ${context.openCreations.map((record5) => `'${record5.bundle_id}'${record5.folder ? ` from ${record5.folder}` : ""}`).join(", ")})` : ""}, or wait for one to expire 7 days after it began` : "ask a workspace admin in the Superbee app"
+        }
+      );
+    }
     case "request_conflict":
       return new CliError("CONFLICT", `an unfinished publish of '${context.bundleId}' from this folder carried other contents, and the host holds the id for it`, {
         details,
@@ -131083,6 +131684,103 @@ function createRefusal(code3, message, context) {
       return new CliError("USAGE", `${context.target.origin} refused the bundle (${code3}): ${message}`, { details, help: "fix the files it names, then preview again" });
   }
 }
+function progressLine(event, json2) {
+  if (json2) return `${JSON.stringify({ event: "publish.progress", ...event })}
+`;
+  const mib = (bytes) => `${(bytes / (1024 * 1024)).toFixed(1)} MiB`;
+  switch (event.phase) {
+    case "begin":
+      return `publish: ${event.state}: ${event.staged}/${event.versions} objects and ${event.stagedBlobs}/${event.blobs} files on the host
+`;
+    case "stage":
+      return `publish: sent part ${event.part}/${event.parts} (${event.objects} objects)
+`;
+    case "blob":
+      return `publish: sent file ${event.blob}/${event.blobs} ${event.key} (${mib(event.bytes)})
+`;
+    case "commit":
+      return `publish: commit ${event.call}: ${event.state}${event.written ? ` (written: ${Object.entries(event.written).map(([kind2, count5]) => `${count5} ${kind2}`).join(", ")})` : ""}
+`;
+    case "wait":
+      return `publish: waiting ${event.seconds} s: ${event.reason}
+`;
+  }
+}
+async function sendCreation(plan, context) {
+  const { workspace, bundleId, name, home: home2, canonical: canonical2, target: target2, client, yesCommand } = context;
+  const staged = plan.path.mode === "staged" ? stagedContent(plan) : null;
+  const body = staged ? manifestBody(staged, { workspace, bundleId, name }) : createBody(plan, { workspace, bundleId, name });
+  const digest3 = planDigest(body);
+  const earlier = await readPendingCreate(home2, canonical2, bundleId);
+  const resumes = earlier !== null && earlier.host === target2.origin && earlier.workspace === workspace;
+  const requestId2 = resumes ? earlier.request_id : randomUUID6();
+  const record5 = resumes ? { ...earlier, ...staged ? { staged: true, folder: canonical2 } : {} } : { request_id: requestId2, host: target2.origin, workspace, bundle_id: bundleId, digest: digest3, ...staged ? { staged: true, folder: canonical2 } : {} };
+  if (!resumes || staged && earlier.staged !== true) await writePendingCreate(home2, canonical2, record5);
+  const refusalContext = { bundleId, workspace, target: target2, resume: yesCommand, folder: canonical2 };
+  if (staged) {
+    let data;
+    try {
+      data = await runStagedCreate({
+        client,
+        requestId: requestId2,
+        target: { workspace, bundleId, name },
+        content: staged,
+        resume: String(yesCommand),
+        progress: (event) => context.deps.stderr(progressLine(event, context.json)),
+        ...context.deps.sleep ? { sleep: context.deps.sleep } : {},
+        // Once the host holds the id for this request, only this request id can finish it.
+        onReserved: async () => {
+          if (record5.reserved !== true) await writePendingCreate(home2, canonical2, { ...record5, reserved: true });
+        }
+      });
+    } catch (error51) {
+      if (error51 instanceof StagedRefusal) {
+        if (record5.reserved !== true && isFinalBeforeReservation(error51)) await clearPendingCreate(home2, canonical2, bundleId);
+        const openCreations = error51.code === "bundle_create_limit" ? (await listPendingCreates(home2)).filter((other) => other.staged === true && other.host === target2.origin && other.workspace === workspace && other.request_id !== requestId2) : void 0;
+        throw createRefusal(error51.code, error51.hostMessage, { ...refusalContext, ...openCreations ? { openCreations } : {} });
+      }
+      throw error51;
+    }
+    await clearPendingCreate(home2, canonical2, bundleId);
+    return data;
+  }
+  let answer2;
+  try {
+    answer2 = await client.carrier.json(`${client.prefix}/bundle-create`, body, client.signal, { maximum: CREATE_ANSWER_BYTES, writeRequest: requestId2 });
+  } catch (error51) {
+    if (error51 instanceof HostedCarrierError && error51.code === "unavailable") {
+      throw new CliError("TRANSIENT", `the answer from ${target2.origin} did not arrive; the bundle may be partly created`, {
+        details: { reason: "write_outcome_unknown", bundle_id: bundleId, workspace, host: target2.origin, request_id: requestId2, retryable: true },
+        help: `re-run the same command; it re-sends the same request, which finishes or confirms the creation: ${yesCommand}`
+      });
+    }
+    throw hostedFailure(error51, target2, yesCommand);
+  }
+  const envelope = answer2.body ?? {};
+  const code3 = typeof envelope.error?.code === "string" ? envelope.error.code : null;
+  const hostMessage = typeof envelope.error?.message === "string" ? envelope.error.message : "";
+  if (answer2.status === 503 && code3 === "write_outcome_unknown") {
+    throw new CliError("TRANSIENT", `${target2.origin} may have partly created '${bundleId}'`, {
+      details: { reason: "write_outcome_unknown", bundle_id: bundleId, workspace, host: target2.origin, request_id: requestId2, retryable: true },
+      help: `re-run the same command; it re-sends the same request, which finishes or confirms the creation: ${yesCommand}`
+    });
+  }
+  const forgettable = record5.reserved !== true;
+  if (answer2.status === 429 && code3 === "bundle_create_limit") {
+    if (forgettable) await clearPendingCreate(home2, canonical2, bundleId);
+    throw createRefusal(code3, hostMessage, refusalContext);
+  }
+  if (answer2.status === 200 && envelope.ok === false && code3 !== null) {
+    if (code3 !== "request_conflict" && forgettable) await clearPendingCreate(home2, canonical2, bundleId);
+    throw createRefusal(code3, hostMessage, refusalContext);
+  }
+  if (answer2.status !== 200 || envelope.ok !== true || typeof envelope.data !== "object" || envelope.data === null) {
+    if (answer2.status === 400 && forgettable) await clearPendingCreate(home2, canonical2, bundleId);
+    throw hostedFailure(new RemoteError(`hosted bundle-create answered ${answer2.status}`, code3 ?? "RUNTIME", answer2.status), target2, yesCommand);
+  }
+  await clearPendingCreate(home2, canonical2, bundleId);
+  return envelope.data;
+}
 async function publish(argv2, partial2 = {}) {
   const deps = publishDeps(partial2);
   const { values } = parseLeafOrUsage(
@@ -131138,13 +131836,15 @@ async function publish(argv2, partial2 = {}) {
   const withHistory = values["with-history"] === true;
   const plan = await planPublish(canonical2, withHistory ? { history: true, ...board ? { board } : {}, now: deps.auth.now() } : { history: false });
   const yesCommand = commandFragment`${cliInvocation()} publish --to hosted${values.dir !== void 0 ? commandFragment` --dir ${commandToken(canonical2)}` : commandFragment``}${target2 ? commandFragment` --host ${commandToken(bindingHostArgument(target2))}` : commandFragment``}${values.workspace !== void 0 ? commandFragment` --workspace ${commandToken(values.workspace)}` : commandFragment``} --bundle-id ${commandToken(bundleId)}${values.name !== void 0 ? commandFragment` --name ${commandToken(name)}` : commandFragment``}${withHistory ? commandFragment` --with-history` : commandFragment``} --yes${values.json ? commandFragment` --json` : commandFragment``}`;
+  const converts = plan.documents.length <= CHECKOUT_DOCUMENT_LIMIT;
+  const uncheckable = `leave this folder as it is${board ? " (still bound to the Git board)" : ""}: a hosted checkout holds at most ${CHECKOUT_DOCUMENT_LIMIT} documents, so use the bundle in the app; from then on, edits here do not reach the hosted bundle, nor its edits here`;
   const gitPlan = board ? {
     branch: board.branch,
     upstream: board.upstream,
     head: boardHead(board),
     sync: boardState?.block.state,
     ...boardState && (boardState.block.ahead ?? 0) + (boardState.block.uncommitted ?? 0) > 0 ? { not_on_branch: { ahead: boardState.block.ahead, uncommitted: boardState.block.uncommitted, note: "these travel to hosted but not to the board branch teammates still sync" } } : {},
-    will: "unbind this folder from the board branch; the branch and its commits stay, locally and on origin"
+    will: converts ? "unbind this folder from the board branch; the branch and its commits stay, locally and on origin" : "keep this folder bound to the board branch: the board and the hosted bundle then diverge, and neither's edits reach the other"
   } : null;
   if (!values.yes) {
     const blockers = [...plan.blockers.map((b) => ({ path: b.path, reason: b.reason, message: b.message })), ...boardState?.blocker ? [boardState.blocker] : []];
@@ -131168,8 +131868,10 @@ async function publish(argv2, partial2 = {}) {
           ...gitPlan ? { git: gitPlan } : {},
           then: [
             "create the bundle in your workspace, reachable only by you (write) until you share it in the app",
-            "convert this folder in place into a hosted checkout: no file rewritten, a read-only .superbee/checkout.json added",
-            ...board ? ["unbind the Git board first; teammates keep the board branch until you tell them"] : []
+            ...converts ? [
+              "convert this folder in place into a hosted checkout: no file rewritten, a read-only .superbee/checkout.json added",
+              ...board ? ["unbind the Git board first; teammates keep the board branch until you tell them"] : []
+            ] : [uncheckable]
           ],
           network: "none (preview)",
           help: blockers.length === 0 ? [String(yesCommand)] : !target2 ? [`${cliInvocation()} login --host <url>`] : ["fix the blocking files, then preview again"]
@@ -131206,48 +131908,34 @@ async function publish(argv2, partial2 = {}) {
       help: otherWorkspace
     });
   }
-  const body = createBody(plan, { workspace, bundleId, name });
-  const digest3 = planDigest(body);
-  const earlier = await readPendingCreate(home2, canonical2, bundleId);
-  const resumes = earlier !== null && earlier.host === target2.origin && earlier.workspace === workspace;
-  const requestId2 = resumes ? earlier.request_id : randomUUID6();
-  if (!resumes) await writePendingCreate(home2, canonical2, { request_id: requestId2, host: target2.origin, workspace, bundle_id: bundleId, digest: digest3 });
-  const context = { bundleId, workspace, target: target2, resume: yesCommand, folder: canonical2 };
-  let answer2;
-  try {
-    answer2 = await client.carrier.json(`${client.prefix}/bundle-create`, body, client.signal, { maximum: CREATE_ANSWER_BYTES, writeRequest: requestId2 });
-  } catch (error51) {
-    if (error51 instanceof HostedCarrierError && error51.code === "unavailable") {
-      throw new CliError("TRANSIENT", `the answer from ${target2.origin} did not arrive; the bundle may be partly created`, {
-        details: { reason: "write_outcome_unknown", bundle_id: bundleId, workspace, host: target2.origin, request_id: requestId2, retryable: true },
-        help: `re-run the same command; it re-sends the same request, which finishes or confirms the creation: ${yesCommand}`
-      });
-    }
-    throw hostedFailure(error51, target2, yesCommand);
-  }
-  const envelope = answer2.body ?? {};
-  const code3 = typeof envelope.error?.code === "string" ? envelope.error.code : null;
-  const hostMessage = typeof envelope.error?.message === "string" ? envelope.error.message : "";
-  if (answer2.status === 503 && code3 === "write_outcome_unknown") {
-    throw new CliError("TRANSIENT", `${target2.origin} may have partly created '${bundleId}'`, {
-      details: { reason: "write_outcome_unknown", bundle_id: bundleId, workspace, host: target2.origin, request_id: requestId2, retryable: true },
-      help: `re-run the same command; it re-sends the same request, which finishes or confirms the creation: ${yesCommand}`
-    });
-  }
-  if (answer2.status === 429 && code3 === "bundle_create_limit") {
-    await clearPendingCreate(home2, canonical2, bundleId);
-    throw createRefusal(code3, hostMessage, context);
-  }
-  if (answer2.status === 200 && envelope.ok === false && code3 !== null) {
-    if (code3 !== "request_conflict") await clearPendingCreate(home2, canonical2, bundleId);
-    throw createRefusal(code3, hostMessage, context);
-  }
-  if (answer2.status !== 200 || envelope.ok !== true || typeof envelope.data !== "object" || envelope.data === null) {
-    if (answer2.status === 400) await clearPendingCreate(home2, canonical2, bundleId);
-    throw hostedFailure(new RemoteError(`hosted bundle-create answered ${answer2.status}`, code3 ?? "RUNTIME", answer2.status), target2, yesCommand);
+  const created = await sendCreation(plan, { workspace, bundleId, name, home: home2, canonical: canonical2, target: target2, client, yesCommand, deps, json: values.json === true });
+  if (!converts) {
+    deps.stdout(
+      render(
+        {
+          published: "created",
+          bundle_id: bundleId,
+          name,
+          host: target2.origin,
+          workspace,
+          access: "write (only you, until you share it in the app)",
+          sent: {
+            documents: created.documents ?? plan.documents.length,
+            reserved_files: created.reserved ?? plan.reserved.length,
+            other_files: created.blobs ?? plan.blobs.length,
+            history: created.history ?? { imported: plan.history.length, verified: false }
+          },
+          folder: canonical2,
+          home: facts.home,
+          checkout: `not converted: ${uncheckable}`,
+          diverges: `this folder${board ? " and its Git board" : ""} and the hosted bundle '${bundleId}' are now separate copies: edits here do not reach the hosted bundle`,
+          help: [hostedListCommand(target2)]
+        },
+        mode
+      )
+    );
+    return;
   }
-  await clearPendingCreate(home2, canonical2, bundleId);
-  const created = envelope.data;
   await writePublishedExtras(home2, canonical2, { host: target2.origin, bundle_id: bundleId, extras: plan.extras }).catch(() => {
   });
   const slug = identity.workspaces.find((w2) => w2.tenantId === workspace)?.slug ?? null;
@@ -131348,6 +132036,7 @@ var init_publish = __esm({
     init_account();
     init_marker();
     init_publish_plan();
+    init_publish_staged();
     init_publish_state();
     init_invocation();
     init_output2();
@@ -131361,9 +132050,16 @@ Usage:
                    [--bundle-id <id>] [--name <name>] [--with-history] [--yes] [--json]
 
 Without --yes, previews only, with no network: what travels (documents, reserved files, other
-files), what stays (dot-files, links), every bound the host enforces (at most 1,000 documents,
-100 other files, 1,500 objects in all, 3 MiB in one request; 64 KiB per document, 16 KiB of
-frontmatter), the history plan, and what will happen to the folder.
+files), what stays (dot-files, links), how it is sent, every bound the host enforces, the history
+plan, and what will happen to the folder.
+
+A bundle within one request's bounds (at most 1,000 documents, 100 other files of 1 MB each,
+1,000 earlier versions, 1,500 objects in all, 3 MiB) is sent in one request. A larger one is sent
+staged: a list of everything, then parts of about 1 MiB, then each file, then commits until the
+host has created it, with progress on stderr (JSON lines with --json). Staged, a bundle holds at
+most 10,000 documents, 1,000 reserved files, 1,000 other files of 16 MiB each and 64 MiB of
+current files in all, and 5,000 earlier versions (64 MiB); the list of everything is at most
+3 MiB. Every way: 64 KiB per document and reserved file, 16 KiB of frontmatter.
 
 With --yes, signs in if needed (AUTH_REQUIRED, exit 4, carries the one link to relay and the
 command to re-run), creates the bundle in your workspace (only you can reach it, at write, until
@@ -131378,7 +132074,7 @@ branch, or any other folder that is its own Git working tree, is refused.
 --with-history imports each document's earlier Git versions as labeled, unverified history
 (imported:git/<commit>); without it, history starts at publish. A local bundle has only its current
 versions. A retry after an unknown outcome (TRANSIENT) re-sends the same request, so the host
-finishes or confirms the one creation.
+finishes or confirms the one creation; a staged one resumes, sending only what the host lacks.
 
 Options:
   --to hosted         Required: the only destination