busabase-sdk 0.9.3 → 0.9.5

package/dist/index.js

@@ -4,145 +4,6 @@ import { oc, eventIterator } from '@orpc/contract';
 import { z } from 'zod';
 
 // src/client.ts
-var AttachmentMetadataSchema = z.record(z.string(), z.unknown());
-z.object({
-  id: z.string(),
-  url: z.string(),
-  fileName: z.string(),
-  mimeType: z.string(),
-  size: z.number().int().nonnegative()
-});
-var RequestUploadUrlInputSchema = z.object({
-  fileName: z.string().min(1).max(255),
-  mimeType: z.string().min(1),
-  sizeBytes: z.number().int().positive(),
-  spaceId: z.string().optional(),
-  context: z.string().regex(/^[a-zA-Z0-9_/-]+$/).max(100).optional(),
-  /** Content fingerprint (e.g. "sha256:<hex>") for dedup; computed client-side. */
-  contentHash: z.string().max(80).optional()
-});
-var ConfirmUploadInputSchema = z.object({
-  storageKey: z.string().min(1),
-  fileName: z.string().min(1).max(255),
-  mimeType: z.string().min(1),
-  sizeBytes: z.number().int().positive(),
-  spaceId: z.string().optional(),
-  context: z.string().regex(/^[a-zA-Z0-9_/-]+$/).max(100).optional(),
-  metadata: AttachmentMetadataSchema.optional(),
-  /** Content fingerprint (e.g. "sha256:<hex>") persisted for dedup. */
-  contentHash: z.string().max(80).optional()
-});
-var RequestUploadUrlVOSchema = z.object({
-  uploadUrl: z.string(),
-  storageKey: z.string(),
-  publicUrl: z.string(),
-  expiresIn: z.number(),
-  /**
-   * True when an identical file (same contentHash, same scope) already exists.
-   * The client should SKIP the byte upload and the confirm step, and use
-   * `attachmentId`/`publicUrl` directly. `uploadUrl` is empty in this case.
-   */
-  duplicate: z.boolean().optional(),
-  /** Existing attachment id — present only when `duplicate` is true. */
-  attachmentId: z.string().optional(),
-  /** Host-specific logical asset id, when the app maps uploads into an Asset library. */
-  assetId: z.string().optional()
-});
-var ConfirmUploadVOSchema = z.object({
-  success: z.boolean(),
-  attachmentId: z.string(),
-  /** Host-specific logical asset id, when the app maps uploads into an Asset library. */
-  assetId: z.string().optional(),
-  storageKey: z.string(),
-  publicUrl: z.string()
-});
-var AssetVOSchema = z.object({
-  id: z.string(),
-  attachmentId: z.string(),
-  name: z.string(),
-  contentKind: z.enum(["text", "binary"]),
-  metadata: z.record(z.string(), z.unknown()).default({}),
-  fileName: z.string(),
-  mimeType: z.string(),
-  size: z.number().int().nonnegative(),
-  url: z.string(),
-  contentHash: z.string().nullable(),
-  /** How many places reference this asset (Base records + Doc bodies). */
-  usageCount: z.number().int().nonnegative(),
-  createdAt: z.string()
-});
-var AssetUsageVOSchema = z.object({
-  ownerType: z.enum(["drive", "skill", "base", "doc", "file_node"]),
-  nodeId: z.string(),
-  nodeName: z.string(),
-  nodeType: z.string(),
-  /** Node slug, so the UI can link to the owning Base/Doc (`/{type}/{slug}`). */
-  nodeSlug: z.string(),
-  /** Drive/Skill mounted path, or null when the usage is not path-based. */
-  path: z.string().nullable(),
-  /** Base record id, or null for whole-node usages (e.g. a Doc body). */
-  recordId: z.string().nullable(),
-  /** Attachment field slug, or null for whole-node usages. */
-  fieldSlug: z.string().nullable(),
-  /** Doc block id, or null when the usage is not block-based. */
-  blockId: z.string().nullable(),
-  createdAt: z.string()
-});
-var AssetDetailVOSchema = z.object({
-  asset: AssetVOSchema,
-  usages: z.array(AssetUsageVOSchema)
-});
-
-// ../../packages/busabase-contract/src/domains/assets/contract.ts
-var UpdateAssetMetadataInputSchema = z.object({
-  assetId: z.string(),
-  metadata: z.record(z.string(), z.unknown()),
-  mode: z.enum(["merge", "replace"]).optional().default("merge")
-});
-var assetsContract = {
-  createUploadUrl: oc.route({
-    method: "POST",
-    path: "/assets/upload-urls",
-    tags: ["Assets"],
-    summary: "Request asset upload URL",
-    successDescription: "Presigned (or dev) upload URL plus the public URL and asset id when identical bytes are already in the library."
-  }).input(RequestUploadUrlInputSchema).output(RequestUploadUrlVOSchema),
-  confirm: oc.route({
-    method: "POST",
-    path: "/assets/confirmations",
-    tags: ["Assets"],
-    summary: "Confirm asset upload",
-    successDescription: "Recorded the file and ensured its Busabase Asset library entry."
-  }).input(ConfirmUploadInputSchema).output(ConfirmUploadVOSchema),
-  list: oc.route({
-    method: "GET",
-    path: "/assets",
-    tags: ["Assets"],
-    summary: "List assets",
-    successDescription: "Every asset in the space, with file metadata and usage counts."
-  }).output(z.array(AssetVOSchema)),
-  get: oc.route({
-    method: "GET",
-    path: "/assets/{assetId}",
-    tags: ["Assets"],
-    summary: "Get asset detail",
-    successDescription: "Asset metadata plus every place it is referenced (where-used)."
-  }).input(z.object({ assetId: z.string() })).output(AssetDetailVOSchema),
-  updateMetadata: oc.route({
-    method: "PATCH",
-    path: "/assets/{assetId}/metadata",
-    tags: ["Assets"],
-    summary: "Update asset metadata",
-    successDescription: "Updated AI-readable metadata for a file, such as summary, extracted text, tags, source URL, or schema-specific hints."
-  }).input(UpdateAssetMetadataInputSchema).output(AssetDetailVOSchema),
-  delete: oc.route({
-    method: "DELETE",
-    path: "/assets/{assetId}",
-    tags: ["Assets"],
-    summary: "Delete asset",
-    successDescription: "Removed the asset and, if no other row references its bytes, the stored object. Refused while the asset is still referenced (where-used)."
-  }).input(z.object({ assetId: z.string() })).output(z.object({ deleted: z.boolean() }))
-};
 var i18n = {
   locales: ["en", "zh-CN", "zh-TW", "ja", "ko", "de", "fr", "es", "pt"]};
 var LocaleSchema = z.enum(i18n.locales);
@@ -263,7 +124,12 @@ var createBaseInputSchema = z.object({
       required: z.boolean().default(false),
       options: fieldOptionsSchema.optional().default({})
     })
