busabase-sdk 0.17.3 → 0.19.0

package/dist/airapp.js

@@ -1,451 +1,610 @@
-// src/airapp.ts
+import { z } from "zod";
+const TemplateAirAppRefSchema = z.object({
+	/** Slug of the `content/<dir>` holding the AirApp. */
+	slug: z.string().min(1),
+	role: z.enum([
+		"primary",
+		"admin",
+		"public",
+		"tool"
+	]),
+	label: z.string().optional()
+});
+/**
+* Secrets the app expects to find in the Vault.
+*
+* DECLARED, never created: the package format has no slot for secret values and
+* must not grow one (the same "you cannot leak what the format cannot express"
+* rule the whole format is built on). Install surfaces these as a post-install
+* prompt; the user fills them in the Vault themselves.
+*/
+const TemplateSecretSchema = z.object({
+	key: z.string().min(1),
+	description: z.string().default(""),
+	required: z.boolean().default(true)
+});
+z.object({
+	/** Template Center category, e.g. `"crm"`, `"email"`, `"content"`. */
+	category: z.string().min(1),
+	tags: z.array(z.string()).default([]),
+	/** Card/detail screenshots, package-relative (`assets/screenshots/overview.webp`). */
+	screenshots: z.array(z.string()).default([]),
+	/**
+	* Ready-made prompts shown after install ("Ask agent" prefills the first).
+	*
+	* They are the difference between a folder of tables and something a user can
+	* *use*: the point of a template is that the agent already knows the job, and
+	* these are how that is made visible rather than left for the user to guess.
+	*/
+	agentPrompts: z.array(z.string()).default([]),
+	/** Single-AirApp shorthand. Mutually exclusive with `airapps`. */
+	airapp: z.string().optional(),
+	/** Multi-AirApp form. Exactly one entry must have `role: "primary"`. */
+	airapps: z.array(TemplateAirAppRefSchema).optional(),
+	/**
+	* Bumped by the author when the declared resource shape changes.
+	*
+	* Part of the ownership stamp, so BOTH doors must agree on it: the installer
+	* writes it, and a skill's own `setup.mjs` compares against it to decide
+	* whether a node it finds is its own current shape or an older one to repair.
+	* Defaulted rather than required so an author who never versions their app
+	* still gets a stamp both sides recognise.
+	*/
+	schemaVersion: z.number().int().nonnegative().default(1),
+	vaultNamespace: z.string().optional(),
+	secrets: z.array(TemplateSecretSchema).default([]),
+	requires: z.object({ airapp: z.boolean().optional() }).default({})
+});
+/**
+* `metadata.busabase` inside the root `SKILL.md`'s YAML frontmatter.
+*
+* `template: true` is an EXPLICIT opt-in, not an inference from "this skill
+* happens to contain a package". Publishing a template means accepting that
+* installers will run its AirApp code and feed its SKILL.md to their agent; that
+* deserves a deliberate flag rather than a side effect of directory shape.
+*/
+const SkillBusabaseMetadataSchema = z.object({
+	template: z.boolean().default(false),
+	folderSlug: z.string().optional(),
+	/** Resource keys the manual talks about; each must exist under `content/`. */
+	resources: z.array(z.string()).default([]),
+	risk: z.string().optional()
+});
+z.object({
+	name: z.string().min(1),
+	description: z.string().default(""),
+	metadata: z.object({ busabase: SkillBusabaseMetadataSchema.optional() }).passthrough().optional()
+});
+/** Stamp on every resource node (Base, Drive, AirApp, …) an app owns. */
+const AppResourceOwnershipSchema = z.object({
+	appId: z.string().min(1),
+	/** Stable internal handle (`"contacts"`), NOT the installed slug. */
+	resourceKey: z.string().min(1),
+	schemaVersion: z.number().int().nonnegative()
+});
+/**
+* The `resourceKey` reserved for an app's root Folder.
+*
+* `busabase-sdk` recognises an app's own Folder by looking for exactly this
+* value (`ownsAppRoot`), so the installer must write it too — a Folder stamped
+* with anything else reads as a stranger's, and the skill's own `setup.mjs`
+* then refuses to touch its own workspace with `SETUP_CONFLICT`. Exported so
+* neither side carries the string literal privately.
+*/
+const APP_ROOT_RESOURCE_KEY = "app-root";
+AppResourceOwnershipSchema.extend({
+	resourceKey: z.literal(APP_ROOT_RESOURCE_KEY),
+	version: z.string().optional(),
+	source: z.object({
+		repo: z.string().optional(),
+		ref: z.string().optional(),
+		subdir: z.string().optional()
+	}).optional(),
+	installedAt: z.string().optional()
+});
+z.object({
+	appId: z.string().min(1),
+	["isTemplateSkill"]: z.literal(true)
+});
+//#endregion
+//#region src/airapp.ts
+/**
+* AirApp resource provisioning — how an app claims (or creates) the Folder and
+* Bases it declares, exactly once, without ever taking over someone else's.
+*
+* Every App-in-Skill shipped a byte-identical copy of this module (280 lines ×
+* 65 apps, two spellings). That is the wrong place for it: the rules encoded
+* here are not app preferences, they are the safety boundary that keeps an app
+* from adopting a Folder a human created for something else. A third party
+* re-deriving them from scratch gets the happy path right and the conflict
+* cases wrong, and the failure is silent — the app happily writes into data it
+* does not own.
+*
+* The contract, in one line: **an app owns a node only if it stamped it.**
+* Ownership lives in `node.metadata` as `{ appId, resourceKey, schemaVersion }`.
+* Anything else is either a legacy node this app plausibly created before
+* stamping existed (claimable *only* after a full structural fingerprint match)
+* or someone else's (never touched, always a `SETUP_CONFLICT`).
+*
+* This module is isomorphic — browser and Node both — and holds no I/O beyond
+* the passed-in client.
+*
+* @example
+* ```ts
+* import { createBusabaseClient } from "busabase-sdk";
+* import { inspectProvisionedResources, provisionDeclaredResources } from "busabase-sdk/airapp";
+*
+* const client = createBusabaseClient({ baseUrl: window.location.origin });
+* const config = {
+*   appId: "kelly-crm",
+*   appName: "Kelly CRM",
+*   schemaVersion: 1,
+*   folder: { slug: "kelly-crm", name: "Kelly CRM", description: "CRM workspace" },
+*   bases: [{ key: "contacts", slug: "kelly-crm-contacts-v1", name: "Contacts", fields: [...] }],
+* };
+*
+* let resources = await inspectProvisionedResources(client, config);
+* if (!resources.folder || resources.missing.length) {
+*   resources = await provisionDeclaredResources(client, config); // one idempotent ChangeRequest
+* }
+* ```
+*/
+/**
+* A setup failure carrying its state as a `code`.
+*
+* `message` is deliberately kept in the historical `"CODE: detail"` shape: the
+* generated apps parse the prefix off `error.message`, so an app can migrate to
+* this class without touching its rendering code, then move to `error.code`.
+*/
 var AirAppSetupError = class extends Error {
-  code;
-  /** The human-readable half, without the `CODE: ` prefix. */
-  detail;
-  constructor(code, detail) {
-    super(`${code}: ${detail}`);
-    this.name = "AirAppSetupError";
-    this.code = code;
-    this.detail = detail;
-  }
+	code;
+	/** The human-readable half, without the `CODE: ` prefix. */
+	detail;
+	constructor(code, detail) {
+		super(`${code}: ${detail}`);
+		this.name = "AirAppSetupError";
+		this.code = code;
+		this.detail = detail;
+	}
 };
-var setupError = (code, detail) => new AirAppSetupError(code, detail);
-var isNotFound = (error) => typeof error === "object" && error !== null && ("code" in error && error.code === "NOT_FOUND" || "status" in error && error.status === 404);
-var isForbidden = (error) => typeof error === "object" && error !== null && ("code" in error && error.code === "FORBIDDEN" || "status" in error && error.status === 403);
-var ownsResource = (node, appId, resourceKey, schemaVersion) => node?.metadata?.appId === appId && node?.metadata?.resourceKey === resourceKey && node?.metadata?.schemaVersion === schemaVersion;
-var hasResourceIdentity = (node, appId, resourceKey) => node?.metadata?.appId === appId && node?.metadata?.resourceKey === resourceKey;
-var ownsAppRoot = (node, appId, schemaVersion) => hasResourceIdentity(node, appId, "app-root") && node?.metadata?.schemaVersion === schemaVersion;
-var hasEmptyMetadata = (node) => Object.keys(node?.metadata ?? {}).length === 0;
-var isUnclaimed = (node) => node?.metadata?.appId === void 0;
-var matchesDeclaration = (node, declaration, type) => node?.type === type && node?.slug === declaration.slug && node?.name === declaration.name && node?.description === (declaration.description ?? "");
-var matchesLegacyAirApp = (node, config) => isUnclaimed(node) && node?.type === "airapp" && node?.slug === config.airApp?.slug && node?.name === config.airApp?.name;
-var resourceMetadata = (config, resourceKey) => ({
-  appId: config.appId,
-  resourceKey,
-  schemaVersion: config.schemaVersion
+const setupError = (code, detail) => new AirAppSetupError(code, detail);
+/** True for a 404 / NOT_FOUND from any of the client's transports. */
+const isNotFound = (error) => typeof error === "object" && error !== null && ("code" in error && error.code === "NOT_FOUND" || "status" in error && error.status === 404);
+const isForbidden = (error) => typeof error === "object" && error !== null && ("code" in error && error.code === "FORBIDDEN" || "status" in error && error.status === 403);
+const ownsResource = (node, appId, resourceKey, schemaVersion) => node?.metadata?.appId === appId && node?.metadata?.resourceKey === resourceKey && node?.metadata?.schemaVersion === schemaVersion;
+const hasResourceIdentity = (node, appId, resourceKey) => node?.metadata?.appId === appId && node?.metadata?.resourceKey === resourceKey;
+const ownsAppRoot = (node, appId, schemaVersion) => hasResourceIdentity(node, appId, "app-root") && node?.metadata?.schemaVersion === schemaVersion;
+const hasEmptyMetadata = (node) => Object.keys(node?.metadata ?? {}).length === 0;
+/**
+* Nobody has stamped ownership on this node — weaker than `hasEmptyMetadata`,
+* and deliberately so: a file-tree node (Skill/Drive/AirApp) always carries a
+* server-written `metadata.version`, even freshly created and never stamped
+* by any app. Requiring literally-empty metadata there would mean a node
+* `publishAirApp` itself just created is never recognized as ours on the very
+* next read — confirmed against a live server, not assumed.
+*/
+const isUnclaimed = (node) => node?.metadata?.appId === void 0;
+/**
+* The legacy-claim test. An unstamped node is adopted only when its every
+* visible attribute still matches the declaration — a weaker test would let an
+* app claim a same-slug Folder a human repurposed.
+*/
+const matchesDeclaration = (node, declaration, type) => node?.type === type && node?.slug === declaration.slug && node?.name === declaration.name && node?.description === (declaration.description ?? "");
+/**
+* The AirApp equivalent of the legacy claim: an unclaimed `airapp` node counts
+* as ours only when its slug and name still match what we declare.
+*/
+const matchesLegacyAirApp = (node, config) => isUnclaimed(node) && node?.type === "airapp" && node?.slug === config.airApp?.slug && node?.name === config.airApp?.name;
+const resourceMetadata = (config, resourceKey) => ({
+	appId: config.appId,
+	resourceKey,
+	schemaVersion: config.schemaVersion
 });
+/**
+* Decide, from one already-read Folder, what exists / is missing / needs
+* re-stamping. Pure — no I/O — so the ownership rules are directly testable.
+*
+* @throws {AirAppSetupError} `SETUP_CONFLICT` when a node in the way is not
+* this app's. Nothing is ever mutated on that path.
+*/
 function resolveProvisionedFolder(folder, config) {
-  if (!folder) {
-    return { folder: null, bases: [], missing: [...config.bases], repairs: [], airApp: null };
-  }
-  if (folder.node?.type !== "folder" || folder.node?.slug !== config.folder.slug) {
-    throw setupError(
-      "SETUP_CONFLICT",
-      `A different Folder already uses the slug ${config.folder.slug}; nothing was changed`
-    );
-  }
-  const rootOwned = hasResourceIdentity(folder.node, config.appId, "app-root");
-  const legacyRoot = hasEmptyMetadata(folder.node) && matchesDeclaration(folder.node, config.folder, "folder");
-  if (!rootOwned && !legacyRoot) {
-    throw setupError(
-      "SETUP_CONFLICT",
-      `The Folder ${config.folder.slug} does not belong to this app; nothing was changed`
-    );
-  }
-  const bases = [];
-  const missing = [];
-  const repairs = [];
-  if (!ownsAppRoot(folder.node, config.appId, config.schemaVersion)) {
-    repairs.push({
-      nodeId: folder.node.id,
-      resourceKey: "app-root",
-      metadata: resourceMetadata(config, "app-root")
-    });
-  }
-  for (const base of config.bases) {
-    const matches = (folder.children ?? []).filter((node2) => node2.slug === base.slug);
-    if (!matches.length) {
-      if (legacyRoot) {
-        throw setupError(
-          "SETUP_CONFLICT",
-          `The existing unstamped Folder is missing the resource ${base.slug}, so it cannot be claimed safely`
-        );
-      }
-      missing.push(base);
-      continue;
-    }
-    const node = matches[0];
-    if (matches.length !== 1 || node.type !== "base" || !node.baseId) {
-      throw setupError(
-        "SETUP_CONFLICT",
-        `The resource ${base.slug} does not match this app's declaration; nothing was changed`
-      );
-    }
-    const owned = hasResourceIdentity(node, config.appId, base.key);
-    const legacy = hasEmptyMetadata(node) && matchesDeclaration(node, base, "base");
-    if (!owned && !legacy) {
-      throw setupError(
-        "SETUP_CONFLICT",
-        `The resource ${base.slug} does not match this app's declaration; nothing was changed`
-      );
-    }
-    if (!ownsResource(node, config.appId, base.key, config.schemaVersion)) {
-      repairs.push({
-        nodeId: node.id,
-        baseId: node.baseId,
-        resourceKey: base.key,
-        metadata: resourceMetadata(config, base.key)
-      });
-    }
-    bases.push({ ...base, nodeId: node.id, baseId: node.baseId });
-  }
-  const airAppNode = config.airApp ? (folder.children ?? []).find(
-    (node) => hasResourceIdentity(
-      node,
-      config.appId,
-      config.airApp.resourceKey
-    ) || matchesLegacyAirApp(node, config)
-  ) : void 0;
-  if (config.airApp && airAppNode && !ownsResource(airAppNode, config.appId, config.airApp.resourceKey, config.schemaVersion)) {
-    repairs.push({
-      nodeId: airAppNode.id,
-      resourceKey: config.airApp.resourceKey,
-      metadata: resourceMetadata(config, config.airApp.resourceKey)
-    });
-  }
-  if (legacyRoot) {
-    const declaredSlugs = new Set(config.bases.map((base) => base.slug));
-    const ambiguousExtra = (folder.children ?? []).find(
-      (node) => !declaredSlugs.has(node.slug) && node.id !== airAppNode?.id && node?.metadata?.appId !== config.appId
-    );
-    if (ambiguousExtra) {
-      throw setupError(
-        "SETUP_CONFLICT",
-        `The existing unstamped Folder holds an unattributable resource ${ambiguousExtra.slug}; nothing was changed`
-      );
-    }
-  }
-  return {
-    folder: { ...config.folder, nodeId: folder.node.id },
-    bases,
-    missing,
-    repairs,
-    airApp: airAppNode ? { nodeId: airAppNode.id } : null
-  };
+	if (!folder) return {
+		folder: null,
+		bases: [],
+		missing: [...config.bases],
+		repairs: [],
+		airApp: null
+	};
+	if (folder.node?.type !== "folder" || folder.node?.slug !== config.folder.slug) throw setupError("SETUP_CONFLICT", `A different Folder already uses the slug ${config.folder.slug}; nothing was changed`);
+	const rootOwned = hasResourceIdentity(folder.node, config.appId, APP_ROOT_RESOURCE_KEY);
+	const legacyRoot = hasEmptyMetadata(folder.node) && matchesDeclaration(folder.node, config.folder, "folder");
+	if (!rootOwned && !legacyRoot) throw setupError("SETUP_CONFLICT", `The Folder ${config.folder.slug} does not belong to this app; nothing was changed`);
+	const bases = [];
+	const missing = [];
+	const repairs = [];
+	if (!ownsAppRoot(folder.node, config.appId, config.schemaVersion)) repairs.push({
+		nodeId: folder.node.id,
+		resourceKey: APP_ROOT_RESOURCE_KEY,
+		metadata: resourceMetadata(config, APP_ROOT_RESOURCE_KEY)
+	});
+	for (const base of config.bases) {
+		const matches = (folder.children ?? []).filter((node) => node.slug === base.slug);
+		if (!matches.length) {
+			if (legacyRoot) throw setupError("SETUP_CONFLICT", `The existing unstamped Folder is missing the resource ${base.slug}, so it cannot be claimed safely`);
+			missing.push(base);
+			continue;
+		}
+		const node = matches[0];
+		if (matches.length !== 1 || node.type !== "base" || !node.baseId) throw setupError("SETUP_CONFLICT", `The resource ${base.slug} does not match this app's declaration; nothing was changed`);
+		const owned = hasResourceIdentity(node, config.appId, base.key);
+		const legacy = hasEmptyMetadata(node) && matchesDeclaration(node, base, "base");
+		if (!owned && !legacy) throw setupError("SETUP_CONFLICT", `The resource ${base.slug} does not match this app's declaration; nothing was changed`);
+		if (!ownsResource(node, config.appId, base.key, config.schemaVersion)) repairs.push({
+			nodeId: node.id,
+			baseId: node.baseId,
+			resourceKey: base.key,
+			metadata: resourceMetadata(config, base.key)
+		});
+		bases.push({
+			...base,
+			nodeId: node.id,
+			baseId: node.baseId
+		});
+	}
+	const airAppNode = config.airApp ? (folder.children ?? []).find((node) => hasResourceIdentity(node, config.appId, config.airApp.resourceKey) || matchesLegacyAirApp(node, config)) : void 0;
+	if (config.airApp && airAppNode && !ownsResource(airAppNode, config.appId, config.airApp.resourceKey, config.schemaVersion)) repairs.push({
+		nodeId: airAppNode.id,
+		resourceKey: config.airApp.resourceKey,
+		metadata: resourceMetadata(config, config.airApp.resourceKey)
+	});
+	if (legacyRoot) {
+		const declaredSlugs = new Set(config.bases.map((base) => base.slug));
+		const ambiguousExtra = (folder.children ?? []).find((node) => !declaredSlugs.has(node.slug) && node.id !== airAppNode?.id && node?.metadata?.appId !== config.appId);
+		if (ambiguousExtra) throw setupError("SETUP_CONFLICT", `The existing unstamped Folder holds an unattributable resource ${ambiguousExtra.slug}; nothing was changed`);
+	}
+	return {
+		folder: {
+			...config.folder,
+			nodeId: folder.node.id
+		},
+		bases,
+		missing,
+		repairs,
+		airApp: airAppNode ? { nodeId: airAppNode.id } : null
+	};
 }
+/**
+* The create operations for one idempotent ChangeRequest. Pure.
+*
+* When the Folder does not exist yet it is created under the temp `ref`
+* `"app-root"` and the Bases nest under it via `parentNodeRef`, so the whole
+* structure lands in a single reviewable change.
+*/
 function buildProvisionOperations(config, folder, missingBases) {
-  const operations = [];
-  if (!folder) {
-    operations.push({
-      kind: "create",
-      ref: "app-root",
-      nodeType: "folder",
-      slug: config.folder.slug,
-      name: config.folder.name,
-      description: config.folder.description ?? "",
-      metadata: resourceMetadata(config, "app-root")
-    });
-  }
-  for (const base of missingBases) {
-    operations.push({
-      kind: "create",
-      ...folder ? { parentNodeId: folder.nodeId } : { parentNodeRef: "app-root" },
-      nodeType: "base",
-      slug: base.slug,
-      name: base.name,
-      description: base.description ?? "",
-      metadata: resourceMetadata(config, base.key),
-      // The declaration's `type` is a plain `string` (see AirAppFieldDeclaration);
-      // the server validates the real field-type enum on the wire.
-      fields: base.fields
-    });
-  }
-  return operations;
+	const operations = [];
+	if (!folder) operations.push({
+		kind: "create",
+		ref: "app-root",
+		nodeType: "folder",
+		slug: config.folder.slug,
+		name: config.folder.name,
+		description: config.folder.description ?? "",
+		metadata: resourceMetadata(config, APP_ROOT_RESOURCE_KEY)
+	});
+	for (const base of missingBases) operations.push({
+		kind: "create",
+		...folder ? { parentNodeId: folder.nodeId } : { parentNodeRef: "app-root" },
+		nodeType: "base",
+		slug: base.slug,
+		name: base.name,
+		description: base.description ?? "",
+		metadata: resourceMetadata(config, base.key),
+		fields: base.fields
+	});
+	return operations;
 }
-var findTopLevelFolder = async (client, config) => {
-  const roots = await client.nodes.list({ parentId: null, depth: 2 });
-  const candidates = (roots ?? []).flatMap((node) => [node, ...node.children ?? []]).filter((node) => node.type === "folder" && node.slug === config.folder.slug);
-  if (candidates.length > 1) {
-    throw setupError(
-      "SETUP_CONFLICT",
-      `Found more than one Folder with the slug ${config.folder.slug}; nothing was changed`
-    );
-  }
-  return candidates[0] ?? null;
+const findTopLevelFolder = async (client, config) => {
+	const candidates = (await client.nodes.list({
+		parentId: null,
+		depth: 2
+	}) ?? []).flatMap((node) => [node, ...node.children ?? []]).filter((node) => node.type === "folder" && node.slug === config.folder.slug);
+	if (candidates.length > 1) throw setupError("SETUP_CONFLICT", `Found more than one Folder with the slug ${config.folder.slug}; nothing was changed`);
+	return candidates[0] ?? null;
 };
-var readFolder = async (client, config) => {
-  let nodeId = config.folder.nodeId;
-  if (!nodeId) nodeId = (await findTopLevelFolder(client, config))?.id;
-  if (!nodeId) return null;
-  try {
-    return await client.nodes.get({ nodeId, type: "folder" });
-  } catch (error) {
-    if (isNotFound(error) && config.folder.nodeId) {
-      const discovered = await findTopLevelFolder(client, config);
-      return discovered ? await client.nodes.get({
-        nodeId: discovered.id,
-        type: "folder"
-      }) : null;
-    }
-    if (isNotFound(error)) return null;
-    throw error;
-  }
+const readFolder = async (client, config) => {
+	let nodeId = config.folder.nodeId;
+	if (!nodeId) nodeId = (await findTopLevelFolder(client, config))?.id;
+	if (!nodeId) return null;
+	try {
+		return await client.nodes.get({
+			nodeId,
+			type: "folder"
+		});
+	} catch (error) {
+		if (isNotFound(error) && config.folder.nodeId) {
+			const discovered = await findTopLevelFolder(client, config);
+			return discovered ? await client.nodes.get({
+				nodeId: discovered.id,
+				type: "folder"
+			}) : null;
+		}
+		if (isNotFound(error)) return null;
+		throw error;
+	}
 };
+/** Read the current state of this app's declared resources. Never mutates. */
 async function inspectProvisionedResources(client, config) {
-  return resolveProvisionedFolder(await readFolder(client, config), config);
+	return resolveProvisionedFolder(await readFolder(client, config), config);
 }
-var provisionStates = /* @__PURE__ */ new WeakMap();
-var stateFor = (client, appId) => {
-  let byApp = provisionStates.get(client);
-  if (!byApp) {
-    byApp = /* @__PURE__ */ new Map();
-    provisionStates.set(client, byApp);
-  }
-  let state = byApp.get(appId);
-  if (!state) {
-    state = { inFlight: null, metadataUpdatesSupported: void 0 };
-    byApp.set(appId, state);
-  }
-  return state;
+const provisionStates = /* @__PURE__ */ new WeakMap();
+const stateFor = (client, appId) => {
+	let byApp = provisionStates.get(client);
+	if (!byApp) {
+		byApp = /* @__PURE__ */ new Map();
+		provisionStates.set(client, byApp);
+	}
+	let state = byApp.get(appId);
+	if (!state) {
+		state = {
+			inFlight: null,
+			metadataUpdatesSupported: void 0
+		};
+		byApp.set(appId, state);
+	}
+	return state;
 };
-var sameFieldName = (actual, expected) => JSON.stringify(actual) === JSON.stringify(expected);
-var fieldMatches = (actual, expected) => actual?.slug === expected.slug && actual?.type === expected.type && actual?.required === expected.required && sameFieldName(actual?.name, expected.name);
-var additiveFieldsFor = (actual, expected) => {
-  const fields = actual?.fields ?? [];
-  if (fields.length > expected.fields.length || !fields.every((field, index) => fieldMatches(field, expected.fields[index]))) {
-    throw setupError(
-      "SETUP_CONFLICT",
-      `The structure of ${expected.slug} does not match this app's declaration, so it cannot be upgraded safely`
-    );
-  }
-  return expected.fields.slice(fields.length);
+const sameFieldName = (actual, expected) => JSON.stringify(actual) === JSON.stringify(expected);
+const fieldMatches = (actual, expected) => actual?.slug === expected.slug && actual?.type === expected.type && actual?.required === expected.required && sameFieldName(actual?.name, expected.name);
+/**
+* How an app evolves a Base it already owns: the declared field list may grow,
+* and only at the end.
+*
+* A live Base whose fields are a strict *prefix* of the declaration is an older
+* schema of ours, and the missing suffix is added. Anything else — a field
+* renamed, retyped, reordered, or removed — is not an upgrade this can reason
+* about, so it refuses rather than guessing which of the two shapes is right.
+*
+* @throws {AirAppSetupError} `SETUP_CONFLICT` when the existing fields are not a
+* prefix of the declared ones.
+*/
+const additiveFieldsFor = (actual, expected) => {
+	const fields = actual?.fields ?? [];
+	if (fields.length > expected.fields.length || !fields.every((field, index) => fieldMatches(field, expected.fields[index]))) throw setupError("SETUP_CONFLICT", `The structure of ${expected.slug} does not match this app's declaration, so it cannot be upgraded safely`);
+	return expected.fields.slice(fields.length);
 };
-var validateRepairBase = (actual, expected, nodeId) => {
-  if (!expected) {
-    throw setupError("SETUP_CONFLICT", "Cannot repair a resource this app does not declare");
-  }
-  const fields = actual?.fields ?? [];
-  const exactFields = fields.length === expected.fields.length && fields.every((field, index) => fieldMatches(field, expected.fields[index]));
-  if (actual?.nodeId !== nodeId || actual?.slug !== expected.slug || actual?.name !== expected.name || actual?.description !== (expected.description ?? "") || !exactFields) {
-    throw setupError(
-      "SETUP_CONFLICT",
-      `The structure of ${expected.slug} does not match this app's declaration, so it cannot be claimed safely`
-    );
-  }
+/**
+* Before re-stamping an unstamped Base as ours, prove it is structurally the
+* Base we declared — same slug, name, description, and exact field list in
+* order. Without this, a stamp would launder a name collision into ownership.
+*/
+const validateRepairBase = (actual, expected, nodeId) => {
+	if (!expected) throw setupError("SETUP_CONFLICT", "Cannot repair a resource this app does not declare");
+	const fields = actual?.fields ?? [];
+	const exactFields = fields.length === expected.fields.length && fields.every((field, index) => fieldMatches(field, expected.fields[index]));
+	if (actual?.nodeId !== nodeId || actual?.slug !== expected.slug || actual?.name !== expected.name || actual?.description !== (expected.description ?? "") || !exactFields) throw setupError("SETUP_CONFLICT", `The structure of ${expected.slug} does not match this app's declaration, so it cannot be claimed safely`);
 };
 async function repairResourceOwnership(client, config, current) {
-  if (!current.repairs.length) return current;
-  const state = stateFor(client, config.appId);
-  const baseRepairs = current.repairs.filter((repair) => repair.baseId);
-  const baseByKey = new Map(config.bases.map((base) => [base.key, base]));
-  const details = await Promise.all(
-    baseRepairs.map((repair) => client.bases.get({ baseId: repair.baseId }))
-  );
-  const migrations = details.map((detail, index) => {
-    const repair = baseRepairs[index];
-    const expected = baseByKey.get(repair.resourceKey);
-    if (!expected) {
-      throw setupError("SETUP_CONFLICT", "Cannot repair a resource this app does not declare");
-    }
-    if (detail?.nodeId !== repair.nodeId || detail?.slug !== expected.slug || detail?.name !== expected.name || detail?.description !== (expected.description ?? "")) {
-      throw setupError(
-        "SETUP_CONFLICT",
-        `The structure of ${expected.slug} does not match this app's declaration, so it cannot be upgraded safely`
-      );
-    }
-    return { repair, expected, fields: additiveFieldsFor(detail, expected) };
-  });
-  const pendingFieldRequests = [];
-  for (const migration of migrations) {
-    for (const field of migration.fields) {
-      const changeRequest = await client.bases.fieldChangeRequest({
-        operation: "create",
-        baseId: migration.repair.baseId,
-        slug: field.slug,
-        name: field.name,
-        // The declaration's `type` is a plain `string` (see AirAppFieldDeclaration);
-        // the server validates the real field-type enum on the wire.
-        type: field.type,
-        required: field.required,
-        message: `Upgrade ${config.appName}: add ${field.slug}`,
-        submittedBy: config.appId
-      });
-      const merged = changeRequest?.status === "merged" || changeRequest?.materialized === true;
-      if (!merged) pendingFieldRequests.push(changeRequest?.id ?? field.slug);
-    }
-  }
-  if (pendingFieldRequests.length) {
-    throw setupError(
-      "SETUP_PENDING",
-      `Submitted ${pendingFieldRequests.length} field upgrade request(s) awaiting Space admin approval: ${pendingFieldRequests.join(", ")}`
-    );
-  }
-  const verified = migrations.some((migration) => migration.fields.length) ? await Promise.all(
-    baseRepairs.map((repair) => client.bases.get({ baseId: repair.baseId }))
-  ) : details;
-  verified.forEach((detail, index) => {
-    const repair = baseRepairs[index];
-    validateRepairBase(detail, baseByKey.get(repair.resourceKey), repair.nodeId);
-  });
-  if (state.metadataUpdatesSupported === false) {
-    return { ...current, repairs: [], compatibilityMode: "verified-legacy-fingerprint" };
-  }
-  try {
-    for (const repair of current.repairs) {
-      await client.nodes.updateMetadata({ nodeId: repair.nodeId, metadata: repair.metadata });
-      state.metadataUpdatesSupported = true;
-    }
-  } catch (error) {
-    if (isNotFound(error)) {
-      state.metadataUpdatesSupported = false;
-      return { ...current, repairs: [], compatibilityMode: "verified-legacy-fingerprint" };
-    }
-    if (isForbidden(error)) {
-      throw setupError(
-        "SETUP_PERMISSION",
-        "This account may not repair resource ownership metadata for this app"
-      );
-    }
-    throw error;
-  }
-  const repaired = await inspectProvisionedResources(client, config);
-  if (repaired.repairs.length) {
-    throw setupError("SCHEMA_INCOMPLETE", "Ownership was repaired but read back incomplete");
-  }
-  return repaired;
+	if (!current.repairs.length) return current;
+	const state = stateFor(client, config.appId);
+	const baseRepairs = current.repairs.filter((repair) => repair.baseId);
+	const baseByKey = new Map(config.bases.map((base) => [base.key, base]));
+	const details = await Promise.all(baseRepairs.map((repair) => client.bases.get({ baseId: repair.baseId })));
+	const migrations = details.map((detail, index) => {
+		const repair = baseRepairs[index];
+		const expected = baseByKey.get(repair.resourceKey);
+		if (!expected) throw setupError("SETUP_CONFLICT", "Cannot repair a resource this app does not declare");
+		if (detail?.nodeId !== repair.nodeId || detail?.slug !== expected.slug || detail?.name !== expected.name || detail?.description !== (expected.description ?? "")) throw setupError("SETUP_CONFLICT", `The structure of ${expected.slug} does not match this app's declaration, so it cannot be upgraded safely`);
+		return {
+			repair,
+			expected,
+			fields: additiveFieldsFor(detail, expected)
+		};
+	});
+	const pendingFieldRequests = [];
+	for (const migration of migrations) for (const field of migration.fields) {
+		const changeRequest = await client.bases.fieldChangeRequest({
+			operation: "create",
+			baseId: migration.repair.baseId,
+			slug: field.slug,
+			name: field.name,
+			type: field.type,
+			required: field.required,
+			message: `Upgrade ${config.appName}: add ${field.slug}`,
+			submittedBy: config.appId
+		});
+		if (!(changeRequest?.status === "merged" || changeRequest?.materialized === true)) pendingFieldRequests.push(changeRequest?.id ?? field.slug);
+	}
+	if (pendingFieldRequests.length) throw setupError("SETUP_PENDING", `Submitted ${pendingFieldRequests.length} field upgrade request(s) awaiting Space admin approval: ${pendingFieldRequests.join(", ")}`);
+	(migrations.some((migration) => migration.fields.length) ? await Promise.all(baseRepairs.map((repair) => client.bases.get({ baseId: repair.baseId }))) : details).forEach((detail, index) => {
+		const repair = baseRepairs[index];
+		validateRepairBase(detail, baseByKey.get(repair.resourceKey), repair.nodeId);
+	});
+	if (state.metadataUpdatesSupported === false) return {
+		...current,
+		repairs: [],
+		compatibilityMode: "verified-legacy-fingerprint"
+	};
+	try {
+		for (const repair of current.repairs) {
+			await client.nodes.updateMetadata({
+				nodeId: repair.nodeId,
+				metadata: repair.metadata
+			});
+			state.metadataUpdatesSupported = true;
+		}
+	} catch (error) {
+		if (isNotFound(error)) {
+			state.metadataUpdatesSupported = false;
+			return {
+				...current,
+				repairs: [],
+				compatibilityMode: "verified-legacy-fingerprint"
+			};
+		}
+		if (isForbidden(error)) throw setupError("SETUP_PERMISSION", "This account may not repair resource ownership metadata for this app");
+		throw error;
+	}
+	const repaired = await inspectProvisionedResources(client, config);
+	if (repaired.repairs.length) throw setupError("SCHEMA_INCOMPLETE", "Ownership was repaired but read back incomplete");
+	return repaired;
 }
-var waitForMaterializedResources = async (client, config, attempts = 20) => {
-  let current;
-  for (let attempt = 0; attempt < attempts; attempt += 1) {
-    current = await inspectProvisionedResources(client, config);
-    current = await repairResourceOwnership(client, config, current);
-    if (current.folder && current.missing.length === 0) return current;
-    if (attempt < attempts - 1) {
-      await new Promise((resolve) => globalThis.setTimeout(resolve, 100));
-    }
-  }
-  throw setupError(
-    "SCHEMA_INCOMPLETE",
-    "Initialization merged but the resources read back incomplete"
-  );
+/**
+* A merged ChangeRequest is not immediately readable — materialization is
+* asynchronous — so poll briefly rather than reporting a successful setup as
+* incomplete.
+*/
+const waitForMaterializedResources = async (client, config, attempts = 20) => {
+	let current;
+	for (let attempt = 0; attempt < attempts; attempt += 1) {
+		current = await inspectProvisionedResources(client, config);
+		current = await repairResourceOwnership(client, config, current);
+		if (current.folder && current.missing.length === 0) return current;
+		if (attempt < attempts - 1) await new Promise((resolve) => globalThis.setTimeout(resolve, 100));
+	}
+	throw setupError("SCHEMA_INCOMPLETE", "Initialization merged but the resources read back incomplete");
 };
 async function provisionOnce(client, config) {
-  let current = await inspectProvisionedResources(client, config);
-  current = await repairResourceOwnership(client, config, current);
-  if (current.folder && current.missing.length === 0) return current;
-  const operations = buildProvisionOperations(config, current.folder, current.missing);
-  let changeRequest;
-  try {
-    changeRequest = await client.nodes.createChangeRequest({
-      message: `Initialize ${config.appName} workspace`,
-      submittedBy: config.appId,
-      autoMerge: true,
-      operations
-    });
-  } catch (error) {
-    if (isForbidden(error)) {
-      throw setupError(
-        "SETUP_PERMISSION",
-        "This account may not create this app's resources in this Space"
-      );
-    }
-    const concurrent = await inspectProvisionedResources(client, config).catch(() => null);
-    if (concurrent?.folder && concurrent.missing.length === 0) return concurrent;
-    throw error;
-  }
-  if (changeRequest?.status !== "merged") {
-    throw setupError(
-      "SETUP_PENDING",
-      `Initialization request ${changeRequest?.id ?? ""} was submitted and awaits Space admin approval`.trim()
-    );
-  }
-  return waitForMaterializedResources(client, config);
+	let current = await inspectProvisionedResources(client, config);
+	current = await repairResourceOwnership(client, config, current);
+	if (current.folder && current.missing.length === 0) return current;
+	const operations = buildProvisionOperations(config, current.folder, current.missing);
+	let changeRequest;
+	try {
+		changeRequest = await client.nodes.createChangeRequest({
+			message: `Initialize ${config.appName} workspace`,
+			submittedBy: config.appId,
+			autoMerge: true,
+			operations
+		});
+	} catch (error) {
+		if (isForbidden(error)) throw setupError("SETUP_PERMISSION", "This account may not create this app's resources in this Space");
+		const concurrent = await inspectProvisionedResources(client, config).catch(() => null);
+		if (concurrent?.folder && concurrent.missing.length === 0) return concurrent;
+		throw error;
+	}
+	if (changeRequest?.status !== "merged") throw setupError("SETUP_PENDING", `Initialization request ${changeRequest?.id ?? ""} was submitted and awaits Space admin approval`.trim());
+	return waitForMaterializedResources(client, config);
 }
+/**
+* Ensure the declared Folder and Bases exist, as one idempotent ChangeRequest.
+*
+* Safe to call concurrently: calls for the same client + `appId` share one
+* in-flight promise, so a multi-pane app cannot submit the structure twice.
+*
+* @throws {AirAppSetupError} with a `code` describing which screen to show.
+*/
 function provisionDeclaredResources(client, config) {
-  const state = stateFor(client, config.appId);
-  if (!state.inFlight) {
-    state.inFlight = provisionOnce(client, config).finally(() => {
-      state.inFlight = null;
-    });
-  }
-  return state.inFlight;
+	const state = stateFor(client, config.appId);
+	if (!state.inFlight) state.inFlight = provisionOnce(client, config).finally(() => {
+		state.inFlight = null;
+	});
+	return state.inFlight;
 }
+/**
+* The create-vs-update operation list for one AirApp publish. Pure — no I/O —
+* so the decision is directly testable: a local path already present on the
+* deployed node updates it, anything else is a new file. Never deletes a
+* remote-only path — a file this bundle stopped shipping is left alone rather
+* than assumed stale, the same conservative choice the rest of this module
+* makes for a Base's fields (`additiveFieldsFor` only ever appends).
+*/
 function buildAirAppFileOperations(localFiles, deployedPaths) {
-  const deployed = new Set(deployedPaths);
-  return localFiles.map(
-    (file) => ({
-      kind: deployed.has(file.path) ? "update" : "create",
-      path: file.path,
-      content: file.content,
-      ...file.mimeType ? { mimeType: file.mimeType } : {}
-    })
-  );
+	const deployed = new Set(deployedPaths);
+	return localFiles.map((file) => ({
+		kind: deployed.has(file.path) ? "update" : "create",
+		path: file.path,
+		content: file.content,
+		...file.mimeType ? { mimeType: file.mimeType } : {}
+	}));
 }
+/**
+* Find a still-pending ChangeRequest that already proposes creating this
+* declared AirApp, so a second `publishAirApp` call before the first is
+* reviewed does not propose a second, duplicate create for the same slug.
+*
+* Scoped to the first 500 in-review ChangeRequests (10 pages of 50) — a
+* Space with more open reviews than that has bigger problems than this
+* scan not reaching the one it is looking for, and a missed match only
+* costs an extra (harmless, reviewer-visible) duplicate proposal, never a
+* wrong merge.
+*/
 async function findPendingAirAppCreate(client, slug) {
-  let cursor;
-  for (let page = 0; page < 10; page += 1) {
-    const result = await client.changeRequests.list({
-      status: ["in_review"],
-      ...cursor ? { cursor } : {}
-    });
-    for (const changeRequest of result.changeRequests) {
-      const matches = (changeRequest.operations ?? []).some((operation) => {
-        const payload = operation.headCommit?.payload;
-        return payload?.kind === "create" && payload?.nodeType === "airapp" && payload?.slug === slug;
-      });
-      if (matches) return changeRequest.id;
-    }
-    if (!result.nextCursor) return null;
-    cursor = result.nextCursor;
-  }
-  return null;
+	let cursor;
+	for (let page = 0; page < 10; page += 1) {
+		const result = await client.changeRequests.list({
+			status: ["in_review"],
+			...cursor ? { cursor } : {}
+		});
+		for (const changeRequest of result.changeRequests) if ((changeRequest.operations ?? []).some((operation) => {
+			const payload = operation.headCommit?.payload;
+			return payload?.kind === "create" && payload?.nodeType === "airapp" && payload?.slug === slug;
+		})) return changeRequest.id;
+		if (!result.nextCursor) return null;
+		cursor = result.nextCursor;
+	}
+	return null;
 }
+/**
+* Publish the app's own AirApp bundle: create it under the Folder when this
+* Space has never had it, or propose the local files as an update when it
+* already exists. Always a separate, always-review-first ChangeRequest from
+* the data layer's `provisionDeclaredResources` — see the note on
+* `AirAppNodeDeclaration` for why the two must never share a request.
+*
+* Call after `provisionDeclaredResources` has confirmed the Folder exists.
+* Every call proposes the full local file list, even when nothing actually
+* changed — this module has no access to the deployed content hashes
+* (`fileTrees.listFiles` reports paths, not hashes; only a per-file
+* `readFile` does, and fetching one per file to skip a no-op publish is not
+* worth the round trips a normal publish cadence would spend on it). A
+* reviewer sees an empty diff and merges or ignores it; this is a cost in
+* review noise, not correctness.
+*
+* @throws {AirAppSetupError} `SETUP_CONFLICT` when `config` declares no
+* `airApp`; `SETUP_REQUIRED` when the Folder does not exist yet.
+*/
 async function publishAirApp(client, config, files) {
-  const airApp = config.airApp;
-  if (!airApp) {
-    throw setupError("SETUP_CONFLICT", "This app does not declare an airApp to publish");
-  }
-  const current = await inspectProvisionedResources(client, config);
-  if (!current.folder) {
-    throw setupError(
-      "SETUP_REQUIRED",
-      "Provision the Folder and Bases with provisionDeclaredResources before publishing the AirApp"
-    );
-  }
-  if (!current.airApp) {
-    const pendingChangeRequestId = await findPendingAirAppCreate(client, airApp.slug);
-    if (pendingChangeRequestId) {
-      return { status: "pending", changeRequestId: pendingChangeRequestId };
-    }
-    const changeRequest2 = await client.fileTrees.create({
-      type: "airapp",
-      parentNodeId: current.folder.nodeId,
-      slug: airApp.slug,
-      name: airApp.name,
-      description: airApp.description ?? "",
-      files,
-      mergeMode: "replace",
-      // Explicit even though this app's write-permission credential would
-      // otherwise auto-merge it: executable AirApp code always gets human
-      // review before it runs in a viewer's browser, no exceptions.
-      autoMerge: false
-    });
-    if (changeRequest2.materialized) {
-      throw setupError(
-        "SCHEMA_INCOMPLETE",
-        "AirApp create unexpectedly materialized despite autoMerge: false"
-      );
-    }
-    return { status: "created", changeRequestId: changeRequest2.id };
-  }
-  const deployedFiles = await client.fileTrees.listFiles({
-    nodeId: current.airApp.nodeId,
-    type: "airapp"
-  });
-  const operations = buildAirAppFileOperations(
-    files,
-    deployedFiles.map((file) => file.path)
-  );
-  const changeRequest = await client.fileTrees.createChangeRequest({
-    nodeId: current.airApp.nodeId,
-    type: "airapp",
-    operations,
-    message: `Publish ${config.appName} AirApp`,
-    submittedBy: config.appId,
-    autoMerge: false
-  });
-  return { status: "updated", changeRequestId: changeRequest.id };
+	const airApp = config.airApp;
+	if (!airApp) throw setupError("SETUP_CONFLICT", "This app does not declare an airApp to publish");
+	const current = await inspectProvisionedResources(client, config);
+	if (!current.folder) throw setupError("SETUP_REQUIRED", "Provision the Folder and Bases with provisionDeclaredResources before publishing the AirApp");
+	if (!current.airApp) {
+		const pendingChangeRequestId = await findPendingAirAppCreate(client, airApp.slug);
+		if (pendingChangeRequestId) return {
+			status: "pending",
+			changeRequestId: pendingChangeRequestId
+		};
+		const changeRequest = await client.fileTrees.create({
+			type: "airapp",
+			parentNodeId: current.folder.nodeId,
+			slug: airApp.slug,
+			name: airApp.name,
+			description: airApp.description ?? "",
+			files,
+			mergeMode: "replace",
+			autoMerge: false
+		});
+		if (changeRequest.materialized) throw setupError("SCHEMA_INCOMPLETE", "AirApp create unexpectedly materialized despite autoMerge: false");
+		return {
+			status: "created",
+			changeRequestId: changeRequest.id
+		};
+	}
+	const operations = buildAirAppFileOperations(files, (await client.fileTrees.listFiles({
+		nodeId: current.airApp.nodeId,
+		type: "airapp"
+	})).map((file) => file.path));
+	return {
+		status: "updated",
+		changeRequestId: (await client.fileTrees.createChangeRequest({
+			nodeId: current.airApp.nodeId,
+			type: "airapp",
+			operations,
+			message: `Publish ${config.appName} AirApp`,
+			submittedBy: config.appId,
+			autoMerge: false
+		})).id
+	};
 }
-
+//#endregion
 export { AirAppSetupError, buildAirAppFileOperations, buildProvisionOperations, inspectProvisionedResources, isNotFound, provisionDeclaredResources, publishAirApp, resolveProvisionedFolder };