-  ).default([])
+  ).default([]),
+  // Review-first by default: without `autoMerge: true`, this proposes the Base
+  // as a pending ChangeRequest (status "in_review") instead of creating it
+  // immediately. Pass `autoMerge: true` only for callers that don't need human
+  // review (seed/migration scripts, an explicit no-review agent task).
+  autoMerge: z.boolean().optional().default(false)
 });
 var createBaseFieldInputSchema = z.object({
   name: fieldNameSchema,
@@ -330,6 +196,43 @@ var restoreFieldChangeRequestInputSchema = z.object({
   submittedBy: z.string().optional().default("local-editor")
 });
 
+// ../../packages/busabase-contract/src/domains/filetree/definition.ts
+var fileTreeOperations = (type) => [
+  {
+    kind: `${type}_file_create`,
+    label: "Create file",
+    tone: "border-emerald-200 bg-emerald-50 text-emerald-800"
+  },
+  {
+    kind: `${type}_file_update`,
+    label: "Update file",
+    tone: "border-blue-200 bg-blue-50 text-blue-800"
+  },
+  {
+    kind: `${type}_file_delete`,
+    label: "Delete file",
+    tone: "border-rose-200 bg-rose-50 text-rose-800"
+  },
+  {
+    kind: `${type}_metadata_update`,
+    label: `Update ${type}`,
+    tone: "border-violet-200 bg-violet-50 text-violet-800"
+  }
+];
+var makeFileTreeNodeType = (config) => ({
+  type: config.type,
+  label: config.label,
+  icon: config.icon,
+  capabilities: { hasDetail: true, creatable: true },
+  operations: fileTreeOperations(config.type)
+});
+
+// ../../packages/busabase-contract/src/domains/airapp/definition.ts
+var airappNodeType = makeFileTreeNodeType({
+  type: "airapp",
+  label: "AirApp",
+  icon: "app-window"});
+
 // ../../packages/busabase-contract/src/domains/base/definition.ts
 var baseNodeType = {
   type: "base",
@@ -424,37 +327,6 @@ var docNodeType = {
   ]
 };
 
-// ../../packages/busabase-contract/src/domains/filetree/definition.ts
-var fileTreeOperations = (type) => [
-  {
-    kind: `${type}_file_create`,
-    label: "Create file",
-    tone: "border-emerald-200 bg-emerald-50 text-emerald-800"
-  },
-  {
-    kind: `${type}_file_update`,
-    label: "Update file",
-    tone: "border-blue-200 bg-blue-50 text-blue-800"
-  },
-  {
-    kind: `${type}_file_delete`,
-    label: "Delete file",
-    tone: "border-rose-200 bg-rose-50 text-rose-800"
-  },
-  {
-    kind: `${type}_metadata_update`,
-    label: `Update ${type}`,
-    tone: "border-violet-200 bg-violet-50 text-violet-800"
-  }
-];
-var makeFileTreeNodeType = (config) => ({
-  type: config.type,
-  label: config.label,
-  icon: config.icon,
-  capabilities: { hasDetail: true, creatable: true },
-  operations: fileTreeOperations(config.type)
-});
-
 // ../../packages/busabase-contract/src/domains/drive/definition.ts
 var driveNodeType = makeFileTreeNodeType({
   type: "drive",
@@ -510,6 +382,7 @@ var BUILTIN_NODE_TYPES = [
   baseNodeType,
   skillNodeType,
   driveNodeType,
+  airappNodeType,
   fileNodeType,
   docNodeType
 ];
@@ -695,7 +568,14 @@ var liveEventSchema = z.object({
     "change_request.updated",
     "change_request.deleted",
     "change_request.reviewed",
-    "change_request.merged"
+    "change_request.merged",
+    // Fired only when a CONTENT change request freshly enters human review
+    // (record_* ops created via record-ops.ts) — never for structural ops
+    // that auto-merge instantly (those still fire "change_request.created"
+    // via the audit funnel, but nothing needs reviewing). Consumed by
+    // `use-live-sync.ts` to pop a desktop Notification, and by
+    // busabase-cloud's host hook to persist an inbox notification row.
+    "change_request.pending_review"
   ]),
   spaceId: z.string(),
   actorId: z.string(),
@@ -723,8 +603,11 @@ var auditActionSchema = z.enum([
   "file.created",
   "skill.created",
   "drive.created",
+  "airapp.created",
   "asset.deleted",
   "asset.metadata_updated",
+  "asset.text_written",
+  "asset.text_marked_none",
   "node.purged"
 ]);
 var auditEventSchema = z.object({
@@ -810,6 +693,13 @@ var createNodeChangeRequestInputSchema = z.object({
   ),
   operations: z.array(nodeOperationInputSchema).min(1)
 });
+var moveNodeInputSchema = z.object({
+  nodeId: z.string(),
+  parentNodeId: z.string().optional().describe("New parent folder node id. Omit to keep the current parent and only reorder."),
+  position: z.number().int().optional().describe("New position among the target parent's children."),
+  message: z.string().optional().describe("Reviewer-facing Change Request message."),
+  submittedBy: z.string().optional()
+});
 var createDeleteChangeRequestInputSchema = z.object({
   message: z.string().optional().default("Delete record").describe(
     'Explanation shown to the human reviewer. Say what is being removed and why, e.g. "Archive duplicate contact \u2014 merged into Acme Corp".'
@@ -898,6 +788,477 @@ var authInfoSchema = z.object({
    */
   spaces: z.array(authSpaceSchema)
 });
+
+// ../../packages/busabase-contract/src/domains/filetree/contract.ts
+var fileTreeFileSchema = z.object({
+  path: z.string(),
+  name: z.string(),
+  size: z.number(),
+  updatedAt: z.string().nullable(),
+  mimeType: z.string().nullable(),
+  assetId: z.string(),
+  displayName: z.string().nullable()
+});
+var assetFileInputSchema = z.object({
+  path: z.string().min(1),
+  assetId: z.string().min(1),
+  displayName: z.string().optional(),
+  mimeType: z.string().optional()
+}).strict();
+var textFileInputSchema = z.object({
+  path: z.string().min(1),
+  content: z.string().default(""),
+  mimeType: z.string().optional()
+}).strict();
+var assetFileOperationInputSchema = z.object({
+  kind: z.enum(["create", "update"]),
+  path: z.string().min(1),
+  assetId: z.string().min(1),
+  displayName: z.string().optional(),
+  mimeType: z.string().optional(),
+  baseContentHash: z.string().optional()
+}).strict();
+var textFileOperationInputSchema = z.object({
+  kind: z.enum(["create", "update"]),
+  path: z.string().min(1),
+  content: z.string(),
+  mimeType: z.string().optional(),
+  baseContentHash: z.string().optional()
+}).strict();
+var fileTreeNodeSchema = z.object({
+  node: nodeSchema,
+  entryFile: z.string(),
+  visibility: z.enum(["private", "workspace", "public"]),
+  version: z.string(),
+  files: z.array(fileTreeFileSchema)
+});
+var createFileTreeInputSchema = z.object({
+  parentNodeId: z.string().optional(),
+  slug: z.string().min(1).regex(/^[a-z0-9-]+$/),
+  name: z.string().min(1),
+  description: z.string().optional().default(""),
+  visibility: z.enum(["private", "workspace", "public"]).optional().default("private"),
+  version: z.string().optional().default("0.1.0"),
+  files: z.array(z.union([assetFileInputSchema, textFileInputSchema])).optional().default([]),
+  // Review-first by default: without `autoMerge: true`, this proposes the node
+  // as a pending ChangeRequest (status "in_review") instead of creating it
+  // immediately. Pass `autoMerge: true` only for callers that don't need human
+  // review (seed/migration scripts, an explicit no-review agent task).
+  autoMerge: z.boolean().optional().default(false),
+  // "merge" (default): `files` is layered on top of the config's default seed
+  // files by path — a caller supplying just a couple of extra files (e.g. a
+  // Skill's own reference doc) still gets the default scaffold (SKILL.md,
+  // skill.json, ...) for any path they didn't provide themselves. "replace":
+  // `files` replaces the defaults entirely — for a caller handing over a
+  // complete, different-shaped project (e.g. an AirApp seeded with a Vite
+  // project instead of the default Hono template) who does NOT want leftover
+  // default files with unrelated content mixed in.
+  mergeMode: z.enum(["merge", "replace"]).optional().default("merge")
+});
+var fileTreeFileOperationInputSchema = z.union([
+  assetFileOperationInputSchema,
+  textFileOperationInputSchema,
+  z.object({
+    kind: z.literal("delete"),
+    path: z.string().min(1),
+    baseContentHash: z.string().optional()
+  }).strict(),
+  z.object({
+    kind: z.literal("metadata_update"),
+    metadata: z.object({
+      entryFile: z.string().optional(),
+      visibility: z.enum(["private", "workspace", "public"]).optional(),
+      version: z.string().optional()
+    }).default({})
+  }).strict()
+]);
+var createFileTreeChangeRequestInputSchema = z.object({
+  message: z.string().optional().default("Update file tree").describe(
+    'Explanation shown to the human reviewer. Write a conventional-commit style subject \u2014 imperative verb + what + why, e.g. "Rewrite README.md quickstart for the new auth flow".'
+  ),
+  submittedBy: z.string().optional().default("local-producer"),
+  operations: z.array(fileTreeFileOperationInputSchema).min(1)
+});
+var makeFileTreeContract = (routeBase, tag) => {
+  const label = tag.endsWith("s") ? tag.slice(0, -1) : tag;
+  const basePath = `/${routeBase}`;
+  return {
+    list: oc.route({
+      method: "GET",
+      path: basePath,
+      tags: [tag],
+      summary: `List ${label} nodes`,
+      successDescription: `${label} nodes with their Asset-backed file trees.`
+    }).output(z.array(fileTreeNodeSchema)),
+    create: oc.route({
+      method: "POST",
+      path: basePath,
+      tags: [tag],
+      summary: `Create ${label} node`,
+      successDescription: `Review-first by default: a pending ChangeRequest proposing the ${label} node. Returns the materialized ${label} node instead when \`autoMerge: true\` is passed.`
+    }).input(createFileTreeInputSchema).output(z.union([fileTreeNodeSchema, changeRequestSchema])),
+    get: oc.route({
+      method: "GET",
+      path: `${basePath}/{nodeId}`,
+      tags: [tag],
+      summary: `Get ${label} node`,
+      successDescription: `${label} node detail and file tree.`
+    }).input(z.object({ nodeId: z.string() })).output(fileTreeNodeSchema),
+    listFiles: oc.route({
+      method: "GET",
+      path: `${basePath}/{nodeId}/files`,
+      tags: [tag],
+      summary: `List ${label} files`,
+      successDescription: `Asset-backed files mounted under the ${label} node.`
+    }).input(z.object({ nodeId: z.string() })).output(z.array(fileTreeFileSchema)),
+    readFile: oc.route({
+      method: "GET",
+      path: `${basePath}/{nodeId}/files/{+filePath}`,
+      tags: [tag],
+      summary: `Read ${label} file`,
+      successDescription: `${label} file content and content hash.`
+    }).input(z.object({ nodeId: z.string(), filePath: z.string() })).output(
+      z.object({
+        nodeId: z.string(),
+        path: z.string(),
+        encoding: z.enum(["utf8", "url"]),
+        content: z.string(),
+        mimeType: z.string(),
+        assetId: z.string(),
+        displayName: z.string().nullable(),
+        assetUrl: z.string().nullable(),
+        contentHash: z.string()
+      })
+    ),
+    createChangeRequest: oc.route({
+      method: "POST",
+      path: `${basePath}/{nodeId}/change-requests`,
+      tags: [tag, "Change Requests"],
+      summary: `Create ${label} change request`,
+      successDescription: `Created file-tree change request for a ${label} node.`
+    }).input(createFileTreeChangeRequestInputSchema.extend({ nodeId: z.string() })).output(changeRequestSchema)
+  };
+};
+
+// ../../packages/busabase-contract/src/domains/airapp/contract.ts
+var airappContract = makeFileTreeContract("airapps", "AirApps");
+var AttachmentMetadataSchema = z.record(z.string(), z.unknown());
+z.object({
+  id: z.string(),
+  url: z.string(),
+  fileName: z.string(),
+  mimeType: z.string(),
+  size: z.number().int().nonnegative()
+});
+var RequestUploadUrlInputSchema = z.object({
+  fileName: z.string().min(1).max(255),
+  mimeType: z.string().min(1),
+  sizeBytes: z.number().int().positive(),
+  spaceId: z.string().optional(),
+  context: z.string().regex(/^[a-zA-Z0-9_/-]+$/).max(100).optional(),
+  /** Content fingerprint (e.g. "sha256:<hex>") for dedup; computed client-side. */
+  contentHash: z.string().max(80).optional()
+});
+var ConfirmUploadInputSchema = z.object({
+  storageKey: z.string().min(1),
+  fileName: z.string().min(1).max(255),
+  mimeType: z.string().min(1),
+  sizeBytes: z.number().int().positive(),
+  spaceId: z.string().optional(),
+  context: z.string().regex(/^[a-zA-Z0-9_/-]+$/).max(100).optional(),
+  metadata: AttachmentMetadataSchema.optional(),
+  /** Content fingerprint (e.g. "sha256:<hex>") persisted for dedup. */
+  contentHash: z.string().max(80).optional()
+});
+var RequestUploadUrlVOSchema = z.object({
+  uploadUrl: z.string(),
+  storageKey: z.string(),
+  publicUrl: z.string(),
+  expiresIn: z.number(),
+  /**
+   * True when an identical file (same contentHash, same scope) already exists.
+   * The client should SKIP the byte upload and the confirm step, and use
+   * `attachmentId`/`publicUrl` directly. `uploadUrl` is empty in this case.
+   */
+  duplicate: z.boolean().optional(),
+  /** Existing attachment id — present only when `duplicate` is true. */
+  attachmentId: z.string().optional(),
+  /** Host-specific logical asset id, when the app maps uploads into an Asset library. */
+  assetId: z.string().optional()
+});
+var ConfirmUploadVOSchema = z.object({
+  success: z.boolean(),
+  attachmentId: z.string(),
+  /** Host-specific logical asset id, when the app maps uploads into an Asset library. */
+  assetId: z.string().optional(),
+  storageKey: z.string(),
+  publicUrl: z.string()
+});
+var AssetTextStatusSchema = z.enum(["missing", "present", "none", "stale"]);
+var AssetVOSchema = z.object({
+  id: z.string(),
+  attachmentId: z.string(),
+  name: z.string(),
+  contentKind: z.enum(["text", "binary"]),
+  metadata: z.record(z.string(), z.unknown()).default({}),
+  fileName: z.string(),
+  mimeType: z.string(),
+  size: z.number().int().nonnegative(),
+  url: z.string(),
+  contentHash: z.string().nullable(),
+  /** How many places reference this asset (Base records + Doc bodies). */
+  usageCount: z.number().int().nonnegative(),
+  /** Drive Grep Retrieval text-slot status — see {@link AssetTextStatusSchema}. */
+  textStatus: AssetTextStatusSchema,
+  createdAt: z.string()
+});
+var AssetUsageVOSchema = z.object({
+  ownerType: z.enum(["drive", "skill", "airapp", "base", "doc", "file_node"]),
+  nodeId: z.string(),
+  nodeName: z.string(),
+  nodeType: z.string(),
+  /** Node slug, so the UI can link to the owning Base/Doc (`/{type}/{slug}`). */
+  nodeSlug: z.string(),
+  /** Drive/Skill mounted path, or null when the usage is not path-based. */
+  path: z.string().nullable(),
+  /** Base record id, or null for whole-node usages (e.g. a Doc body). */
+  recordId: z.string().nullable(),
+  /** Attachment field slug, or null for whole-node usages. */
+  fieldSlug: z.string().nullable(),
+  /** Doc block id, or null when the usage is not block-based. */
+  blockId: z.string().nullable(),
+  createdAt: z.string()
+});
+var AssetDetailVOSchema = z.object({
+  asset: AssetVOSchema,
+  usages: z.array(AssetUsageVOSchema)
+});
+var PutTextInputSchema = z.object({
+  assetId: z.string(),
+  /** Inline text body, ≤ 1 MB. For larger text, use `createTextUploadUrl` + bind by `storageKey`. */
+  text: z.string().optional(),
+  /** Bind a presigned-uploaded text object (a temp `asset-texts/pending/*.txt` key). */
+  storageKey: z.string().optional(),
+  /**
+   * Claimed content hash for the `storageKey` bind path (`sha256:<hex>`, echoing
+   * `createTextUploadUrl`'s input like `open-domains/attachments`' confirm step).
+   * The server always computes the ACTUAL hash from the bytes during the
+   * confirm scan and rejects a mismatch (hash-poisoning defense) — this field
+   * is only an optional early-mismatch check, never trusted for addressing.
+   */
+  contentHash: z.string().optional(),
+  /** Mark as having no extractable text (e.g. a scanned, image-only PDF). */
+  none: z.boolean().optional()
+});
+var AssetTextVOSchema = z.object({
+  assetId: z.string(),
+  textStatus: AssetTextStatusSchema,
+  lineCount: z.number().int().nonnegative(),
+  charCount: z.number().int().nonnegative(),
+  byteCount: z.number().int().nonnegative()
+});
+var CreateTextUploadUrlInputSchema = z.object({
+  assetId: z.string(),
+  sizeBytes: z.number().int().positive(),
+  /** Optional claim, mirrors `RequestUploadUrlDTO.contentHash` (never trusted for addressing). */
+  contentHash: z.string().optional()
+});
+var CreateTextUploadUrlVOSchema = z.object({
+  uploadUrl: z.string(),
+  storageKey: z.string(),
+  expiresIn: z.number().int().nonnegative()
+});
+var GrepScopeSchema = z.object({
+  assetIds: z.array(z.string()).optional(),
+  /** Drive/Skill mounted path prefix (matches `busabase_asset_usages.path`). */
+  drivePath: z.string().optional(),
+  mimeTypes: z.array(z.string()).optional()
+});
+var GREP_DEFAULT_MAX_MATCHES = 100;
+var GREP_HARD_MAX_MATCHES = 1e3;
+var GREP_DEFAULT_CONTEXT_LINES = 0;
+var GREP_MAX_CONTEXT_LINES = 10;
+var GrepInputSchema = z.object({
+  pattern: z.string().min(1),
+  /** JS RegExp flags, e.g. `"i"` for case-insensitive. `g`/`y` are ignored (grep always scans every match per line). */
+  flags: z.string().optional().default(""),
+  scope: GrepScopeSchema.optional(),
+  maxMatches: z.coerce.number().int().min(1).max(GREP_HARD_MAX_MATCHES).optional().default(GREP_DEFAULT_MAX_MATCHES),
+  contextLines: z.coerce.number().int().min(0).max(GREP_MAX_CONTEXT_LINES).optional().default(GREP_DEFAULT_CONTEXT_LINES)
+});
+var GrepMatchVOSchema = z.object({
+  assetId: z.string(),
+  fileName: z.string(),
+  /** Drive/Skill mounted path, or "" when the asset isn't path-mounted (e.g. a File node). */
+  drivePath: z.string(),
+  line: z.number().int().positive(),
+  /** 1-based character column (not byte offset) of the match start within the line. */
+  column: z.number().int().positive(),
+  /** The matching line, truncated if it exceeds the long-line guard. */
+  text: z.string(),
+  before: z.array(z.string()),
+  after: z.array(z.string())
+});
+var GrepResultVOSchema = z.object({
+  matches: z.array(GrepMatchVOSchema),
+  filesScanned: z.number().int().nonnegative(),
+  /** Asset ids in scope with no text yet (contentKind text-or-writable-binary, no row). */
+  missing: z.array(z.string()),
+  /** Asset ids in scope whose derived text is stale (source replaced since it was written). */
+  stale: z.array(z.string()),
+  /** Count of assets in scope explicitly marked `none` (no extractable text). */
+  unsearchable: z.number().int().nonnegative(),
+  /**
+   * Asset ids whose scan was attempted but failed (storage error, corrupt
+   * cache file, object deleted mid-flight) — NOT counted in `filesScanned`.
+   * Honest coverage: these were not actually searched, so a caller must not
+   * treat their absence from `matches` as a clean "no match".
+   */
+  errored: z.array(z.string()),
+  /**
+   * Count of in-scope, present-and-searchable assets the scan never even
+   * reached because the deadline or `maxMatches` budget ran out first. Only
+   * nonzero when `truncated` is true.
+   */
+  notReached: z.number().int().nonnegative(),
+  truncated: z.boolean()
+});
+var ReadTextLinesInputSchema = z.object({
+  assetId: z.string(),
+  startLine: z.coerce.number().int().min(1),
+  endLine: z.coerce.number().int().min(1)
+});
+var ReadLinesVOSchema = z.object({
+  lines: z.array(z.string()),
+  startLine: z.number().int().positive(),
+  endLine: z.number().int().positive(),
+  totalLines: z.number().int().nonnegative(),
+  truncated: z.boolean()
+});
+var AssetContentEditSchema = z.object({
+  oldString: z.string().min(1),
+  newString: z.string(),
+  /** Replace every occurrence instead of requiring a single unique match. */
+  replaceAll: z.boolean().optional().default(false)
+}).strict();
+var EditAssetContentInputSchema = z.object({
+  assetId: z.string(),
+  edits: z.array(AssetContentEditSchema).min(1),
+  message: z.string().optional().default("Edit file content").describe(
+    'Explanation shown to the human reviewer. Write a conventional-commit style subject \u2014 imperative verb + what + why, e.g. "Fix typo in setup instructions".'
+  ),
+  submittedBy: z.string().optional().default("agent")
+});
+var AssetDownloadInputSchema = z.object({ assetId: z.string() });
+var AssetDownloadVOSchema = z.object({
+  assetId: z.string(),
+  downloadUrl: z.string(),
+  fileName: z.string(),
+  mimeType: z.string(),
+  size: z.number().int().nonnegative(),
+  contentHash: z.string().nullable()
+});
+
+// ../../packages/busabase-contract/src/domains/assets/contract.ts
+var UpdateAssetMetadataInputSchema = z.object({
+  assetId: z.string(),
+  metadata: z.record(z.string(), z.unknown()),
+  mode: z.enum(["merge", "replace"]).optional().default("merge")
+});
+var assetsContract = {
+  createUploadUrl: oc.route({
+    method: "POST",
+    path: "/assets/upload-urls",
+    tags: ["Assets"],
+    summary: "Request asset upload URL",
+    successDescription: "Presigned (or dev) upload URL plus the public URL and asset id when identical bytes are already in the library."
+  }).input(RequestUploadUrlInputSchema).output(RequestUploadUrlVOSchema),
+  confirm: oc.route({
+    method: "POST",
+    path: "/assets/confirmations",
+    tags: ["Assets"],
+    summary: "Confirm asset upload",
+    successDescription: "Recorded the file and ensured its Busabase Asset library entry."
+  }).input(ConfirmUploadInputSchema).output(ConfirmUploadVOSchema),
+  list: oc.route({
+    method: "GET",
+    path: "/assets",
+    tags: ["Assets"],
+    summary: "List assets",
+    successDescription: "Every asset in the space, with file metadata and usage counts."
+  }).output(z.array(AssetVOSchema)),
+  get: oc.route({
+    method: "GET",
+    path: "/assets/{assetId}",
+    tags: ["Assets"],
+    summary: "Get asset detail",
+    successDescription: "Asset metadata plus every place it is referenced (where-used)."
+  }).input(z.object({ assetId: z.string() })).output(AssetDetailVOSchema),
+  updateMetadata: oc.route({
+    method: "PATCH",
+    path: "/assets/{assetId}/metadata",
+    tags: ["Assets"],
+    summary: "Update asset metadata",
+    successDescription: "Updated AI-readable metadata for a file, such as summary, tags, source URL, or schema-specific hints. Large text does not live here \u2014 see putText / grep / readTextLines."
+  }).input(UpdateAssetMetadataInputSchema).output(AssetDetailVOSchema),
+  delete: oc.route({
+    method: "DELETE",
+    path: "/assets/{assetId}",
+    tags: ["Assets"],
+    summary: "Delete asset",
+    successDescription: "Removed the asset and, if no other row references its bytes, the stored object. Refused while the asset is still referenced (where-used)."
+  }).input(z.object({ assetId: z.string() })).output(z.object({ deleted: z.boolean() })),
+  download: oc.route({
+    method: "GET",
+    path: "/assets/{assetId}/content",
+    tags: ["Assets"],
+    summary: "Get an asset's binary content download URL",
+    successDescription: "A resolved, time-bounded download URL for the asset's raw bytes (local dev: the existing static /uploads route; cloud/S3: a presigned URL) plus its file metadata \u2014 see AssetDownloadVOSchema for why this returns a URL, not a raw-binary oRPC response."
+  }).input(AssetDownloadInputSchema).output(AssetDownloadVOSchema),
+  // ── Drive Grep Retrieval ─────────────────────────────────────────────────
+  // Busabase stores, indexes, and searches text; it never generates it. Text
+  // always arrives via putText — an agent's own extractor, or (future) an
+  // Outgoing-Hook-triggered service — never a bundled parser/OCR library.
+  putText: oc.route({
+    method: "PUT",
+    path: "/assets/{assetId}/text",
+    tags: ["Assets"],
+    summary: "Write (or mark none) an asset's text slot",
+    successDescription: "Text slot updated: inline body (\u22641MB), or bound from a presigned upload (server-verified content hash, hash-poisoning-safe), or marked `none` for files with no extractable text. Direct write, audit-logged, not ChangeRequest-gated."
+  }).input(PutTextInputSchema).output(AssetTextVOSchema),
+  createTextUploadUrl: oc.route({
+    method: "POST",
+    path: "/assets/text/upload-urls",
+    tags: ["Assets"],
+    summary: "Request a presigned upload URL for large text",
+    successDescription: "Presigned (or dev) upload URL for a temporary text object; PUT the bytes there, then call putText with the returned storageKey to bind, verify, and content-address it."
+  }).input(CreateTextUploadUrlInputSchema).output(CreateTextUploadUrlVOSchema),
+  grep: oc.route({
+    method: "POST",
+    path: "/assets/grep",
+    tags: ["Assets"],
+    summary: "Search every text-bearing asset in scope",
+    successDescription: "Streaming regex/literal matches with real file + line + column numbers and context, across every asset with text \u2014 any size, no 256KB cap. Honest coverage: missing/stale/unsearchable/errored name assets that were not (fully or successfully) searched, notReached counts present assets the scan never got to, and truncated flags a capped response."
+  }).input(GrepInputSchema).output(GrepResultVOSchema),
+  readTextLines: oc.route({
+    method: "GET",
+    path: "/assets/{assetId}/text/lines",
+    tags: ["Assets"],
+    summary: "Read an exact line range from an asset's text",
+    successDescription: "Lines [startLine, endLine] (range capped at 2000 lines / ~2MB response) read via a storage byte-range request \u2014 the server never loads the whole object, even for a multi-GB file."
+  }).input(ReadTextLinesInputSchema).output(ReadLinesVOSchema),
+  // ── editContent — edit an asset's REAL file content via ChangeRequest ──────
+  // Unlike putText (derived/extracted text, direct write, disposable), this
+  // edits the asset's actual mounted Drive/Skill file bytes and always goes
+  // through the existing filetree ChangeRequest pipeline — never auto-merged.
+  editContent: oc.route({
+    method: "POST",
+    path: "/assets/{assetId}/edit-content",
+    tags: ["Assets", "Change Requests"],
+    summary: "Edit an asset's file content via string-replace edits, as a ChangeRequest",
+    successDescription: `Applied the string-replace edits (coding-agent Edit-tool semantics: unique-match or replaceAll) to the asset's current mounted Drive/Skill file content and proposed the result as a ChangeRequest (status "in_review") for human review. Reuses the existing filetree update-via-CR pipeline end to end, including baseContentHash optimistic-concurrency conflict protection at merge time. Requires the asset to be mounted in exactly one editable Drive/Skill location.`
+  }).input(EditAssetContentInputSchema).output(changeRequestSchema)
+};
 var viewFilterOperatorSchema = z.enum([
   "contains",
   "equals",
@@ -1003,6 +1364,12 @@ var listRecordsResponseSchema = z.object({
   records: z.array(recordSchema),
   nextCursor: z.string().nullable()
 });
+var listArchivedRecordsPagedInputSchema = z.object({
+  baseId: z.string(),
+  limit: z.coerce.number().int().min(1).max(100).optional().default(50),
+  /** Opaque base64 cursor (createdAt-keyed) for keyset pagination. */
+  cursor: z.string().optional()
+});
 var countRecordsInputSchema = z.object({
   baseId: z.string().optional()
 }).optional().default({});
@@ -1101,13 +1468,20 @@ var baseContract = {
     summary: "List archived records for a Base",
     successDescription: "Records that have been archived (soft-deleted) from a Base."
   }).input(z.object({ baseId: z.string() })).output(z.array(recordSchema)),
+  listArchivedRecordsPaged: oc.route({
+    method: "GET",
+    path: "/bases/{baseId}/records/archived/paged",
+    tags: ["Records"],
+    summary: "List archived records for a Base with keyset pagination",
+    successDescription: "A page of archived (soft-deleted) records plus an opaque nextCursor (null at the end)."
+  }).input(listArchivedRecordsPagedInputSchema).output(listRecordsResponseSchema),
   create: oc.route({
     method: "POST",
     path: "/bases",
     tags: ["Bases"],
     summary: "Create Base",
-    successDescription: "Created Base."
-  }).input(createBaseInputSchema).output(baseSchema),
+    successDescription: "Review-first by default: a pending ChangeRequest proposing the Base. Returns the materialized Base instead when `autoMerge: true` is passed."
+  }).input(createBaseInputSchema).output(z.union([baseSchema, changeRequestSchema])),
   createChangeRequest: oc.route({
     method: "POST",
     path: "/bases/{baseId}/change-requests",
@@ -1295,6 +1669,13 @@ var viewContract = {
     successDescription: "Created change request that restores an archived View."
   }).input(restoreViewInputSchema.extend({ viewId: z.string() })).output(changeRequestSchema)
 };
+var ReadDocLinesInputSchema = z.object({
+  nodeId: z.string(),
+  startLine: z.coerce.number().int().min(1),
+  endLine: z.coerce.number().int().min(1)
+});
+
+// ../../packages/busabase-contract/src/domains/doc/contract.ts
 var docSchema = z.object({
   node: nodeSchema,
   storagePrefix: z.string(),
@@ -1305,7 +1686,12 @@ var createDocInputSchema = z.object({
   slug: z.string().min(1).regex(/^[a-z0-9-]+$/),
   name: z.string().min(1),
   description: z.string().optional().default(""),
-  body: z.string().optional().default("")
+  body: z.string().optional().default(""),
+  // Review-first by default: without `autoMerge: true`, this proposes the Doc
+  // as a pending ChangeRequest (status "in_review") instead of creating it
+  // immediately. Pass `autoMerge: true` only for callers that don't need human
+  // review (seed/migration scripts, an explicit no-review agent task).
+  autoMerge: z.boolean().optional().default(false)
 });
 var updateDocInputSchema = z.object({
   body: z.string()
@@ -1330,8 +1716,8 @@ var docContract = {
     path: "/docs",
     tags: ["Docs"],
     summary: "Create Doc node",
-    successDescription: "Created Doc node and initialized its body."
-  }).input(createDocInputSchema).output(docSchema),
+    successDescription: "Review-first by default: a pending ChangeRequest proposing the Doc. Returns the materialized Doc node instead when `autoMerge: true` is passed."
+  }).input(createDocInputSchema).output(z.union([docSchema, changeRequestSchema])),
   get: oc.route({
     method: "GET",
     path: "/docs/{nodeId}",
@@ -1339,6 +1725,13 @@ var docContract = {
     summary: "Get Doc node",
     successDescription: "Doc node detail and body."
   }).input(z.object({ nodeId: z.string() })).output(docSchema),
+  readLines: oc.route({
+    method: "GET",
+    path: "/docs/{nodeId}/lines",
+    tags: ["Docs"],
+    summary: "Read an exact line range from a Doc body",
+    successDescription: "Lines [startLine, endLine] (range capped at 2000 lines / ~2MB response) sliced from the Doc's full body \u2014 Docs are KB-scale, so the whole body is read in memory; no byte-range/checkpoint machinery like assets.readTextLines uses for potentially multi-GB files. The Doc-domain follow-up to a Unified Grep match with `source: \"docs\"`, so an agent can read just the lines around a match instead of `get`'s entire body."
+  }).input(ReadDocLinesInputSchema).output(ReadLinesVOSchema),
   updateBody: oc.route({
     method: "PUT",
     path: "/docs/{nodeId}/body",
@@ -1354,144 +1747,100 @@ var docContract = {
     successDescription: "Created a change request that proposes a new Doc body."
   }).input(createDocChangeRequestInputSchema.extend({ nodeId: z.string() })).output(changeRequestSchema)
 };
-var fileTreeFileSchema = z.object({
-  path: z.string(),
-  name: z.string(),
-  size: z.number(),
-  updatedAt: z.string().nullable(),
-  mimeType: z.string().nullable(),
-  assetId: z.string(),
-  displayName: z.string().nullable()
+
+// ../../packages/busabase-contract/src/domains/drive/contract.ts
+var driveContract = makeFileTreeContract("drives", "Drives");
+var DumpTableSchema = z.enum([
+  "nodes",
+  "bases",
+  "baseFields",
+  "views",
+  "records",
+  "fieldValues",
+  "recordLinks",
+  /** The physical bytes registry (open-domains/attachments) an Asset's `attachmentId` FKs into. */
+  "attachments",
+  "assets",
+  "assetUsages",
+  "assetTexts",
+  "commits",
+  "changeRequests",
+  "operations",
+  "comments",
+  "reviews",
+  "auditEvents"
+]);
+var ExportTablesInputSchema = z.object({
+  table: DumpTableSchema,
+  /** Opaque pagination cursor from a previous page's `nextCursor`; omit for the first page. */
+  cursor: z.string().optional(),
+  /** Page size, default 500, capped at 2000. */
+  limit: z.number().int().positive().max(2e3).optional().default(500)
 });
-var assetFileInputSchema = z.object({
-  path: z.string().min(1),
-  assetId: z.string().min(1),
-  displayName: z.string().optional(),
-  mimeType: z.string().optional()
-}).strict();
-var textFileInputSchema = z.object({
-  path: z.string().min(1),
-  content: z.string().default(""),
-  mimeType: z.string().optional()
-}).strict();
-var assetFileOperationInputSchema = z.object({
-  kind: z.enum(["create", "update"]),
-  path: z.string().min(1),
-  assetId: z.string().min(1),
-  displayName: z.string().optional(),
-  mimeType: z.string().optional(),
-  baseContentHash: z.string().optional()
-}).strict();
-var textFileOperationInputSchema = z.object({
-  kind: z.enum(["create", "update"]),
-  path: z.string().min(1),
-  content: z.string(),
-  mimeType: z.string().optional(),
-  baseContentHash: z.string().optional()
-}).strict();
-var fileTreeNodeSchema = z.object({
-  node: nodeSchema,
-  entryFile: z.string(),
-  visibility: z.enum(["private", "workspace", "public"]),
-  version: z.string(),
-  files: z.array(fileTreeFileSchema)
+var ExportTablesVOSchema = z.object({
+  rows: z.array(z.record(z.string(), z.unknown())),
+  nextCursor: z.string().nullable()
 });
-var createFileTreeInputSchema = z.object({
-  parentNodeId: z.string().optional(),
-  slug: z.string().min(1).regex(/^[a-z0-9-]+$/),
-  name: z.string().min(1),
-  description: z.string().optional().default(""),
-  visibility: z.enum(["private", "workspace", "public"]).optional().default("private"),
-  version: z.string().optional().default("0.1.0"),
-  files: z.array(z.union([assetFileInputSchema, textFileInputSchema])).optional().default([])
+var ImportBeginVOSchema = z.object({
+  sessionId: z.string()
 });
-var fileTreeFileOperationInputSchema = z.union([
-  assetFileOperationInputSchema,
-  textFileOperationInputSchema,
-  z.object({
-    kind: z.literal("delete"),
-    path: z.string().min(1),
-    baseContentHash: z.string().optional()
-  }).strict(),
-  z.object({
-    kind: z.literal("metadata_update"),
-    metadata: z.object({
-      entryFile: z.string().optional(),
-      visibility: z.enum(["private", "workspace", "public"]).optional(),
-      version: z.string().optional()
-    }).default({})
-  }).strict()
-]);
-var createFileTreeChangeRequestInputSchema = z.object({
-  message: z.string().optional().default("Update file tree").describe(
-    'Explanation shown to the human reviewer. Write a conventional-commit style subject \u2014 imperative verb + what + why, e.g. "Rewrite README.md quickstart for the new auth flow".'
-  ),
-  submittedBy: z.string().optional().default("local-producer"),
-  operations: z.array(fileTreeFileOperationInputSchema).min(1)
+var ImportTablesInputSchema = z.object({
+  sessionId: z.string(),
+  table: z.union([DumpTableSchema, z.literal("docBodies"), z.literal("attachmentBlobs")]),
+  rows: z.array(z.record(z.string(), z.unknown()))
+});
+var ImportTablesVOSchema = z.object({
+  inserted: z.number().int().nonnegative()
+});
+var ImportSessionInputSchema = z.object({
+  sessionId: z.string()
+});
+var ImportCommitVOSchema = z.object({
+  ok: z.boolean(),
+  warnings: z.array(z.string())
+});
+var ImportAbortVOSchema = z.object({
+  ok: z.boolean()
 });
-var makeFileTreeContract = (routeBase, tag) => {
-  const label = tag.endsWith("s") ? tag.slice(0, -1) : tag;
-  const basePath = `/${routeBase}`;
-  return {
-    list: oc.route({
-      method: "GET",
-      path: basePath,
-      tags: [tag],
-      summary: `List ${label} nodes`,
-      successDescription: `${label} nodes with their Asset-backed file trees.`
-    }).output(z.array(fileTreeNodeSchema)),
-    create: oc.route({
-      method: "POST",
-      path: basePath,
-      tags: [tag],
-      summary: `Create ${label} node`,
-      successDescription: `Created ${label} node and initialized file tree.`
-    }).input(createFileTreeInputSchema).output(fileTreeNodeSchema),
-    get: oc.route({
-      method: "GET",
-      path: `${basePath}/{nodeId}`,
-      tags: [tag],
-      summary: `Get ${label} node`,
-      successDescription: `${label} node detail and file tree.`
-    }).input(z.object({ nodeId: z.string() })).output(fileTreeNodeSchema),
-    listFiles: oc.route({
-      method: "GET",
-      path: `${basePath}/{nodeId}/files`,
-      tags: [tag],
-      summary: `List ${label} files`,
-      successDescription: `Asset-backed files mounted under the ${label} node.`
-    }).input(z.object({ nodeId: z.string() })).output(z.array(fileTreeFileSchema)),
-    readFile: oc.route({
-      method: "GET",
-      path: `${basePath}/{nodeId}/files/{+filePath}`,
-      tags: [tag],
-      summary: `Read ${label} file`,
-      successDescription: `${label} file content and content hash.`
-    }).input(z.object({ nodeId: z.string(), filePath: z.string() })).output(
-      z.object({
-        nodeId: z.string(),
-        path: z.string(),
-        encoding: z.enum(["utf8", "url"]),
-        content: z.string(),
-        mimeType: z.string(),
-        assetId: z.string(),
-        displayName: z.string().nullable(),
-        assetUrl: z.string().nullable(),
-        contentHash: z.string()
-      })
-    ),
-    createChangeRequest: oc.route({
-      method: "POST",
-      path: `${basePath}/{nodeId}/change-requests`,
-      tags: [tag, "Change Requests"],
-      summary: `Create ${label} change request`,
-      successDescription: `Created file-tree change request for a ${label} node.`
-    }).input(createFileTreeChangeRequestInputSchema.extend({ nodeId: z.string() })).output(changeRequestSchema)
-  };
-};
 
-// ../../packages/busabase-contract/src/domains/drive/contract.ts
-var driveContract = makeFileTreeContract("drives", "Drives");
+// ../../packages/busabase-contract/src/domains/dump/contract.ts
+var dumpContract = {
+  exportTables: oc.route({
+    method: "POST",
+    path: "/dump/export/tables",
+    tags: ["Dump"],
+    summary: "Export raw rows for one table (cursor-paginated)",
+    successDescription: "A page of raw rows for the requested table (id-ordered), plus an opaque nextCursor (null at the end). Vault items and webhook secrets are never exportable through this endpoint."
+  }).input(ExportTablesInputSchema).output(ExportTablesVOSchema),
+  importBegin: oc.route({
+    method: "POST",
+    path: "/dump/import/begin",
+    tags: ["Dump"],
+    summary: "Begin a full-fidelity import session",
+    successDescription: "Created an import session for the current space. Refused unless the space's node tree is empty (full-fidelity import preserves original ids and cannot merge into existing data)."
+  }).output(ImportBeginVOSchema),
+  importTables: oc.route({
+    method: "POST",
+    path: "/dump/import/tables",
+    tags: ["Dump"],
+    summary: "Import a batch of raw rows into an open session",
+    successDescription: "Inserted rows preserving their original ids. `docBodies` is a pseudo-table ({nodeId, markdown}[]) written directly to object storage (doc bodies are not a DB row)."
+  }).input(ImportTablesInputSchema).output(ImportTablesVOSchema),
+  importCommit: oc.route({
+    method: "POST",
+    path: "/dump/import/commit",
+    tags: ["Dump"],
+    summary: "Finalize an import session",
+    successDescription: "Ran integrity checks (FK orphans, missing blobs) and closed the session. `ok:false` or a non-empty `warnings` array means the import completed but may be incomplete \u2014 inspect before relying on the space."
+  }).input(ImportSessionInputSchema).output(ImportCommitVOSchema),
+  importAbort: oc.route({
+    method: "POST",
+    path: "/dump/import/abort",
+    tags: ["Dump"],
+    summary: "Abort an import session",
+    successDescription: "Best-effort cleanup of everything written so far in this session. Only ever touches the target space validated empty at `importBegin` time."
+  }).input(ImportSessionInputSchema).output(ImportAbortVOSchema)
+};
 z.object({
   assetId: z.string()
 });
@@ -1506,7 +1855,12 @@ var createFileNodeInputSchema = z.object({
   slug: z.string().min(1).regex(/^[a-z0-9-]+$/),
   name: z.string().min(1),
   description: z.string().optional().default(""),
-  assetId: z.string().min(1)
+  assetId: z.string().min(1),
+  // Review-first by default: without `autoMerge: true`, this proposes the File
+  // node as a pending ChangeRequest (status "in_review") instead of creating it
+  // immediately. Pass `autoMerge: true` only for callers that don't need human
+  // review (seed/migration scripts, an explicit no-review agent task).
+  autoMerge: z.boolean().optional().default(false)
 });
 var fileContract = {
   list: oc.route({
@@ -1521,8 +1875,8 @@ var fileContract = {
     path: "/files",
     tags: ["Files"],
     summary: "Create File node",
-    successDescription: "Created a first-class File node that references an Asset."
-  }).input(createFileNodeInputSchema).output(FileNodeVOSchema),
+    successDescription: "Review-first by default: a pending ChangeRequest proposing the File node. Returns the materialized File node instead when `autoMerge: true` is passed."
+  }).input(createFileNodeInputSchema).output(z.union([FileNodeVOSchema, changeRequestSchema])),
   get: oc.route({
     method: "GET",
     path: "/files/{nodeId}",
@@ -1630,6 +1984,303 @@ var vaultContract = {
     successDescription: "Removed local Vault secrets and variables."
   }).output(VaultSuccessSchema)
 };
+var WebhookEventTypeSchema = z.enum([
+  "record.created",
+  "ai_mention",
+  "changes_requested",
+  "asset.uploaded"
+]);
+z.enum(["webhook", "notify_agent", "run_function"]);
+var WebhookDeliveryStatusSchema = z.enum(["success", "failed", "skipped"]);
+var WebhookHttpConfigSchema = z.object({
+  targetUrl: z.string().url(),
+  secret: z.string().min(1).max(256).optional(),
+  headers: z.record(z.string(), z.string()).optional()
+});
+var WebhookFunctionConfigSchema = z.object({
+  code: z.string().min(1).max(2e4),
+  timeoutMs: z.number().int().min(100).max(5e3).default(2e3)
+});
+var WebhookHttpConfigVOSchema = z.object({
+  targetUrl: z.string().url(),
+  hasSecret: z.boolean(),
+  headers: z.record(z.string(), z.string()).optional()
+});
+var WebhookFunctionConfigVOSchema = WebhookFunctionConfigSchema;
+var webhookRuleCommonInputFields = {
+  name: z.string().min(1).max(200),
+  eventType: WebhookEventTypeSchema,
+  baseId: z.string().nullable().optional(),
+  enabled: z.boolean().default(true)
+};
+var WebhookRuleInputSchema = z.discriminatedUnion("actionKind", [
+  z.object({
+    ...webhookRuleCommonInputFields,
+    actionKind: z.literal("webhook"),
+    config: WebhookHttpConfigSchema
+  }),
+  z.object({
+    ...webhookRuleCommonInputFields,
+    actionKind: z.literal("notify_agent"),
+    config: WebhookHttpConfigSchema
+  }),
+  z.object({
+    ...webhookRuleCommonInputFields,
+    actionKind: z.literal("run_function"),
+    config: WebhookFunctionConfigSchema
+  })
+]);
+var WebhookRuleUpdateInputSchema = z.discriminatedUnion("actionKind", [
+  z.object({
+    id: z.string(),
+    ...webhookRuleCommonInputFields,
+    actionKind: z.literal("webhook"),
+    config: WebhookHttpConfigSchema
+  }),
+  z.object({
+    id: z.string(),
+    ...webhookRuleCommonInputFields,
+    actionKind: z.literal("notify_agent"),
+    config: WebhookHttpConfigSchema
+  }),
+  z.object({
+    id: z.string(),
+    ...webhookRuleCommonInputFields,
+    actionKind: z.literal("run_function"),
+    config: WebhookFunctionConfigSchema
+  })
+]);
+var webhookRuleVOCommonFields = {
+  id: z.string(),
+  spaceId: z.string(),
+  baseId: z.string().nullable(),
+  name: z.string(),
+  eventType: WebhookEventTypeSchema,
+  enabled: z.boolean(),
+  createdBy: z.string(),
+  createdAt: z.string(),
+  updatedAt: z.string(),
+  lastTriggeredAt: z.string().nullable(),
+  lastStatus: WebhookDeliveryStatusSchema.nullable()
+};
+var WebhookRuleVOSchema = z.discriminatedUnion("actionKind", [
+  z.object({
+    ...webhookRuleVOCommonFields,
+    actionKind: z.literal("webhook"),
+    config: WebhookHttpConfigVOSchema
+  }),
+  z.object({
+    ...webhookRuleVOCommonFields,
+    actionKind: z.literal("notify_agent"),
+    config: WebhookHttpConfigVOSchema
+  }),
+  z.object({
+    ...webhookRuleVOCommonFields,
+    actionKind: z.literal("run_function"),
+    config: WebhookFunctionConfigVOSchema
+  })
+]);
+var WebhookDeliveryVOSchema = z.object({
+  id: z.string(),
+  ruleId: z.string(),
+  eventType: WebhookEventTypeSchema,
+  status: WebhookDeliveryStatusSchema,
+  httpStatus: z.number().nullable(),
+  detail: z.string().nullable(),
+  durationMs: z.number().nullable(),
+  createdAt: z.string()
+});
+z.object({}).optional().default({});
+var ListWebhookDeliveriesInputSchema = z.object({
+  ruleId: z.string(),
+  limit: z.coerce.number().int().min(1).max(100).default(20)
+});
+
+// ../../packages/busabase-contract/src/domains/webhook/contract.ts
+var webhookContract = {
+  list: oc.route({
+    method: "GET",
+    path: "/webhooks",
+    tags: ["Webhooks"],
+    summary: "List webhook automation rules",
+    successDescription: "Configured webhook automation rules for this space."
+  }).output(WebhookRuleVOSchema.array()),
+  get: oc.route({
+    method: "GET",
+    path: "/webhooks/{id}",
+    tags: ["Webhooks"],
+    summary: "Get webhook automation rule",
+    successDescription: "A single webhook automation rule."
+  }).input(z.object({ id: z.string() })).output(WebhookRuleVOSchema),
+  create: oc.route({
+    method: "POST",
+    path: "/webhooks",
+    tags: ["Webhooks"],
+    summary: "Create webhook automation rule",
+    successDescription: "Created webhook automation rule. Dispatches on the configured event via an HTTP webhook, an agent notification, or a sandboxed function."
+  }).input(WebhookRuleInputSchema).output(WebhookRuleVOSchema),
+  update: oc.route({
+    method: "PUT",
+    path: "/webhooks/{id}",
+    tags: ["Webhooks"],
+    summary: "Update webhook automation rule",
+    successDescription: "Updated webhook automation rule."
+  }).input(WebhookRuleUpdateInputSchema).output(WebhookRuleVOSchema),
+  delete: oc.route({
+    method: "DELETE",
+    path: "/webhooks/{id}",
+    tags: ["Webhooks"],
+    summary: "Delete webhook automation rule",
+    successDescription: "Removed the webhook automation rule."
+  }).input(z.object({ id: z.string() })).output(z.object({ success: z.boolean() })),
+  deliveries: oc.route({
+    method: "GET",
+    path: "/webhooks/{ruleId}/deliveries",
+    tags: ["Webhooks"],
+    summary: "List webhook rule delivery attempts",
+    successDescription: "Recent delivery attempts for a webhook rule, newest first."
+  }).input(ListWebhookDeliveriesInputSchema).output(WebhookDeliveryVOSchema.array()),
+  testFire: oc.route({
+    method: "POST",
+    path: "/webhooks/{id}/test-fire",
+    tags: ["Webhooks"],
+    summary: "Test-fire a webhook automation rule",
+    successDescription: "The delivery record produced by firing this rule right now with a synthetic payload \u2014 runs regardless of the rule's enabled state or its real trigger."
+  }).input(z.object({ id: z.string() })).output(WebhookDeliveryVOSchema)
+};
+var activityItemSchema = z.discriminatedUnion("kind", [
+  z.object({
+    kind: z.literal("change_request"),
+    timestamp: z.string(),
+    changeRequest: changeRequestSchema
+  }),
+  z.object({
+    kind: z.literal("operation"),
+    timestamp: z.string(),
+    operationId: z.string(),
+    changeRequest: changeRequestSchema
+  }),
+  z.object({
+    kind: z.literal("record"),
+    timestamp: z.string(),
+    record: recordSchema
+  }),
+  z.object({
+    kind: z.literal("audit"),
+    timestamp: z.string(),
+    auditEvent: auditEventSchema,
+    record: recordSchema.nullable()
+  })
+]);
+var listActivityPagedInputSchema = z.object({
+  limit: z.coerce.number().int().min(1).max(100).optional().default(50),
+  cursor: z.string().optional()
+}).optional().default({ limit: 50 });
+var listActivityResponseSchema = z.object({
+  items: z.array(activityItemSchema),
+  nextCursor: z.string().nullable()
+});
+var GrepSourceSchema = z.enum(["files", "docs", "records"]);
+var UnifiedGrepFilesScopeSchema = z.object({
+  assetIds: z.array(z.string()).optional(),
+  /** Drive/Skill mounted path prefix (matches `busabase_asset_usages.path`). */
+  drivePath: z.string().optional(),
+  mimeTypes: z.array(z.string()).optional()
+});
+var UnifiedGrepDocsScopeSchema = z.object({
+  nodeIds: z.array(z.string()).optional()
+});
+var UnifiedGrepRecordsScopeSchema = z.object({
+  baseIds: z.array(z.string()).optional(),
+  baseSlugs: z.array(z.string()).optional()
+});
+var UnifiedGrepScopeSchema = z.object({
+  files: UnifiedGrepFilesScopeSchema.optional(),
+  docs: UnifiedGrepDocsScopeSchema.optional(),
+  records: UnifiedGrepRecordsScopeSchema.optional()
+});
+var UnifiedGrepInputSchema = z.object({
+  pattern: z.string().min(1),
+  /** JS RegExp flags, e.g. `"i"` for case-insensitive — same language as `assets.grep`. */
+  flags: z.string().optional().default(""),
+  /** Which sources to scan. Omitted = all three (`files`, `docs`, `records`). */
+  sources: z.array(GrepSourceSchema).optional(),
+  scope: UnifiedGrepScopeSchema.optional(),
+  /** Shared across every scanned source — files run to completion first, then docs, then whatever remains goes to records. */
+  maxMatches: z.coerce.number().int().min(1).max(GREP_HARD_MAX_MATCHES).optional().default(GREP_DEFAULT_MAX_MATCHES),
+  contextLines: z.coerce.number().int().min(0).max(GREP_MAX_CONTEXT_LINES).optional().default(GREP_DEFAULT_CONTEXT_LINES)
+});
+var grepHitFields = {
+  line: z.number().int().positive(),
+  /** 1-based character column (not byte offset) of the match start within the line. */
+  column: z.number().int().positive(),
+  /** The matching line, truncated if it exceeds the long-line guard. */
+  text: z.string(),
+  before: z.array(z.string()),
+  after: z.array(z.string())
+};
+var UnifiedGrepFileMatchVOSchema = z.object({
+  source: z.literal("files"),
+  assetId: z.string(),
+  fileName: z.string(),
+  /** Drive/Skill mounted path, or "" when the asset isn't path-mounted (e.g. a File node). */
+  drivePath: z.string(),
+  ...grepHitFields
+});
+var UnifiedGrepDocMatchVOSchema = z.object({
+  source: z.literal("docs"),
+  nodeId: z.string(),
+  slug: z.string(),
+  name: z.string(),
+  ...grepHitFields
+});
+var UnifiedGrepRecordMatchVOSchema = z.object({
+  source: z.literal("records"),
+  baseId: z.string(),
+  baseSlug: z.string(),
+  recordId: z.string(),
+  fieldSlug: z.string(),
+  ...grepHitFields
+});
+var UnifiedGrepMatchVOSchema = z.discriminatedUnion("source", [
+  UnifiedGrepFileMatchVOSchema,
+  UnifiedGrepDocMatchVOSchema,
+  UnifiedGrepRecordMatchVOSchema
+]);
+var UnifiedGrepFilesCoverageSchema = z.object({
+  scanned: z.number().int().nonnegative(),
+  missing: z.array(z.string()),
+  stale: z.array(z.string()),
+  unsearchable: z.number().int().nonnegative(),
+  errored: z.array(z.string()),
+  notReached: z.number().int().nonnegative()
+});
+var UnifiedGrepDocsCoverageSchema = z.object({
+  scanned: z.number().int().nonnegative(),
+  /** Doc node ids whose body read/scan was attempted but failed — NOT a clean "scanned, no match". */
+  errored: z.array(z.string()),
+  /** Count of in-scope docs the scan never reached because the deadline/maxMatches budget ran out first. */
+  notReached: z.number().int().nonnegative()
+});
+var UnifiedGrepRecordsCoverageSchema = z.object({
+  scanned: z.number().int().nonnegative(),
+  /** Record ids whose commit-fields read/flatten/scan was attempted but failed — NOT a clean "scanned, no match". */
+  errored: z.array(z.string()),
+  /** Count of in-scope records the scan never reached because the deadline/maxMatches budget ran out first. */
+  notReached: z.number().int().nonnegative()
+});
+var UnifiedGrepCoverageSchema = z.object({
+  files: UnifiedGrepFilesCoverageSchema,
+  docs: UnifiedGrepDocsCoverageSchema,
+  records: UnifiedGrepRecordsCoverageSchema
+});
+var UnifiedGrepResultVOSchema = z.object({
+  /** Deterministic order: every `files` match, then every `docs` match, then every `records` match. */
+  matches: z.array(UnifiedGrepMatchVOSchema),
+  coverage: UnifiedGrepCoverageSchema,
+  /** True when any source truncated, or any source has `notReached > 0`. */
+  truncated: z.boolean()
+});
 
 // ../../packages/busabase-contract/src/contract/busabase.ts
 var changeRequestBatchResultSchema = z.object({
@@ -1659,6 +2310,18 @@ var busabaseContractRoutes = {
     summary: "Search Busabase",
     successDescription: "Paginated search results across records, change requests, Bases, File nodes, and Assets."
   }).input(searchInputSchema).output(searchResponseSchema),
+  // Unified Grep (P2a files+docs, P2b records) — top-level, cross-source
+  // superset of `assets.grep`. See apps/busabase/content/spec/unified-grep.md.
+  // Composes `logic/grep.ts`; `assets.grep` (files-only specialist) is
+  // unchanged and stays the dedicated endpoint for its fuller
+  // missing/stale/unsearchable reporting.
+  grep: oc.route({
+    method: "POST",
+    path: "/grep",
+    tags: ["Search"],
+    summary: "Search files, Docs, and Base records with one pattern (unified grep)",
+    successDescription: "Streaming regex/literal matches across every in-scope source \u2014 Drive/Skill files, Doc bodies, and Base records (canonical headCommit.fields, never the truncated search projection) \u2014 with one shared pattern, one shared maxMatches/deadline budget (files scanned first, then docs, then whatever budget remains goes to records), and a per-source honest coverage report (files keeps its existing missing/stale/unsearchable/errored/notReached; docs and records report scanned/errored/notReached). truncated is set when any source truncated or has notReached > 0."
+  }).input(UnifiedGrepInputSchema).output(UnifiedGrepResultVOSchema),
   nodes: {
     list: oc.route({
       method: "GET",
@@ -1681,6 +2344,13 @@ var busabaseContractRoutes = {
       summary: "Create Node tree change request",
       successDescription: "Created change request for folder or node tree changes."
     }).input(createNodeChangeRequestInputSchema).output(changeRequestSchema),
+    move: oc.route({
+      method: "POST",
+      path: "/nodes/{nodeId}/move",
+      tags: ["Nodes"],
+      summary: "Move or reorder a node",
+      successDescription: "Merged change request that repositioned the node under its (optionally new) parent. Applied immediately (auto-merged) since reordering is a low-risk structural tweak, not a review-worthy content change."
+    }).input(moveNodeInputSchema).output(changeRequestSchema),
     purge: oc.route({
       method: "DELETE",
       path: "/nodes/{nodeId}",
@@ -1705,6 +2375,15 @@ var busabaseContractRoutes = {
       successDescription: "Recorded audit event."
     }).input(createAuditEventInputSchema).output(auditEventSchema)
   },
+  activity: {
+    listPaged: oc.route({
+      method: "GET",
+      path: "/activity/paged",
+      tags: ["Activity"],
+      summary: "List the activity feed with keyset pagination",
+      successDescription: "A page of activity items (change requests, operations, records and audit events merged, newest first) plus an opaque nextCursor (null at the end)."
+    }).input(listActivityPagedInputSchema).output(listActivityResponseSchema)
+  },
   comments: {
     list: oc.route({
       method: "GET",
@@ -1738,11 +2417,14 @@ var busabaseContractRoutes = {
   bases: baseContract,
   skills: skillContract,
   drives: driveContract,
+  airapps: airappContract,
   files: fileContract,
   docs: docContract,
   folders: folderContract,
   assets: assetsContract,
   vault: vaultContract,
+  webhooks: webhookContract,
+  dump: dumpContract,
   changeRequests: {
     list: oc.route({
       method: "GET",
@@ -2069,10 +2751,61 @@ var Busabase = class {
   get agentTasks() {
     return this.client.agentTasks;
   }
+  get webhooks() {
+    return this.client.webhooks;
+  }
   /** Full-text search across records, change requests, and Bases. */
   search(input) {
     return this.client.search(input);
   }
+  /**
+   * Unified grep — one regex/literal pattern scanned across every in-scope
+   * source (Drive/Skill files, Doc bodies, and Base records — records read
+   * the canonical `headCommit.fields`, never the truncated search
+   * projection), with a shared `maxMatches`/deadline budget and per-source
+   * honest coverage. Use this when the answer could live anywhere; use
+   * `client.assets.grep` directly instead when you specifically only care
+   * about files and want its fuller `missing`/`stale`/`unsearchable`
+   * file-only reporting.
+   */
+  grep(input) {
+    return this.client.grep(input);
+  }
+  /**
+   * Supply text for an Asset's Drive Grep Retrieval text slot in one call —
+   * inline for small text, a presigned upload for large text — so callers
+   * never see the underlying three-step flow
+   * (`createTextUploadUrl` → PUT bytes → `putText({ storageKey })`).
+   *
+   * @example
+   * ```ts
+   * await bb.putText(assetId, extractedText); // picks inline vs presigned by size
+   * ```
+   */
+  async putText(assetId, text) {
+    const INLINE_TEXT_MAX_BYTES = 1024 * 1024;
+    const byteLength = typeof Buffer !== "undefined" ? Buffer.byteLength(text, "utf8") : new Blob([text]).size;
+    if (byteLength <= INLINE_TEXT_MAX_BYTES) {
+      return this.client.assets.putText({ assetId, text });
+    }
+    const upload = await this.client.assets.createTextUploadUrl({
+      assetId,
+      sizeBytes: byteLength
+    });
+    const doFetch = this.config.fetch ?? fetch;
+    const response = await doFetch(upload.uploadUrl, {
+      method: "PUT",
+      headers: { "content-type": "text/plain; charset=utf-8" },
+      body: text
+    });
+    if (!response.ok) {
+      const detail = await response.text().catch(() => "");
+      throw new Error(
+        `putText: presigned upload failed (${response.status} ${response.statusText})${detail ? `: ${detail}` : ""}`
+      );
+    }
+    return this.client.assets.putText({ assetId, storageKey: upload.storageKey });
+  }
   /** Service health — reaches the server without requiring auth. */
   health() {
     return this.client.system.health();